household-bot/docs/specs/HOUSEBOT-022-hybrid-purchase-parser.md

HOUSEBOT-022: Hybrid Purchase Parser

Summary

Implement a rules-first purchase parser with optional LLM fallback for ambiguous Telegram purchase messages.

Goals

• Parse common RU/EN purchase text with deterministic regex rules first.
• Call LLM fallback only when rules cannot safely resolve a single amount.
• Persist raw + parsed fields + confidence + parser mode.

Non-goals

• Receipt OCR.
• Complex multi-item itemization.

Scope

• In: parser core logic, fallback interface, bot ingestion integration, DB fields for parser output.
• Out: settlement posting and command UIs.

Interfaces and Contracts

• parsePurchaseMessage({ rawText }, { llmFallback? })
• Parser result fields:
  • amountMinor
  • currency
  • itemDescription
  • confidence
  • parserMode (rules | llm)
  • needsReview

Domain Rules

• Rules parser attempts single-amount extraction first.
• Missing currency defaults to GEL and marks needsReview=true.
• Ambiguous text (multiple amounts) triggers LLM fallback if configured.

Data Model Changes

• purchase_messages stores parsed fields:
  • parsed_amount_minor
  • parsed_currency
  • parsed_item_description
  • parser_mode
  • parser_confidence
  • needs_review
  • parser_error

Security and Privacy

• LLM fallback sends only minimal raw text needed for parsing.
• API key required for fallback path.

Observability

• processing_status and parser_error capture parse outcomes.

Edge Cases and Failure Modes

• Empty message text.
• Multiple numeric amounts.
• Invalid LLM output payload.
• Missing API key disables LLM fallback.

Test Plan

• Unit tests for rules parser and fallback behavior.
• Ingestion tests for topic filter remain valid.

Acceptance Criteria

• Rules parser handles common message patterns.
• LLM fallback is invoked only when rules are insufficient.
• Parsed result + confidence + parser mode persisted.

Rollout Plan

• Enable in dev group and monitor needs_review rate before stricter auto-accept rules.