Metadata-Version: 2.4
Name: config-spine
Version: 0.1.0
Summary: A compiler for engineering analysis configuration — ICD as code: typed, unit-aware interface contracts between analyses, cycle-aware planning, N² review packs, and provenance
Project-URL: Repository, https://gitlab.com/config-afficianados/config_spine_project
Project-URL: Documentation, https://gitlab.com/config-afficianados/config_spine_project/-/blob/main/docs/installation.md
Project-URL: Issues, https://gitlab.com/config-afficianados/config_spine_project/-/issues
Project-URL: Changelog, https://gitlab.com/config-afficianados/config_spine_project/-/blob/main/CHANGELOG.md
Project-URL: Live demo (N² review pack), https://config-afficianados.gitlab.io/config_spine_project/
Project-URL: Security, https://gitlab.com/config-afficianados/config_spine_project/-/blob/main/SECURITY.md
Author: David Prime
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: dsm,engineering,icd,interface-control-document,mdo,n2-matrix,provenance,systems-engineering,units,validation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Manufacturing
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: datamodel-code-generator>=0.25
Requires-Dist: frictionless>=5.16
Requires-Dist: jsonpointer>=2.4
Requires-Dist: jsonschema>=4.21
Requires-Dist: networkx>=3.2
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pandas>=2.0
Requires-Dist: pint>=0.24
Requires-Dist: pydantic>=2.7
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: typer>=0.12
Requires-Dist: watchfiles>=1.2.0
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# Config Spine

Config Spine is a compiler for engineering analysis configuration. It is a tool that **enforces ICD as code**. It is used to allow interface contracts between your analyses — which today may be a Word doc ICD, a spreadsheet, or tribal knowledge. And allows them to become typed, unit-aware, Git-versioned artifacts that a compiler checks **before anything runs**.

The value add of this config-compilation step is that it will catch most misconfiguration errors that might error any of your simulations/analyses ahead of time and allow quick config review and error detection. This can save you hours/days/weeks of expensive simulation/analysis time.

A good example is the Mars Climate Orbiter failure, which was lost because one side of an interface produced lbf·s and the other consumed N·s. In Config Spine that is a specific error code `SPINE-E004`, which surfaces unit mismatch errors. If that project had used Config Spine, it might have caught a the mismatch which resulted in a $327M failure.

## Core features and use cases include

- **Catch interface errors before execution** — units, shapes, references, and schema conformance, with stable error codes and located diagnostics.
- **See the whole process** — the N×N (N²) design structure matrix, feedback loops and all, generated as a build artifact (**[live demo review pack](https://config-afficianados.gitlab.io/config_spine_project/)**), plus Mermaid/DOT graphs and an offline HTML review pack.
- **Manage iteration deliberately** — feedback cycles are first-class: declared convergence strategies, fixed-point execution, `spine sequence` reordering to minimize feedback (the DeMAID job).
- **Prove any result** — provenance (git commit, content hashes, fragment origins), baselines and diffs, field-level history from Git, margins against requirements.
- **Keep your tools** — analyses stay in your Python, legacy executables, and vendor codes; adapters wrap them. Config Spine replaces the brittle glue *between* tools, never the tools.
- **Safe for AI agents** — deterministic CLI, JSON everywhere, validation-gated writes, 13 shipped agent skills, and an MCP server. The workflow becomes: AI drafts, the compiler validates, the engineer approves.



## Who it's for

The integration lead on a 5–50-engineer multidisciplinary hardware team (launch, satellite, eVTOL, fusion, motorsport, process plant…) who owns a coupled analysis loop across heterogeneous tools.

**Who it's not for:** single-tool workflows with no coupling (a Makefile is enough), or teams wanting a hosted GUI.

## Security design

This project is open-source and designed to be local-first, git-first and air-gap-safe — see [SECURITY.md](https://gitlab.com/config-afficianados/config_spine_project/-/blob/main/SECURITY.md).

## Install

Into your own project (Python 3.11+; full guide: `docs/installation.md`):

```bash
uv tool install config-spine        # or: pipx install config-spine

spine init          # scaffold a workspace in your repo
spine validate      # green compile
```

Working on Config Spine itself: clone, then `uv sync && uv run spine --help`.

## Adopting Config Spine on an existing codebase

Your ICD is probably already written — in Python. Point the tool at your repo
and it mines the evidence (signatures, unit-suffixed names like `thrust_n`,
file handoffs, import edges, hand-rolled convergence loops) into a map your
agent turns into draft contracts:

```bash
spine adopt path/to/your/repo   # survey + printed next steps
```

The funnel: `spine survey` collects evidence deterministically (no LLM, authors
nothing, works air-gapped) → the `spine-codebase-cartographer` agent skill
proposes draft analyses, artifact types, mappings, and adapters — every
inference citing its `file:line` evidence, every unknown an explicit gap →
`spine validate` gates the writes → `spine review` renders **your own process
as an N² matrix** in the first session.

The whole funnel is written up as a step-by-step worked example — a simulated
team repo (hand-rolled convergence loops, an imperial legacy tool, and a
silent lbm/kg bug the compiler catches) taken from zero to a validated,
rebuild-on-demand model: see
`[examples/zero_to_adopted/README.md](https://gitlab.com/config-afficianados/config_spine_project/-/blob/main/examples/zero_to_adopted/README.md)`.

## Demo workspace

The repository root is itself a working demo workspace: a toy aeroelastic
sizing loop (`aero_vlm` <-> `structures_beam` feedback cycle, feeding a
`mass_rollup`).

```bash
uv run spine validate            # phases 1-3: syntax, structural, semantic
uv run spine compile             # build IR, link, emit build/<run_id>/compiled_plan.json
uv run spine plan                # show execution plan (layers, cycles, data flow)
uv run spine graph               # emit build/arch.mermaid (or --format dot)
uv run spine review              # offline HTML review pack incl. the N² matrix
uv run spine codegen             # emit generated/models + generated/stubs
uv run spine run                 # compile + phase-4 checks + execute the plan
uv run spine status              # changed files / stale outputs since last build
```

`spine run` is the top rung of the **runtime adoption ladder** — you never
have to hand over your execution loop to get the contract enforced:


| Level | Posture                                                                       | Who owns the loop    | Cost to try       |
| ----- | ----------------------------------------------------------------------------- | -------------------- | ----------------- |
| 0     | `spine survey` / `spine validate`                                             | nobody runs anything | minutes           |
| 1     | **shadow validation** — your orchestrator + `spine.shadow` / `spine check-io` | **the team**         | one line per seam |
| 2     | `spine run` — the executor                                                    | Config Spine         | adapter manifests |


Both levels enforce the same compiled ICD; teams that stay at Level 1 forever
are a success, not a failure. Shadow checks are opt-in per call site and never
mutate values; `SPINE_SHADOW=off` makes them no-ops (overhead numbers in
[docs/shadow_performance.md](https://gitlab.com/config-afficianados/config_spine_project/-/blob/main/docs/shadow_performance.md)). See
[docs/integration/external_orchestrator.md](https://gitlab.com/config-afficianados/config_spine_project/-/blob/main/docs/integration/external_orchestrator.md).

The same workspace also contains a second, harder example: a launch-vehicle
sizing loop with nine analyses, two disjoint feedback cycles, an imperial
legacy trajectory tool (psf/fps/lbm with explicit `unit_convert` mappings to
SI consumers), a CSV drag table flowing between analyses, a fan-in
multiplicity-`list` mass port, and a `[3, 3]` inertia-tensor array artifact.
Select it with `--run` on any command (see `docs/examples.md`):

```bash
uv run spine plan --run projects/vehicle_sizing/runs/vehicle_sizing.yaml
uv run spine run  --run projects/vehicle_sizing/runs/vehicle_sizing.yaml
```

Exit codes: `0` success, `1` validation error, `2` compilation error,
`3` execution error, `4` environment error.

## Layout


| Path                                       | Role                                                                                                                                                                                                        |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schemas/spine/`                           | Meta-schemas for manifest types (workspace-global)                                                                                                                                                          |
| `lib/`                                     | Shared schemas, analyses, mappings, adapters, and demo implementations                                                                                                                                      |
| `projects/<id>/`                           | Program-specific authored trees and run manifests                                                                                                                                                           |
| `src/spine/`                               | The compiler: `frontend/`, `semantic/`, `ir/`, `backends/`, `runtime/` (executor + `shadow*` validation), `survey/`, `inspectors/`, `scaffold/`, `templates/`, `api/`, `mcp/`, `history/`, `cache/`, `cli/` |
| `generated/`, `build/<run_id>/`, `.spine/` | Build artifacts (gitignored, reproducible)                                                                                                                                                                  |
| `outputs/`                                 | Runtime artifacts per run: results, logs, provenance (gitignored)                                                                                                                                           |
| `docs/diagrams/`                           | Architecture diagrams (draw.io sources + rendered PNGs)                                                                                                                                                     |


Each run manifest selects an ordered `library` of roots (inferred from
`projects/<id>/runs/` when omitted). Later roots shadow earlier ones on
duplicate symbol ids. Run `inputs` bind project-specific instance data.

## Validation phases

1. **Syntax** - files parse (YAML/JSON/CSV well-formed)
2. **Structural** - instances conform to schemas (JSON Schema + Frictionless)
3. **Semantic** - references resolve; units, shapes, and mappings are
  compatible; cycles have declared iteration strategies
4. **Execution** - adapters callable, files present, environment ready

Every diagnostic carries file, line/column, JSON Pointer, schema path,
analysis/port id, and an error class (see `docs/validation_strategy.md`). Run
`spine explain SPINE-E004` to look up any code's meaning, guidance, and fix from
the terminal; the full table is generated into `docs/error_codes.md`.

## Status, stability, and security

Pre-1.0 and moving deliberately: diagnostic codes, authored file formats, and
JSON output shapes carry explicit stability guarantees — see
`docs/versioning_and_stability.md` and [CHANGELOG.md](https://gitlab.com/config-afficianados/config_spine_project/-/blob/main/CHANGELOG.md). All
authored artifacts are plain YAML/JSON/CSV in your own repo, so the exit cost
is low by design. No network calls, no telemetry, air-gap-safe:
[SECURITY.md](https://gitlab.com/config-afficianados/config_spine_project/-/blob/main/SECURITY.md).

## Tests

```bash
uv run pytest -n auto
```



## Code quality

Formatting and linting are automated — format-on-save in VS Code/Cursor,
`ruff` + `pyright` via pre-commit and CI. One-time setup after `uv sync`:

```bash
uv run pre-commit install --install-hooks
```

Day-to-day commands (see `Justfile`):

```bash
just format      # ruff format
just lint        # ruff check
just lint-fix    # ruff check --fix
just typecheck   # pyright (standard mode)
just test        # pytest -n auto
just check       # lint + typecheck + pre-commit — run before committing
```

Conventions, the `# type: ignore[code]` policy, and agent tooling are
documented in `AGENTS.md` (see "Code Quality").

## What `spine review` gives you

Worth a look even if you never adopt the compile-time checking. One command —
`spine review` — turns a coupled analysis process into a design-review
deliverable: static HTML, no server, no network, generated in seconds and
regenerated in CI on every commit, so it cannot drift from the model. Everything
below is emitted output from the nine-analysis launch-vehicle demo in this
repository; none of it was drawn by hand.

The N² design structure matrix — feed-forward above the diagonal, **feedback
below it**, the artifact named in every cell, cycle members badged with their
cycle and iteration count, external file-bound inputs in the leading column,
owning team on every row:

![N×N design structure matrix](https://gitlab.com/config-afficianados/config_spine_project/-/raw/main/docs/review_showcase/img/n2_dsm.png)

The same process as a graph, with each cycle boxed alongside the convergence
strategy it declared and each node tinted by what happened on the last run:

![Analysis graph](https://gitlab.com/config-afficianados/config_spine_project/-/raw/main/docs/review_showcase/img/analysis_graph.png)

See an example of the full review pack using the links below:

- **[Live demo](https://config-afficianados.gitlab.io/config_spine_project/)** — the real pack, zero install.
- **[The full tour](https://gitlab.com/config-afficianados/config_spine_project/-/blob/main/docs/review_showcase/README.md)** — every section, with the honest caveats.
- **[Committed snapshot](https://gitlab.com/config-afficianados/config_spine_project/-/blob/main/docs/review_showcase/index.html)** — the same pack as one self-contained, JavaScript-free HTML file.

You never have to hand over your execution loop to get this: `spine review`
works straight off `validate`/`compile`, and `--with-provenance` merely overlays
run results when you have them.

## Background & FAQ

Why this project exists, how it was built (candidly), and the questions people
tend to ask:

- [Why I built this — developer thoughts](https://gitlab.com/config-afficianados/config_spine_project/-/blob/main/Readme-developer-thoughts-on-project.md)
- [FAQ](https://gitlab.com/config-afficianados/config_spine_project/-/blob/main/Readme-FAQs.md)

Interested in contributing? See [CONTRIBUTING.md](https://gitlab.com/config-afficianados/config_spine_project/-/blob/main/CONTRIBUTING.md). If you are interested in contributing, you may want to look over the `/planning_and_roadmaps/` to see what kinds of considerations were thought of in developing this project. In particular the `business_case_and_target_engineer` and `market_driven_roadmap` were core design documents.

## License

[Apache-2.0](https://gitlab.com/config-afficianados/config_spine_project/-/blob/main/LICENSE).
