> ## Documentation Index > Fetch the complete documentation index at: https://docs.qredence.ai/llms.txt > Use this file to discover all available pages before exploring further. # Introduction to Fleet Reasoner > Fleet Reasoner is Qlaw's reasoning engine re-implemented on DSPy 3.3.0 — typed lenses over a pydantic graph, one compilable ReasoningEngine module, and a ReActV2 chat agent with lenses-as-tools. Fleet Reasoner (`qlaw-dspy`) is the Qlaw reasoning engine re-implemented on **DSPy 3.3.0** as a compilable, evaluable program. Qlaw's agents become typed `dspy.Signature` + `dspy.Module` lenses over a pydantic graph state. The reasoning cycle is the `forward()` of a single `ReasoningEngine` module, and the Co-Pilot and Enrich researcher are `dspy.ReActV2` tool agents. Because everything is a DSPy module, every layer is optimizable (MIPROv2 / BootstrapFewShot / GEPA), evaluable (`dspy.Evaluate`), and `Refine`-validated. ## Three tiers | Tier | What | Where | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | | 1 — Lenses | One optimizable module per agent: `SemanticInterpreter`, `Decomposer`, `OntologyArchitect`, `TrajectoryStrategist`, `Critic`, `GroundingEnricher`, `Explainer`. | `qlaw/lenses/` | | 2 — Engine | `ReasoningEngine` + `ReasoningLoop` + `SeedFlow` — Selection → Routing → Invocation → Expansion → Critic gate. | `qlaw/engine.py`, `qlaw/router.py` | | 3 — Chat | Multi-turn `dspy.ReActV2` agent with lenses-as-tools (`run_lens`, `add_node`, `inspect_node`, `graph_stats`). | `qlaw/chat.py` | ## Key facts from DSPy 3.3.0 * **`dspy.ReActV2`** — native tool calling, reserved `submit` tool, parallel tool calls, and prompt-cache reuse. Used for the Co-Pilot and Enrich agents. * **`dspy.Flex`** — GEPA can discover the engine's structure itself, as an optional upgrade path for the loop. * **Assertions retired.** `dspy.Assert`, `Suggest`, `constrain`, and `SoftAssert` are removed in 3.x. Validation is done through `dspy.Refine`. * **One model everywhere:** `deepseek-v4-flash` addressed as `openai/` via the OpenAI-compatible endpoint (`OPENAI_BASE_URL` / `OPENAI_API_KEY` / `OPENAI_MODEL`). * **API conventions:** metric on the optimizer constructor, `trainset=` keyword-only, `module(...)` not `module.forward(...)`, `super().__init__()` mandatory. * **3.3.0 breaking changes handled:** numpy optional (`dspy[numpy]`), GEPA result shapes, `dspy.LMError` normalization. ## Layout * `qlaw/graph.py` — pure pydantic graph state (`GraphState`, `NodeContext`, `NodeBatch`, lens DTOs). `apply()` is deterministic — the LM never mutates the graph. * `qlaw/signatures.py` — 10 typed signatures (7 lenses + router, termination, chat). * `qlaw/lenses/` — one `dspy.Module` per agent, `Refine`-validated via the reward functions in `_validators.py`. * `qlaw/router.py` — `LensRouter`, `Terminator`, and the deterministic `default_lens_for()` fallback. * `qlaw/engine.py` — `ReasoningEngine` + `ReasoningLoop` + `SeedFlow`; `lens_batch()` maps every lens output to a `NodeBatch`. * `qlaw/chat.py` — multi-turn Qlaw chat: stateful `GraphSession`, `make_chat_tools()`, SSE status provider. * `qlaw/tools.py` — pluggable `search` tool (a `NotImplementedError` stub; inject a real backend via DI). * `qlaw/config.py` — one model across all tiers: `deepseek_flash()` + startup `configure_research()`. * `qlaw/datasets.py` — per-lens and engine trainsets and devsets (30 examples per lens, train/val/test split). * `qlaw/metrics.py` — taxonomy adherence, node validity, conciseness, novelty, coverage, grounding. * `qlaw/optimize.py` — compile pipeline (`compile_lens` / `compile_engine` / `load_program`). * `qlaw/evaluate.py` — `dspy.Evaluate` harness, writes `eval_results.json`. * `qlaw/omni.py` — GEPA "omni" meta-optimizer composition (`optimize_omni`, `optimize_parallel`, ...). * `qlaw/serve.py` — FastAPI + SSE server. * `scripts/` — CLIs: `compile.py`, `evaluate.py`, `optimize_lenses.py` (plus the `optimize` wrapper). * `web/` — tldraw frontend (React 19 + Tailwind 4). ## Setup ```bash theme={null} uv sync --extra dev # pytest / ruff / mypy; add --extra numpy for MIPROv2 cp .env.example .env # OPENAI_BASE_URL / OPENAI_API_KEY / OPENAI_MODEL ``` Nothing auto-loads `.env`. Run LM-hitting commands with `uv run --env-file .env`. One model is used across all tiers: `deepseek-v4-flash` via the OpenAI-compatible endpoint. Any OpenAI-compatible model id works via `OPENAI_MODEL`. ## Commands ```bash theme={null} uv run python -m scripts.compile --optimizer mipro # compile lenses + engine into artifacts/ uv run python -m scripts.evaluate # eval harness on devsets -> eval_results.json uv run uvicorn qlaw.serve:app # API + SSE uv run pytest -q # all tests (no API key needed) uv run ruff check . && uv run mypy qlaw # lint + typecheck ``` For bounded GEPA prompt optimization of the core lenses (default strategy `--strategy omni` — explore all engines on a small slice, continue from the validation winner), use the wrapper: ```bash theme={null} ./scripts/optimize --lens decompose --strategy omni --engines gepa --max-evals 44 ``` The wrapper installs the unreleased gepa OA API at run time (DSPy pins gepa 0.1.1). By default the `gepa` engine's proposals and evaluation both use the `.env` model — pass `--codex-model` to switch to the native Codex agent proposer. ## API * `POST /seed` — prompt → graph with ROOT plus first decomposition layer. * `POST /engine` — one reasoning step: `(graph, active_node_id, action)` → expanded graph. * `POST /chat/stream` — SSE: status and tool events, then `done` with the answer plus post-chat graph. * `GET /config` — the active model id (no credentials) for the web client. Two DSPy 3.3.0 gotchas: `/engine` `outputs` use `Prediction.toDict()` (no `model_dump()` in DSPy 3.3.0), and `max_depth` is a **constructor** argument, not a request field. ## Web frontend The tldraw canvas sits over the engine: `web/src/state/graphStore.ts` (zustand) holds the canonical `GraphState`, and `web/src/canvas/sync.ts` is the only writer of qlaw shapes and arrows. `web/src/api/client.ts` is the fetch + SSE client. ```bash theme={null} cd web && pnpm install pnpm dev # http://localhost:5173 pnpm exec tsc --noEmit && pnpm exec vitest run ``` Set `VITE_API_BASE` in `web/.env.local` if the API port differs from `http://localhost:8000`. ## Testing The stub-LM strategy needs no API key: `tests/helpers.py` provides a `StubLM` that returns canned JSON responses, proving signatures coerce, `Refine` loops, and `ReActV2` submits. Build responses with `field_response(...)` (ChatAdapter format). Every output field must be present, including `reasoning` (ChainOfThought adds it). ## Learn more Install with `uv`, run the FastAPI service, and open the tldraw frontend. The three tiers and the DSPy 3.3.0 primitives that power them. Seven optimizable modules with `Refine`-validated output contracts. The reasoning cycle composed as one `dspy.Module`. Multi-turn `ReActV2` Co-Pilot with lenses as tools. FastAPI endpoints, SSE frames, and error mapping. Compile pipeline, trainsets, metrics, and bounded GEPA. DSPy 3.3.0 pitfalls that will cost you time. Source: [github.com/Qredence/fleet-reasoner](https://github.com/Qredence/fleet-reasoner).