modelable 1.0.0__py3-none-any.whl

modelable/commands/scenario.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+console = Console()
+
+_REPO_ROOT = Path(__file__).resolve().parents[4]
+_SCENARIOS_DIR = _REPO_ROOT / "samples" / "scenarios"
+_SAMPLES_README = _REPO_ROOT / "samples" / "README.md"
+_ROW_PATTERN = re.compile(
+    r"^\|\s*\d+\s*\|\s*`(?P<id>[^`]+)`\s*\|\s*(?P<title>[^|]+?)\s*\|",
+    re.MULTILINE,
+)
+
+
+@dataclass(frozen=True)
+class ScenarioInfo:
+    scenario_id: str
+    title: str
+    path: Path
+
+
+def register_scenario_commands(cli_group: click.Group) -> None:
+    cli_group.add_command(scenario)
+
+
+@click.group()
+def scenario() -> None:
+    """Browse and load bundled sample scenarios."""
+
+
+@scenario.command(name="list")
+def list_scenarios() -> None:
+    """List bundled scenario IDs and titles."""
+    for index, info in enumerate(_load_scenarios(), start=1):
+        console.print(f"{index}. {info.scenario_id} - {info.title}")
+
+
+@scenario.command(name="show")
+@click.argument("scenario_id")
+def show_scenario(scenario_id: str) -> None:
+    """Show the contents of a bundled sample scenario."""
+    info = _find_scenario(scenario_id)
+    if info is None:
+        raise click.ClickException(f"unknown scenario: {scenario_id}")
+
+    console.print(f"{info.scenario_id} - {info.title}")
+    for path in _scenario_files(info.path):
+        console.print(f"[bold]{path.name}[/bold]")
+        console.print(path.read_text(encoding="utf-8").rstrip())
+
+
+@scenario.command(name="load")
+@click.argument("scenario_id")
+@click.option(
+    "--output-dir",
+    "output_dir",
+    type=click.Path(path_type=Path),
+    default=Path("."),
+    show_default=True,
+    help="Destination directory for the copied scenario.",
+)
+def load_scenario(scenario_id: str, output_dir: Path) -> None:
+    """Copy a bundled sample scenario into a working directory."""
+    info = _find_scenario(scenario_id)
+    if info is None:
+        raise click.ClickException(f"unknown scenario: {scenario_id}")
+
+    target = output_dir / scenario_id
+    shutil.copytree(info.path, target)
+    console.print(f"[green]OK[/green] wrote {target}")
+
+
+def _load_scenarios() -> list[ScenarioInfo]:
+    titles = _parse_readme_titles()
+    infos: list[ScenarioInfo] = []
+    for scenario_dir in sorted(
+        [path for path in _SCENARIOS_DIR.iterdir() if path.is_dir()],
+        key=lambda path: path.name,
+    ):
+        title = titles.get(scenario_dir.name, scenario_dir.name)
+        infos.append(ScenarioInfo(scenario_dir.name, title, scenario_dir))
+    return infos
+
+
+def _parse_readme_titles() -> dict[str, str]:
+    if not _SAMPLES_README.exists():
+        return {}
+    text = _SAMPLES_README.read_text(encoding="utf-8")
+    return {match.group("id"): match.group("title").strip() for match in _ROW_PATTERN.finditer(text)}
+
+
+def _find_scenario(scenario_id: str) -> ScenarioInfo | None:
+    return next((info for info in _load_scenarios() if info.scenario_id == scenario_id), None)
+
+
+def _scenario_files(path: Path) -> list[Path]:
+    return sorted(path.glob("*.mdl"), key=lambda item: item.name)

modelable/commands/spec.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from modelable.specs.tracking import (
+    SpecEntry,
+    add_spec,
+    change_dicts,
+    evaluate_spec,
+    select_specs,
+    spec_config_path,
+)
+
+console = Console()
+
+
+def register_spec_commands(cli_group: click.Group) -> None:
+    cli_group.add_command(spec)
+
+
+@click.group()
+def spec() -> None:
+    """Track external specifications and detect drift."""
+
+
+@spec.command(name="add")
+@click.argument("spec_id")
+@click.option("--kind", required=True, help="Tracked spec kind, for example dbt, fhir, or odcs.")
+@click.option("--source", required=True, help="Local external specification path.")
+@click.option("--ref", "model_ref", required=True, help="Modelable model reference, for example domain.Model@1.")
+@click.option("--source-name", default=None, help="Named source object inside multi-object specs.")
+@click.option("--path", "workspace_path", type=click.Path(exists=True, path_type=Path), default=Path("."))
+@click.option(
+    "--update-policy", default="preview", help="Default update policy. Currently informational; defaults to preview."
+)
+def add(
+    spec_id: str,
+    kind: str,
+    source: str,
+    model_ref: str,
+    source_name: str | None,
+    workspace_path: Path,
+    update_policy: str,
+) -> None:
+    """Add a tracked external specification."""
+    try:
+        path = add_spec(
+            workspace_path,
+            SpecEntry(
+                id=spec_id,
+                kind=kind.lower(),
+                source=source,
+                ref=model_ref,
+                source_name=source_name,
+                update_policy=update_policy,
+            ),
+        )
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+    console.print(f"[green]OK[/green] added tracked spec {spec_id} to {path}")
+
+
+@spec.command(name="status")
+@click.option("--path", "workspace_path", type=click.Path(exists=True, path_type=Path), default=Path("."))
+@click.option("--json", "json_output", is_flag=True, help="Print machine-readable JSON.")
+@click.option("--fail-on", default="", help="Comma-separated statuses that should return a non-zero exit code.")
+def status(workspace_path: Path, json_output: bool, fail_on: str) -> None:
+    """Report drift status for tracked external specifications."""
+    token = os.getenv("MODELABLE_SPEC_TOKEN")
+    entries = select_specs(workspace_path, None)
+    evaluations = [evaluate_spec(workspace_path, entry, write=False, token=token) for entry in entries]
+    payload = {"specs": [evaluation.as_status_dict() for evaluation in evaluations]}
+    if json_output:
+        click.echo(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        if not evaluations:
+            console.print(f"[yellow]No tracked specs in {spec_config_path(workspace_path)}[/yellow]")
+        for evaluation in evaluations:
+            suffix = ""
+            if evaluation.change_kind:
+                suffix = f" ({evaluation.change_kind}, {evaluation.change_count} change(s))"
+            if evaluation.error:
+                suffix = f" ({evaluation.error})"
+            console.print(f"{evaluation.entry.id}: {evaluation.status}{suffix}")
+    fail_statuses = {item.strip() for item in fail_on.split(",") if item.strip()}
+    if fail_statuses and any(evaluation.status in fail_statuses for evaluation in evaluations):
+        raise click.ClickException("tracked spec status matched --fail-on")
+
+
+@spec.command(name="diff")
+@click.argument("spec_id")
+@click.option("--path", "workspace_path", type=click.Path(exists=True, path_type=Path), default=Path("."))
+@click.option("--json", "json_output", is_flag=True, help="Print machine-readable JSON.")
+def diff(spec_id: str, workspace_path: Path, json_output: bool) -> None:
+    """Compare one tracked specification against its bound Modelable model."""
+    token = os.getenv("MODELABLE_SPEC_TOKEN")
+    try:
+        entry = select_specs(workspace_path, spec_id)[0]
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+    evaluation = evaluate_spec(workspace_path, entry, write=False, token=token)
+    payload = evaluation.as_status_dict()
+    if evaluation.result is not None:
+        payload["changes"] = change_dicts(evaluation.result)
+    if json_output:
+        click.echo(json.dumps(payload, indent=2, sort_keys=True))
+        return
+    if evaluation.error:
+        raise click.ClickException(evaluation.error)
+    if evaluation.status == "clean":
+        console.print(f"[green]OK[/green] {spec_id} is clean")
+        return
+    console.print(f"{spec_id}: {evaluation.change_kind} drift")
+    for change in payload.get("changes", []):
+        console.print(f"- {change['kind']}: {change['field_name']}")
+
+
+@spec.command(name="sync")
+@click.argument("spec_id", required=False)
+@click.option("--path", "workspace_path", type=click.Path(exists=True, path_type=Path), default=Path("."))
+@click.option("--preview", is_flag=True, help="Show proposed changes without writing.")
+@click.option("--write", "write_changes", is_flag=True, help="Write proposed .mdl changes.")
+def sync(spec_id: str | None, workspace_path: Path, preview: bool, write_changes: bool) -> None:
+    """Synchronize tracked specs into reviewed Modelable version updates."""
+    if preview and write_changes:
+        raise click.UsageError("choose either --preview or --write")
+    write = write_changes
+    try:
+        entries = select_specs(workspace_path, spec_id)
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+    if not preview and not write:
+        preview = True
+
+    token = os.getenv("MODELABLE_SPEC_TOKEN")
+    for entry in entries:
+        evaluation = evaluate_spec(workspace_path, entry, write=write, token=token)
+        if evaluation.error:
+            raise click.ClickException(f"{entry.id}: {evaluation.error}")
+        result = evaluation.result
+        if result is None:
+            continue
+        if not result.attached:
+            console.print(f"[green]OK[/green] {entry.id} already matches {entry.ref}; no new version created")
+            continue
+        if preview:
+            console.print(_render_preview(result.original_content, result.content))
+            continue
+        _write_spec_attachment_record(entry.id, result.path, evaluation)
+        console.print(result.content.rstrip())
+        console.print(f"[green]OK[/green] synced {entry.id}; new version {result.to_version} ({result.change_kind})")
+
+
+def _render_preview(original: str, updated: str) -> str:
+    import difflib
+
+    return "\n".join(
+        difflib.unified_diff(
+            original.splitlines(),
+            updated.splitlines(),
+            fromfile="current",
+            tofile="tracked-spec",
+            lineterm="",
+        )
+    )
+
+
+def _write_spec_attachment_record(spec_id: str, artifact_path: Path, evaluation) -> Path:
+    result = evaluation.result
+    if result is None:
+        raise ValueError("cannot write attachment record without an attach result")
+    sidecar_path = artifact_path.with_name(f"{artifact_path.name}.attachments.json")
+    records: list[dict[str, object]] = []
+    if sidecar_path.exists():
+        records = json.loads(sidecar_path.read_text(encoding="utf-8"))
+    records.append(
+        {
+            "spec_id": spec_id,
+            "ref": result.ref,
+            "source_format": result.source_format,
+            "source_name": result.source_name,
+            "source_path": result.source_descriptor,
+            "source_hash": result.source_hash,
+            "from_version": result.from_version,
+            "to_version": result.to_version,
+            "change_kind": result.change_kind,
+            "changes": [asdict(change) for change in result.changes],
+        }
+    )
+    sidecar_path.write_text(json.dumps(records, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    return sidecar_path

modelable/commands/workspace.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from modelable.commands.common import console, load_workspace_or_exit, render_version_spec
+from modelable.llm.context import parse_model_ref_version_spec
+from modelable.llm.render import render_model_version, render_projection_version
+from modelable.planner.lineage import build_projection_lineage
+from modelable.registry.resolver import resolve_model_ref
+
+
+def register_workspace_commands(cli_group: click.Group) -> None:
+    cli_group.add_command(validate)
+    cli_group.add_command(resolve)
+    cli_group.add_command(lineage)
+    cli_group.add_command(inspect)
+
+
+@click.command()
+@click.argument("path", default=".", type=click.Path(exists=True, path_type=Path))
+@click.option("--strict", is_flag=True, help="Exit non-zero on any validation error.")
+def validate(path: Path, strict: bool) -> None:
+    """Validate Modelable definition files at PATH."""
+    workspace = load_workspace_or_exit(path)
+
+    if len(workspace.sources) == 1:
+        console.print(f"[green]OK[/green] {workspace.sources[0].path} is valid.")
+    else:
+        console.print(f"[green]OK[/green] {len(workspace.sources)} files valid.")
+
+    sys.exit(0)
+
+
+@click.command()
+@click.argument("ref")
+@click.option("--path", "path", type=click.Path(exists=True, path_type=Path), default=".")
+def resolve(ref: str, path: Path) -> None:
+    """Resolve and print a normalized model or projection definition."""
+    workspace = load_workspace_or_exit(path)
+
+    try:
+        domain, name, version_spec = parse_model_ref_version_spec(ref)
+        resolved = resolve_model_ref(workspace.mdl, domain + "." + name, version_spec)
+    except (ValueError, LookupError) as exc:
+        console.print(f"[red]ERROR[/red] {exc}")
+        sys.exit(1)
+
+    domain = next((d for d in workspace.mdl.domains if d.name == resolved.domain_name), None)
+    if domain is None:
+        console.print(f"[red]ERROR[/red] domain '{resolved.domain_name}' not found.")
+        sys.exit(1)
+
+    model_versions = domain.models.get(resolved.model_name, [])
+    model_version = next((version for version in model_versions if version.version == resolved.version.version), None)
+    if model_version is not None:
+        console.print(
+            render_model_version(domain.name, resolved.model_name, model_version, domain.owner, domain.description),
+            end="",
+        )
+        sys.exit(0)
+
+    projection_versions = domain.projections.get(resolved.model_name, [])
+    projection_version = next(
+        (version for version in projection_versions if version.version == resolved.version.version),
+        None,
+    )
+    if projection_version is not None:
+        console.print(
+            render_projection_version(
+                domain.name,
+                resolved.model_name,
+                projection_version,
+                domain.owner,
+                domain.description,
+            ),
+            end="",
+        )
+        sys.exit(0)
+
+    console.print(f"[red]ERROR[/red] unresolved reference {ref}")
+    sys.exit(1)
+
+
+@click.command()
+@click.argument("ref")
+@click.option("--path", "path", type=click.Path(exists=True, path_type=Path), default=".")
+def lineage(ref: str, path: Path) -> None:
+    """Show field-level lineage for a model or projection."""
+    workspace = load_workspace_or_exit(path)
+
+    try:
+        domain, name, version_spec = parse_model_ref_version_spec(ref)
+        resolved = resolve_model_ref(workspace.mdl, domain + "." + name, version_spec)
+    except (ValueError, LookupError) as exc:
+        console.print(f"[red]ERROR[/red] {exc}")
+        sys.exit(1)
+
+    domain = next((d for d in workspace.mdl.domains if d.name == resolved.domain_name), None)
+    if domain is None:
+        console.print(f"[red]ERROR[/red] domain '{resolved.domain_name}' not found.")
+        sys.exit(1)
+
+    model_versions = domain.models.get(resolved.model_name, [])
+    model_version = next(
+        (version for version in model_versions if version.version == resolved.version.version),
+        None,
+    )
+    if model_version is not None:
+        console.print(f"{domain.name}.{resolved.model_name}@{model_version.version}")
+        console.print(f"kind: {model_version.model_kind.value}")
+        for field in model_version.fields:
+            flags = []
+            if field.is_key:
+                flags.append("key")
+            if field.is_pii:
+                flags.append("pii")
+            if field.classification:
+                flags.append(f"classification={field.classification.value}")
+            suffix = f" [{', '.join(flags)}]" if flags else ""
+            console.print(f"- {field.name}: {field.type.kind}{suffix}", markup=False)
+        sys.exit(0)
+
+    projection_versions = domain.projections.get(resolved.model_name, [])
+    projection_version = next(
+        (version for version in projection_versions if version.version == resolved.version.version),
+        None,
+    )
+    if projection_version is not None:
+        lineage = build_projection_lineage(domain.name, resolved.model_name, projection_version, workspace.mdl)
+        console.print(f"{domain.name}.{resolved.model_name}@{projection_version.version}")
+        console.print(
+            f"source: {projection_version.source.model} @ {render_version_spec(projection_version.source.version)} as {projection_version.source.alias}"
+        )
+        if projection_version.joins:
+            for join in projection_version.joins:
+                console.print(f"join: {join.model} @ {render_version_spec(join.version)} as {join.alias} on {join.on}")
+        if projection_version.group_by:
+            console.print(f"group by: {', '.join(projection_version.group_by)}")
+        by_name = {item.field_name: item for item in lineage.fields}
+        for field in projection_version.fields:
+            field_lineage = by_name.get(field.name)
+            if field_lineage is None:
+                console.print(f"- {field.name}: unknown")
+                continue
+            console.print(f"- {field.name}: {field_lineage.kind}")
+            for source in field_lineage.lineage:
+                console.print(f"  <- {source}")
+            if field_lineage.expression:
+                console.print(f"  expr: {field_lineage.expression}")
+        sys.exit(0)
+
+    console.print(f"[red]ERROR[/red] unresolved reference {ref}")
+    sys.exit(1)
+
+
+@click.command()
+@click.argument("ref")
+@click.option("--auto", is_flag=True, help="Display generated auto projections.")
+@click.option("--path", "path", type=click.Path(exists=True, path_type=Path), default=".")
+def inspect(ref: str, auto: bool, path: Path) -> None:
+    """Inspect a model or projection at REF (domain.Model@version)."""
+    workspace = load_workspace_or_exit(path)
+
+    try:
+        domain_name, model_name, version_spec = _parse_entity_ref_version_spec(ref)
+    except click.BadParameter as exc:
+        console.print(f"[red]ERROR[/red] {exc}")
+        sys.exit(1)
+
+    domain = next((d for d in workspace.mdl.domains if d.name == domain_name), None)
+    if domain is None:
+        console.print(f"[red]ERROR[/red] domain '{domain_name}' not found.")
+        sys.exit(1)
+
+    try:
+        resolved = resolve_model_ref(workspace.mdl, domain_name + "." + model_name, version_spec)
+    except LookupError as exc:
+        console.print(f"[red]ERROR[/red] {exc}")
+        sys.exit(1)
+
+    version = resolved.version.version
+
+    if auto:
+        model_versions = domain.models.get(model_name)
+        if not model_versions:
+            console.print(f"[red]ERROR[/red] model '{model_name}' not found in domain '{domain_name}'.")
+            sys.exit(1)
+
+        targets = ["db", "request", "reply", "event"]
+        for kind in targets:
+            projection_name = f"{model_name}{kind.capitalize()}"
+            if kind == "db":
+                projection_name = f"{model_name}Db"
+            versions = domain.projections.get(projection_name)
+            if not versions:
+                continue
+            pv = next((v for v in versions if v.version == version), None)
+            if pv is None:
+                continue
+            console.print(f"[bold]{domain_name}.{projection_name}@{pv.version}[/bold] (auto {kind})")
+            for field in pv.fields:
+                console.print(f"  {field.name}")
+        sys.exit(0)
+
+    model_versions = domain.models.get(model_name, [])
+    model_version = next((mv for mv in model_versions if mv.version == version), None)
+    if model_version is not None:
+        console.print(
+            render_model_version(domain.name, model_name, model_version, domain.owner, domain.description), end=""
+        )
+        sys.exit(0)
+
+    projection_versions = domain.projections.get(model_name, [])
+    projection_version = next((pv for pv in projection_versions if pv.version == version), None)
+    if projection_version is not None:
+        console.print(
+            render_projection_version(domain.name, model_name, projection_version, domain.owner, domain.description),
+            end="",
+        )
+        sys.exit(0)
+
+    console.print(f"[red]ERROR[/red] '{model_name}@{version}' not found in domain '{domain.name}'.")
+    sys.exit(1)
+
+
+def _parse_entity_ref_version_spec(ref: str) -> tuple[str, str, int | object]:
+    if "@" not in ref:
+        raise click.BadParameter("REF must be in the form domain.Model@version")
+    model_ref, _version_str = ref.rsplit("@", 1)
+    parts = model_ref.split(".")
+    if len(parts) != 2:
+        raise click.BadParameter("REF must be in the form domain.Model@version")
+    try:
+        _, _, version_spec = parse_model_ref_version_spec(ref)
+    except ValueError as exc:
+        raise click.BadParameter(str(exc)) from exc
+    return parts[0], parts[1], version_spec

modelable/compat/__init__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from .checker import CompatibilityReport, check_model_version_compatibility
+from .diff import FieldChange, compare_model_versions
+
+__all__ = [
+    "CompatibilityReport",
+    "FieldChange",
+    "check_model_version_compatibility",
+    "compare_model_versions",
+]