arctx 0.2.0b2__py3-none-any.whl

arctx/__init__.py

@@ -0,0 +1,48 @@
+"""arctx: records the process of optimization and problem-solving."""
+
+from __future__ import annotations
+
+from arctx.core.graph_view import GraphView
+from arctx.core.run import RunHandle
+from arctx.core.run import init as _core_init
+from arctx.core.run_graph import RunGraph
+from arctx.core.schema import (
+    CutPayload,
+    Node,
+    NodePayload,
+    Payload,
+    PayloadBase,
+    Requirement,
+    TraceContext,
+    Transition,
+    TransitionPayload,
+    register_payload_class,
+)
+from arctx.core.types import (
+    TargetKind,
+)
+
+__version__ = "0.2.0b2"
+
+
+def init(requirement: Requirement, *, run_id: str | None = None) -> RunHandle:
+    """Create a core run handle without enabling extensions."""
+    return _core_init(requirement, run_id=run_id)
+
+__all__ = [
+    "CutPayload",
+    "GraphView",
+    "Node",
+    "NodePayload",
+    "Payload",
+    "PayloadBase",
+    "Requirement",
+    "RunGraph",
+    "RunHandle",
+    "TargetKind",
+    "TraceContext",
+    "Transition",
+    "TransitionPayload",
+    "init",
+    "register_payload_class",
+]

arctx/core/__init__.py

@@ -0,0 +1,43 @@
+"""Core graph model."""
+
+from arctx.core.graph_view import GraphView
+from arctx.core.ids import opaque_id, sequential_id, slugify, timestamp_id
+from arctx.core.run import RunHandle, init
+from arctx.core.run_graph import RunGraph
+from arctx.core.schema import (
+    CutPayload,
+    Node,
+    NodePayload,
+    Payload,
+    PayloadBase,
+    Requirement,
+    TraceContext,
+    Transition,
+    TransitionPayload,
+    register_payload_class,
+)
+from arctx.core.types import (
+    TargetKind,
+)
+
+__all__ = [
+    "CutPayload",
+    "GraphView",
+    "Node",
+    "NodePayload",
+    "Payload",
+    "PayloadBase",
+    "Requirement",
+    "RunGraph",
+    "RunHandle",
+    "TargetKind",
+    "TraceContext",
+    "Transition",
+    "TransitionPayload",
+    "init",
+    "opaque_id",
+    "register_payload_class",
+    "sequential_id",
+    "slugify",
+    "timestamp_id",
+]

arctx/core/_json.py

@@ -0,0 +1,28 @@
+"""Fast JSON helpers with orjson fallback.
+
+Used by storage hot paths. CLI output formatting should keep using
+the stdlib `json` module directly for ensure_ascii / indent control.
+"""
+from __future__ import annotations
+
+try:
+    import orjson as _orjson
+
+    def loads(s: str | bytes) -> object:
+        return _orjson.loads(s)
+
+    def dumps(obj: object) -> str:
+        return _orjson.dumps(obj, option=_orjson.OPT_SORT_KEYS).decode("utf-8")
+
+    HAVE_ORJSON: bool = True
+
+except ImportError:
+    import json as _json
+
+    def loads(s: str | bytes) -> object:  # type: ignore[misc]
+        return _json.loads(s)
+
+    def dumps(obj: object) -> str:  # type: ignore[misc]
+        return _json.dumps(obj, ensure_ascii=False, sort_keys=True)
+
+    HAVE_ORJSON = False

arctx/core/append.py

@@ -0,0 +1,46 @@
+"""Append-only storage batches for concurrent writers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Union
+
+from arctx.core.graph_view import GraphView
+from arctx.core.schema.graph import Node, Transition
+from arctx.core.schema.payloads import PayloadBase
+from arctx.core.schema.work import WorkEvent, WorkSession
+
+GraphRecordKind = Literal["node", "transition", "payload", "view"]
+GraphRecord = Union[Node, Transition, PayloadBase, GraphView]
+
+
+@dataclass(frozen=True)
+class GraphRecordEnvelope:
+    """A graph record plus the table/category it belongs to."""
+
+    record_kind: GraphRecordKind
+    record_id: str
+    record: GraphRecord
+
+
+@dataclass(frozen=True)
+class AppendBatch:
+    """One atomic append unit for a run."""
+
+    run_id: str
+    user_id: str
+    work_session_id: str
+    records: tuple[GraphRecordEnvelope, ...]
+    work_session: WorkSession
+    events: tuple[WorkEvent, ...]
+
+
+@dataclass(frozen=True)
+class AppendResult:
+    """Result returned after an append batch is committed."""
+
+    event_id: str
+    event_seq: int
+    record_ids: tuple[str, ...]
+    event_ids: tuple[str, ...] = ()
+    event_seqs: tuple[int, ...] = ()

arctx/core/cuts.py

@@ -0,0 +1,61 @@
+"""Read-time computation of inactive transitions and nodes."""
+
+from __future__ import annotations
+
+from arctx.core.run_graph import RunGraph
+from arctx.core.schema.payloads import CutPayload
+
+
+def _cut_payloads(graph: RunGraph) -> list[CutPayload]:
+    return [p for p in graph.payloads.values() if isinstance(p, CutPayload)]
+
+
+def cut_transition_ids(graph: RunGraph) -> set[str]:
+    return {p.target_id for p in _cut_payloads(graph) if p.target_kind == "transition"}
+
+
+def cut_node_ids(graph: RunGraph) -> set[str]:
+    return {p.target_id for p in _cut_payloads(graph) if p.target_kind == "node"}
+
+
+def _compute_inactive(graph: RunGraph) -> tuple[set[str], set[str]]:
+    inactive_transitions: set[str] = set(cut_transition_ids(graph))
+    inactive_nodes: set[str] = set(cut_node_ids(graph))
+
+    frontier_nodes = list(inactive_nodes)
+    frontier_transitions = list(inactive_transitions)
+
+    while frontier_nodes or frontier_transitions:
+        while frontier_transitions:
+            transition_id = frontier_transitions.pop()
+            out = graph.transition_output(transition_id)
+            if out and out not in inactive_nodes:
+                inactive_nodes.add(out)
+                frontier_nodes.append(out)
+
+        while frontier_nodes:
+            node_id = frontier_nodes.pop()
+            for transition_id in graph.transitions_from_node(node_id):
+                if transition_id not in inactive_transitions:
+                    inactive_transitions.add(transition_id)
+                    frontier_transitions.append(transition_id)
+
+    return inactive_transitions, inactive_nodes
+
+
+def inactive_transition_ids(graph: RunGraph) -> set[str]:
+    inactive_transitions, _ = _compute_inactive(graph)
+    return inactive_transitions
+
+
+def inactive_node_ids(graph: RunGraph) -> set[str]:
+    _, inactive_nodes = _compute_inactive(graph)
+    return inactive_nodes
+
+
+def is_active_node(graph: RunGraph, node_id: str) -> bool:
+    return node_id not in inactive_node_ids(graph)
+
+
+def is_inactive_transition(graph: RunGraph, transition_id: str) -> bool:
+    return transition_id in inactive_transition_ids(graph)

arctx/core/graph_view.py

@@ -0,0 +1,26 @@
+"""GraphView: a named label anchored to a root node in RunGraph.
+
+The contents of a view are determined at read time by reachability from
+root_node_id via output transitions. No membership sets are stored.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from arctx.core.types import JSONValue, to_jsonable
+
+
+@dataclass
+class GraphView:
+    """A named label for a subgraph rooted at a single node."""
+
+    view_id: str
+    name: str
+    root_node_id: str
+    metadata: dict[str, JSONValue] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, JSONValue]:
+        d = to_jsonable(self)
+        assert isinstance(d, dict)
+        return d  # type: ignore[return-value]

arctx/core/ids.py

@@ -0,0 +1,32 @@
+"""Identifier helpers for run and transition records."""
+
+from __future__ import annotations
+
+import re
+import uuid
+from datetime import datetime, timezone
+
+
+_SAFE_ID = re.compile(r"[^a-zA-Z0-9_.-]+")
+
+
+def slugify(value: str, fallback: str = "item") -> str:
+    """Return a stable filesystem-safe slug."""
+    slug = _SAFE_ID.sub("_", value.strip()).strip("._-").lower()
+    return slug or fallback
+
+
+def timestamp_id(prefix: str, now: datetime | None = None) -> str:
+    """Return a timestamp-based id."""
+    current = now or datetime.now(timezone.utc)
+    return f"{slugify(prefix)}_{current.strftime('%Y%m%d_%H%M%S')}"
+
+
+def sequential_id(prefix: str, index: int, width: int = 4) -> str:
+    """Return ids such as ``state_0001``."""
+    return f"{slugify(prefix)}_{index:0{width}d}"
+
+
+def opaque_id(prefix: str) -> str:
+    """Return a collision-resistant opaque id with a readable kind prefix."""
+    return f"{slugify(prefix)}_{uuid.uuid4().hex}"

arctx/core/run/__init__.py

@@ -0,0 +1,5 @@
+"""Run handle and initialization."""
+
+from arctx.core.run.handle import RunHandle, init
+
+__all__ = ["RunHandle", "init"]

arctx/core/run/anchor.py

@@ -0,0 +1,40 @@
+"""RunHandle.anchor implementation."""
+
+from __future__ import annotations
+
+from arctx.core.schema.graph import Node
+from arctx.core.schema.payloads import TransitionPayload
+
+
+def anchor_impl(
+    self,
+    from_node_id: str,
+    label: str,
+    *,
+    metadata: dict | None = None,
+    user_id: str | None = None,
+    work_session_id: str | None = None,
+) -> Node:
+    """Create a lightweight scope anchor node from an existing node.
+
+    An anchor is a Transition with type="anchor" and a generated output node.
+    The output node can then be used as a shared branching point for experiments.
+    """
+    meta = dict(metadata or {})
+    meta.setdefault("kind", "anchor")
+    meta.setdefault("label", label)
+
+    payload = TransitionPayload(
+        payload_id="pending",
+        target_id="pending",
+        type="anchor",
+        content={"label": label},
+        metadata=meta,
+    )
+    transition = self.transition(
+        [from_node_id],
+        payload,
+        user_id=user_id,
+        work_session_id=work_session_id,
+    )
+    return self.run_graph.nodes[transition.output_node_id]

arctx/core/run/attach.py

@@ -0,0 +1,49 @@
+"""RunHandle.attach implementation."""
+
+from __future__ import annotations
+
+from arctx.core.schema.payloads import PayloadBase
+from arctx.core.run.transition import _clone_payload
+
+
+def attach_impl(
+    self,
+    node_id: str,
+    payload: PayloadBase,
+    *,
+    user_id: str | None = None,
+    work_session_id: str | None = None,
+) -> PayloadBase:
+    """Attach a node-targeting payload to a node.
+
+    *payload* must be a node-targeting payload (target_kind="node").
+    Returns the attached payload (with a freshly minted payload_id).
+    """
+    if payload.target_kind != "node":
+        raise ValueError(
+            f"attach() requires a node-targeting payload "
+            f"(target_kind='node'), got {payload.target_kind!r}"
+        )
+    if node_id not in self.run_graph.nodes:
+        raise KeyError(f"unknown node_id: {node_id}")
+
+    cloned = _clone_payload(payload, self._next_id("pl"), node_id)
+    self.run_graph.attach_payload(cloned)
+    self.record_work_event(
+        user_id=user_id,
+        work_session_id=work_session_id,
+        event_type="payload_attached",
+        target_kind="node",
+        target_id=node_id,
+        created_records=(cloned.payload_id,),
+        summary=_node_payload_summary(cloned),
+    )
+    return cloned
+
+
+def _node_payload_summary(payload: PayloadBase) -> str | None:
+    for attr in ("type", "text"):
+        val = getattr(payload, attr, None)
+        if isinstance(val, str) and val:
+            return val
+    return None

arctx/core/run/cut.py

@@ -0,0 +1,50 @@
+"""RunHandle.cut implementation."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from arctx.core.cuts import cut_node_ids, cut_transition_ids
+from arctx.core.schema.payloads import CutPayload
+
+
+def cut_impl(
+    self,
+    target_id: str,
+    *,
+    target_kind: Literal["node", "transition"],
+    reason: str | None = None,
+    user_id: str | None = None,
+    work_session_id: str | None = None,
+) -> CutPayload:
+    """Append a CutPayload to mark a Node or Transition inactive."""
+    if target_kind == "node":
+        if target_id not in self.run_graph.nodes:
+            raise KeyError(f"unknown node_id: {target_id}")
+        if target_id in cut_node_ids(self.run_graph):
+            raise ValueError(f"node already cut: {target_id}")
+    elif target_kind == "transition":
+        if target_id not in self.run_graph.transitions:
+            raise KeyError(f"unknown transition_id: {target_id}")
+        if target_id in cut_transition_ids(self.run_graph):
+            raise ValueError(f"transition already cut: {target_id}")
+    else:
+        raise ValueError(f"invalid target_kind: {target_kind!r}")
+
+    cut = CutPayload(
+        payload_id=self._next_id("pl"),
+        target_id=target_id,
+        target_kind=target_kind,
+        reason=reason,
+    )
+    self.run_graph.attach_payload(cut)
+    self.record_work_event(
+        user_id=user_id,
+        work_session_id=work_session_id,
+        event_type="cut_added",
+        target_kind=target_kind,
+        target_id=target_id,
+        created_records=(cut.payload_id,),
+        summary=reason,
+    )
+    return cut

arctx/core/run/dump.py

@@ -0,0 +1,174 @@
+"""Dump RunGraph as outline or mermaid."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from arctx.core.cuts import inactive_node_ids, inactive_transition_ids
+from arctx.core.run.handle import RunHandle
+from arctx.core.run_graph import RunGraph
+from arctx.core.schema.payloads import CutPayload, NodePayload, TransitionPayload
+
+
+@dataclass
+class DumpOptions:
+    node_id: str | None = None
+    depth: int | None = None
+    full_payloads: bool = False
+    observed_only: bool = False   # unused after schema change; kept for CLI compat
+    predicted_only: bool = False  # unused after schema change; kept for CLI compat
+
+
+def _truncate(s: str | None, n: int) -> str:
+    if not s:
+        return ""
+    return s if len(s) <= n else s[: n - 1] + "…"
+
+
+def _node_summary(graph: RunGraph, node_id: str) -> str | None:
+    for payload in graph.payloads_for_node(node_id):
+        if isinstance(payload, NodePayload):
+            text = payload.content.get("text")
+            if isinstance(text, str) and text:
+                return text
+            return payload.type
+    return None
+
+
+def _transition_summary(graph: RunGraph, transition_id: str, full: bool) -> str:
+    payloads = graph.payloads_for_transition(transition_id)
+    parts = []
+    for payload in payloads:
+        if isinstance(payload, CutPayload):
+            parts.append("✂cut")
+        elif isinstance(payload, TransitionPayload):
+            parts.append(payload.type)
+            if full and payload.content:
+                import json
+                parts.append(json.dumps(payload.content)[:60])
+        else:
+            parts.append(payload.payload_type)
+    return " ".join(parts) if parts else "transition"
+
+
+def render_outline(handle: RunHandle, opts: DumpOptions) -> str:
+    graph = handle.run_graph
+    inactive_nodes = inactive_node_ids(graph)
+    inactive_trans = inactive_transition_ids(graph)
+    root_id = opts.node_id or handle.root_node_id
+
+    lines = [
+        (
+            f"run={handle.run_id}  nodes={len(graph.nodes)}  "
+            f"transitions={len(graph.transitions)}"
+        ),
+        "",
+    ]
+    visited_nodes: set[str] = set()
+    visited_transitions: set[str] = set()
+
+    # Count multi-input transitions for joins index.
+    multi_input_trans = [
+        tid for tid, t in graph.transitions.items() if len(t.input_node_ids) > 1
+    ]
+
+    def emit_node(node_id: str, prefix: str, is_last: bool, depth: int) -> None:
+        cut = " ✂" if node_id in inactive_nodes else ""
+        connector = "" if depth == 0 else ("└─" if is_last else "├─")
+        if node_id in visited_nodes:
+            lines.append(f"{prefix}{connector}↻ {node_id}{cut}")
+            return
+        visited_nodes.add(node_id)
+        lines.append(f"{prefix}{connector}{node_id}{cut}")
+        note = _node_summary(graph, node_id)
+        child_prefix = prefix + ("  " if depth == 0 or is_last else "│ ")
+        if note:
+            lines.append(f"{child_prefix}note: {_truncate(note, 80)}")
+        if opts.depth is not None and depth >= opts.depth:
+            return
+        transition_ids = graph.transitions_from_node(node_id)
+        for index, transition_id in enumerate(transition_ids):
+            t = graph.transitions[transition_id]
+            # Only render as primary if this node is inputs[0].
+            if t.input_node_ids and t.input_node_ids[0] != node_id:
+                lines.append(
+                    f"{child_prefix}▸ feeds {transition_id} (@{t.input_node_ids[0]})"
+                )
+                continue
+            emit_transition(
+                transition_id,
+                child_prefix,
+                index == len(transition_ids) - 1,
+                depth + 1,
+            )
+
+    def emit_transition(transition_id: str, prefix: str, is_last: bool, depth: int) -> None:
+        t = graph.transitions[transition_id]
+        summary = _transition_summary(graph, transition_id, opts.full_payloads)
+        cut = " ✂" if transition_id in inactive_trans else ""
+        connector = "└─" if is_last else "├─"
+        if transition_id in visited_transitions:
+            lines.append(f"{prefix}{connector}↻ {transition_id}{cut}")
+            return
+        visited_transitions.add(transition_id)
+        # Show extra inputs inline.
+        extras = ""
+        if len(t.input_node_ids) > 1:
+            extras = " " + " ".join(f"(+{n})" for n in t.input_node_ids[1:])
+        lines.append(f"{prefix}{connector}→ {transition_id}{cut}{extras}  {summary}")
+        child_prefix = prefix + ("  " if is_last else "│ ")
+        if t.output_node_id:
+            emit_node(t.output_node_id, child_prefix, True, depth + 1)
+
+    emit_node(root_id, "", True, 0)
+
+    if len(multi_input_trans) >= 3:
+        lines.append("")
+        lines.append("joins:")
+        for tid in multi_input_trans:
+            t = graph.transitions[tid]
+            lines.append(f"  {tid}: inputs={list(t.input_node_ids)}")
+
+    return "\n".join(lines)
+
+
+def render_mermaid(handle: RunHandle, opts: DumpOptions) -> str:
+    graph = handle.run_graph
+    inactive_nodes = inactive_node_ids(graph)
+    inactive_trans = inactive_transition_ids(graph)
+    lines = ["```mermaid", "flowchart TD"]
+    for node_id in graph.nodes:
+        label = "State"
+        note = _node_summary(graph, node_id)
+        if note:
+            label = _truncate(note, 36).replace('"', "'")
+        is_root = node_id == handle.root_node_id
+        cls = "root" if is_root else "cut" if node_id in inactive_nodes else "state"
+        lines.append(f'  {node_id}["{label}"]')
+        if cls != "state":
+            lines.append(f"  class {node_id} {cls}")
+
+    for transition_id, t in graph.transitions.items():
+        summary = _transition_summary(graph, transition_id, False)
+        summary = _truncate(summary, 42).replace('"', "'")
+        is_cut = transition_id in inactive_trans
+        if t.output_node_id:
+            for inp in t.input_node_ids:
+                lines.append(f'  {inp} -->|"{summary}"| {t.output_node_id}')
+        if is_cut:
+            lines.append(f"  class {transition_id} cut")
+
+    if inactive_nodes:
+        lines.append(f"  class {','.join(sorted(inactive_nodes))} cut")
+    lines.append("  classDef cut stroke:#999,stroke-dasharray: 4 4,color:#999")
+    lines.append("  classDef root fill:#ffcc00,stroke:#1d4ed8")
+    lines.append("```")
+    return "\n".join(lines)
+
+
+def dump(handle: RunHandle, fmt: str, opts: DumpOptions) -> str:
+    if fmt == "outline":
+        return render_outline(handle, opts)
+    if fmt == "mermaid":
+        return render_mermaid(handle, opts)
+    raise ValueError(f"unknown dump format: {fmt!r}")