cdsl-cad/backend/README.md

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:

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:

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.

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