Upload folder using huggingface_hub

app.py

@@ -11,6 +11,12 @@ Brain + Hands: Nemotron (on Modal) never calls an API or names a price; Python
 executes every call and scores every value. Every figure carries provenance.
 
 The gr.Blocks streaming version is retained at ``matchday/app.py`` as a fallback.
+
+Reference patterns (3-codebase study, see MATCHDAY_UNCONSTRAINED_PLAN.md):
+  - N1 gradio.Server custom-frontend architecture (Off-Brand badge):
+    https://huggingface.co/blog/introducing-gradio-server ("Why @app.api()…").
+  - N35 preflight gate (fail-fast on missing SerpApi key): Claude Code
+    utils/preflightChecks.tsx:1-60.
 """
 from __future__ import annotations
 

matchday/agent.py

@@ -12,6 +12,14 @@ class parses. Nemotron decides; Python executes (Brain + Hands).
 
 Requires the Modal app to be deployed (``modal deploy matchday/modal_spike.py``)
 so ``Server().generate.remote()`` resolves from any client.
+
+Reference patterns (3-codebase study, see MATCHDAY_UNCONSTRAINED_PLAN.md):
+  - N2/N4 streaming client — SSE parsing + reasoning/content split + Modal-Session-ID
+    sticky routing adapted from modal-labs/modal-examples nemotron_inference.py
+    (`_send_request_streaming` SSE parser ~L330-380; Modal-Session-ID ~L340-350).
+  - N29 error classification — hermes-agent error_classifier.py + Claude Code
+    services/api/errors.ts classifyAPIError (a cold-start timeout is re-tagged
+    MODEL_COLD_START here, not the generic NETWORK_TIMEOUT).
 """
 from __future__ import annotations
 

matchday/prompts.py

@@ -12,6 +12,15 @@ the persona + behavior + decision guidance — never the tool JSON schemas.
 Brain + Hands: Nemotron picks tools, reasons, explains. Python executes every
 tool and scores every price. Nemotron NEVER calls an API, names a price, or
 invents a flight number / weather reading — it calls a tool.
+
+Reference patterns (3-codebase study, see MATCHDAY_UNCONSTRAINED_PLAN.md):
+  - N22 behavior preset (no preamble; understand→act→verify; "first attempt
+    rarely correct"; disagree respectfully; don't stop partway): deepagents-main
+    /deepagents/graph.py:50-91 (BASE_AGENT_PROMPT).
+  - N28/K7 byte-stable prompt prefix (date-only timestamp; stable persona/context
+    tier at the prefix, volatile date tier at the suffix for KV-cache reuse):
+    deepagents system_prompt.py:329-337,353-369 + graph.py:584-600.
+  - A3 tool-use guidance: deepagents + Claude Code tool-description conventions.
 """
 from __future__ import annotations
 

matchday/trip_tool.py

@@ -22,6 +22,12 @@ to ``format_for_nemotron`` for compact serialisation.
 
 ``TripPackageResult`` is the structured return type, carrying the scored
 packages, a status enum, degradation notices, and provenance metadata.
+
+Reference patterns (3-codebase study, see MATCHDAY_UNCONSTRAINED_PLAN.md):
+  - Compact tool-result serialization (``format_for_nemotron``): hermes-agent-main
+    /agent/tool_dispatch_helpers.py:320-397 (`make_tool_result_message`).
+  - U1 parallel dispatch of read-only tools (asyncio.gather, partial-failure
+    tolerant): Claude Code/Tool.ts capability-predicate pattern (N27).
 """
 
 from __future__ import annotations