Pipeline steps (test each one)

Every finished step has its own HTTP surface. You can test it alone with mock adapters before running a full session.

Live map:

GET /api/steps

Full schemas & examples: Redoc.

Offline mock env

AUTH_ADAPTER=mock
CATALOG_ADAPTER=yaml
LLM_ADAPTER=mock
QUERY_ADAPTER=mock
SESSION_STORE=memory

Mock login token looks like mock.30 (restaurant id 30).

---

1. Auth — who is the restaurant?

Does: Issue / validate a bearer token. subject.principalId = FOSA shop id used for data scope.

Method	Path	Auth
POST	/api/auth/login	no
GET	/api/auth/me	Bearer

TOKEN=$(curl -s -X POST http://localhost:3040/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"a@b.com","password":"x"}' | jq -r '.data.token')

curl -s http://localhost:3040/api/auth/me \
  -H "Authorization: Bearer $TOKEN" | jq '.data.subject'

Expect: principalId, tenantId, resolved tenant (name, channels, domains, …).

Live: AUTH_ADAPTER=querycraft → QueryCraft Auth Gateway (AUTH_LOGIN_VALIDATE.md).

---

2. Catalog — diagnostic knowledge pack

Does: Load playbooks + recommendations from diagnostics/**. No LLM. No POS data.

Method	Path	Auth
GET	/api/catalog/playbooks	no
GET	/api/catalog/playbooks/{id}	no
GET	/api/catalog/recommendations/{recId}	no

curl -s http://localhost:3040/api/catalog/playbooks | jq '.data.count'
curl -s http://localhost:3040/api/catalog/playbooks/demand-decline \
  | jq '.data.playbook.hypotheses | length'
curl -s http://localhost:3040/api/catalog/recommendations/lapsed-customer-winback | jq .

Expect: summaries with symptoms / negative_symptoms; full playbook includes hypotheses & probes.

---

3. Classify — pick the playbook

Does: Owner problem text → 1–2 playbook_ids.

Method	Path	Auth
POST	/api/classify	Bearer

curl -s -X POST http://localhost:3040/api/classify \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"problem_statement":"sales are down across the board"}' | jq .

Expect:

{
  "success": true,
  "data": {
    "playbook_ids": ["demand-decline"],
    "source": "llm",
    "adapters": { "catalog": "yaml", "llm": "mock" }
  }
}

source may be llm | symptom_fallback | empty.

---

4. Query — ask the numbers

Does: One analytics question (agent uses the same port via query_data).

Method	Path	Auth
POST	/api/query/ask	Bearer

curl -s -X POST http://localhost:3040/api/query/ask \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"question":"Weekly orders last 8 weeks vs prior 8 weeks","probe_id":"adhoc"}' \
  | jq '.data.result | {kind, row_count, columns}'

Expect: result.kind = data | clarification | empty | unknown.
Mock returns a tiny table; live QueryCraft returns SQL + rows.

---

5. Agent + advisor sessions

Does: Classify → investigate tool loop → concluded or awaiting_manager.

See Sessions for response fields and resume.
See Live test run for a real QueryCraft + OpenAI walkthrough.

Method	Path	Auth
POST	/api/advisor/sessions	Bearer
GET	/api/advisor/sessions/{id}	Bearer
POST	/api/advisor/sessions/{id}/answers	Bearer

curl -s -X POST http://localhost:3040/api/advisor/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"problem_statement":"sales are down across the board"}' | jq .

With mock LLM, start often returns status: concluded immediately (scripted tools).
With OpenAI, you may get awaiting_manager — then POST answers.

Agent tools: query_data, ask_manager, update_hypothesis, select_playbook, conclude_diagnosis.

Tweak prompts / playbooks: Tweaking.

---

Folder cheat sheet

Piece	Role
diagnostics/playbooks	Investigation scripts
diagnostics/recommendations	Shared actions
Catalog API	Loads YAML
Classify API	Chooses playbook
Query API	One data ask
Advisor sessions	Full diagnose loop