Where to control prompts, rules, and data
Use this when you want variations of Advisor behavior without rewriting the engine.
Also linked from Redoc overview and /api/steps agent step (tweak paths).
1. How the AI thinks (system prompt & tools)
| What | File |
|---|---|
| Block A — diagnostic method, tone, hard rules | src/application/agent/block-a.ts |
| Caps — max queries / asks / turns | src/application/agent/constants.ts |
| Tool names + JSON schemas | src/application/agent/tools.ts |
| Block B/C assembly (tenant + playbooks into prompt) | src/application/agent/prompt.ts |
| Agent loop / tool dispatch | src/application/agent/loop.ts, dispatch.ts |
| Classifier prompt (problem → playbook) | src/application/classify-problem.ts |
Models per reasoning stage (.env)
OPENAI_MODEL=gpt-4o-mini
OPENAI_MODEL_CLASSIFY=gpt-4o-mini
OPENAI_MODEL_INVESTIGATE=gpt-4o
OPENAI_MODEL_VERIFY=gpt-4o-mini
Empty stage env falls back to OPENAI_MODEL.
2. What the AI knows (YAML knowledge pack)
| What | Path |
|---|---|
| Playbooks — symptoms, hypotheses, quant/qual probes, follow-up | diagnostics/playbooks/*.yaml |
Shared recommendations (rec_id, effort, impact) | diagnostics/recommendations/catalog.yaml |
| Data domain registry (Block B descriptions) | diagnostics/registry/data-domains.yaml |
Edit YAML → restart npm run dev (catalog loads at boot).
Playbook tips for variations
- Add symptoms / negative_symptoms to steer classification
- Reorder / reweight hypotheses (
prior) - Change quant_probes.question_template to change what
query_dataasks - Point recommendation_refs at ids in
catalog.yaml - Adjust follow_up.check_after_days for verification timing
3. Restaurant context & live data
| What | Where |
|---|---|
| Shop id | Auth subject.principalId |
| Tenant defaults (tz, dayparts) | .env → DEFAULT_TZ, DEFAULT_DAYPARTS |
| Tenant resolver | src/adapters/tenant/from-subject.tenant.ts |
| Live analytics | QueryCraft QUERYCRAFT_URL + bearer |
| Offline analytics | QUERY_ADAPTER=mock |
4. Adapter switches (.env)
AUTH_ADAPTER=mock|querycraft
QUERY_ADAPTER=mock|querycraft
LLM_ADAPTER=mock|openai
CATALOG_ADAPTER=yaml|memory
SESSION_STORE=memory|json
NOTIFY_ADAPTER=noop|webhook
Mental model
block-a.ts + tools.ts → how the AI thinks / what it can call
diagnostics/*.yaml → what problems & actions it knows
.env models + adapters → which brain & which data backend
tenant / QueryCraft → this restaurant's facts
Still stubbed
- Verification cron / batch (
verifySessionsStub) - Notify webhook delivery for follow-ups
- SSE streaming of tool events