Project Overview
Smart Choice Agent is a Python multi-agent system for structured recommendations and explainable choices. It returns more than a final answer: user intent, hard constraints, candidates, trade-offs, risk review, and agent runs are organized into a traceable decision path.
Pain Points & Opportunities
A common issue in AI recommendation products is that the answer may look plausible while the process cannot be inspected. When user constraints are vague, conflicting, or numerous, the system needs visible filtering logic, scoring evidence, and trace records to be debuggable and repeatable.
Goals & Metrics
The goal is an extensible decision framework that can run the full flow through local rule agents without an API key, while also supporting OpenAI-compatible model integration. Diet recommendation is the first concrete domain, with room to expand into travel, career, learning-path, and shopping decisions.
User Research
The project breaks down the evidence chain behind trustworthy recommendations. Agents handle language understanding, clarification, and explanation; the deterministic engine handles hard-constraint filtering, seven-dimensional scoring, ranking, and candidate selection; persistence records DecisionState, Evidence, and Agent Run data instead of leaving the process opaque.
Solution Design
The architecture flows from FastAPI / Static Web to DietOrchestrator, specialized agents, the deterministic decision engine, the diet-domain plugin, and SQLAlchemy / SQLite persistence. The diet domain supports single-meal recommendation, multi-turn clarification, refresh suggestions, three-meal planning, personal meals, and public meals. Candidate selection can be ranked, random, weighted, or least-recent.
Execution Plan
I used Python, FastAPI, SQLAlchemy, and SQLite to implement backend services, data models, repositories, agent protocols, the orchestration state machine, and a local web UI. LLM mode is disabled by default, so rule agents can run independently. If model calls fail, intent and explanation agents fall back to local rule behavior while the deterministic decision engine continues.
Results Review
The repository now includes a runnable service, initialization scripts, test commands, a local web UI, diet-domain data, and a generic demo workbench. It validates the local loop from user input to candidate ranking, explanation, feedback, and trace persistence. External evidence retrieval, additional domain templates, and richer evaluation datasets remain future work.
Iteration Reflection
The core product point is not making recommendations feel more conversational; it is making the decision process reviewable. For AI decision products, stable, explainable, replayable behavior matters more than one clever-looking answer. The next iteration should keep expanding reusable domains and regression evaluation.