interlaced 2.0.0a2__py3-none-any.whl

interlace/ir/__init__.py

@@ -0,0 +1,24 @@
+"""Intermediate representation: the canonical sqlglot AST + Arrow contract."""
+
+from __future__ import annotations
+
+from interlace.ir.canonicalize import parse, resolve_references, table_references
+from interlace.ir.fingerprint import canonical_sql, data_fingerprint, metadata_fingerprint
+from interlace.ir.relation import EngineRef, Relation, SqlRelation, TableRef
+from interlace.ir.schema import ArrowSchema, empty_schema, schema_from_fields
+
+__all__ = [
+    "ArrowSchema",
+    "EngineRef",
+    "Relation",
+    "SqlRelation",
+    "TableRef",
+    "canonical_sql",
+    "data_fingerprint",
+    "empty_schema",
+    "metadata_fingerprint",
+    "parse",
+    "resolve_references",
+    "schema_from_fields",
+    "table_references",
+]

interlace/ir/canonicalize.py

@@ -0,0 +1,71 @@
+"""Parsing and static analysis of SQL into the canonical IR.
+
+Phase 1 covers parsing (dialect-aware) and table-reference extraction for
+implicit dependency discovery. Qualification and type annotation
+(``sqlglot.optimizer.qualify`` against the project schema graph) land alongside
+column lineage in a later phase.
+"""
+
+from __future__ import annotations
+
+import sqlglot
+from sqlglot import exp
+
+from interlace.exceptions import CompilationError
+from interlace.ir.relation import TableRef
+
+
+def parse(sql: str, dialect: str = "duckdb") -> exp.Expression:
+    """Parse a single SQL statement in the given dialect into a sqlglot AST."""
+    try:
+        parsed = sqlglot.parse_one(sql, dialect=dialect)
+    except Exception as exc:  # sqlglot raises ParseError and friends
+        raise CompilationError(f"failed to parse SQL ({dialect})", details={"sql": sql, "error": str(exc)}) from exc
+    if parsed is None:
+        raise CompilationError("empty SQL statement", details={"sql": sql})
+    return parsed
+
+
+def table_references(ast: exp.Expression) -> list[str]:
+    """Return the distinct real table references in an AST, excluding CTE names.
+
+    Each reference is keyed as ``db.name`` (or ``name`` when unqualified). CTE
+    aliases are filtered out — they are local names, not dependencies.
+    """
+    cte_names = {cte.alias_or_name for cte in ast.find_all(exp.CTE)}
+    refs: list[str] = []
+    seen: set[str] = set()
+    for table in ast.find_all(exp.Table):
+        name = table.name
+        if not name or name in cte_names:
+            continue
+        key = f"{table.db}.{name}" if table.db else name
+        if key not in seen:
+            seen.add(key)
+            refs.append(key)
+    return refs
+
+
+def resolve_references(ast: exp.Expression, mapping: dict[str, TableRef]) -> exp.Expression:
+    """Rewrite model-name table references to their physical tables (returns a new AST).
+
+    ``mapping`` is keyed by dependency model name; a reference matches by its
+    ``db.name`` key or, failing that, its bare name (so ``main.orders`` resolves
+    to model ``orders``). Aliases are preserved; the input AST is not mutated.
+    """
+    if not mapping:
+        return ast
+
+    def rewrite(node: exp.Expression) -> exp.Expression:
+        if isinstance(node, exp.Table):
+            key = f"{node.db}.{node.name}" if node.db else node.name
+            target = mapping.get(key) or mapping.get(node.name)
+            if target is not None:
+                if not node.alias:  # keep qualified column refs (b.x) resolving after the rename
+                    node.set("alias", exp.TableAlias(this=exp.to_identifier(node.name)))
+                node.set("this", exp.to_identifier(target.name))
+                node.set("db", exp.to_identifier(target.schema) if target.schema else None)
+                node.set("catalog", exp.to_identifier(target.catalog) if target.catalog else None)
+        return node
+
+    return ast.transform(rewrite)

interlace/ir/fingerprint.py

@@ -0,0 +1,55 @@
+"""Snapshot fingerprinting.
+
+A model's ``data`` fingerprint is a hash of its normalised SQL AST, its
+materialisation/strategy config, and the sorted fingerprints of its upstreams —
+so any change that affects results (here or upstream) yields a new fingerprint
+and triggers a rebuild. A separate ``metadata`` fingerprint covers comments,
+owner, and tags, which must never trigger a rebuild.
+
+This mirrors sqlmesh's snapshot model. The hash is deliberately short (16 hex
+chars) because it becomes part of physical table names.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+from sqlglot import exp
+
+_FP_LEN = 16
+
+
+def canonical_sql(ast: exp.Expression) -> str:
+    """Render an AST to a stable, comment-free, normalised string for hashing."""
+    return ast.sql(comments=False, normalize=True, pretty=False)
+
+
+def _stable_json(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), default=str)
+
+
+def _digest(*parts: str) -> str:
+    h = hashlib.sha256("\x00".join(parts).encode("utf-8"))
+    return h.hexdigest()[:_FP_LEN]
+
+
+def data_fingerprint(
+    *,
+    query: str | exp.Expression,
+    strategy_config: dict[str, Any],
+    upstream_fingerprints: list[str],
+) -> str:
+    """Fingerprint that changes whenever the model's output could change.
+
+    ``query`` is the canonical SQL for SQL models, or for Python models the
+    dedented source plus closure bytecode digest produced by the caller.
+    """
+    sql = canonical_sql(query) if isinstance(query, exp.Expression) else query
+    return _digest(sql, _stable_json(strategy_config), *sorted(upstream_fingerprints))
+
+
+def metadata_fingerprint(metadata: dict[str, Any]) -> str:
+    """Fingerprint over non-semantic metadata (comments, owner, tags)."""
+    return _digest(_stable_json(metadata))

interlace/ir/relation.py

@@ -0,0 +1,71 @@
+"""The universal model-output contract.
+
+Every model produces a :class:`Relation`. A relation is *logical* until a sink
+forces it: a :class:`SqlRelation` carries a sqlglot AST that the owning engine
+evaluates natively (zero rows enter Python). Python models move data as plain
+Arrow ``RecordBatchReader`` handles (see ``runtime/``), not as relations.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import ClassVar, Protocol, runtime_checkable
+
+from sqlglot import exp
+
+from interlace.ir.schema import ArrowSchema
+
+
+@dataclass(frozen=True)
+class TableRef:
+    """A fully-qualified table identifier, dialect-agnostic until transpiled."""
+
+    schema: str
+    name: str
+    catalog: str | None = None
+
+    def to_expr(self) -> exp.Table:
+        """This table as a sqlglot Table node (identifier-safe, dialect-agnostic)."""
+        return exp.table_(self.name, db=self.schema, catalog=self.catalog)
+
+    def qualified(self) -> str:
+        parts = [p for p in (self.catalog, self.schema, self.name) if p]
+        return ".".join(parts)
+
+    def __str__(self) -> str:
+        return self.qualified()
+
+
+@dataclass(frozen=True)
+class EngineRef:
+    """Identifies which engine (gateway) can evaluate a relation, and its dialect."""
+
+    name: str  # connection/gateway name from config
+    dialect: str  # sqlglot dialect name
+
+
+@runtime_checkable
+class Relation(Protocol):
+    """What every model produces. Logical until a sink forces it."""
+
+    @property
+    def schema(self) -> ArrowSchema: ...
+
+    @property
+    def plane(self) -> str: ...
+
+
+@dataclass(frozen=True)
+class SqlRelation:
+    """Logical plane: a sqlglot AST bound to the engine that can evaluate it.
+
+    The AST is canonical (qualified, type-annotated, dialect-neutral); the engine
+    adapter transpiles it at execution time. Composing SQL models never leaves
+    this plane, so no data is materialised until a sink runs a single statement.
+    """
+
+    ast: exp.Expression
+    engine: EngineRef
+    schema: ArrowSchema
+
+    plane: ClassVar[str] = "logical"

interlace/ir/schema.py

@@ -0,0 +1,23 @@
+"""Canonical schema representation.
+
+Apache Arrow is the single source of truth for column names and types across the
+IR. Engine adapters map this to and from their native catalogs; nothing else in
+the framework invents its own type system.
+"""
+
+from __future__ import annotations
+
+import pyarrow as pa
+
+# The canonical schema type used throughout the IR.
+type ArrowSchema = pa.Schema
+
+
+def schema_from_fields(fields: dict[str, pa.DataType]) -> ArrowSchema:
+    """Build an Arrow schema from an ordered mapping of name to Arrow type."""
+    return pa.schema([pa.field(name, dtype) for name, dtype in fields.items()])
+
+
+def empty_schema() -> ArrowSchema:
+    """An empty schema (no columns) — used when a relation's shape is not yet known."""
+    return pa.schema([])

interlace/plan/__init__.py

@@ -0,0 +1,23 @@
+"""Plan/apply: diff models, classify changes, compute backfills, swap views."""
+
+from __future__ import annotations
+
+from interlace.plan.apply import ApplyResult, apply
+from interlace.plan.differ import diff, snapshot_of
+from interlace.plan.plan import BackfillTask, ChangeType, ModelChange, Plan, TransferEdge, ViewSwap, env_view
+from interlace.plan.run import run_plan
+
+__all__ = [
+    "ApplyResult",
+    "BackfillTask",
+    "ChangeType",
+    "ModelChange",
+    "Plan",
+    "TransferEdge",
+    "ViewSwap",
+    "apply",
+    "diff",
+    "env_view",
+    "run_plan",
+    "snapshot_of",
+]