# so1vanlaso1/last_pipeline architecture

> Architecture diagram of the GitHub repository so1vanlaso1/last_pipeline, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/so1vanlaso1/last_pipeline
- Repository: https://github.com/so1vanlaso1/last_pipeline

## Overview

1. **Overall shape**
   - This repo is a competition submission for EXACT 2026 with **one serving entrypoint** and two distinct QA pipelines behind it.
   - The runtime architecture is centered on `serve/`, which exposes `POST /predict` and coordinates model servers plus deterministic tooling.

2. **Primary serving boundary: `serve/`**
   - `serve/gateway/app.py` is the public HTTP layer.
   - It accepts a request shaped as `{query_id, type, query, premises, options}` and always returns a **list** of answers.
   - The gateway is the orchestration boundary: it does not solve logic/physics itself; it delegates to adapters and model clients.

3. **Type 1 path: logic generate→judge**
   - Logic requests go through `serve/gateway/logic_adapter.py`.
   - The flow is: **two generators run concurrently** → a **judge** model reviews them → the gateway emits the final answer, explanation, and premises-used indices.
   - The default resident models are Qwen3-4B and Qwen3-4B-Instruct as generators, with Gemma-4-E4B-it as judge.

4. **Type 2 path: physics solver-first**
   - Physics requests go through `serve/gateway/physics_adapter.py`.
   - The flow is: **deterministic physics solver first** → optional generator stage → **judge** decides the final answer/unit.
   - This path blends symbolic/analytic solving with LLM arbitration rather than relying on the LLM alone.

5. **Model-serving layer**
   - `serve/gateway/vllm_client.py` talks to **vLLM servers** using an OpenAI-compatible API.
   - `serve/run_server.sh` and `setup.sh` launch **one vLLM server per resident model**, then the gateway on top.
   - `GET /v1/models` aggregates the resident model list across those servers, which is part of the compliance story for the submission.

6. **Residency and GPU budget control**
   - `serve/gateway/residency.py` manages the sleep/wake behavior that swaps the judge in and out of GPU memory.
   - The default design is a **swap-based residency scheme**: generators stay resident together, and the judge is offloaded/slept when not in use.
   - `serve/gateway/config.py` and `serve/logic_config.yaml` define the line-up, model roles, quantization, and budget checks.

7. **Shared model lineup config**
   - `serve/logic_config.yaml` is the canonical deployment config for both logic and physics serving.
   - It defines model roles (`generator`, `judge`), per-model parameters, quantization, thinking mode, and the total residency budget.
   - This config is what determines which models are actually downloaded and launched on the GPU box.

8. **Physics pipeline as a standalone subsystem**
   - `physic_pipeline/src/exact_fama/` is the full research-grade physics stack.
   - Key internal layers:
     - `router.py` routes tasks.
     - `physics/` contains domain solvers, formula registry, extraction, and verification.
     - `logic/` contains symbolic/FOL solving support used when physics questions include logic-like structure.
     - `llm/` contains parser and fallback/rewrite components.
     - `pipeline.py` and `api.py` are the orchestration surfaces.
   - This subsystem is deterministic-first and can run with or without LLM help.

9. **Logic pipeline as a standalone subsystem**
   - `logic_pipeline/src/` is a separate generate→judge experimentation pipeline for type1-style tasks.
   - It contains the prompt templates, cascade orchestration, model chat wrapper, scoring, and dataset loading.
   - This pipeline can be run independently for offline evaluation and development, but the serving gateway imports the same conceptual behavior.

10. **Data, evaluation, and experiment tooling**
   - `physic_pipeline/data/` and `logic_pipeline/Logic_Based_Educational_Queries.json` hold datasets and benchmark material.
   - Both pipelines include scripts for running inference, evaluating outputs, filtering errors, and generating train/eval splits.
   - The repo is therefore not just a server; it is also an experimentation and benchmarking workspace.

11. **Testing and no-GPU stubs**
   - `serve/tests/` provides wiring tests that use a stub backend instead of GPU models.
   - `logic_pipeline/tests/` and `physic_pipeline/tests/` validate solver behavior, router logic, API schema, and regression cases.
   - These tests protect the boundaries between deterministic solvers, model adapters, and the HTTP layer.

12. **Operational/deployment concerns**
   - The serving stack is designed to be launched on a fresh GPU box with a single command and optionally exposed through a Cloudflare tunnel.
   - Runtime behavior is controlled by environment variables for model choice, swap behavior, quantization, and ports.
   - The gateway is the only public interface; the model servers are internal implementation detail.

13. **Important architectural takeaway**
   - The repo is best drawn as **three layers**:
     1. **Public gateway/API**
     2. **Two task pipelines**: logic and physics
     3. **Resident vLLM model servers + deterministic solvers**
   - The data flow is request → routing by `type` → pipeline-specific orchestration → model/solver execution → normalized response.

Main entry points: [`logic_pipeline/src/cascade.py`](https://github.com/so1vanlaso1/last_pipeline/blob/main/logic_pipeline/src/cascade.py) (Cascade), [`serve/gateway/app.py`](https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/gateway/app.py) (Gateway API), [`physic_pipeline/src/exact_fama/router.py`](https://github.com/so1vanlaso1/last_pipeline/blob/main/physic_pipeline/src/exact_fama/router.py) (Router), [`serve/gateway/logic_adapter.py`](https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/gateway/logic_adapter.py) (Logic adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serve["Serving stack"]
  node_serve_app["Gateway API<br/>HTTP entrypoint<br/>[app.py]"]
  node_serve_logic_adapter["Logic adapter<br/>gen-judge flow<br/>[logic_adapter.py]"]
  node_serve_physics_adapter["Physics adapter<br/>solver-first flow<br/>[physics_adapter.py]"]
  node_serve_residency["Residency<br/>GPU swap control<br/>[residency.py]"]
  node_serve_vllm["vLLM client<br/>model RPC<br/>[vllm_client.py]"]
  node_serve_config["Serve config<br/>runtime config<br/>[config.py]"]
  node_serve_logic_yaml["Model lineup<br/>yaml manifest<br/>[logic_config.yaml]"]
  node_serve_server["Launch scripts<br/>deployment scripts<br/>[run_server.sh]"]
end

subgraph group_logic["Logic pipeline"]
  node_logic_cascade["Cascade<br/>orchestration<br/>[cascade.py]"]
  node_logic_chat["Chat model<br/>model wrapper<br/>[chat_model.py]"]
  node_logic_prompts["Prompts<br/>prompt templates<br/>[prompts.py]"]
  node_logic_data["Data loader<br/>dataset I/O<br/>[data_load.py]"]
  node_logic_score["Scoring<br/>evaluation<br/>[score.py]"]
end

subgraph group_physics["Physics pipeline"]
  node_physics_api["Pipeline API<br/>orchestration surface<br/>[api.py]"]
  node_physics_router["Router<br/>[router.py]"]
  node_physics_solver["Physics solver<br/>domain solving<br/>[solver.py]"]
  node_physics_registry["Solver registry<br/>domain registry<br/>[registry.py]"]
  node_physics_logic["Logic solver<br/>symbolic solver<br/>[solver.py]"]
  node_physics_llm["LLM helpers<br/>parse/rewrite"]
  node_physics_verify["Verification<br/>validation<br/>[verification.py]"]
end

subgraph group_ops["Ops and data"]
  node_physics_data["Datasets<br/>benchmarks"]
  node_logic_tests["Logic tests<br/>regression<br/>[test_smoke.py]"]
  node_serve_tests["Serve tests<br/>stubbed wiring"]
  node_physics_tests["Physics tests<br/>regression<br/>[test_router.py]"]
end

node_serve_app -->|"type=1"| node_serve_logic_adapter
node_serve_app -->|"type=2"| node_serve_physics_adapter
node_serve_app -.->|"loads config"| node_serve_config
node_serve_app -->|"manages GPU"| node_serve_residency
node_serve_logic_adapter -->|"generators"| node_serve_vllm
node_serve_logic_adapter -->|"wake/sleep"| node_serve_residency
node_serve_physics_adapter -->|"judge/gen"| node_serve_vllm
node_serve_physics_adapter -->|"swap judge"| node_serve_residency
node_serve_vllm -.->|"resident list"| node_serve_logic_yaml
node_serve_logic_yaml -.->|"budgeting"| node_serve_config
node_serve_server -->|"starts servers"| node_serve_vllm
node_logic_cascade -->|"LLM calls"| node_logic_chat
node_logic_cascade -->|"prompting"| node_logic_prompts
node_logic_cascade -->|"examples"| node_logic_data
node_logic_cascade -->|"rank/filter"| node_logic_score
node_physics_api -->|"orchestrates"| node_physics_router
node_physics_router -->|"solve"| node_physics_solver
node_physics_solver -->|"domains"| node_physics_registry
node_physics_router -->|"symbolic path"| node_physics_logic
node_physics_router -->|"fallback parse"| node_physics_llm
node_physics_api -->|"normalize"| node_physics_verify
node_physics_api -.->|"benchmarks"| node_physics_data
node_serve_physics_adapter -.->|"parity"| node_physics_api
node_serve_logic_adapter -.->|"parity"| node_logic_cascade
node_serve_tests -.->|"wires"| node_serve_app
node_logic_tests -.->|"regresses"| node_logic_cascade
node_physics_tests -.->|"regresses"| node_physics_router

click node_serve_app "https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/gateway/app.py"
click node_serve_logic_adapter "https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/gateway/logic_adapter.py"
click node_serve_physics_adapter "https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/gateway/physics_adapter.py"
click node_serve_residency "https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/gateway/residency.py"
click node_serve_vllm "https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/gateway/vllm_client.py"
click node_serve_config "https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/gateway/config.py"
click node_serve_logic_yaml "https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/logic_config.yaml"
click node_serve_server "https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/run_server.sh"
click node_logic_cascade "https://github.com/so1vanlaso1/last_pipeline/blob/main/logic_pipeline/src/cascade.py"
click node_logic_chat "https://github.com/so1vanlaso1/last_pipeline/blob/main/logic_pipeline/src/chat_model.py"
click node_logic_prompts "https://github.com/so1vanlaso1/last_pipeline/blob/main/logic_pipeline/src/prompts.py"
click node_logic_data "https://github.com/so1vanlaso1/last_pipeline/blob/main/logic_pipeline/src/data_load.py"
click node_logic_score "https://github.com/so1vanlaso1/last_pipeline/blob/main/logic_pipeline/src/score.py"
click node_physics_api "https://github.com/so1vanlaso1/last_pipeline/blob/main/physic_pipeline/src/exact_fama/api.py"
click node_physics_router "https://github.com/so1vanlaso1/last_pipeline/blob/main/physic_pipeline/src/exact_fama/router.py"
click node_physics_solver "https://github.com/so1vanlaso1/last_pipeline/blob/main/physic_pipeline/src/exact_fama/physics/solver.py"
click node_physics_registry "https://github.com/so1vanlaso1/last_pipeline/blob/main/physic_pipeline/src/exact_fama/physics/physics_solvers/registry.py"
click node_physics_logic "https://github.com/so1vanlaso1/last_pipeline/blob/main/physic_pipeline/src/exact_fama/logic/solver.py"
click node_physics_llm "https://github.com/so1vanlaso1/last_pipeline/blob/main/physic_pipeline/src/exact_fama/llm/structured_parser.py"
click node_physics_verify "https://github.com/so1vanlaso1/last_pipeline/blob/main/physic_pipeline/src/exact_fama/verification.py"
click node_physics_data "https://github.com/so1vanlaso1/last_pipeline/tree/main/physic_pipeline/data/external_dataset"
click node_logic_tests "https://github.com/so1vanlaso1/last_pipeline/blob/main/logic_pipeline/tests/test_smoke.py"
click node_serve_tests "https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/tests/test_gateway_stub.py"
click node_physics_tests "https://github.com/so1vanlaso1/last_pipeline/blob/main/physic_pipeline/tests/test_router.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_serve_app,node_serve_logic_adapter,node_serve_physics_adapter,node_serve_residency,node_serve_vllm,node_serve_config,node_serve_logic_yaml,node_serve_server toneBlue
class node_logic_cascade,node_logic_chat,node_logic_prompts,node_logic_data,node_logic_score toneAmber
class node_physics_api,node_physics_router,node_physics_solver,node_physics_registry,node_physics_logic,node_physics_llm,node_physics_verify toneMint
class node_physics_data,node_logic_tests,node_serve_tests,node_physics_tests toneRose
```

## Components

### Serving stack

Public gateway, adapters, residency control, and model-client layer for competition serving.

- [Gateway API](https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/gateway/app.py): HTTP entrypoint · Public POST /predict boundary that normalizes requests and returns a list of answers. · `serve/gateway/app.py`
- [Logic adapter](https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/gateway/logic_adapter.py): gen-judge flow · Type-1 request path: two generators run, then a judge produces the final answer. · `serve/gateway/logic_adapter.py`
- [Physics adapter](https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/gateway/physics_adapter.py): solver-first flow · Type-2 request path: deterministic solver first, optional generation, then judge arbitration. · `serve/gateway/physics_adapter.py`
- [Residency](https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/gateway/residency.py): GPU swap control · Controls judge sleep/wake behavior and resident model placement under the GPU budget. · `serve/gateway/residency.py`
- [vLLM client](https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/gateway/vllm_client.py): model RPC · Calls resident model servers through an OpenAI-compatible API and aggregates resident models. · `serve/gateway/vllm_client.py`
- [Serve config](https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/gateway/config.py): runtime config · Runtime settings for roles, ports, quantization, and budget checks. · `serve/gateway/config.py`
- [Model lineup](https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/logic_config.yaml): yaml manifest · Canonical resident model lineup, roles, and residency budget for serving. · `serve/logic_config.yaml`
- [Launch scripts](https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/run_server.sh): deployment scripts · Shell entrypoints that start one vLLM server per resident model and then the gateway. · `serve/run_server.sh`

### Logic pipeline

Standalone generate-judge pipeline for type-1 tasks and offline experimentation.

- [Cascade](https://github.com/so1vanlaso1/last_pipeline/blob/main/logic_pipeline/src/cascade.py): orchestration · Coordinates generation, judging, and answer assembly for logic experiments. · `logic_pipeline/src/cascade.py`
- [Chat model](https://github.com/so1vanlaso1/last_pipeline/blob/main/logic_pipeline/src/chat_model.py): model wrapper · Thin model invocation layer used by the logic pipeline. · `logic_pipeline/src/chat_model.py`
- [Prompts](https://github.com/so1vanlaso1/last_pipeline/blob/main/logic_pipeline/src/prompts.py): prompt templates · Task prompts and judge/generator instructions for logic workflows. · `logic_pipeline/src/prompts.py`
- [Data loader](https://github.com/so1vanlaso1/last_pipeline/blob/main/logic_pipeline/src/data_load.py): dataset I/O · Loads benchmark data and prepares examples for logic evaluation. · `logic_pipeline/src/data_load.py`
- [Scoring](https://github.com/so1vanlaso1/last_pipeline/blob/main/logic_pipeline/src/score.py): evaluation · Scores, filters, and ranks candidate answers in offline logic runs. · `logic_pipeline/src/score.py`

### Physics pipeline

Deterministic-first physics subsystem with routing, solvers, parsing, and orchestration.

- [Pipeline API](https://github.com/so1vanlaso1/last_pipeline/blob/main/physic_pipeline/src/exact_fama/api.py): orchestration surface · Top-level API surface for physics inference and composition. · `physic_pipeline/src/exact_fama/api.py`
- [Router](https://github.com/so1vanlaso1/last_pipeline/blob/main/physic_pipeline/src/exact_fama/router.py): task router · Dispatches physics questions into solver, parser, and logic-assisted paths. · `physic_pipeline/src/exact_fama/router.py`
- [Physics solver](https://github.com/so1vanlaso1/last_pipeline/blob/main/physic_pipeline/src/exact_fama/physics/solver.py): domain solving · Deterministic physics solving core that uses registered domain solvers. · `physic_pipeline/src/exact_fama/physics/solver.py`
- [Solver registry](https://github.com/so1vanlaso1/last_pipeline/blob/main/physic_pipeline/src/exact_fama/physics/physics_solvers/registry.py): domain registry · Registers domain-specific physics solvers and formula resources. · `physic_pipeline/src/exact_fama/physics/physics_solvers/registry.py`
- [Logic solver](https://github.com/so1vanlaso1/last_pipeline/blob/main/physic_pipeline/src/exact_fama/logic/solver.py): symbolic solver · Handles logic-like structure inside physics problems with symbolic and FOL support. · `physic_pipeline/src/exact_fama/logic/solver.py`
- [LLM helpers](https://github.com/so1vanlaso1/last_pipeline/blob/main/physic_pipeline/src/exact_fama/llm/structured_parser.py): parse/rewrite · Parser, rewrite, and fallback helpers for LLM-assisted physics processing. · `physic_pipeline/src/exact_fama/llm/structured_parser.py`
- [Verification](https://github.com/so1vanlaso1/last_pipeline/blob/main/physic_pipeline/src/exact_fama/verification.py): validation · Normalizes and verifies answers, units, and extracted physics results. · `physic_pipeline/src/exact_fama/verification.py`

### Ops and data

Deployment scripts, configs, datasets, and tests supporting serving and evaluation.

- [Datasets](https://github.com/so1vanlaso1/last_pipeline/tree/main/physic_pipeline/data/external_dataset): benchmarks · Bundled physics datasets and benchmark material used for training and evaluation. · `physic_pipeline/data/external_dataset`
- [Logic tests](https://github.com/so1vanlaso1/last_pipeline/blob/main/logic_pipeline/tests/test_smoke.py): regression · Wiring and smoke tests that validate the logic pipeline. · `logic_pipeline/tests/test_smoke.py`
- [Serve tests](https://github.com/so1vanlaso1/last_pipeline/blob/main/serve/tests/test_gateway_stub.py): stubbed wiring · Gateway tests that use a stub backend instead of GPU models. · `serve/tests/test_gateway_stub.py`
- [Physics tests](https://github.com/so1vanlaso1/last_pipeline/blob/main/physic_pipeline/tests/test_router.py): regression · API, router, solver, and upgrade tests for the physics subsystem. · `physic_pipeline/tests/test_router.py`

## Connections

- Gateway API → Logic adapter: type=1 · Dispatches logic requests to the generate-judge branch.
- Gateway API → Physics adapter: type=2 · Dispatches physics requests to the solver-first branch.
- Gateway API → Serve config: loads config · Reads runtime settings and model roles.
- Gateway API → Residency: manages GPU · Uses residency control to keep the judge swapped appropriately.
- Logic adapter → vLLM client: generators · Invokes resident generator models via vLLM.
- Logic adapter → Residency: wake/sleep · Brings the judge into GPU memory when needed.
- Physics adapter → vLLM client: judge/gen · Uses resident models for optional generation and final judging.
- Physics adapter → Residency: swap judge · Controls judge residency around physics inference.
- vLLM client → Model lineup: resident list · Reads the canonical model lineup and roles.
- Model lineup → Serve config: budgeting · Defines model roles and residency budget constraints.
- Launch scripts → vLLM client: starts servers · Launches one vLLM server per resident model before the gateway.
- Cascade → Chat model: LLM calls · Wraps model chat for generation and judging.
- Cascade → Prompts: prompting · Uses task-specific prompts for each stage.
- Cascade → Data loader: examples · Consumes loaded benchmark items and splits.
- Cascade → Scoring: rank/filter · Scores candidates and produces final selection.
- Pipeline API → Router: orchestrates · Top-level orchestration for physics inference.
- Router → Physics solver: solve · Sends solvable tasks to deterministic physics solvers.
- Physics solver → Solver registry: domains · Looks up domain-specific formulas and solver modules.
- Router → Logic solver: symbolic path · Routes logic-like physics structure to symbolic solving.
- Router → LLM helpers: fallback parse · Uses parsing and rewrite helpers when LLM assistance is needed.
- Pipeline API → Verification: normalize · Checks and normalizes final answers and units.
- Pipeline API → Datasets: benchmarks · Evaluates against bundled datasets and external packs.
- Physics adapter → Pipeline API: parity · Serving path mirrors the standalone physics pipeline behavior.
- Logic adapter → Cascade: parity · Serving path mirrors the standalone logic pipeline behavior.
- Serve tests → Gateway API: wires · Validates the HTTP gateway with stubbed backends.
- Logic tests → Cascade: regresses · Checks the logic pipeline behavior and smoke paths.
- Physics tests → Router: regresses · Checks router, solver, API schema, and solver upgrades.