apc-model-parser 0.1.0__tar.gz

apc_model_parser-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.11"
+
+      - name: Sync environment
+        run: uv sync --all-groups
+
+      - name: Ruff check
+        run: uv run ruff check .
+
+      - name: Ruff format (check only)
+        run: uv run ruff format --check .
+
+      - name: Pytest
+        run: uv run pytest
+
+      - name: MkDocs strict build
+        run: uv run mkdocs build --strict

apc_model_parser-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+# Publish MkDocs to GitHub Pages (Settings → Pages → Source: GitHub Actions).
+name: Docs
+
+on:
+  push:
+    branches: [main, master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.11"
+
+      - name: Sync environment
+        run: uv sync --all-groups
+
+      - name: Build site
+        run: uv run mkdocs build --strict
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

apc_model_parser-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+.*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/apc-model-parser/
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.11"
+
+      - name: Sync environment
+        run: uv sync --all-groups
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload build artefacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-${{ github.ref_name }}
+          path: dist/
+
+      - name: Create GitHub Release with assets
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

apc_model_parser-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# uv
+# uv.lock is committed; the environment is not.
+
+# Julia
+/julia/**/Manifest.toml
+*.jl.cov
+*.jl.*.cov
+*.jl.mem
+
+# Generated artifacts (examples write here)
+/examples/outputs/
+
+# MkDocs (local build; CI deploys via artifact)
+site/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/

apc_model_parser-0.1.0/AGENTS.md

@@ -0,0 +1,379 @@
+# Coding agent guidelines for model-parser
+
+This file defines how AI coding agents (e.g. Cursor, Copilot) and human
+contributors collaborate on this repository. Human reviewers should treat it as
+the canonical contributor guide. It is **public**: describe behaviour only in
+terms of this project and its published design — avoid internal codenames or
+unrelated repositories.
+
+**Authoritative product specification:**
+[`docs/design/model-parser.md`](docs/design/model-parser.md). When CLI
+semantics, the IR shape, scope, or roadmap change, update that document (and the
+relevant `docs/decisions/NNNN-*.md` ADR) in the same change series as the code.
+
+## What this repository is
+
+`model-parser` converts process-model definitions **to and from a canonical
+intermediate representation (IR)**. It owns the model-*scaffold* contract: the
+parser, AST, normalizer, IR data model + JSON Schema, validators, and the
+IR→backend lowerings (codegen). It is one tool in the Advanced Process Control
+ecosystem and must remain usable **standalone**.
+
+```text
+authoring (ExprTk INI)  --parse-->  AST  --normalize-->  canonical IR (JSON)
+                                                          |
+                                          emit julia  --> ModelingToolkit .jl
+                                          emit cpp    --> (planned) realtime C++
+```
+
+## Language
+
+- **All content in English:** code, comments, docstrings, commit messages,
+  user-facing CLI strings, `docs/chatlogs/` entries, and Markdown under `docs/`.
+- Keep domain vocabulary consistent with the org glossary and design docs:
+  *scaffold*, *parameter set*, *scenario*, *AST*, *canonical IR*, *profile*,
+  *lower*, *export*, *conformance*, *provenance*.
+
+## Platform and paths
+
+- **Targets:** Linux, macOS, and Windows where the CLI runs. Prefer `pathlib`,
+  avoid hard-coded host-specific paths in tests and examples; use `tmp_path` in
+  pytest and placeholders in docs (`/tmp`, `example.ini`).
+- **Julia side:** `julia/ModelParserJL/` must remain loadable on the supported
+  Julia versions stated in that package; document any extra env assumptions in
+  the design doc or `examples/README.md`.
+
+## Two languages, one contract
+
+| Concern | Home |
+|---|---|
+| CLI, AST, IR data model, JSON Schema, validators, **codegen** | **Python** (`src/model_parser/`) |
+| IR → ModelingToolkit `System`, in-memory build, conformance reference | **Julia** (`julia/ModelParserJL/`) |
+
+Both consume the **same** IR JSON. Do not re-implement expression semantics in
+more than one place without IR-level tests. See
+[`docs/decisions/0001-python-cli-with-julia-backend.md`](docs/decisions/0001-python-cli-with-julia-backend.md).
+
+## Python tooling — strictly uv
+
+Use **uv** for every environment and dependency operation.
+
+- `uv add <pkg>` / `uv add --dev <pkg>` to add dependencies.
+- `uv remove <pkg>` to remove them.
+- `uv run <cmd>` to execute commands in the project environment.
+- `uv sync` / `uv sync --all-groups` to recreate the environment from the
+  lockfile (use **`--all-groups`** so dev dependencies match CI).
+- **Do not** hand-edit `[project.dependencies]` or `[dependency-groups]` in
+  `pyproject.toml`; those are owned by `uv add` / `uv remove`.
+- **Do** edit `[project]` metadata (including `version`), `[project.scripts]`,
+  and tool configuration (`[tool.ruff]`, `[tool.pytest.ini_options]`, …).
+
+## Code style
+
+| Area | Rule |
+| --- | --- |
+| Python | 3.11+ per `requires-python` |
+| Linter / formatter | **ruff** (line length **100**, target **py311**) |
+| Type hints | Required on every **public** function and method |
+| Docstrings | Google-flavoured on public APIs; module docstring atop each `.py` |
+| Imports | ruff isort; absolute imports (`model_parser.…`) |
+| Julia | follow the prototype style in `apcplants/ProcessModelingJL`; `Pkg` for deps |
+
+Local checks (must match CI):
+
+```bash
+uv sync --all-groups
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+uv run mkdocs build --strict
+```
+
+## Architecture principles
+
+### Pure logic vs. I/O separation
+
+**Pure modules** parse, normalize, validate, and lower — no filesystem,
+subprocess, or network access. Keep `ir/`, `frontends/`, `backends/`, and
+`validation/` pure and deterministic.
+
+**I/O modules** read/write files and implement the CLI. `io.py` and `cli.py` own
+filesystem access; the CLI must stay a thin shell over the pure functions.
+
+### One transformation ≈ one module
+
+- `frontends/<format>.py` — one authoring format → IR (`parse` + `normalize`).
+- `backends/<target>.py` — IR → one target view (`lower` / codegen).
+- `validation/` — semantic and profile checks.
+- `ir/` — the data model and expression tree; the shared contract.
+
+Adding a backend means **one new `backends/*.py` + tests**, never editing every
+other backend (that is the whole point of the hub-and-spoke IR).
+
+### The IR is the single semantic truth
+
+- The IR describes a **scaffold only** (structure + equations + roles + units +
+  metadata). Parameter sets and scenarios (incl. initial values `x0`/`u0`) are
+  **out of scope** — frontends drop them with a `WARN`.
+- The IR is **versioned JSON** (`ir_version`, SemVer). A breaking schema change
+  requires migration notes and an ADR.
+- Every IR carries a **content hash** over its semantic body; downstream
+  artifacts reference scaffolds by hash, not path.
+- Expression semantics live in the **explicit expression tree**
+  (`ir/expr.py`), never in per-backend string rewrites.
+
+### Codegen, not serialized objects
+
+The durable form of an MTK model is the **IR JSON + generated `.jl` script**,
+never a serialized `System`. Generated Julia targets **MTK v11** idioms
+(`System(eqs, t)`, `mtkcompile`, `t_nounits`/`D_nounits`, no `@mtkmodel`, no
+`structural_simplify`). See ADRs 0002 and 0004.
+
+### Determinism & idempotency
+
+Re-running `parse`/`emit` on unchanged input must produce byte-identical output
+(stable ordering, stable number formatting). The content hash depends only on
+the semantic body.
+
+### Status vocabulary and exit codes
+
+CLI diagnostics use `OK` · `WARN` · `ERROR`. Exit codes:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | success; no `ERROR` diagnostics |
+| `1` | at least one `ERROR` (e.g. validation failed) |
+| `2` | invalid usage / load failure before meaningful work |
+
+### CLI conventions
+
+- Long options in kebab-case (`--from`, `--profile`, `--output`/`-o`).
+- The two core verbs are `parse` (authoring → IR) and `emit <target>` (IR →
+  view). Supporting commands: `validate`, `inspect`, `ast`, `schema`.
+- Breaking CLI changes require a SemVer bump and release notes.
+
+## Scope guardrails
+
+**In scope:** authoring-format parsing, the canonical IR + JSON Schema, semantic
+& profile validation, IR↔backend lowering / codegen, conformance fixtures.
+
+**Out of scope:** parameter identification, scenario execution / simulation,
+result storage, controller synthesis, deployment, UI. Those are sibling tools
+that *consume* the IR.
+
+If a change request conflicts with the design doc, stop and resolve via an
+explicit doc + ADR update — do not silently expand scope.
+
+## Work tracking (ADRs and issues)
+
+- **ADRs:** numbered files under [`docs/decisions/`](docs/decisions/) (`NNNN-title.md`),
+  indexed in [`docs/decisions/index.md`](docs/decisions/index.md). One decision per
+  file; never delete — supersede with a newer ADR and update the index.
+- **Issues:** use GitHub issues for backlog items that are not yet an ADR; link
+  ADRs from issue/PR text when a decision motivates the change.
+- Prefer **small, reviewable slices** (one coherent feature, bugfix, or refactor
+  per PR when practical). For larger work, split PRs and reference the same ADR
+  or design section in each.
+
+### Recommended slice workflow (maintainers & agents)
+
+1. **Align scope** — confirm design doc + ADR if behaviour or IR contract changes.
+2. **Implement & test** — code and automated tests for that slice; keep pure vs I/O
+   boundaries intact.
+3. **Verify locally** — `uv sync --all-groups`, ruff check/format, `uv run pytest`,
+   `uv run mkdocs build --strict` (same as CI).
+4. **Docs** — update `docs/design/model-parser.md`, schema regeneration command, or
+   ADR in the **same** change series when the public contract moves.
+5. **`docs/chatlogs/…`** when the slice materially changes behaviour or governance.
+
+## Testing
+
+- Framework: **pytest** (`uv run pytest`).
+- **Unit tests** for pure logic: expression parser, frontend, backend codegen,
+  validators.
+- **CLI smoke tests** with `typer.testing.CliRunner`.
+- **Conformance** (as it grows): an IR fixture plus expected Julia output and/or
+  expected trajectories, shared between the Python codegen and `ModelParserJL`.
+
+## Documentation system
+
+**Target stack** (align when a docs site is added): **MkDocs** with the **Material**
+theme and **mkdocstrings** (or equivalent) for Python API reference; Julia API
+docs may stay in `julia/ModelParserJL/` README until unified.
+
+**Intended layout** (keep consistent with [`docs/design/model-parser.md`](docs/design/model-parser.md)):
+
+- `docs/index.md` or root `README.md` — overview, install (`uv`), quick `parse` /
+  `emit` examples (when expanded).
+- `docs/design/` — product spec (`model-parser.md`) and deep architecture notes.
+- `docs/decisions/` — ADRs (`NNNN-title.md`) + `index.md`.
+- `docs/chatlogs/` — session summaries (see **Session summaries** below).
+- `docs/deployment/` — optional summaries for CI/CD, packaging, and release
+  process once those exist in-repo.
+
+**Rules:**
+
+- User-facing prose lives under `docs/`; IR semantics and the CLI contract stay
+  accurate relative to the design doc and JSON Schema.
+- Do not commit secrets, real tokens, or customer-specific identifiers; use
+  placeholders (`example.com`, generic model names).
+- Once `mkdocs.yml` exists, CI **should** run `uv run mkdocs build --strict`; until
+  then, Markdown in `docs/` remains valid without a site build.
+
+**Generated artefacts:**
+
+- [`schemas/canonical-ir.schema.json`](schemas/canonical-ir.schema.json) is
+  committed output; regenerate with  
+  `uv run model-parser schema -o schemas/canonical-ir.schema.json`  
+  whenever the IR Pydantic models change, in the same change series as the code.
+
+## Runnable examples (`examples/`)
+
+- Keep **small, well-commented, copy-paste-friendly** inputs under
+  [`examples/models/`](examples/models/) and expected outputs under
+  [`examples/outputs/`](examples/outputs/) where helpful for reviewers and users
+  (not only pytest).
+- Prefer **English** comments and placeholders — never real proprietary model text
+  or secrets.
+- When a session ships **user-visible CLI or IR** behaviour, add or refresh an
+  **`examples/…`** entry in the **same** merge series as the chatlog when feasible.
+- Document how to run examples in [`examples/README.md`](examples/README.md)
+  (e.g. `examples/run.sh`, `uv run model-parser …`).
+
+## Session summaries (`docs/chatlogs/`)
+
+**Required** after substantive sessions (multi-step implementation, non-trivial
+design discussion, or when behaviour or doc intent shifts).
+
+### Commit helper (mandatory placement)
+
+Every chatlog MUST begin with a **`## Commit helper`** section (level-2 heading).
+
+**Order of file contents**
+
+1. **YAML frontmatter** (when used) MUST be the **first bytes** of the file (`---` … `---`).
+2. Immediately after the closing `---`, **`## Commit helper`** MUST be the **first
+   Markdown body content** — nothing above it except frontmatter.
+3. Next, **`## How to try`** MUST follow **`## Commit helper`** (not the long narrative).
+4. If frontmatter is omitted, **`## Commit helper`** is the first line, then **`## How to try`**, then the narrative.
+
+**Commit helper MUST contain**
+
+- **`SemVer / version bump`:** **no bump** vs **PATCH / MINOR / MAJOR**, tied to
+  what shipped (docs-only vs user-visible CLI/IR vs breaking schema or CLI). See
+  [**Versioning, releases, and release notes**](#versioning-releases-and-release-notes).
+- **`Tags / GitHub Release`:** always fill — **None** (stack on default branch) or
+  **Tag after bump** with exact tag string (e.g. `v0.2.0`), pre-release if needed,
+  and whether a **`release.yml`** (or future) workflow should run on tag push.
+- **Suggested commit message:** one imperative subject; optional Conventional scope
+  (`feat(cli): …`, `fix(ir): …`). Use `BREAKING CHANGE:` footer when applicable.
+- **Copy-paste git commands:** fenced `bash` with `git add` paths and
+  `git commit -m '…'`. If the version bump belongs in the same commit, note updates
+  to `pyproject.toml` and `src/model_parser/__init__.py`.
+- **Git order when tagging:** never tag before the release commit exists locally:
+  **commit / push branch (with version bump)** → **`git tag -a vX.Y.Z` on that
+  commit** → **`git push origin vX.Y.Z`**.
+
+### How to try (mandatory unless N/A)
+
+Immediately after **`## Commit helper`**, include **`## How to try`** with concrete
+`uv run model-parser …` steps, pytest selection, or `examples/…` commands. For
+pure docs/chatlog hygiene: **`N/A (docs-only).`**
+
+### Session narrative
+
+After **How to try**, summarize shipped modules, CLI/IR edge cases, and regression
+risks in English (**goal → shipped surface → decisions → follow-ups**).
+
+**Naming:** `YYYY-MM-DD_short-topic.md` (ASCII slug).
+
+**Frontmatter (YAML):** at least `title`, `topic`, `date_added`, `tags: [chatlogs]`,
+and `links:` to touched specs or code (e.g. `AGENTS.md`, `docs/design/model-parser.md`).
+
+**Not a substitute for:** ADRs, tests, or commit messages — those remain the source
+of truth for the contract.
+
+## CI/CD (GitHub Actions)
+
+Workflows live under [`.github/workflows/`](.github/workflows/). Maintainer-facing
+detail (Pages setup, PyPI trusted publishing, tag order) is in
+[`docs/deployment/ci-cd.md`](docs/deployment/ci-cd.md).
+
+| Workflow | Trigger | Purpose |
+| --- | --- | --- |
+| [`ci.yml`](.github/workflows/ci.yml) | Push / PR to `main` or `master` | `uv sync --all-groups`, ruff, pytest, **`mkdocs build --strict`** |
+| [`docs.yml`](.github/workflows/docs.yml) | Push to `main`/`master`, `workflow_dispatch` | Build MkDocs and deploy to **GitHub Pages** |
+| [`release.yml`](.github/workflows/release.yml) | Push SemVer tags `vX.Y.Z` (and pre-release suffixes) | `uv build`, GitHub Release + assets, **PyPI** (OIDC) |
+
+**Rules:**
+
+- CI commands must be reproducible locally (`uv run …`); the **local check block**
+  above must stay aligned with `ci.yml`.
+- **PyPI** uses **trusted publishing** via `pypa/gh-action-pypi-publish` with GitHub
+  **environment** `pypi` — configure the same environment name on PyPI’s pending
+  publisher (or adjust the workflow if PyPI omits environment). Distribution name:
+  **`apc-model-parser`**; import package and CLI: **`model_parser`** / `model-parser`.
+- **GitHub Pages:** repository **Settings → Pages → Source: GitHub Actions** (one-time).
+  Published site: `https://advanced-process-control.github.io/model-parser/` (must
+  match `site_url` in `mkdocs.yml`).
+
+## Versioning, releases, and release notes
+
+### Semantic versioning
+
+Follow **[Semantic Versioning 2.0.0](https://semver.org/)** (`MAJOR.MINOR.PATCH`).
+
+- **`0.y.z`:** breaking CLI or IR schema changes are allowed but must be called out
+  in release notes and usually accompanied by an ADR.
+- **`1.0.0` onward:** honour SemVer for the **documented** public surface: stable
+  CLI flags, `ir_version`, JSON Schema compatibility as advertised.
+
+### Single source of truth for the running version
+
+Bump **both** in the same release series until tooling ties them automatically:
+
+- `project.version` in [`pyproject.toml`](pyproject.toml)
+- `__version__` in [`src/model_parser/__init__.py`](src/model_parser/__init__.py)
+
+Keep them identical for each release tag.
+
+### Tags and GitHub Releases
+
+- **Ordering:** merge the commit(s) that bump version fields; **then** create an
+  **annotated** tag **`vX.Y.Z`** on **that** commit; **then** `git push origin vX.Y.Z`.
+  Release automation (when added) should trigger on tag push; the leading `v` is
+  a common convention — match whatever `release.yml` expects.
+- **Release notes:** use GitHub auto-generated notes where helpful; edit for IR or
+  CLI highlights.
+- **Optional `CHANGELOG.md`:** if introduced, follow
+  [Keep a Changelog](https://keepachangelog.com/) and update it in the release
+  commit series.
+
+### Artefacts
+
+- **`uv build`** produces `dist/*.tar.gz` and `dist/*.whl`. A release workflow can
+  attach them to GitHub Releases and PyPI.
+- **Wheel tags** and `requires-python` must match actual dependency and runtime
+  support; adjust classifiers in `pyproject.toml` as the project matures.
+
+### Pre-releases
+
+Pre-release tags (e.g. `v0.2.0-rc.1`, PEP 440–compatible) are fine for testers.
+Mark GitHub Releases as **pre-release** when behaviour or schema is unstable.
+
+## Security
+
+- Never commit secrets (tokens, private URLs with embedded credentials).
+- Logs and user-visible errors must not echo full file contents of untrusted inputs
+  at high verbosity without care — follow the design doc for diagnostic redaction
+  policy as it evolves.
+- Generated Julia/C++ must not embed secrets from authoring files; treat IR JSON as
+  shareable engineering data unless the org classifies it otherwise.
+
+## Commit conventions
+
+- Imperative, concise subjects (`add mtk v11 emit path`, not `added path`).
+- Prefer one logical change per commit.
+- Reference GitHub issues or ADR filenames when it aids traceability.
+- [Conventional Commits](https://www.conventionalcommits.org/) shape where it
+  helps (`feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `ci`).

apc_model_parser-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: apc-model-parser
+Version: 0.1.0
+Summary: Convert process-model definitions to and from a canonical intermediate representation.
+Project-URL: Repository, https://github.com/Advanced-Process-Control/model-parser
+Author: Advanced Process Control
+License: MIT
+Keywords: codegen,exprtk,intermediate-representation,modelingtoolkit,process-model
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.6
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# model-parser
+
+**Convert process-model definitions to and from a canonical intermediate
+representation (IR).**
+
+`model-parser` is the Advanced Process Control toolbox component that owns the
+*model scaffold* contract and the transformations around it. It parses an
+authoring format (today: the ExprTk-style INI used by the MPC / simulation
+toolchain) into a normalized, backend-independent **canonical IR**, and lowers
+that IR into target views — starting with a generated **ModelingToolkit (Julia)**
+model script.
+
+```text
+authoring (ExprTk INI)  --parse-->  AST  --normalize-->  canonical IR (JSON)
+                                                          |
+                                          emit julia  --> ModelingToolkit .jl
+                                          emit cpp    --> (planned) realtime C++
+```
+
+The IR is the single semantic contract. Adding a backend means writing one
+`lower` + one `export`, not an N×N mesh of view-to-view translators. See
+[`docs/design/model-parser.md`](docs/design/model-parser.md) for the
+authoritative product specification and
+[`docs/decisions/`](docs/decisions/) for the design decision records.
+
+## Why two languages?
+
+| Concern | Home | Why |
+|---|---|---|
+| CLI, AST, IR, JSON Schema, validators, **codegen** | **Python** (this package) | Parsing & orchestration strength; no symbolic runtime needed to emit code. |
+| IR → MTK `System`, simulation, analysis, conformance | **Julia** ([`julia/ModelParserJL`](julia/ModelParserJL/)) | Natural fit for ModelingToolkit; reference for parity tests. |
+
+The Python CLI builds and validates the IR and **generates** Julia code; the
+Julia package can additionally load an IR directly into an MTK `System` for
+in-memory, dynamic workflows. Both consume the *same* IR. See
+[ADR 0001](docs/decisions/0001-python-cli-with-julia-backend.md).
+
+## Install
+
+This project uses **[uv](https://docs.astral.sh/uv/)** for everything.
+
+```bash
+uv sync --all-groups    # include dev tools (ruff, pytest, mkdocs)
+uv run model-parser --help
+```
+
+## CLI
+
+```bash
+# 1. ExprTk INI  ->  canonical IR JSON
+uv run model-parser parse examples/models/model_monod_simple.ini -o monod.ir.json
+
+# 2. canonical IR  ->  ModelingToolkit (v11) Julia model
+uv run model-parser emit julia monod.ir.json -o monod.jl
+
+# Supporting commands
+uv run model-parser validate monod.ir.json --profile julia-analysis
+uv run model-parser inspect  monod.ir.json
+uv run model-parser ast      examples/models/model_monod_simple.ini   # debug tree
+uv run model-parser schema   -o schemas/canonical-ir.schema.json      # export schema
+```
+
+`parse` accepts `--from exprtk-ini` (default). `validate` accepts either an IR
+`.json` file or an INI file (parsed on the fly). Exit codes: `0` success,
+`1` validation errors, `2` usage / load failure.
+
+## How "stored MTK models" work
+
+The persisted, version-controlled form of a model is the **IR JSON** plus the
+**generated `.jl` script** — *not* a serialized `System` object. ModelingToolkit
+v11 changed `System` internals significantly (precompilation, removal of
+`defaults`, deprecation of `@mtkmodel`), so serializing the live object is
+brittle across versions. Regenerating from the IR is the durable path. See
+[ADR 0002](docs/decisions/0002-codegen-over-serialized-system.md) and
+[`docs/design/storing-mtk-models.md`](docs/design/storing-mtk-models.md).
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+uv run mkdocs build --strict   # same as CI
+```
+
+Documentation site (after [Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow) is set to GitHub Actions):
+[https://advanced-process-control.github.io/model-parser/](https://advanced-process-control.github.io/model-parser/)
+
+## Scope
+
+**In scope:** authoring-format parsing, the canonical IR data model + JSON
+Schema, semantic & profile validation, IR↔backend lowering/codegen.
+
+**Out of scope:** parameter identification, scenario execution, simulation
+result storage, controller synthesis, deployment. Those are sibling tools that
+*consume* the IR. The parser stays small (see
+[`AGENTS.md`](AGENTS.md) scope guardrails).