Spaces:
Sleeping
Download docs/ARCHITECTURE.md from xPushkal/snl-intern: direct link, hf CLI and curl.
- Browser
- Download file 4.45 kB
-
https://huggingface.co/spaces/xPushkal/snl-intern/resolve/main/docs/ARCHITECTURE.md
- Command line
-
hf download hf://spaces/xPushkal/snl-intern/docs/ARCHITECTURE.md
-
curl -L -o ARCHITECTURE.md https://huggingface.co/spaces/xPushkal/snl-intern/resolve/main/docs/ARCHITECTURE.md
Architecture
Request lifecycle
POST /chat (stateless: full history every call)
β
βΌ
FastAPI layer (app/main.py)
β’ lenient request parsing (unknown fields ignored β never a 422)
β’ run pipeline in a worker thread under a whole-turn timeout
β’ RequestValidationError + Exception handlers β schema-valid 200
βΌ
Turn orchestrator (app/agent/turn.py) β defense-in-depth try/except
βΌ
LangGraph: understand β act β respond (app/agent/graph.py)
β
ββ understand (app/agent/understand.py)
β deterministic keyword router by default (vagueness-aware) β
β {in_scope, intent, search_query, hard, soft, compare_names,
β remove_names, add_query, clarifying_question, user_done}
β optional (ENABLE_LLM): one Groq JSON call over the WHOLE history,
β with the deterministic router as the fallback on any failure
β
ββ act (app/agent/dispatch.py) β deterministic
β refuse | clarify(β€1) | recommend | refine | compare
β reconstructs prior shortlist from the last assistant reply
β
ββ respond (app/agent/render.py + app/responder.py)
templated reply + anti-hallucination/schema gate
βΌ
Retrieval (app/retrieval/*) β rank the FULL catalog
HARD filters (never relaxed) β RRF(BM25, dense) β SOFT boosts β top-10
[MMR / LLM-rerank optional, OFF by default]
Why these choices
Stateless state lives in the reply. The wire schema is fixed
(reply, recommendations, end_of_conversation), and the grader replays the full
history each call. So the numbered list embedded in the reply text is the only
cross-turn state carrier. Every recommendation line prints its catalog URL;
render.parse_prior_shortlist reads those URLs back out of the most recent assistant
message to reconstruct the prior shortlist (URLs are unambiguous keys, unlike names
with parentheses). This is what makes "remove the second one" work without a database.
β€2 LLM calls per turn. One understand call routes + extracts; replies are
templated; only compare (and the optional reranker) make a second call. Groq is
sub-second, so a turn finishes well inside the 30s cap with timeout headroom.
Rank the whole catalog. With ~370 recommendable items, there is no need for an ANN
index or a candidate cap β we score every document with a brute-force matrix multiply
(dense, embeddings @ query) plus BM25, fuse with Reciprocal Rank Fusion, then add
soft boosts. Exact, instant, and one fewer dependency (no FAISS).
Hard vs soft. understand tags each constraint. Hard constraints (max_duration,
required languages, required test_types) are applied as filters before scoring
and are never relaxed β if fewer than 10 survive, we return fewer than 10. Soft
preferences (job_levels, preferred types) only add a small ranking boost and can
never exclude an item, which protects recall.
Reliability / fallback matrix
| Failure | Handling | Result |
|---|---|---|
| Malformed request body | lenient schema + RequestValidationError handler |
200, safe reply |
understand LLM error/timeout |
1 stricter retry β deterministic router | valid route |
| Deterministic router on vague input | vagueness check β clarify (not blind recommend) | empty recs, clarify |
| Rerank disabled/fails | deterministic fusion order | top-10 |
| Compare LLM fails | deterministic field-by-field template | grounded compare |
| Off-catalog / duplicate item | responder canonicalization gate |
dropped |
| Whole turn exceeds budget | asyncio.wait_for in main.py |
200, safe reply |
test_type derivation
The catalog has no test_type; its keys[] are SHL category names (trace-confirmed:
Personality & Behavior β P). app/data/test_type_map.py maps each category to its
letter and exposes all codes plus a single primary. 338/377 records have one category;
for the 39 multi-category records the catalog lists categories alphabetically (so order
is not meaningful) and we apply a documented priority K>A>P>B>C>S>E>D.
Scope
Verified empirically: all 10 sample-trace gold shortlists are 100% present in the
provided catalog, so it is the recommendable universe (no website scraping). The 7
pre-packaged Job Solutions (all literally "β¦ Solution") are tagged is_individual=False
and excluded from recommendations, but remain in the catalog for validation.