How the system behaves at runtime. Read the plain line, then open Go deeper for the mechanism and Internals for the code-level detail. Every trace is captured from the running code.
L1The system doesn't follow one fixed script. It decides what to do, calls tools to get data, changes its plan based on what it finds, and remembers the last answer.
| Property | Where it shows | Proof |
|---|---|---|
| Autonomous reasoning | Planner classifies intent → builds its own plan | plan_trace[0] names the plan |
| Tool / function calling | Agents call typed tools, never the store | trace logs every get_*() + row count |
| Data-dependent flow | Plan pruned / extended on intermediate results | Alerting runs even when unplanned |
| Memory / context | Follow-ups answered from cache | trace: reused cached insight |
list[str] every agent appends to — is the single artifact proving all four. It renders in the UI's "Agent trace" panel.A rule engine has no visible "thoughts" — so reasoning is emitted, not inferred. Each agent receives the shared trace: list[str] by reference and appends to it; the Planner owns the list and returns it as FinalResponse.plan_trace.
This is deliberately the same shape a real LLM tool-calling loop produces. Swapping the rule-based reason() for a Claude loop later changes the origin of the lines, not the contract — the UI and tests are unaffected.
L1Each message runs through one function: look for a follow-up → figure out intent → run the right agents → merge one answer.
Planner.handle()insert(0) trickSpending runs (step 6) and appends its tool-call lines before the Planner knows it succeeded. Only afterward does the Planner prepend the header:
trace.insert(0, ...) guarantees the human-readable narrative reads top-down (Planner → … then SpendingAnalysis → …) even though the spending lines were appended first.
The proactive line is appended only in the override case: if run_alert and "alert" not in plan. So a planned alert stays silent about the branch; an unplanned one announces itself.
L1"How can I improve my monthly savings?" → the system reads the month's spending, spots that food jumped, suggests cuts, and warns that entertainment is near its budget.
| Totals | food ₹12000 · entertainment ₹4500 · shopping ₹8000 · travel ₹3500 · groceries ₹6200 · utilities ₹3000 |
| Anomaly | food +25.0% (₹9600 → ₹12000) |
| Recs | food 15% → ₹1800/mo · shopping 15% → ₹1200/mo |
| Alert | warning — entertainment ₹4500 / ₹5000 (90%) |
Debits only. Spending sums type == "debit" per category; the salary credit is excluded — that's why the 14 May rows collapse to 6 spend categories.
Why 20% fixed, not z-score. Two months gives no distribution to estimate variance from. pct > 20.0 is deterministic and demo-stable. food: (12000−9600)/9600 = 25.0% → flagged.
Anomaly ranked first. Recommendation sorts candidates by (c not in anomaly_cats, -spend). False < True, so flagged categories sort ahead even if another category spent more. Essentials (groceries/utilities) are never in DISCRETIONARY, so never reduced.
The 15%. REDUCTION_BY_RISK = {conservative:10, balanced:15, aggressive:20}. Profile balanced → 15%. round(12000 × 0.15) = 1800. A different profile yields a different number on identical spending.
L1"Summarize my spending last month." only asked for a summary — but the system noticed the food anomaly and raised an alert on its own.
The whole behaviour is one expression evaluated after Spending returns:
Because plan == ['spending'], "alert" in plan is False — the alert fires purely on insight.anomalies being non-empty. The trace line is conditional on the override, so it appears here but not in Example 01 (where alert was planned).
L1"What about food specifically?" right after → the system answers instantly from what it already computed. No agents, no tool calls.
Detection. _is_followup() returns a category only if a prior insight is cached AND the query is referential — startswith(("what about","and ","just ","how about")) or len(split) ≤ 3 — AND a known category word appears.
Identity preserved. The returned FinalResponse.insights is the same object pulled from the cache (get_last_insight), not a copy — verifiable by is. The follow-up only slices it.
Honest nuance. The follow-up path uses a flat _FOLLOWUP_PCT = 15, not the risk-driven percentage the Recommendation agent uses. With a balanced profile both are 15%, so they agree here — but an aggressive profile would get 20% from the agent and 15% from a follow-up. A known, documented simplification, not a bug.
L1The words in your message decide which agents run.
| Intent | Candidate plan |
|---|---|
| IMPROVE_SAVINGS | spending → recommend → alert |
| SPENDING_SUMMARY | spending |
| BUDGET_STATUS | spending → alert |
| WHY_OVERSPENT | spending → alert → recommend |
| GENERAL_ADVICE | spending → recommend |
| GREETING / UNKNOWN | direct reply, no agents |
| Condition (after Spending) | Override |
|---|---|
insight.anomalies non-empty | run Alerting even if not planned |
| no discretionary category | Recommendation returns [] |
| follow-up + cached insight | bypass all agents |
Precedence is order, not score. classify_intent checks an ordered keyword list and returns on first hit. Greeting is matched by exact word / prefix first (so "hi there" ≠ a finance query). A query touching two groups routes to whichever appears earlier in the list — deterministic by construction.
Fallthrough. No keyword group hit but a finance term present → GENERAL_ADVICE; otherwise UNKNOWN (polite fallback, no agents).
Concurrency assumption. The store is single-flight-per-session — one in-flight turn per session_id. Fine for the demo; a real-LLM build adds a per-session lock so the in-memory dict can't race. The interface stays; swap the dict for Redis.