arctx 0.2.0b2__tar.gz

arctx-0.2.0b2/.gitignore

@@ -0,0 +1,30 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# ARCTX generated run/output files
+runs/
+arctx_output/
+.arctx/
+state_round_*.json
+request_*.json
+attempts.jsonl
+decisions.jsonl
+findings.jsonl
+requirements.json
+run.json
+
+# Package build artifacts
+dist/
+*.egg-info/
+
+# IDE / Agent state directories
+.claude/
+.antigravitycli/
+

arctx-0.2.0b2/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: arctx
+Version: 0.2.0b2
+Summary: ARCTX: append-only DAG for thought, work context, and parallel exploration
+Project-URL: Homepage, https://github.com/takumiecd/stag
+Project-URL: Repository, https://github.com/takumiecd/stag
+Author: Takumi Ishida
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: fast
+Requires-Dist: orjson>=3.9; extra == 'fast'
+Description-Content-Type: text/markdown
+
+# arctx
+
+Python API for ARCTX (Arc + Context) — records the process of optimization and problem-solving.
+
+## Installation
+
+```bash
+pip install arctx
+```
+
+## Usage
+
+```python
+import arctx as arctx
+
+handle = arctx.init(arctx.Requirement(text="Solve the problem"))
+```
+
+## Package layout
+
+This package provides the core API, storage, and extension framework. The `arctx` command-line tool is in the separate `arctx-cli` package.

arctx-0.2.0b2/README.md

@@ -0,0 +1,21 @@
+# arctx
+
+Python API for ARCTX (Arc + Context) — records the process of optimization and problem-solving.
+
+## Installation
+
+```bash
+pip install arctx
+```
+
+## Usage
+
+```python
+import arctx as arctx
+
+handle = arctx.init(arctx.Requirement(text="Solve the problem"))
+```
+
+## Package layout
+
+This package provides the core API, storage, and extension framework. The `arctx` command-line tool is in the separate `arctx-cli` package.

arctx-0.2.0b2/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "arctx"
+version = "0.2.0b2"
+description = "ARCTX: append-only DAG for thought, work context, and parallel exploration"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "Takumi Ishida"},
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "typing-extensions>=4.0.0",
+]
+
+[project.optional-dependencies]
+fast = [
+    "orjson>=3.9",
+]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "black>=23.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/takumiecd/stag"
+Repository = "https://github.com/takumiecd/stag"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/arctx"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.black]
+line-length = 100
+target-version = ["py310"]
+
+[tool.ruff]
+line-length = 100
+select = ["E", "F", "W", "I", "N", "D", "UP", "B", "C4", "SIM"]
+ignore = ["D100", "D104", "D203", "D213"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true

arctx-0.2.0b2/src/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-0.2.0b2/src/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-0.2.0b2/src/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-0.2.0b2/src/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-0.2.0b2/src/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-0.2.0b2/src/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-0.2.0b2/src/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-0.2.0b2/src/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-0.2.0b2/src/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-0.2.0b2/src/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-0.2.0b2/src/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