OpenSDL AGENTS.md

Repository instructions

Project

OpenSDL is a modular framework for computational and autonomous laboratories.

Layout

• reusable packages: packages/
• deployable applications: apps/
• integrations: adapters/
• scientific extensions: domain-packs/
• complete examples: examples/
• cross-package tests: tests/

Commands

• install: uv sync --locked --all-packages --group dev
• test: make test — workspace suite and the digital-twin surrogate overlay
• lint: make lint — lockfile, Ruff lint and format, Pyright, boundaries, schema drift, repository, and versions
• viewer: make viewer — surrogate viewer lint, typecheck, tests, build, and committed asset drift
• docs: make docs — mkdocs build --strict
• example: make example — the complete simulated campaign
• format: make format — applies Ruff formatting and safe fixes; make lint enforces it
• schemas: uv run --locked python scripts/generate-schemas.py

make test, make lint, make viewer, make docs, make example, and make showcase together cover every check the pull-request CI job enforces. make showcase re-derives the campaign the README frame is rendered from, which takes about a minute and is why CI runs it as its own job. make scene covers the one that runs separately: the headless Blender rebuild proving the committed scene is reproducible from source. It needs the exact Blender version recorded in the scene's node inventory and takes several minutes. A bare uv run --locked pytest is not the full suite: testpaths excludes examples/, so the surrogate tests are reachable only through make test or make surrogate, and the showcase campaign only through make showcase. Narrower targets (unit, integration, e2e, conformance, typecheck, boundaries, validate, showcase, surrogate, propagation, scene) and the raw command behind each target are in the Makefile.

Architecture rules

• core imports no internal package.
• Applications compose packages; business logic stays in packages.
• Vendor or facility behavior belongs in adapters.
• Every operational adapter needs simulation and conformance coverage.
• Public models are typed and exported as versioned schemas.
• Database access goes through repository interfaces.
• A change is complete when code, tests, schemas, examples, and documentation agree.
• A laboratory with one instrument stays expressible in about fifteen manifest lines, runnable in one process against SQLite, with no scheduler, broker, or optional service. Facility features are opt-in by configuration, never by requirement, and a change that lengthens the minimum manifest needs justifying. tests/test_minimal_laboratory.py enforces this.