imas-codex Development

Essential Commands

All commands use uv run — never bare python or pytest.

Testing

uv run pytest                                        # Default (excludes slow/graph/sn_health)
uv run pytest tests/standard_names/ -q               # SN tests (~3300, ~90s)
uv run pytest tests/path/to/test.py::test_func -v    # Specific test
uv run pytest --cov=imas_codex --cov-report=term     # With coverage
uv run pytest -m graph                               # Graph tests (needs Neo4j)

Never pipe pytest output — it prevents auto-approval in agentic workflows. Default addopts produces compact output (-q --tb=short --no-header). See AGENTS.md "Testing" for full guidance.

Linting & Formatting

uv run ruff check --fix .     # Lint with auto-fix
uv run ruff format .          # Format

Schema Workflow

When modifying LinkML schemas (imas_codex/schemas/*.yaml):

uv run build-models --force   # Rebuild generated models
uv run pytest tests/graph/test_schema_compliance.py -v  # Verify compliance

Never commit auto-generated files: models.py, dd_models.py, physics_domain.py, schema-reference.md.

Dependency Management

uv sync                  # Install all deps
uv sync --extra test     # Include test deps (needed in worktrees)
uv sync --extra gpu      # Include GPU deps (for embedding)

Git Workflow

git add <file1> <file2>                          # Stage specific files only
uv run git commit -m 'type: concise summary'     # Conventional commit
git pull --no-rebase origin main                  # Always merge, never rebase
git push origin main

Commit Types

Never Do

• git add -A or git add . — stage specific files only
• Commit auto-generated files (models.py, dd_models.py, physics_domain.py)
• Use git rebase — always merge
• Run bare python or pytest (always uv run)
• Include AI co-authorship trailers in commits
• Add phase labels or step numbers in commit titles
• Stage files you didn't modify (other agents may be working in parallel)

Test Markers

SN tests live in tests/sn/ and run with uv run pytest tests/sn/ -v. They do not require Neo4j unless marked @pytest.mark.graph — the rest use mocks. Benchmark tests validate prompt parity with the generate pipeline, calibration dataset integrity, and reference set coverage.

Project Structure

Key Patterns

• Import from generated models: from imas_codex.graph.models import SourceFile, SourceFileStatus
• LLM calls: Use call_llm_structured() from imas_codex.discovery.base.llm
• Prompt rendering: Use render_prompt() from imas_codex.llm.prompt_loader
• Model selection: Use get_model(section) from imas_codex.settings
• Facility config: Use get_facility(facility) — never hardcode facility values
• Remote execution: Use run_python_script() from imas_codex.remote.executor

SN Key Files