| name | project-dev |
| description | How to develop, test, lint, and build the imas-codex project. Use when making code changes, running tests, or building the project. |
imas-codex Development
Essential Commands
All commands use uv run — never bare python or pytest.
Testing
uv run pytest
uv run pytest tests/standard_names/ -q
uv run pytest tests/path/to/test.py::test_func -v
uv run pytest --cov=imas_codex --cov-report=term
uv run pytest -m graph
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 .
uv run ruff format .
Schema Workflow
When modifying LinkML schemas (imas_codex/schemas/*.yaml):
uv run build-models --force
uv run pytest tests/graph/test_schema_compliance.py -v
Never commit auto-generated files: models.py, dd_models.py, physics_domain.py, schema-reference.md.
Dependency Management
uv sync
uv sync --extra test
uv sync --extra gpu
Git Workflow
git add <file1> <file2>
uv run git commit -m 'type: concise summary'
git pull --no-rebase origin main
git push origin main
Commit Types
| Type | Purpose |
|---|
| feat | New feature |
| fix | Bug fix |
| refactor | Code restructuring |
| docs | Documentation |
| test | Test changes |
| chore | Maintenance |
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
| Marker | Purpose |
|---|
@pytest.mark.graph | Requires live Neo4j (auto-skipped if unavailable) |
@pytest.mark.slow | Excluded by default |
@pytest.mark.integration | Full integration tests |
@pytest.mark.unit | Fast unit tests |
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
| Directory | Purpose |
|---|
imas_codex/cli/ | CLI commands (entry point: imas-codex) |
imas_codex/schemas/ | LinkML schema definitions (source of truth) |
imas_codex/graph/ | Graph client, generated models |
imas_codex/discovery/ | Discovery pipelines (wiki, code, signals, paths) |
imas_codex/tools/ | MCP tool implementations |
imas_codex/remote/ | Remote execution (SSH, scripts) |
imas_codex/llm/ | LLM integration and prompt templates |
imas_codex/standard_names/ | Standard name pipeline (generate, benchmark, graph ops) |
tests/ | Test suite (mirrors source structure) |
tests/sn/ | Standard name test suite (mostly mock-based) |
plans/features/ | Active feature plans |
agents/ | Agent documentation and schema reference |
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
| File | Purpose |
|---|
imas_codex/standard_names/benchmark_reference.py | Gold reference set (52 entries across 8 IDSs) |
imas_codex/standard_names/benchmark_calibration.yaml | Known-quality examples for reviewer consistency |
imas_codex/llm/prompts/sn/ | LLM prompt templates for generate, review, and benchmark |
