Skopeo Intent Parser

Natural language parser for spreadsheet operations. Converts user queries into structured intents with entity extraction and safety validation.

Setup

Prerequisites

• Node.js 18+
• OpenAI API key

Installation

npm install

Configuration

Create .env file:

cp .env.example .env

Edit .env and add your OpenAI API key:

OPENAI_API_KEY=your-key-here
LLM_MODEL=gpt-4o-mini-2024-07-18
LLM_TEMPERATURE=0.2
PORT=3000
MAX_INPUT_LENGTH=2000

Usage

Web Interface

Start the web app:

npm run webapp

Open http://localhost:3000

API Server

Start API server only:

npm run start:dev

API Endpoint

POST http://localhost:3000/api/parse
Content-Type: application/json

{
  "text": "sum revenue in column C where region = West"
}

Response:

{
  "intent": "CREATE_FORMULA",
  "tool": "formula_generator",
  "confidence": 0.95,
  "command_text": "sum revenue in column C where region = West",
  "entities": {
    "aggregation": "sum",
    "column": "C",
    "condition": "region = West"
  },
  "safety_flags": {
    "risky_external_fetch": false,
    "file_write": false
  },
  "requires_disambiguation": false,
  "ask": []
}

Supported Intents

Intent	Description
CREATE_FORMULA	Create/modify formulas
FIX_FORMULA	Debug formula errors
CLEAN_DATA	Remove duplicates, trim, format
FILTER_SORT	Filter and sort data
SUMMARIZE	Group and aggregate data
CREATE_PIVOT	Create pivot tables
CREATE_CHART	Create visualizations
EXPLAIN_CELL	Explain cell contents
IMPORT_DATA	Import external data
JOIN_SHEETS	Merge data from sheets
VALIDATE_DATA	Validate data patterns
AUTOMATE_MACRO	Create automation
HELP	General help
CANCEL	Cancel operation
AMBIGUOUS	Unclear intent (triggers clarification)

Clarifying Agent

When queries are ambiguous, the clarifying agent asks follow-up questions:

Input: make a chart

Response:

{
  "intent": "AMBIGUOUS",
  "clarification": {
    "needsClarification": true,
    "questions": [
      "What type of chart? (bar, line, pie, etc.)",
      "What data should be visualized?"
    ],
    "suggestedIntents": ["CREATE_CHART"]
  }
}

Follow-up: bar chart showing sales by region

Final Result: Refined query with CREATE_CHART intent

Project Structure

├── src/
│   ├── api/              # Express server
│   ├── config/           # Configuration
│   ├── models/           # Type definitions
│   ├── services/         # Core services
│   │   ├── Parser.ts
│   │   ├── IntentClassifier.ts
│   │   ├── EntityExtractor.ts
│   │   ├── ClarifyingAgent.ts
│   │   └── SafetyValidator.ts
│   └── utils/            # Utilities
├── public/               # Web UI
├── docs/                 # Documentation
└── examples/             # Usage examples

Development

Build

npm run build

Run Demo

npm run demo

Stop Server

Press Ctrl+C in the terminal

API Endpoints

Endpoint	Method	Description
/api/parse	POST	Parse user query
/api/clarify	POST	Process clarification response
/api/v1/parse	POST	Parse with full error handling
/api/v1/metrics	GET	Get performance metrics
/health	GET	Health check

Environment Variables

Variable	Default	Description
OPENAI_API_KEY	-	OpenAI API key (required)
LLM_MODEL	gpt-4o-mini-2024-07-18	Model to use
LLM_TEMPERATURE	0.2	Temperature (0-1)
PORT	3000	Server port
MAX_INPUT_LENGTH	2000	Max query length

License

MIT