// How to develop, test, lint, and build the imas-codex project. Use when making code changes, running tests, or building the project.
[HINT] Download the complete skill directory including SKILL.md and all related files
| 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. |
All commands use uv run — never bare python or pytest.
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.
uv run ruff check --fix . # Lint with auto-fix
uv run ruff format . # Format
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.
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 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
| Type | Purpose |
|---|---|
| feat | New feature |
| fix | Bug fix |
| refactor | Code restructuring |
| docs | Documentation |
| test | Test changes |
| chore | Maintenance |
git add -A or git add . — stage specific files onlygit rebase — always mergepython or pytest (always uv run)| 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.
| 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 |
from imas_codex.graph.models import SourceFile, SourceFileStatuscall_llm_structured() from imas_codex.discovery.base.llmrender_prompt() from imas_codex.llm.prompt_loaderget_model(section) from imas_codex.settingsget_facility(facility) — never hardcode facility valuesrun_python_script() from imas_codex.remote.executor| 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 |