seam-runtime 1.3.0__py3-none-any.whl

seam.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from seam_runtime.cli import run_cli
+from seam_runtime.dsl import compile_dsl
+from seam_runtime.lossless import (
+    LosslessArtifact,
+    LosslessBenchmarkResult,
+    ReadableCompressionArtifact,
+    ReadableQueryResult,
+    benchmark_text_lossless,
+    compress_text_lossless,
+    compress_text_readable,
+    decompress_text_lossless,
+    decompress_text_readable,
+    query_readable_compressed,
+)
+from seam_runtime.holographic import (
+    HolographicReader,
+    SurfaceArtifact,
+    SurfacePayload,
+    SurfaceQueryResult,
+    SurfaceVerification,
+    context_surface,
+    decode_surface,
+    encode_surface,
+    query_surface,
+    verify_surface,
+)
+from seam_runtime.mirl import IRBatch, MIRLRecord, Pack, RecordKind
+from seam_runtime.models import HashEmbeddingModel, OpenAICompatibleEmbeddingModel
+from seam_runtime.nl import compile_nl
+from seam_runtime.pack import pack_records, unpack_exact_pack
+from seam_runtime.runtime import SeamRuntime
+from seam_runtime.verify import verify_ir
+
+
+def pack_ir(records, lens: str = "general", budget: int = 512, mode: str = "context") -> Pack:
+    if isinstance(records, IRBatch):
+        batch = records
+    else:
+        batch = IRBatch(list(records))
+    return pack_records(batch.records, lens=lens, budget=budget, mode=mode)
+
+
+def decompile_ir(records, mode: str = "expanded") -> str:
+    if isinstance(records, IRBatch):
+        batch = records
+    else:
+        batch = IRBatch(list(records))
+    states = [record for record in batch.records if record.kind == RecordKind.STA]
+    claims = [record for record in batch.records if record.kind == RecordKind.CLM]
+    if states:
+        summary = "; ".join(f"{key}={value}" for key, value in states[0].attrs.get("fields", {}).items())
+    elif claims:
+        summary = "; ".join(f"{record.attrs.get('subject')} {record.attrs.get('predicate')} {record.attrs.get('object')}" for record in claims)
+    else:
+        summary = "No MIRL records available."
+    return summary if mode == "minimal" else f"MIRL summary: {summary}"
+
+
+def render_ir(records) -> str:
+    if isinstance(records, IRBatch):
+        return records.to_text()
+    return IRBatch(list(records)).to_text()
+
+
+def load_ir_lines(text: str) -> list[MIRLRecord]:
+    return IRBatch.from_text(text).records
+
+
+def unpack_pack(pack: Pack | str):
+    if isinstance(pack, Pack):
+        if pack.mode == "exact":
+            return unpack_exact_pack(pack).to_json()
+        return pack.payload
+    raise TypeError("unpack_pack now expects a Pack instance")
+
+
+def lossless_compress(text: str, codec: str = "auto", transform: str = "auto", tokenizer: str = "auto") -> LosslessArtifact:
+    return compress_text_lossless(text, codec=codec, transform=transform, tokenizer=tokenizer)
+
+
+def lossless_decompress(machine_text: str) -> str:
+    return decompress_text_lossless(machine_text)
+
+
+def readable_compress(text: str, source_ref: str = "local://input", granularity: str = "auto", tokenizer: str = "auto") -> ReadableCompressionArtifact:
+    return compress_text_readable(text, source_ref=source_ref, granularity=granularity, tokenizer=tokenizer)
+
+
+def readable_query(machine_text: str, query: str, limit: int = 5) -> ReadableQueryResult:
+    return query_readable_compressed(machine_text, query=query, limit=limit)
+
+
+def readable_decompress(machine_text: str) -> str:
+    return decompress_text_readable(machine_text)
+
+
+def surface_encode(payload: bytes, output_path: str | Path, mode: str = "rgb24", payload_format: str = "auto") -> SurfaceArtifact:
+    return encode_surface(payload, Path(output_path), mode=mode, payload_format=payload_format)
+
+
+def surface_compile(text: str, output_path: str | Path, mode: str = "rgb24", source_ref: str = "local://input") -> SurfaceArtifact:
+    batch = compile_nl(text, source_ref=source_ref)
+    return encode_surface(batch.to_text().encode("utf-8"), Path(output_path), mode=mode, payload_format="MIRL", source_ref=source_ref)
+
+
+def surface_decode(path: str | Path) -> SurfacePayload:
+    return decode_surface(Path(path))
+
+
+def surface_verify(path: str | Path) -> SurfaceVerification:
+    return verify_surface(Path(path))
+
+
+def surface_query(path: str | Path, query: str, limit: int = 5) -> SurfaceQueryResult:
+    return query_surface(Path(path), query=query, limit=limit)
+
+
+def lossless_benchmark(
+    text: str,
+    codec: str = "auto",
+    transform: str = "auto",
+    min_token_savings: float = 0.30,
+    tokenizer: str = "auto",
+) -> LosslessBenchmarkResult:
+    return benchmark_text_lossless(text, codec=codec, transform=transform, min_token_savings=min_token_savings, tokenizer=tokenizer)
+
+
+def main() -> None:
+    run_cli()
+
+
+def benchmark_main() -> None:
+    argv = sys.argv[1:]
+    if argv and argv[0] not in {"run", "show", "verify", "diff", "gate", "-h", "--help"} and Path(argv[0]).exists():
+        run_cli(["lossless-benchmark", *argv])
+        return
+    if not argv:
+        run_cli(["benchmark", "run"])
+        return
+    if argv[0] in {"run", "show", "verify", "diff", "gate"}:
+        run_cli(["benchmark", *argv])
+        return
+    run_cli(["benchmark", "run", *argv])
+
+
+if __name__ == "__main__":
+    main()

seam_runtime/__init__.py

@@ -0,0 +1,29 @@
+from .mirl import (
+    Artifact,
+    IRBatch,
+    MIRLRecord,
+    Pack,
+    PersistReport,
+    ReconcileReport,
+    RecordKind,
+    SearchResult,
+    Status,
+    TraceGraph,
+    VerifyReport,
+)
+from .runtime import SeamRuntime
+
+__all__ = [
+    "Artifact",
+    "IRBatch",
+    "MIRLRecord",
+    "Pack",
+    "PersistReport",
+    "ReconcileReport",
+    "RecordKind",
+    "SearchResult",
+    "SeamRuntime",
+    "Status",
+    "TraceGraph",
+    "VerifyReport",
+]

seam_runtime/agent_memory.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+from .mirl import IRBatch, MIRLRecord, RecordKind
+
+
+@dataclass(frozen=True)
+class IngestReport:
+    document: dict[str, object]
+    stored_ids: list[str]
+
+    def to_dict(self) -> dict[str, object]:
+        return {"document": self.document, "stored_ids": list(self.stored_ids)}
+
+
+def source_hash(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def stable_document_id(source_ref: str, text: str) -> str:
+    digest = hashlib.sha256(f"{source_ref}\n{source_hash(text)}".encode("utf-8")).hexdigest()[:16]
+    return f"doc:{digest}"
+
+
+def namespace_ingest_batch(batch: IRBatch, document_id: str) -> IRBatch:
+    suffix = document_id.split(":", 1)[1]
+    id_map = {record.id: _document_record_id(record.id, suffix) for record in batch.records}
+    records = []
+    for record in batch.records:
+        cloned = MIRLRecord.from_dict(record.to_dict())
+        cloned.id = id_map[record.id]
+        cloned.prov = [id_map.get(item, item) for item in cloned.prov]
+        cloned.evidence = [id_map.get(item, item) for item in cloned.evidence]
+        cloned.attrs = _rewrite_refs(cloned.attrs, id_map)
+        records.append(cloned)
+    return IRBatch(records)
+
+
+def compact_memory_index(records: Iterable[MIRLRecord], query: str, scores: dict[str, float] | None = None) -> dict[str, object]:
+    scores = scores or {}
+    items = []
+    for record in records:
+        items.append(
+            {
+                "id": record.id,
+                "kind": record.kind.value,
+                "score": round(float(scores.get(record.id, 0.0)), 6),
+                "summary": _record_summary(record),
+                "refs": sorted(set(record.prov + record.evidence)),
+            }
+        )
+    return {"query": query, "results": items, "next": "Use `seam memory get <ids>` for full records."}
+
+
+def full_memory_records(records: Iterable[MIRLRecord]) -> dict[str, object]:
+    return {"records": [record.to_dict() for record in records]}
+
+
+def neighbor_timeline(batch: IRBatch, record_ids: list[str]) -> dict[str, object]:
+    by_id = batch.by_id()
+    selected = [by_id[record_id] for record_id in record_ids if record_id in by_id]
+    neighbors: dict[str, list[str]] = {}
+    for record in selected:
+        refs = set(record.prov + record.evidence)
+        for key in ("src", "dst", "target", "raw_id", "subject"):
+            value = record.attrs.get(key)
+            if isinstance(value, str):
+                refs.add(value)
+        obj = record.attrs.get("object")
+        if isinstance(obj, str):
+            refs.add(obj)
+        neighbors[record.id] = sorted(ref for ref in refs if ref in by_id)
+    ordered = sorted(selected, key=lambda item: (item.t0 or item.created_at, item.id))
+    return {
+        "ids": list(record_ids),
+        "timeline": [{"id": record.id, "kind": record.kind.value, "updated_at": record.updated_at} for record in ordered],
+        "neighbors": neighbors,
+    }
+
+
+def render_memory_index(payload: dict[str, object]) -> str:
+    lines = [f"Memory search: {payload.get('query')}"]
+    results = payload.get("results", [])
+    if not results:
+        lines.append("(none)")
+    for index, item in enumerate(results, start=1):
+        lines.append(f"{index}. {item['id']} [{item['kind']}] score={item['score']:.3f}")
+        if item.get("summary"):
+            lines.append(f"   {item['summary']}")
+        refs = item.get("refs") or []
+        if refs:
+            lines.append(f"   refs={', '.join(refs)}")
+    lines.append(str(payload.get("next", "")))
+    return "\n".join(line for line in lines if line)
+
+
+def render_memory_records(payload: dict[str, object]) -> str:
+    records = payload.get("records", [])
+    if not records:
+        return "No records found."
+    return "\n".join(json.dumps(record, sort_keys=True) for record in records)
+
+
+def read_path_text(path: str) -> tuple[str, str]:
+    if path == "-":
+        import sys
+
+        return sys.stdin.read(), "stdin://seam"
+    source = Path(path)
+    return source.read_bytes().decode("utf-8"), str(source)
+
+
+def _record_summary(record: MIRLRecord) -> str:
+    attrs = record.attrs
+    if record.kind == RecordKind.CLM:
+        return f"{attrs.get('subject')} {attrs.get('predicate')} {attrs.get('object')}"
+    if record.kind == RecordKind.REL:
+        return f"{attrs.get('src')} {attrs.get('predicate')} {attrs.get('dst')}"
+    if record.kind == RecordKind.STA:
+        return f"{attrs.get('target')} {attrs.get('fields')}"
+    if record.kind == RecordKind.EVT:
+        return f"{attrs.get('actor')} {attrs.get('action')} {attrs.get('object')}"
+    return str(attrs)[:180]
+
+
+def _document_record_id(record_id: str, suffix: str) -> str:
+    head, sep, tail = record_id.partition(":")
+    if not sep:
+        return f"{record_id}:{suffix}"
+    return f"{head}:{suffix}:{tail}"
+
+
+def _rewrite_refs(value, id_map: dict[str, str]):
+    if isinstance(value, str):
+        return id_map.get(value, value)
+    if isinstance(value, list):
+        return [_rewrite_refs(item, id_map) for item in value]
+    if isinstance(value, dict):
+        return {key: _rewrite_refs(item, id_map) for key, item in value.items()}
+    return value

seam_runtime/benchmark_baseline_policy.py

@@ -0,0 +1,116 @@
+"""CI baseline-source policy for ``seam bench gate``.
+
+Picks the most recent benchmark run reachable from the merge-base of HEAD
+and origin/main, excluding any path under ``benchmarks/runs/holdout/``.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+
+BENCHMARK_RUNS_DIR = Path("benchmarks") / "runs"
+HOLDOUT_PREFIX = str(BENCHMARK_RUNS_DIR / "holdout")
+
+
+def resolve_baseline(
+    repo_root: Path | None = None,
+    current_run: Path | None = None,
+) -> Path | None:
+    """Return the best baseline bundle path, or None for a first-run.
+
+    Policy:
+    1. Find the merge-base of HEAD and origin/main.
+    2. List all JSON files under ``benchmarks/runs/``, newest first.
+    3. Exclude any path under ``benchmarks/runs/holdout/``.
+    4. Exclude *current_run* itself when provided.
+    5. Return the first run whose git SHA is reachable from the merge-base.
+
+    Returns None when no baseline exists — the caller treats this as
+    "first run" (no regression check, exit 0 with a note).
+    """
+    root = repo_root or _git_root()
+    if root is None:
+        return None
+
+    merge_base = _merge_base(root)
+    if merge_base is None:
+        return None
+
+    runs_dir = root / BENCHMARK_RUNS_DIR
+    if not runs_dir.is_dir():
+        return None
+
+    candidates = sorted(
+        runs_dir.glob("**/*.json"),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+
+    for candidate in candidates:
+        if _is_holdout_run(candidate, root):
+            continue
+        if current_run is not None and candidate.resolve() == current_run.resolve():
+            continue
+        sha = _bundle_git_sha(candidate)
+        if sha is None:
+            continue
+        if _is_reachable(root, sha, merge_base):
+            return candidate
+
+    return None
+
+
+def _is_holdout_run(path: Path, repo_root: Path) -> bool:
+    try:
+        relative = path.resolve().relative_to((repo_root / BENCHMARK_RUNS_DIR).resolve())
+    except ValueError:
+        return False
+    return bool(relative.parts) and relative.parts[0] == "holdout"
+
+
+def _git_root() -> Path | None:
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            capture_output=True, text=True, timeout=10,
+        )
+    except Exception:
+        return None
+    return Path(result.stdout.strip()) if result.returncode == 0 else None
+
+
+def _merge_base(repo_root: Path) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "merge-base", "HEAD", "origin/main"],
+            capture_output=True, text=True, timeout=10, cwd=str(repo_root),
+        )
+    except Exception:
+        return None
+    return result.stdout.strip() if result.returncode == 0 and result.stdout.strip() else None
+
+
+def _bundle_git_sha(path: Path) -> str | None:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    if isinstance(payload, dict):
+        manifest = payload.get("manifest") or {}
+        return manifest.get("git_sha") or None
+    return None
+
+
+def _is_reachable(repo_root: Path, sha: str, merge_base: str) -> bool:
+    """True if *sha* is an ancestor of *merge_base* (i.e. reachable from it)."""
+    try:
+        result = subprocess.run(
+            ["git", "merge-base", "--is-ancestor", sha, merge_base],
+            capture_output=True, timeout=10, cwd=str(repo_root),
+        )
+    except Exception:
+        return False
+    return result.returncode == 0