modelable 1.0.0__py3-none-any.whl

modelable/registry/schema.sql

@@ -0,0 +1,119 @@
+create table domains (
+  name text primary key,
+  owner text,
+  description text
+);
+
+create table models (
+  domain_name text not null,
+  name text not null,
+  kind text not null,
+  primary key (domain_name, name)
+);
+
+create table model_versions (
+  domain_name text not null,
+  model_name text not null,
+  version integer not null,
+  change_kind text not null,
+  source_path text not null,
+  primary key (domain_name, model_name, version)
+);
+
+create table fields (
+  domain_name text not null,
+  model_name text not null,
+  model_version integer not null,
+  field_name text not null,
+  position integer not null,
+  type_json text not null,
+  optional integer not null,
+  is_key integer not null,
+  is_pii integer not null,
+  classification text,
+  primary key (domain_name, model_name, model_version, field_name)
+);
+
+create table projections (
+  domain_name text not null,
+  name text not null,
+  primary key (domain_name, name)
+);
+
+create table projection_versions (
+  domain_name text not null,
+  projection_name text not null,
+  version integer not null,
+  source_model text not null,
+  source_version_json text not null,
+  source_alias text not null,
+  primary key (domain_name, projection_name, version)
+);
+
+create table projection_sources (
+  domain_name text not null,
+  projection_name text not null,
+  projection_version integer not null,
+  source_kind text not null,
+  source_model text not null,
+  source_version_json text not null,
+  source_alias text not null,
+  join_on text
+);
+
+create table projection_fields (
+  domain_name text not null,
+  projection_name text not null,
+  projection_version integer not null,
+  field_name text not null,
+  position integer not null,
+  mapping_json text not null,
+  is_pii integer not null,
+  classification text,
+  primary key (domain_name, projection_name, projection_version, field_name)
+);
+
+create table field_mappings (
+  domain_name text not null,
+  projection_name text not null,
+  projection_version integer not null,
+  target_field text not null,
+  mapping_kind text not null,
+  source_alias text,
+  source_field text,
+  expression text
+);
+
+create table lineage_edges (
+  source_ref text not null,
+  target_ref text not null,
+  edge_kind text not null
+);
+
+create table adapter_bindings (
+  name text primary key,
+  model_ref text not null,
+  adapter text not null,
+  table_name text
+);
+
+create table compatibility_reports (
+  domain_name text not null,
+  model_name text not null,
+  from_version integer not null,
+  to_version integer not null,
+  status text not null
+);
+
+create table access_policies (
+  subject_ref text not null,
+  action text not null,
+  grantee text not null
+);
+
+create table por_log (
+  model_ref text not null,
+  issuer text not null,
+  issued_at text not null,
+  signature text
+);

modelable/registry/signature.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import hashlib
+
+from modelable.parser.ir import ModelVersion, ProjectionVersion
+
+
+def compute_version_signature(domain_name: str, model_name: str, version: ModelVersion | ProjectionVersion) -> str:
+    """Return the canonical SHA-256 signature for a published model or projection version."""
+    from modelable.llm.render import render_model_version, render_projection_version
+
+    if isinstance(version, ModelVersion):
+        text = render_model_version(domain_name, model_name, _sorted_model_version(version))
+    elif isinstance(version, ProjectionVersion):
+        text = render_projection_version(domain_name, model_name, _sorted_projection_version(version))
+    else:
+        raise TypeError(f"unsupported version type: {type(version)!r}")
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _sorted_model_version(version: ModelVersion) -> ModelVersion:
+    return version.model_copy(update={"fields": sorted(version.fields, key=lambda field: field.name)})
+
+
+def _sorted_projection_version(version: ProjectionVersion) -> ProjectionVersion:
+    return version.model_copy(update={"fields": sorted(version.fields, key=lambda field: field.name)})

modelable/release.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import tomllib
+from pathlib import Path
+from typing import Any, cast
+
+
+def load_package_version(pyproject_path: Path) -> str:
+    with pyproject_path.open("rb") as fh:
+        data = tomllib.load(fh)
+    return cast(str, data["project"]["version"])
+
+
+def _artifact_kind(path: Path) -> str | None:
+    if path.name.endswith(".whl"):
+        return "wheel"
+    if path.name.endswith(".tar.gz"):
+        return "sdist"
+    if path.name.endswith(".vsix"):
+        return "vsix"
+    return None
+
+
+def build_release_manifest(
+    *,
+    dist_dir: Path,
+    commit_sha: str,
+    git_tag: str | None,
+    package_version: str,
+    python_version: str,
+    build_timestamp: str,
+    repository_url: str = "https://github.com/ktjn/modelable",
+    license_expression: str = "Apache-2.0",
+    workflow_run_url: str | None = None,
+    extension_version: str | None = None,
+) -> dict[str, Any]:
+    tag_version = git_tag.removeprefix("v") if git_tag else None
+    if tag_version is not None and tag_version != package_version:
+        raise ValueError(f"package version {package_version} does not match release tag {git_tag}")
+
+    wheel: dict[str, str] | None = None
+    sdist: dict[str, str] | None = None
+    vsix: dict[str, str] | None = None
+    checksum_lines: list[str] = []
+
+    for artifact in sorted(dist_dir.iterdir()):
+        if not artifact.is_file() or artifact.name in {"SHA256SUMS", "release-manifest.json"}:
+            continue
+        digest = hashlib.sha256(artifact.read_bytes()).hexdigest()
+        checksum_lines.append(f"{digest}  {artifact.name}")
+        kind = _artifact_kind(artifact)
+        if kind == "wheel":
+            wheel = {"filename": artifact.name, "sha256": digest}
+        elif kind == "sdist":
+            sdist = {"filename": artifact.name, "sha256": digest}
+        elif kind == "vsix":
+            vsix = {"filename": artifact.name, "sha256": digest}
+
+    if wheel is None:
+        raise ValueError(f"no wheel artifact found in {dist_dir}")
+    if sdist is None:
+        raise ValueError(f"no sdist artifact found in {dist_dir}")
+    if extension_version is not None and vsix is None:
+        raise ValueError(f"no VS Code extension artifact found in {dist_dir}")
+
+    manifest = {
+        "package_name": "modelable",
+        "package_version": package_version,
+        "git_sha": commit_sha,
+        "git_tag": git_tag,
+        "python_version": python_version,
+        "build_timestamp": build_timestamp,
+        "repository_url": repository_url,
+        "license": license_expression,
+        "workflow_run_url": workflow_run_url,
+        "extension_version": extension_version,
+        "artifacts": {
+            "wheel": wheel,
+            "sdist": sdist,
+            **({"vsix": vsix} if vsix is not None else {}),
+        },
+    }
+
+    (dist_dir / "SHA256SUMS").write_text("\n".join(checksum_lines) + "\n", encoding="utf-8")
+    (dist_dir / "release-manifest.json").write_text(
+        json.dumps(manifest, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    return manifest
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--dist", required=True, type=Path)
+    parser.add_argument("--commit-sha", required=True)
+    parser.add_argument("--git-tag")
+    parser.add_argument("--package-version", required=True)
+    parser.add_argument("--python-version", required=True)
+    parser.add_argument("--build-timestamp", required=True)
+    parser.add_argument("--repository-url", default="https://github.com/ktjn/modelable")
+    parser.add_argument("--license-expression", default="Apache-2.0")
+    parser.add_argument("--workflow-run-url")
+    parser.add_argument("--extension-version")
+    args = parser.parse_args(argv)
+
+    build_release_manifest(
+        dist_dir=args.dist,
+        commit_sha=args.commit_sha,
+        git_tag=args.git_tag,
+        package_version=args.package_version,
+        python_version=args.python_version,
+        build_timestamp=args.build_timestamp,
+        repository_url=args.repository_url,
+        license_expression=args.license_expression,
+        workflow_run_url=args.workflow_run_url,
+        extension_version=args.extension_version,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

modelable/runtime/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .adapter import base
+
+__all__ = ["base"]

modelable/runtime/adapter/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from .base import RuntimeAdapter
+from .postgres import PostgresAdapter
+
+__all__ = ["RuntimeAdapter", "get_adapter"]
+
+_ADAPTERS = {
+    "postgres": PostgresAdapter,
+}
+
+
+def get_adapter(adapter_type: str) -> RuntimeAdapter:
+    adapter_class = _ADAPTERS.get(adapter_type)
+    if not adapter_class:
+        raise ValueError(f"Unknown adapter type: {adapter_type}")
+    return adapter_class()

modelable/runtime/adapter/base.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class RuntimeAdapter(ABC):
+    """Base interface for Modelable runtime adapters."""
+
+    @abstractmethod
+    def bootstrap(self, config: dict[str, Any]) -> None:
+        """Initialize the target environment."""
+        ...
+
+    @abstractmethod
+    def materialize(self, projection_plan: dict[str, Any], data: Any) -> None:
+        """Stream or update data into the target materialization."""
+        ...

modelable/runtime/adapter/postgres.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from typing import Any
+
+import psycopg
+
+from modelable.parser.ir import DecimalType, EnumType, FieldType, PrimitiveType
+
+from .base import RuntimeAdapter
+
+
+def type_to_postgres(field_type: FieldType) -> str:
+    # ... (rest of implementation)
+    mapping = {
+        "string": "TEXT",
+        "int": "INTEGER",
+        "float": "DOUBLE PRECISION",
+        "bool": "BOOLEAN",
+        "date": "DATE",
+        "time": "TIME",
+        "timestamp": "TIMESTAMP",
+        "uuid": "UUID",
+        "duration": "INTERVAL",
+        "binary": "BYTEA",
+    }
+    if isinstance(field_type, PrimitiveType):
+        return mapping.get(field_type.kind, "TEXT")
+    if isinstance(field_type, DecimalType):
+        return f"NUMERIC({field_type.precision}, {field_type.scale})"
+    if isinstance(field_type, EnumType):
+        return "TEXT"
+    return "TEXT"
+
+
+class PostgresAdapter(RuntimeAdapter):
+    """PostgreSQL runtime adapter."""
+
+    def bootstrap(self, config: dict[str, Any]) -> None:
+        """Initialize the PostgreSQL environment."""
+        conn_str = config["connection_string"]
+        with psycopg.connect(conn_str) as conn, conn.cursor() as cur:
+            # Example: create a schema if configured
+            schema = config.get("schema", "public")
+            cur.execute(f"CREATE SCHEMA IF NOT EXISTS {schema}")
+            conn.commit()
+
+    def materialize(self, projection_plan: dict[str, Any], data: Any) -> None:
+        """Stream or update data into the target materialization."""
+        # This implementation assumes data is a list of dictionaries where keys match projection field names
+        # and projection_plan contains 'table_name' and 'keys'.
+        table_name = projection_plan["table_name"]
+        keys = projection_plan["keys"]
+        conn_str = projection_plan["connection_string"]
+
+        with psycopg.connect(conn_str) as conn, conn.cursor() as cur:
+            for record in data:
+                columns = record.keys()
+                values = [record[col] for col in columns]
+
+                # Construct UPSERT
+                col_names = ", ".join(columns)
+                placeholders = ", ".join(["%s"] * len(columns))
+                update_stmt = ", ".join([f"{col} = EXCLUDED.{col}" for col in columns if col not in keys])
+
+                query = f"""
+                        INSERT INTO {table_name} ({col_names})
+                        VALUES ({placeholders})
+                        ON CONFLICT ({", ".join(keys)})
+                        DO UPDATE SET {update_stmt};
+                    """
+
+                cur.execute(query, values)
+            conn.commit()
+
+    def generate_table_ddl(self, table_name: str, fields: list[Any]) -> str:
+        """Generate DDL for a projection table."""
+        columns = []
+        for field in fields:
+            pg_type = type_to_postgres(field.type)
+            columns.append(f"{field.name} {pg_type}")
+
+        return f"CREATE TABLE IF NOT EXISTS {table_name} (\n  {', '.join(columns)}\n);"

modelable/specs/__init__.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from .tracking import (
+    SpecEntry,
+    SpecEvaluation,
+    SpecSourceError,
+    add_spec,
+    evaluate_spec,
+    load_spec_config,
+    select_specs,
+    spec_config_path,
+)
+
+__all__ = [
+    "SpecEntry",
+    "SpecEvaluation",
+    "SpecSourceError",
+    "add_spec",
+    "evaluate_spec",
+    "load_spec_config",
+    "select_specs",
+    "spec_config_path",
+]

modelable/specs/tracking.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import hashlib
+import urllib.error
+import urllib.request
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+import yaml
+
+from modelable.llm.engine import AttachResult, attach_external_version
+
+SUPPORTED_SPEC_KINDS = {"dbt", "fhir", "odcs"}
+
+
+class SpecSourceError(RuntimeError):
+    """Raised when a spec source cannot be resolved."""
+
+
+@dataclass(frozen=True)
+class SpecEntry:
+    id: str
+    kind: str
+    source: str
+    ref: str
+    source_name: str | None = None
+    update_policy: str = "preview"
+
+    def as_config_dict(self) -> dict[str, str]:
+        data = {
+            "id": self.id,
+            "kind": self.kind,
+            "source": self.source,
+            "ref": self.ref,
+        }
+        if self.source_name is not None:
+            data["source_name"] = self.source_name
+        data["update_policy"] = self.update_policy
+        return data
+
+
+@dataclass(frozen=True)
+class SpecEvaluation:
+    entry: SpecEntry
+    status: str
+    source_hash: str | None
+    change_kind: str | None
+    change_count: int
+    result: AttachResult | None = None
+    error: str | None = None
+
+    def as_status_dict(self) -> dict[str, object]:
+        return {
+            "id": self.entry.id,
+            "kind": self.entry.kind,
+            "source": self.entry.source,
+            "ref": self.entry.ref,
+            "source_name": self.entry.source_name,
+            "status": self.status,
+            "source_hash": self.source_hash,
+            "change_kind": self.change_kind,
+            "change_count": self.change_count,
+            "error": self.error,
+        }
+
+
+def spec_config_path(workspace_path: Path) -> Path:
+    return workspace_path / ".modelable" / "specs.yml"
+
+
+def load_spec_config(workspace_path: Path) -> list[SpecEntry]:
+    path = spec_config_path(workspace_path)
+    if not path.exists():
+        return []
+    doc = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    specs = doc.get("specs") or []
+    return [_entry_from_dict(item) for item in specs]
+
+
+def write_spec_config(workspace_path: Path, specs: list[SpecEntry]) -> Path:
+    path = spec_config_path(workspace_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    doc = {"specs": [entry.as_config_dict() for entry in specs]}
+    path.write_text(yaml.safe_dump(doc, sort_keys=False), encoding="utf-8")
+    return path
+
+
+def add_spec(workspace_path: Path, entry: SpecEntry) -> Path:
+    if entry.kind not in SUPPORTED_SPEC_KINDS:
+        supported = ", ".join(sorted(SUPPORTED_SPEC_KINDS))
+        raise ValueError(f"Unsupported tracked spec kind '{entry.kind}'. Supported kinds: {supported}")
+    specs = load_spec_config(workspace_path)
+    if any(item.id == entry.id for item in specs):
+        raise ValueError(f"Tracked spec '{entry.id}' already exists")
+    specs.append(entry)
+    return write_spec_config(workspace_path, specs)
+
+
+def select_specs(workspace_path: Path, spec_id: str | None) -> list[SpecEntry]:
+    specs = load_spec_config(workspace_path)
+    if spec_id is None:
+        return specs
+    selected = [entry for entry in specs if entry.id == spec_id]
+    if not selected:
+        raise ValueError(f"Tracked spec '{spec_id}' not found")
+    return selected
+
+
+def evaluate_spec(
+    workspace_path: Path,
+    entry: SpecEntry,
+    *,
+    write: bool = False,
+    token: str | None = None,
+) -> SpecEvaluation:
+    try:
+        source_text, source_path = _resolve_source(workspace_path, entry, token=token)
+        source_hash = hashlib.sha256(source_text.encode("utf-8")).hexdigest()
+        result = attach_external_version(
+            workspace_path,
+            entry.ref,
+            source_path,
+            entry.kind,
+            source_name=entry.source_name,
+            write=write,
+        )
+        status = "drifted" if result.attached else "clean"
+        return SpecEvaluation(
+            entry=entry,
+            status=status,
+            source_hash=source_hash,
+            change_kind=result.change_kind,
+            change_count=len(result.changes),
+            result=result,
+        )
+    except Exception as exc:
+        return SpecEvaluation(
+            entry=entry,
+            status="error",
+            source_hash=None,
+            change_kind=None,
+            change_count=0,
+            error=str(exc),
+        )
+
+
+def _spec_cache_dir(workspace_path: Path, spec_id: str) -> Path:
+    sanitized = _sanitize_id(spec_id)
+    return workspace_path / ".modelable" / "specs-cache" / sanitized
+
+
+def _sanitize_id(spec_id: str) -> str:
+    return "".join(c if c.isalnum() or c in ("-", "_") else "_" for c in spec_id)
+
+
+def _is_remote_source(source: str) -> bool:
+    return source.startswith(("http://", "https://"))
+
+
+def _resolve_source(
+    workspace_path: Path,
+    entry: SpecEntry,
+    *,
+    token: str | None = None,
+) -> tuple[str, Path]:
+    if _is_remote_source(entry.source):
+        return _fetch_remote_source(entry.source, workspace_path, entry.id, token=token)
+    path = _resolve_local_source_path(workspace_path, entry.source)
+    return path.read_text(encoding="utf-8"), path
+
+
+def _fetch_remote_source(
+    url: str,
+    workspace_path: Path,
+    spec_id: str,
+    *,
+    token: str | None = None,
+) -> tuple[str, Path]:
+    cache_dir = _spec_cache_dir(workspace_path, spec_id)
+    cache_path = cache_dir / "source"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+
+    req = urllib.request.Request(url)
+    if token:
+        req.add_header("Authorization", f"Bearer {token}")
+
+    try:
+        with urllib.request.urlopen(req, timeout=30) as response:
+            content = response.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        raise SpecSourceError(f"Failed to fetch remote spec {url}: HTTP {exc.code} {exc.reason}") from exc
+    except urllib.error.URLError as exc:
+        raise SpecSourceError(f"Failed to fetch remote spec {url}: {exc.reason}") from exc
+    except OSError as exc:
+        raise SpecSourceError(f"Failed to fetch remote spec {url}: {exc}") from exc
+
+    cache_path.write_text(content, encoding="utf-8")
+    return content, cache_path
+
+
+def _resolve_local_source_path(workspace_path: Path, source: str) -> Path:
+    path = Path(source)
+    if path.is_absolute():
+        return path
+    return workspace_path / path
+
+
+def _entry_from_dict(item: dict[str, object]) -> SpecEntry:
+    return SpecEntry(
+        id=str(item["id"]),
+        kind=str(item["kind"]),
+        source=str(item["source"]),
+        ref=str(item["ref"]),
+        source_name=str(item["source_name"]) if item.get("source_name") is not None else None,
+        update_policy=str(item.get("update_policy") or "preview"),
+    )
+
+
+def change_dicts(result: AttachResult) -> list[dict[str, object]]:
+    return [asdict(change) for change in result.changes]

modelable/validation/__init__.py

@@ -0,0 +1,3 @@
+from modelable.validation.semantic import validate
+
+__all__ = ["validate"]