intents

.claude/commands/classify-intent.md

@@ -0,0 +1,13 @@
+Read the file `intents.yaml` in the current working directory.
+
+Using the intent taxonomy from that file, classify the following user utterance:
+
+"$ARGUMENTS"
+
+Return your answer as:
+- **Domain**: the top-level domain key (e.g. `shopping_assistant`)
+- **Intent**: the action label within that domain (e.g. `add_item`)
+- **Confidence**: high / medium / low
+- **Reasoning**: one sentence explaining why
+
+If the utterance matches no known intent, return `domain: unknown, intent: unknown` and suggest where in the taxonomy it might belong or whether a new intent is needed.

INTENT_RESTRUCTURE.md

@@ -0,0 +1,111 @@
+# Intent Taxonomy Restructure — Rationale
+
+## Overview
+
+The original intent specification (`intents.txt`) was reorganized into a structured YAML taxonomy (`intents.yaml`). This document explains what changed, why it was necessary, and how the new format benefits the system going forward.
+
+---
+
+## What the Original File Contained
+
+The original file organized user phrases under package names (e.g. `BENEVOLENCE`, `MONEYSHARE`) using full natural language sentences as the primary identifier, with an optional `Alias` column for alternate phrasing.
+
+**Example from the original:**
+
+| Package    | Intent                          | Alias                        |
+|------------|---------------------------------|------------------------------|
+| MONEYSHARE | I want to avoid a bank fee      |                              |
+| MONEYSHARE | I need a small loan             |                              |
+| MATH       | compute xplusonesquared         | Compute xsquared plus one    |
+
+---
+
+## The Problem
+
+### 1. No Actual Intent Labels
+
+In NLU (Natural Language Understanding) systems, an **intent** is a short, machine-readable label that represents *what the user wants to do* — for example `avoid_fee` or `request_loan`. The original file uses full sentences where the label should be, which means:
+
+- There is no stable, referenceable name for any given intent
+- Two sentences that mean the same thing appear as two different intents
+- Code, APIs, and routing logic have no clean string to match against
+
+### 2. Conflation of Labels and Training Data
+
+The sentences in the `Intent` column serve two completely different purposes in the original file:
+
+- As an **intent identifier** (what the intent *is called*)
+- As a **training utterance** (an example of what a user might say)
+
+These are distinct concepts. A sentence like `"I am hungry"` is a training example — it teaches the system what the `request_food` intent sounds like. It should never be the name of the intent itself. Conflating the two makes the taxonomy brittle: renaming a phrase breaks the intent's identity.
+
+### 3. Duplicate Meaning Without Grouping
+
+`"I'm hungry"` and `"I am hungry"` appear as separate rows under `FOODSHARE`, when they are clearly two utterances for the same intent. The original format has no mechanism to express that these map to a single action. This grows into a maintenance problem as more phrasings are added over time.
+
+### 4. No Structure for Aliasing
+
+The `Alias` column is inconsistently populated and only appears for a few entries. In practice it was doing the job that a proper `utterances` list should do — providing alternate phrasings for the same intent.
+
+---
+
+## What We Changed
+
+The new `intents.yaml` introduces a three-level hierarchy:
+
+```
+domain → intent_label → utterances
+```
+
+- **Domain**: the package or feature area (e.g. `moneyshare`, `shopping_assistant`)
+- **Intent label**: a concise, snake_case action name (e.g. `avoid_fee`, `add_item`)
+- **Utterances**: a list of example phrases a user might say to trigger that intent
+
+**Equivalent example in the new format:**
+
+```yaml
+moneyshare:
+  avoid_fee:
+    utterances:
+      - "I want to avoid a bank fee"
+  request_loan:
+    utterances:
+      - "I need a small loan"
+```
+
+---
+
+## Why This Matters for an LLM Integration
+
+When an LLM is used to classify user input against a set of intents, it needs:
+
+1. **A stable label to return** — the model's output needs to be a value your code can act on. `avoid_fee` is actionable; `"I want to avoid a bank fee"` is not.
+2. **Examples to reason from** — utterances serve as few-shot context that guides the model toward the correct classification.
+3. **A single source of truth** — keeping all phrasings for one intent together under one label means updating coverage requires editing one place, not hunting through a flat list.
+
+The restructured file feeds directly into the `/classify` endpoint, which builds a system prompt from the taxonomy at runtime. Adding a new utterance to `intents.yaml` immediately improves classification accuracy with no code changes.
+
+---
+
+## Summary of Benefits
+
+| Concern                  | Original Format         | New Format                        |
+|--------------------------|-------------------------|-----------------------------------|
+| Machine-readable labels  | None                    | Snake_case intent labels          |
+| Grouping of synonyms     | Separate rows           | Unified utterances list           |
+| Extensibility            | Append rows to flat CSV | Add utterances under existing key |
+| LLM/API integration      | Not directly usable     | Loads directly into system prompt |
+| Aliasing                 | Partial, inconsistent   | First-class `aliases` field       |
+| Readability              | Moderate                | Explicit hierarchy                |
+
+---
+
+## Recommendation
+
+The taxonomy is currently sparse in a few areas worth addressing before production:
+
+- `math.compute_expression` ��� only covers two very specific phrasings; common variants like "calculate", "what is", or "evaluate" are missing
+- `flow_planner.create_flow_plan` — the single utterance references "tomorrow" specifically, which will miss any other time reference
+- `remembot` — has no coverage for listing or deleting memories, only storing and recalling
+
+These can be expanded directly in `intents.yaml` without any engineering changes.

backend/intent_classifier.py

@@ -0,0 +1,45 @@
+import json
+import os
+from pathlib import Path
+
+import yaml
+from openai import OpenAI
+
+client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
+
+_INTENTS_PATH = Path(__file__).parent.parent / "intents.yaml"
+
+
+def _load_taxonomy() -> dict:
+    with open(_INTENTS_PATH) as f:
+        return yaml.safe_load(f)["intents"]
+
+
+def _build_system_prompt(taxonomy: dict) -> str:
+    lines = ["You are an intent classifier. Given a user message, return JSON with keys: domain, intent, confidence (high/medium/low)."]
+    lines.append("\nKnown intents (domain → intent: example utterances):\n")
+    for domain, intents in taxonomy.items():
+        for intent, data in intents.items():
+            utterances = data.get("utterances", [])
+            examples = "; ".join(utterances[:2])
+            lines.append(f"  {domain}.{intent}: \"{examples}\"")
+    lines.append('\nIf nothing matches, return {"domain": "unknown", "intent": "unknown", "confidence": "low"}.')
+    lines.append("Respond with JSON only, no prose.")
+    return "\n".join(lines)
+
+
+def classify(utterance: str) -> dict:
+    taxonomy = _load_taxonomy()
+    system_prompt = _build_system_prompt(taxonomy)
+
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": utterance},
+        ],
+        response_format={"type": "json_object"},
+        temperature=0,
+    )
+
+    return json.loads(response.choices[0].message.content)

backend/main.py

@@ -9,6 +9,7 @@ from backend.jobs import create_job, get_job, update_job
 from backend.parser import parse_file, row_to_text, SUPPORTED_EXTENSIONS
 from backend.embedder import embed_texts, BATCH_SIZE
 from backend.vectordb import ensure_collection, upsert_points, search, list_source_files, get_all_vectors
+from backend.intent_classifier import classify
 
 load_dotenv()
 
@@ -132,6 +133,17 @@ def embed_query(req: EmbedRequest):
     return {"vector": vectors[0]}
 
 
+class ClassifyRequest(BaseModel):
+    utterance: str
+
+
+@app.post("/classify")
+def classify_intent(req: ClassifyRequest):
+    if not req.utterance.strip():
+        raise HTTPException(status_code=400, detail="Utterance cannot be empty")
+    return classify(req.utterance)
+
+
 @app.get("/health")
 def health():
     return {"status": "ok"}

intents.yaml

@@ -0,0 +1,115 @@
+intents:
+  benevolence:
+    view_events:
+      utterances:
+        - "I want to see events coming up"
+    view_wishlists:
+      utterances:
+        - "I want to see wishlists"
+    buy_gifts:
+      utterances:
+        - "I want to buy gifts for my loved ones"
+
+  remembot:
+    remember:
+      utterances:
+        - "I want to remember something"
+    recall:
+      utterances:
+        - "I want to recall something"
+
+  moneyshare:
+    avoid_fee:
+      utterances:
+        - "I want to avoid a bank fee"
+    request_loan:
+      utterances:
+        - "I need a small loan"
+
+  foodshare:
+    request_food:
+      utterances:
+        - "I'm hungry"
+        - "I am hungry"
+    share_food:
+      utterances:
+        - "I have food to share"
+        - "I want to share some food"
+
+  billpayshare:
+    request_bill_help:
+      utterances:
+        - "I need help with a bill"
+
+  bloodshare:
+    request_blood:
+      utterances:
+        - "I need blood"
+    share_blood:
+      utterances:
+        - "I have blood to share"
+
+  math:
+    compute_expression:
+      utterances:
+        - "compute xplusonesquared"
+        - "compute xsquaredplusone"
+      aliases:
+        - "Compute x squared plus one"
+        - "Compute x plus one squared"
+
+  shopping_assistant:
+    add_item:
+      utterances:
+        - "Add an item to my shopping list"
+        - "I want to add items to my shopping list"
+    remove_item:
+      utterances:
+        - "Remove an item from my shopping list"
+    view_list:
+      utterances:
+        - "What's on my shopping list"
+        - "I want to see my shopping list"
+    edit_list:
+      utterances:
+        - "I want to change my shopping list"
+    mark_purchased:
+      utterances:
+        - "I've purchased some items on my shopping list"
+        - "I have purchased some items on my shopping list"
+
+  bot_store:
+    add_package:
+      utterances:
+        - "I want to buy a package"
+      aliases:
+        - "I want to add a package"
+    remove_package:
+      utterances:
+        - "I want to stop using a package"
+      aliases:
+        - "I want to remove a package"
+
+  taskmaster_ai:
+    add_task:
+      utterances:
+        - "I want to add a to do list item to my list"
+        - "Add a to do list item"
+        - "I want to add a to do list item"
+    view_tasks:
+      utterances:
+        - "I want to see my to do list"
+        - "Show to do list"
+        - "Show my to do list"
+    edit_tasks:
+      utterances:
+        - "I want to change my to do list"
+        - "I want to edit my to do list"
+    remove_task:
+      utterances:
+        - "I want to remove items from my to do list"
+
+  flow_planner:
+    create_flow_plan:
+      utterances:
+        - "Create a flow plan for tomorrow"

requirements.txt

@@ -7,6 +7,7 @@ qdrant-client==1.11.3
 pandas==2.2.3
 openpyxl==3.1.5
 python-dotenv==1.0.1
+pyyaml>=6.0
 httpx==0.27.2
 scikit-learn>=1.5.0
 plotly>=5.24.0