apc-model-parser 0.1.0__py3-none-any.whl

apc_model_parser-0.1.0.dist-info/METADATA

@@ -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).

apc_model_parser-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+model_parser/__init__.py,sha256=dACj1q8TSXCZLi8otXh2vmfUnCjfkrOdRYp9WKohWZU,641
+model_parser/cli.py,sha256=aIuJC6bNVei7Gy2Kp7vu8KnqDTAuEXN9s1wK6XEWSUE,6654
+model_parser/io.py,sha256=GkG2U4GILQVTq8fdb1c1tA9UOEsA69e9wdABQplDFnk,1662
+model_parser/schema.py,sha256=xvyBmFjGGKrVLNzWM2ssC1CVBPtJtgsiXHNGie0oNZM,971
+model_parser/backends/__init__.py,sha256=Y3YmRruw9whtvvtp2zmY-Ne4APNwFxNxhFSaxNxJhQA,172
+model_parser/backends/julia_mtk.py,sha256=1P79lKVEgntYrQmR2VwAl1RaJKSS66cscAmDD_W-QzE,5363
+model_parser/frontends/__init__.py,sha256=to_N4GEqlGX7-ipHuIOztOS-T8xCy8UjygMfKvOMztw,235
+model_parser/frontends/expr_parser.py,sha256=Um49TQltfDhk0qx0xotF9nVbPS0QSquz2PjgqpfSYkw,5875
+model_parser/frontends/exprtk_ini.py,sha256=JpgP_sJqYmk-huSXaReM4ZywSk6MTESAoLfAwSGYWTM,7138
+model_parser/ir/__init__.py,sha256=CIzn0srFqsefwZwDkwu__lw-JpVSLM2j3rvoI73Q8ak,813
+model_parser/ir/expr.py,sha256=890lOT1SqFPmNxzqT4c4ZiXUKz_DQKL3cW5rJDgNSlU,2837
+model_parser/ir/model.py,sha256=dPYqQOWhQnAWmGTQJ0d0gz8_FZ2O324UD2GvK08-H6Q,3887
+model_parser/validation/__init__.py,sha256=oe4BBC2AgumuIoA03tIVNtGoxlTgqfbckSjZVPU5-j4,235
+model_parser/validation/validators.py,sha256=VwTUXyQhz6uYXoYkwWxGR4lUwO0SWJgmCj5rnQQsurQ,6207
+apc_model_parser-0.1.0.dist-info/METADATA,sha256=xXObGpQrAwaDEjqRqZJJ0zk2GJUK6etYwdGl_fsJ_WE,4760
+apc_model_parser-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+apc_model_parser-0.1.0.dist-info/entry_points.txt,sha256=7Lxr9OwAdGWx007g6CSk6-J_fx6l-V7BF2Umj8tj_Yc,54
+apc_model_parser-0.1.0.dist-info/RECORD,,

apc_model_parser-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

apc_model_parser-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+model-parser = model_parser.cli:run

model_parser/__init__.py

@@ -0,0 +1,18 @@
+"""model-parser: convert process-model definitions to and from a canonical IR.
+
+The package owns the canonical intermediate representation (IR) for process
+models and the transformations around it:
+
+- **frontends** parse an authoring format (e.g. ExprTk INI) into the IR;
+- **backends** lower the IR into a target view (e.g. a ModelingToolkit Julia
+  script);
+- **validation** checks an IR against the schema and backend profiles.
+
+See ``docs/design/model-parser.md`` for the authoritative product specification.
+"""
+
+from model_parser.ir import IR_VERSION, IRModel
+
+__all__ = ["IRModel", "IR_VERSION", "__version__"]
+
+__version__ = "0.1.0"

model_parser/backends/__init__.py

@@ -0,0 +1,5 @@
+"""Backends: lower the canonical IR into target views."""
+
+from model_parser.backends.julia_mtk import emit_julia, expr_to_julia
+
+__all__ = ["emit_julia", "expr_to_julia"]

model_parser/backends/julia_mtk.py

@@ -0,0 +1,159 @@
+"""Julia / ModelingToolkit backend: lower the IR into a generated ``.jl`` script.
+
+This is the ``lower`` transformation from IR to the Julia analysis view. It
+*generates source code* rather than serializing a compiled ``System`` object —
+see ADR 0002. The generated script is a re-runnable, diffable artifact whose
+source of truth remains the IR.
+
+The emitted code targets **ModelingToolkit v11** idioms (see ADR 0004):
+
+- explicit ``System(eqs, t)`` construction (no deprecated ``@mtkmodel`` DSL);
+- ``mtkcompile`` instead of ``structural_simplify``;
+- ``t``/``D`` imported as ``t_nounits`` / ``D_nounits``;
+- parameter defaults attached via ``@parameters name = value`` (translated by
+  MTK v11 into ``initial_conditions`` for constant values);
+- inputs declared and passed to ``mtkcompile(sys; inputs = [...])``.
+"""
+
+from __future__ import annotations
+
+from model_parser.ir import Call, Expr, IRModel, Num, Sym
+
+GENERATOR = "model-parser julia-mtk backend"
+
+# IR op name -> Julia infix operator.
+_INFIX: dict[str, str] = {
+    "+": "+",
+    "-": "-",
+    "*": "*",
+    "/": "/",
+    "^": "^",
+    "==": "==",
+    "!=": "!=",
+    "<": "<",
+    ">": ">",
+    "<=": "<=",
+    ">=": ">=",
+}
+
+# IR op name -> Julia function name.
+_FUNCS: dict[str, str] = {
+    "max": "max",
+    "min": "min",
+    "sqrt": "sqrt",
+    "exp": "exp",
+    "log": "log",
+    "abs": "abs",
+    "ifelse": "ifelse",
+}
+
+
+class JuliaCodegenError(ValueError):
+    """Raised when an IR construct cannot be lowered to Julia."""
+
+
+def expr_to_julia(expr: Expr) -> str:
+    """Render an IR expression as a parenthesized Julia expression string."""
+    if isinstance(expr, Num):
+        return _render_number(expr.value)
+    if isinstance(expr, Sym):
+        return expr.name
+    if isinstance(expr, Call):
+        return _render_call(expr)
+    raise JuliaCodegenError(f"unknown expression node: {expr!r}")
+
+
+def _render_number(value: float) -> str:
+    if value.is_integer():
+        return f"{value:.1f}"
+    return repr(value)
+
+
+def _render_call(call: Call) -> str:
+    op = call.op
+    args = call.args
+    if op == "neg":
+        if len(args) != 1:
+            raise JuliaCodegenError("'neg' expects exactly one argument")
+        return f"(-{expr_to_julia(args[0])})"
+    if op in _INFIX:
+        if len(args) != 2:
+            raise JuliaCodegenError(f"operator {op!r} expects two arguments")
+        left, right = (expr_to_julia(a) for a in args)
+        return f"({left} {_INFIX[op]} {right})"
+    if op in _FUNCS:
+        rendered = ", ".join(expr_to_julia(a) for a in args)
+        return f"{_FUNCS[op]}({rendered})"
+    raise JuliaCodegenError(f"unsupported operator/function {op!r}")
+
+
+def _julia_name(ir: IRModel) -> str:
+    name = ir.model.name or "model"
+    cleaned = "".join(ch if ch.isalnum() or ch == "_" else "_" for ch in name)
+    if not cleaned or not (cleaned[0].isalpha() or cleaned[0] == "_"):
+        cleaned = f"m_{cleaned}"
+    return cleaned
+
+
+def emit_julia(ir: IRModel) -> str:
+    """Generate a ModelingToolkit v11 Julia script that builds ``ir`` as a System."""
+    name = _julia_name(ir)
+    iv = ir.independent_variable
+    lines: list[str] = []
+
+    lines.append(f"# Generated by {GENERATOR}. Do not edit by hand.")
+    lines.append("# Source of truth: the canonical IR. Regenerate after IR changes.")
+    if ir.provenance is not None:
+        lines.append(f"# IR tool: {ir.provenance.tool}")
+        if ir.provenance.content_hash:
+            lines.append(f"# IR content hash: {ir.provenance.content_hash}")
+    lines.append(f"# IR version: {ir.ir_version}")
+    lines.append("")
+    lines.append("using ModelingToolkit")
+    lines.append(f"using ModelingToolkit: t_nounits as {iv}, D_nounits as D")
+    lines.append("")
+    lines.append(f'"""Build the `{ir.model.name}` model as a compiled MTK `System`."""')
+    lines.append(f"function build_{name}()")
+
+    # Parameters with defaults.
+    if ir.parameters:
+        decls = []
+        for param in ir.parameters:
+            if param.default is None:
+                decls.append(param.name)
+            else:
+                decls.append(f"{param.name} = {_render_number(param.default)}")
+        lines.append(f"    @parameters {' '.join(decls)}")
+
+    # Time-dependent variables: states, inputs, outputs, locals.
+    tvars = (
+        [v.name for v in ir.states]
+        + [v.name for v in ir.inputs]
+        + [v.name for v in ir.outputs]
+        + [local.name for local in ir.locals]
+    )
+    if tvars:
+        decls = " ".join(f"{n}({iv})" for n in tvars)
+        lines.append(f"    @variables {decls}")
+
+    lines.append("")
+    lines.append("    eqs = [")
+    for local in ir.locals:
+        lines.append(f"        {local.name} ~ {expr_to_julia(local.expr)},")
+    for diff in ir.equations.differential:
+        lines.append(f"        D({diff.state}) ~ {expr_to_julia(diff.rhs)},")
+    for out in ir.equations.outputs:
+        lines.append(f"        {out.output} ~ {expr_to_julia(out.rhs)},")
+    lines.append("    ]")
+    lines.append("")
+    lines.append(f"    @named {name} = System(eqs, {iv})")
+
+    if ir.inputs:
+        input_list = ", ".join(v.name for v in ir.inputs)
+        lines.append(f"    return mtkcompile({name}; inputs = [{input_list}])")
+    else:
+        lines.append(f"    return mtkcompile({name})")
+
+    lines.append("end")
+    lines.append("")
+    return "\n".join(lines)

model_parser/cli.py

@@ -0,0 +1,195 @@
+"""Command-line interface for model-parser.
+
+The CLI exposes the IR transformations as composable subcommands. The two core
+verbs follow the ecosystem's transformation vocabulary:
+
+    model-parser parse  <model.ini>      # authoring format  -> canonical IR JSON
+    model-parser emit julia <model.ir.json>  # canonical IR  -> MTK Julia script
+
+Plus supporting commands: ``validate``, ``inspect``, ``ast``, and ``schema``.
+
+Exit codes:
+    0  success, no ERROR-level diagnostics
+    1  at least one ERROR diagnostic during execution
+    2  invalid usage / load failure before meaningful work
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import typer
+
+from model_parser import __version__
+from model_parser.backends import emit_julia
+from model_parser.frontends import parse_ini_file
+from model_parser.io import dumps_ir, load_ir, save_ir, with_content_hash
+from model_parser.schema import dumps_schema
+from model_parser.validation import validate_ir
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="Convert process-model definitions to and from a canonical IR.",
+)
+emit_app = typer.Typer(no_args_is_help=True, help="Lower the canonical IR into a target view.")
+app.add_typer(emit_app, name="emit")
+
+_err = typer.style("error:", fg=typer.colors.RED, bold=True)
+_warn = typer.style("warning:", fg=typer.colors.YELLOW, bold=True)
+
+
+def _echo_err(message: str) -> None:
+    typer.echo(f"{_err} {message}", err=True)
+
+
+def _echo_warn(message: str) -> None:
+    typer.echo(f"{_warn} {message}", err=True)
+
+
+@app.callback(invoke_without_command=True)
+def _main(
+    version: bool = typer.Option(
+        False, "--version", help="Show the version and exit.", is_eager=True
+    ),
+) -> None:
+    if version:
+        typer.echo(f"model-parser {__version__}")
+        raise typer.Exit()
+
+
+@app.command()
+def parse(
+    source: Path = typer.Argument(..., exists=True, readable=True, help="Authoring file."),
+    output: Path | None = typer.Option(
+        None, "-o", "--output", help="IR JSON output path (default: stdout)."
+    ),
+    from_format: str = typer.Option(
+        "exprtk-ini", "--from", help="Authoring format of the source file."
+    ),
+) -> None:
+    """Parse an authoring file (default: ExprTk INI) into canonical IR JSON."""
+    if from_format != "exprtk-ini":
+        _echo_err(f"unsupported source format {from_format!r} (only 'exprtk-ini' for now)")
+        raise typer.Exit(code=2)
+
+    result = parse_ini_file(str(source))
+    ir = with_content_hash(result.ir)
+    for warning in result.warnings:
+        _echo_warn(warning)
+
+    if output is None:
+        typer.echo(dumps_ir(ir), nl=False)
+    else:
+        save_ir(ir, output)
+        typer.echo(f"wrote IR to {output}", err=True)
+
+
+@emit_app.command("julia")
+def emit_julia_cmd(
+    ir_file: Path = typer.Argument(..., exists=True, readable=True, help="IR JSON file."),
+    output: Path | None = typer.Option(
+        None, "-o", "--output", help="Julia output path (default: stdout)."
+    ),
+) -> None:
+    """Generate a ModelingToolkit (v11) Julia script from an IR file."""
+    ir = load_ir(ir_file)
+    code = emit_julia(ir)
+    if output is None:
+        typer.echo(code, nl=False)
+    else:
+        Path(output).write_text(code, encoding="utf-8")
+        typer.echo(f"wrote Julia model to {output}", err=True)
+
+
+@app.command()
+def validate(
+    target: Path = typer.Argument(..., exists=True, readable=True, help="IR JSON or INI file."),
+    profile: str | None = typer.Option(
+        None, "--profile", help="Backend profile to check (e.g. julia-analysis, realtime-cpp)."
+    ),
+) -> None:
+    """Validate an IR (or an INI parsed on the fly) and report diagnostics."""
+    ir = _load_any(target)
+    report = validate_ir(ir, profile=profile)
+    for diag in report.diagnostics:
+        prefix = _err if diag.level == "ERROR" else _warn
+        typer.echo(f"{prefix} [{diag.code}] {diag.message}", err=True)
+    if report.ok:
+        typer.echo(f"OK: {ir.model.name} valid" + (f" for profile {profile!r}" if profile else ""))
+    else:
+        typer.echo(f"FAILED: {len(report.errors)} error(s)", err=True)
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def inspect(
+    target: Path = typer.Argument(..., exists=True, readable=True, help="IR JSON or INI file."),
+) -> None:
+    """Print a human-readable summary of a model."""
+    ir = _load_any(target)
+    typer.echo(f"model:       {ir.model.name}")
+    if ir.model.description:
+        typer.echo(f"description: {ir.model.description}")
+    typer.echo(f"ir version:  {ir.ir_version}")
+    typer.echo(f"states:      {len(ir.states)}  ({', '.join(v.name for v in ir.states)})")
+    typer.echo(f"inputs:      {len(ir.inputs)}  ({', '.join(v.name for v in ir.inputs)})")
+    typer.echo(f"outputs:     {len(ir.outputs)}  ({', '.join(v.name for v in ir.outputs)})")
+    typer.echo(f"parameters:  {len(ir.parameters)}")
+    typer.echo(f"locals:      {len(ir.locals)}")
+    typer.echo(f"profiles:    {', '.join(ir.profiles)}")
+    if ir.provenance and ir.provenance.content_hash:
+        typer.echo(f"hash:        {ir.provenance.content_hash}")
+
+
+@app.command()
+def ast(
+    source: Path = typer.Argument(..., exists=True, readable=True, help="ExprTk INI file."),
+    output: Path | None = typer.Option(
+        None, "-o", "--output", help="AST/IR debug JSON output path (default: stdout)."
+    ),
+) -> None:
+    """Export the parsed IR as a debug JSON tree (parser inspection)."""
+    result = parse_ini_file(str(source))
+    text = dumps_ir(result.ir)
+    if output is None:
+        typer.echo(text, nl=False)
+    else:
+        Path(output).write_text(text, encoding="utf-8")
+        typer.echo(f"wrote debug tree to {output}", err=True)
+
+
+@app.command()
+def schema(
+    output: Path | None = typer.Option(
+        None, "-o", "--output", help="JSON Schema output path (default: stdout)."
+    ),
+) -> None:
+    """Print or write the canonical IR JSON Schema."""
+    text = dumps_schema()
+    if output is None:
+        typer.echo(text, nl=False)
+    else:
+        Path(output).write_text(text, encoding="utf-8")
+        typer.echo(f"wrote schema to {output}", err=True)
+
+
+def _load_any(path: Path):
+    """Load an IR from a ``.json`` file, or parse an INI file on the fly."""
+    if path.suffix.lower() == ".json":
+        return load_ir(path)
+    return parse_ini_file(str(path)).ir
+
+
+def run() -> None:
+    """Entry point wrapper that maps uncaught errors to exit code 2."""
+    try:
+        app()
+    except (ValueError, FileNotFoundError) as exc:  # parse/codegen errors
+        _echo_err(str(exc))
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    run()

model_parser/frontends/__init__.py

@@ -0,0 +1,9 @@
+"""Frontends: parse authoring formats into the canonical IR."""
+
+from model_parser.frontends.exprtk_ini import (
+    ParseResult,
+    parse_ini_file,
+    parse_ini_text,
+)
+
+__all__ = ["ParseResult", "parse_ini_file", "parse_ini_text"]