Smart Choice Agent | Structured, Explainable Decisions

Turning vague intent into ranked options, constraint analysis, evidence records, and auditable traces

Independent Project | Product Design, Agent Orchestration & AI Coding Aug 2026 – Present Independent Project Locally runnable · Diet domain included 2026-08-30

Python FastAPI SQLAlchemy SQLite OpenAI-compatible

Agent AI Product Decision System Open Source

Visual material pendingSmart Choice Agent | Structured, Explainable DecisionsAgent · AI Product · Decision System

30-second summary

Smart Choice Agent turns one recommendation into an inspectable decision process: it understands intent and hard constraints, generates candidates, ranks them, explains the trade-offs, and records the trace for replay and expansion.

Three key numbers

9: Agent nodesIntent, understanding, clarification, candidates, planning, review, explanation, risk, and evaluation
7: Scoring dimensionsA deterministic ranking engine combines hard-constraint filtering with multi-dimensional scoring
2: Runtime modesLocal rule agents by default, with optional OpenAI-compatible model integration

Product flow

01
Enter a request
The user describes a diet or generic decision goal in natural language.
02
Understand constraints
The system extracts intent, hard constraints, preferences, and clarification needs.
03
Generate candidates
A domain plugin supplies options with sources and structured attributes.
04
Rank and review
The deterministic engine filters infeasible options, scores candidates, and checks risk.
05
Explain the choice
The explanation agent returns trade-offs, matched constraints, and alternatives.
06
Record the trace
Sessions, messages, Evidence, DecisionState, and Agent Runs are persisted.

Two key decisions

Split recommendations into a replayable decision path

Why this choice: Recommendation products need to show how candidates were created, how constraints affected ranking, and why one result is better suited.
Alternative not chosen: Let the model directly produce a natural-language recommendation
Tradeoff: The flow has more structure, but debugging, testing, and domain reuse become more stable.

Use deterministic ranking after agent reasoning

Why this choice: Agents are useful for understanding, clarification, and explanation, while final ranking needs reproducible rules and scores.
Alternative not chosen: Rely entirely on model judgment for candidate priority
Tradeoff: Ranking is constrained by the designed dimensions, but the result is easier to validate and regression-test.

One bad case

The explanation sounded right, but ranking was not reproducible

Symptom: For similar requests, each explanation seemed plausible, yet candidate order and constraint-hit reasons shifted across runs.
Diagnosis: If candidate selection, constraint handling, and ranking all stay inside model output, it is hard to locate whether the issue is understanding, candidates, or ranking.
Response: Moved hard constraints, scoring dimensions, candidate-selection strategies, and trace records out of free-form answers into deterministic engine and persistence structures.
Outcome: The diet recommendation loop is locally runnable; additional domain templates and external evidence retrieval remain in progress.

Result and validation status

available

The project is public and locally runnable. The diet-domain loop is complete, while the generic decision workbench, more domain templates, and evaluation datasets remain under iteration.

Evidence links

repoGitHub repository
available ↗
demoLocal web UI
available

Full retrospective

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.