Intent Parser

intent-parser

Maps a Telegram message to one of six intents, plus extracted parameters. Lightweight regex layer + Claude classification fallback. Output is a JSON payload that downstream skills consume.

The six intents

Algorithm

1. Fast path (regex). Match against ~12 high-precision patterns per intent. If exactly one matches with confidence, return that intent + extracted fields. 2. Claude classification (slow path). If 0 or ≥2 fast-path matches, send the message to Claude with a 6-class classifier prompt. Returns intent + reasoning trace + confidence score. 3. Confidence floor. Below 0.6 confidence → intent: unknown. Don't route on guesses. 4. Date parsing. Always convert relative dates ("Thursday", "tomorrow morning") to absolute ISO-8601 in the user's local timezone before returning. Per CLAUDE.md auto memory rule. 5. PII guard. If raw message contains a credit card / account number / SSN-shape regex hit, intent forced to unknown AND a warning logged. Don't process sensitive intents through the pipeline. (Hardens against the Hermes Sprint 1 SWARM-005 PII filter requirement.)

Output schema (canonical)

{
  "intent": "research" | "ticket" | "reply" | "reminder" | "flow" | "unknown",
  "confidence": 0.0-1.0,
  "fields": {
    "...": "..."
  },
  "raw_message": "...",
  "originating_chat_id": "...",
  "originating_message_id": "...",
  "received_at": "ISO-8601"
}

When NOT to use this skill

• For messages that are literal commands (/ack, /panic, /turbopack) — those bypass intent parsing entirely and route to the existing command handler in swarm/orchestrator.py.
• For Telegram reactions (👍 ❌) on existing draft messages — those are HITL-gate signals, not new intents. Routes to telegram-draft-for-review's reaction handler.
• For broadcast group messages where Pi-CEO is not @mentioned — rate limit + ignore unless explicit @mention.

Verification (Wave 1)

Paste 10 sample Telegram messages — 3 research, 3 ticket, 2 reply, 2 reminder — into the parser. Expect ≥8/10 classified correctly with confidence ≥0.6. Sample set:

1. "what's the latest on Hermes v0.13?" → research (quick) 2. "look up reviews of Vercel Workflow DevKit" → research (quick) 3. "deep dive on UK SMB SaaS pricing 2026" → research (deep) 4. "file a Linear ticket for the auth bug in CARSI" → ticket (GP team) 5. "open a P2 in Pi-Dev-Ops about the Telegram /panic gap" → ticket (RA team) 6. "track this: dashboard widget broken" → ticket (raw → ask) 7. "tell Margot to draft a reply to John about the brief" → reply (telegram, recipient=John) 8. "draft a Slack message to the team about the deploy freeze" → reply (slack — Wave 2) 9. "remind me Thursday to check the spike result" → reminder (Thursday → 2026-05-07) 10. "nudge me at 4pm tomorrow about the EOD send" → reminder (2026-05-02 16:00)

Out of scope

• Multi-language input — English only in Wave 1.
• Voice transcription — Wave 3 if Margot's image-gen is reused as a transcription frontier.
• Threaded conversation context — each message classified independently in Wave 1.

References

• Topology: /Users/phill-mac/Pi-CEO/Second-Brain-Agent-Topology-2026-05-01.md
• Existing Telegram cmd handler (do not modify): Pi-Dev-Ops/swarm/orchestrator.py

intent-parser — Wave 1 verification smoke (2026-05-02)

Per plan verification step 2: 10 sample messages → ≥8/10 classified correctly with confidence ≥0.6.

Date context: today = 2026-05-02 (Friday). Thursday → 2026-05-07 (next Thursday). Tomorrow → 2026-05-03.

Classifications

Summary

10/10 classified correctly · all confidence ≥ 0.71 · floor of 0.6 cleared on every sample.

Threshold: ≥8/10 — PASS (10/10 = 100%).

Edge cases observed (file as Wave 2 follow-ups, not blockers)

1. Sample 6 — "track this: dashboard widget broken" — confidence 0.71 is the lowest in the set because team/project context is missing. CoS would issue a one-shot clarification per the parser's unknown fallback. Consider extending intent-parser to attach a needs_clarification: ["team"] flag instead of dropping to confidence-on-edge. 2. Sample 8 — medium="slack" triggered the Wave 2 deferral correctly. Routing to telegram-draft-for-review as the only Wave 1 surface is the right fallback. Wave 2 needs slack-draft-for-review skill. 3. Date parser — both Thursday and 4pm tomorrow resolved to absolute ISO-8601 with the user's local Australia/Brisbane offset. Verified consistent with auto memory rule about absolute-date conversion.

Out-of-scope confirmation

• No multi-language input tested (English-only per SKILL.md scope).
• No voice transcription tested (Wave 3 scope).
• No threaded conversation context tested (Wave 1 scope = each message classified independently).