# Backend

The backend owns the application API and CAD generation workflow:

- `app/`: HTTP API, jobs, orchestration, and persistence adapters.
- `agent/`: AI prompts, tools, and skills used by the generation agent.
- `engine/`: CDSL compiler, sketch solver, and STEP generation runtime.
- `cdsl_library/`: Official CDSL examples, metadata, and search index.
- `tests/`: Engine, API, and end-to-end generation tests.

Expected development entrypoint: `app.main:app`, served by Uvicorn.

## Reasoning Effort

The backend uses the Chat Completions API. Configure a provider's reasoning
budget with `CDSL_<PROVIDER>_REASONING_EFFORT`; for the current OpenAI setup:

```dotenv
CDSL_OPENAI_REASONING_EFFORT=medium
```

Use `low`, `medium`, or `high` according to the latency/cost versus quality
tradeoff. The setting is sent as the provider's `reasoning_effort` field to
requirements analysis and Authoring CDSL generation. Leave it empty to use the
provider/model default. The selected OpenAI-compatible endpoint must support
the requested value.

## Autonomous CDSL Agent Configuration

Each task has one bounded workflow:

```text
request analysis -> complete cad.author.v1 -> server compilation -> runtime build
-> at most two complete repairs -> final or best-effort publication
```

The model outputs only local body/feature names and declarative selectors.
The server validates strict schemas, allocates Runtime CDSL identities,
compiles references, executes dependencies, and preserves the last executable
prefix. STEP is the primary artifact; GLB and the CPU-only OpenCascade/Pillow
render bundle are generated from the same published revision.

```dotenv
# Install Python rendering dependencies. The renderer reads the revision STEP
# file and creates canonical images without a browser or GPU driver.
pip install -r requirements.txt
```

The initial generation plus two repairs are the only model calls allowed after
requirements analysis. A repair returns a complete replacement Authoring CDSL
and may only alter diagnosed features. Runtime selector ambiguity, missing
selectors, and unavailable dependencies produce stable diagnostics rather than
topology guesses. Requirement compliance is reported independently as
`pass`, `fail`, `pending`, or `not_applicable`; a partial executable model is
still published after the repair budget is exhausted.