> ## 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.

# Fleet Reasoner quickstart

> Install Fleet Reasoner with uv, configure the OpenAI-compatible endpoint, run the FastAPI + SSE server, and open the tldraw web frontend against your first Qlaw graph.

Get the Qlaw reasoning engine running locally in a few minutes.

## Prerequisites

* Python 3.10 or newer.
* [`uv`](https://docs.astral.sh/uv/) for dependency management.
* Node.js and `pnpm` for the tldraw web frontend.
* An OpenAI-compatible Chat Completions endpoint and API key.

## 1. Install

```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 any LM-hitting command with `uv run --env-file .env`.

Fleet Reasoner uses one model across all tiers: `deepseek-v4-flash` by default, addressed as `openai/<model>` through the OpenAI-compatible endpoint. Any OpenAI-compatible model id works via `OPENAI_MODEL`.

## 2. Verify without an API key

Stub-LM tests exercise every signature, `Refine` loop, and ReActV2 submission without needing credentials:

```bash theme={null}
uv run pytest -q
```

`tests/helpers.py` provides `StubLM` and `field_response(...)`. Every output field must be present in a stubbed response, including `reasoning` (ChainOfThought adds it).

## 3. Serve the engine

```bash theme={null}
uv run uvicorn qlaw.serve:app
```

The FastAPI service exposes:

* `POST /seed` — prompt → graph with `ROOT` plus the first decomposition layer.
* `POST /engine` — one reasoning step: `(graph, active_node_id, action)` → expanded graph.
* `POST /chat/stream` — SSE: status and tool events, then a `done` event with the answer and post-chat graph.
* `GET /config` — the active model id (no credentials) for the web client.

## 4. Run the web frontend

```bash theme={null}
cd web
pnpm install
pnpm dev                                # http://localhost:5173
pnpm exec tsc --noEmit && pnpm exec vitest run
```

`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. Set `VITE_API_BASE` in `web/.env.local` if the API port differs from `http://localhost:8000`.

## 5. Compile and evaluate

The compile pipeline turns the zero-shot engine into optimized artifacts under `artifacts/`:

```bash theme={null}
uv run python -m scripts.compile --optimizer mipro   # compile lenses + engine
uv run python -m scripts.evaluate                    # eval harness -> eval_results.json
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). The `gepa` engine's proposals and evaluation both use the `.env` model by default. Pass `--codex-model` to switch to the native Codex agent proposer.

## Next steps

* [Architecture](/fleet-reasoner/architecture) — the three tiers and DSPy 3.3.0 primitives that power them.
* [Lenses](/fleet-reasoner/lenses) — one optimizable module per agent.
* [Engine and router](/fleet-reasoner/engine) — the reasoning cycle as one `dspy.Module`.
* [Chat and tools](/fleet-reasoner/chat) — the multi-turn ReActV2 Co-Pilot with lenses as tools.
* [API and streaming](/fleet-reasoner/api) — the FastAPI endpoints, SSE frames, and error mapping.
* [Optimization and evaluation](/fleet-reasoner/optimization) — compile pipeline, trainsets, and metrics.
* [Gotchas](/fleet-reasoner/gotchas) — DSPy 3.3.0 pitfalls that will cost you time.