yanantin 0.1.0__tar.gz

yanantin-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.serena/
+.uv-cache/
+.env
+.claude/pipeline_health.json
+.claude/heartbeat_state.json
+.claude/work_queue.json
+.claude/.pulse.lock
+logs/
+tmp/
+data/
+.vscode/
+.codex

yanantin-0.1.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: yanantin
+Version: 0.1.0
+Summary: Complementary duality between human and AI — composable tensor infrastructure
+Requires-Python: >=3.14
+Requires-Dist: anthropic>=0.84.0
+Requires-Dist: docker>=7.1.0
+Requires-Dist: duckdb>=1.4.4
+Requires-Dist: flask>=3.1.3
+Requires-Dist: httpx>=0.27
+Requires-Dist: numpy>=2.4.2
+Requires-Dist: opentimestamps>=0.4.5
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-arango>=8.2.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: dropbox
+Requires-Dist: dropbox>=12.0; extra == 'dropbox'

yanantin-0.1.0/conftest.py

@@ -0,0 +1,27 @@
+"""Root conftest: loads .env into os.environ at test startup.
+
+Uses stdlib only. Environment variables already set take precedence
+(setdefault, not overwrite). This replaces hardcoded credentials
+in integration test files.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def pytest_configure(config) -> None:
+    """Load .env file if it exists."""
+    env_file = Path(__file__).parent / ".env"
+    if not env_file.exists():
+        return
+
+    for line in env_file.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        os.environ.setdefault(key.strip(), value.strip())

yanantin-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "yanantin"
+version = "0.1.0"
+description = "Complementary duality between human and AI — composable tensor infrastructure"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "opentimestamps>=0.4.5",
+    "pydantic>=2.0",
+    "httpx>=0.27",
+    "duckdb>=1.4.4",
+    "python-arango>=8.2.6",
+    "flask>=3.1.3",
+    "numpy>=2.4.2",
+    "anthropic>=0.84.0",
+    "docker>=7.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+dropbox = [
+    "dropbox>=12.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/yanantin"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/yanantin",
+    "tests",
+    "conftest.py",
+    "pyproject.toml",
+    "README.md",
+]

yanantin-0.1.0/src/yanantin/__init__.py

@@ -0,0 +1,3 @@
+"""Yanantin: complementary duality between human and AI."""
+
+__version__ = "0.1.0"

yanantin-0.1.0/src/yanantin/activity/__init__.py

@@ -0,0 +1,30 @@
+"""Activity stream layer — temporal fact storage and memory anchors.
+
+Two stores, two concerns:
+- **ActivityStreamStore** — temporal fact storage. High volume, append-only,
+  indexed by (provider_id, timestamp). Schema-agnostic.
+- **ApachetaInterface** — authored tensor storage. Low volume, immutable,
+  queryable by epistemic metadata. Existing, unchanged.
+
+The **MemoryAnchorService** bridges them: it tracks which providers have
+new data (cursors), issues handles to callers, and only persists when
+the write gate opens (updated AND referenced).
+"""
+
+from yanantin.activity.anchor import MemoryAnchorService
+from yanantin.activity.models import (
+    AnchorCursor,
+    AnchorView,
+    FactRecord,
+    MemoryAnchor,
+)
+from yanantin.activity.store import ActivityStreamStore
+
+__all__ = [
+    "ActivityStreamStore",
+    "AnchorCursor",
+    "AnchorView",
+    "FactRecord",
+    "MemoryAnchor",
+    "MemoryAnchorService",
+]

yanantin-0.1.0/src/yanantin/activity/anchor.py

@@ -0,0 +1,190 @@
+"""Memory anchor service — the bridge between facts and tensors.
+
+Issues handles, tracks cursors, manages the two-flag write gate
+(updated AND referenced). Implements Indaleko's ActivityContextService
+pattern: write only when something changed AND someone asked for it.
+
+The service owns the lifecycle:
+- update_cursor() — provider reports new data (sets updated)
+- get_handle() — caller requests current position (sets referenced)
+- flush() — write gate check, persist if both flags set
+- materialize() — resolve an anchor against current streams (always fresh)
+- freeze() — pin a temporal view into a permanent tensor (authored act)
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from uuid import UUID, uuid4
+
+from yanantin.activity.models import AnchorCursor, AnchorView, FactRecord, MemoryAnchor
+from yanantin.activity.store import ActivityStreamStore
+from yanantin.apacheta.interface import ApachetaInterface
+from yanantin.apacheta.models import (
+    ProvenanceEnvelope,
+    SourceIdentifier,
+    StrandRecord,
+    TensorRecord,
+)
+
+
+class MemoryAnchorService:
+    """Issues handles, tracks cursors, manages the write gate.
+
+    The service is the bridge between the fact store and the tensor store.
+    It implements Indaleko's two-flag write gate: updated AND referenced.
+    """
+
+    def __init__(self, store: ActivityStreamStore) -> None:
+        self._store = store
+        self._handle: UUID = uuid4()
+        self._timestamp: datetime = datetime.now(timezone.utc)
+        self._cursors: dict[UUID, AnchorCursor] = {}
+        self._updated: bool = False
+        self._referenced: bool = False
+
+    @property
+    def store(self) -> ActivityStreamStore:
+        """The underlying activity stream store."""
+        return self._store
+
+    def update_cursor(
+        self,
+        provider: UUID,
+        reference: UUID,
+        data: str | None = None,
+        attributes: dict[str, str] | None = None,
+    ) -> bool:
+        """Update a provider's cursor position.
+
+        If the provider exists and reference is unchanged, returns False
+        (no-op). Otherwise updates/adds the cursor and sets updated=True.
+        """
+        existing = self._cursors.get(provider)
+        if existing is not None and existing.reference == reference:
+            return False
+
+        self._cursors[provider] = AnchorCursor(
+            provider=provider,
+            reference=reference,
+            data=data,
+            attributes=attributes,
+        )
+        self._updated = True
+        return True
+
+    def get_handle(self) -> UUID:
+        """Get the current anchor handle, setting referenced=True."""
+        self._referenced = True
+        return self._handle
+
+    def flush(self) -> bool:
+        """Persist anchor if both flags are set (updated AND referenced).
+
+        If the write gate is closed, returns False without writing.
+        If both flags are set: builds MemoryAnchor, stores it, advances
+        handle and timestamp, resets flags. Returns True.
+        """
+        if not (self._updated and self._referenced):
+            return False
+
+        anchor = MemoryAnchor(
+            handle=self._handle,
+            timestamp=self._timestamp,
+            cursors=tuple(self._cursors.values()),
+        )
+        self._store.store_anchor(anchor)
+
+        # Advance: new handle, new timestamp, reset flags
+        self._handle = uuid4()
+        self._timestamp = datetime.now(timezone.utc)
+        self._updated = False
+        self._referenced = False
+
+        return True
+
+    def materialize(self, handle: UUID) -> AnchorView:
+        """Resolve an anchor against current streams.
+
+        Always fresh — queries list_providers() at resolution time
+        (late binding), not just the providers in the anchor's cursor
+        list. A new provider registered after the anchor was created
+        will appear in the view if it has facts before the anchor's
+        timestamp.
+        """
+        anchor = self._store.get_anchor(handle)
+
+        # Late binding: discover ALL current providers
+        all_providers = self._store.list_providers()
+
+        # For each provider, find the latest fact at or before anchor time
+        facts: dict[UUID, FactRecord] = {}
+        for provider_id in all_providers:
+            fact = self._store.query_latest(provider_id, before=anchor.timestamp)
+            if fact is not None:
+                facts[provider_id] = fact
+
+        return AnchorView(
+            handle=anchor.handle,
+            timestamp=anchor.timestamp,
+            facts=facts,
+            providers=tuple(all_providers),
+            anchor=anchor,
+        )
+
+    def freeze(self, handle: UUID, interface: ApachetaInterface) -> UUID:
+        """Pin a temporal view into a permanent tensor.
+
+        This is an authored act — it decides to freeze a temporal view.
+        The resulting tensor has provenance and structured content.
+        """
+        view = self.materialize(handle)
+
+        # Strand 0: Anchor summary
+        summary_lines = [
+            f"handle: {view.handle}",
+            f"timestamp: {view.timestamp.isoformat()}",
+            f"provider_count: {len(view.providers)}",
+            f"fact_count: {len(view.facts)}",
+        ]
+        summary_strand = StrandRecord(
+            strand_index=0,
+            title="Anchor Summary",
+            content="\n".join(summary_lines),
+            topics=("anchor", "summary"),
+        )
+
+        # Strand 1: Anchor data — cursor state + resolved facts
+        anchor_data = {
+            "cursors": [c.model_dump(mode="json") for c in view.anchor.cursors],
+            "resolved_facts": {
+                str(pid): f.model_dump(mode="json")
+                for pid, f in view.facts.items()
+            },
+        }
+        data_strand = StrandRecord(
+            strand_index=1,
+            title="Anchor Data",
+            content=json.dumps(anchor_data, sort_keys=True, separators=(",", ":")),
+            topics=("anchor", "data", "facts"),
+        )
+
+        tensor = TensorRecord(
+            provenance=ProvenanceEnvelope(
+                source=SourceIdentifier(
+                    identifier=view.handle,
+                    description="Memory anchor freeze",
+                ),
+                author_model_family="anchor-service",
+            ),
+            preamble=(
+                f"Frozen anchor {view.handle} at {view.timestamp.isoformat()} "
+                f"({len(view.providers)} providers, {len(view.facts)} facts)"
+            ),
+            strands=(summary_strand, data_strand),
+            lineage_tags=("anchor", "frozen-view"),
+        )
+
+        interface.store_tensor(tensor)
+        return tensor.id

yanantin-0.1.0/src/yanantin/activity/backends/__init__.py

@@ -0,0 +1,18 @@
+"""Activity stream store backends.
+
+Three backends, same contract:
+- InMemoryActivityStreamStore — dict + bisect, for tests
+- DuckDBActivityStreamStore — SQL query pushdown, file-backed
+- ArangoDBActivityStreamStore — AQL + persistent sorted index, production
+"""
+
+from yanantin.activity.backends.memory import InMemoryActivityStreamStore
+
+__all__ = [
+    "InMemoryActivityStreamStore",
+]
+
+# ArangoDB and DuckDB backends are not imported at package level to avoid
+# requiring their dependencies (python-arango, duckdb) for all users.
+# Import directly: from yanantin.activity.backends.arango import ArangoDBActivityStreamStore
+# Import directly: from yanantin.activity.backends.duckdb import DuckDBActivityStreamStore

yanantin-0.1.0/src/yanantin/activity/backends/arango.py

@@ -0,0 +1,308 @@
+"""ArangoDB backend for the activity stream store.
+
+Document-based persistent storage with index-driven temporal queries.
+Uses AQL for query pushdown — the composite persistent index on
+(provider_id, timestamp) makes temporal queries O(log n).
+
+Design:
+- Two collections: activity_facts and activity_anchors
+- Persistent sorted index on activity_facts (provider_id, timestamp)
+- Persistent sorted index on activity_anchors (timestamp)
+- Thread safety via RLock
+- Least-privilege: separate user with rw on these collections only
+"""
+
+from __future__ import annotations
+
+import threading
+from uuid import UUID
+from datetime import datetime
+
+from arango import ArangoClient
+from arango.database import StandardDatabase
+
+from yanantin.activity.models import FactRecord, MemoryAnchor
+from yanantin.activity.store import ActivityStreamStore
+from yanantin.apacheta.interface.errors import ImmutabilityError, NotFoundError
+from yanantin.apacheta.storage_obfuscator import StorageObfuscator, TransparentObfuscator
+
+
+_SEMANTIC_COLLECTIONS = ("activity_facts", "activity_anchors")
+
+
+class ArangoDBActivityStreamStore(ActivityStreamStore):
+    """ArangoDB implementation of ActivityStreamStore.
+
+    Thread-safe via RLock. Enforces immutability. Uses AQL with
+    persistent sorted indexes for O(log n) temporal queries.
+    """
+
+    def __init__(
+        self,
+        host: str = "http://localhost:8529",
+        db_name: str = "apacheta",
+        username: str = "",
+        password: str = "",
+        obfuscator: StorageObfuscator | None = None,
+    ) -> None:
+        self._lock = threading.RLock()
+        self._map = obfuscator or TransparentObfuscator()
+        self._client = ArangoClient(hosts=host)
+        self._host = host
+        self._db_name = db_name
+        self._db = self._connect_database(username, password)
+        self._ensure_collections()
+
+    def _connect_database(self, username: str, password: str) -> StandardDatabase:
+        """Connect to the target database. Fail-stop if it doesn't exist."""
+        try:
+            db = self._client.db(self._db_name, username=username, password=password)
+            db.collections()
+            return db
+        except Exception as e:
+            raise ConnectionError(
+                f"Cannot connect to ArangoDB database '{self._db_name}' at {self._host}. "
+                f"Database must be provisioned by an admin before the application can use it. "
+                f"Error: {e}"
+            ) from e
+
+    def _ensure_collections(self) -> None:
+        """Create collections and indexes if they don't exist."""
+        for name in _SEMANTIC_COLLECTIONS:
+            mapped = self._map.collection_name(name)
+            if not self._db.has_collection(mapped):
+                self._db.create_collection(mapped)
+
+        # Persistent sorted index for temporal queries on facts
+        facts_col = self._db.collection(self._map.collection_name("activity_facts"))
+        facts_col.add_index(
+            {
+                "type": "persistent",
+                "fields": [
+                    self._map.field_name("provider_id"),
+                    self._map.field_name("timestamp"),
+                ],
+                "sparse": False,
+            },
+        )
+
+        # Persistent sorted index for temporal anchor queries
+        anchors_col = self._db.collection(self._map.collection_name("activity_anchors"))
+        anchors_col.add_index(
+            {
+                "type": "persistent",
+                "fields": [self._map.field_name("timestamp")],
+                "sparse": False,
+            },
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    # -- Fact operations -----------------------------------------------
+
+    def store_fact(self, fact: FactRecord) -> None:
+        with self._lock:
+            col = self._db.collection(self._map.collection_name("activity_facts"))
+            key = str(fact.id)
+            if col.has(key):
+                raise ImmutabilityError(
+                    f"Fact {fact.id} already exists. "
+                    "Facts are immutable — append, don't overwrite."
+                )
+            doc = fact.model_dump(mode="json")
+            # Build mapped document: _key + mapped field names
+            mapped_doc = {"_key": key}
+            for k, v in doc.items():
+                if k == "id":
+                    continue  # moved to _key
+                elif k == "provider_id":
+                    mapped_doc[self._map.field_name(k)] = str(v)
+                elif k == "timestamp":
+                    mapped_doc[self._map.field_name(k)] = fact.timestamp.isoformat()
+                else:
+                    mapped_doc[self._map.field_name(k)] = v
+            col.insert(mapped_doc)
+
+    def get_fact(self, fact_id: UUID) -> FactRecord:
+        with self._lock:
+            col = self._db.collection(self._map.collection_name("activity_facts"))
+            doc = col.get(str(fact_id))
+            if doc is None:
+                raise NotFoundError(f"Fact {fact_id} not found.")
+            return self._doc_to_fact(doc)
+
+    def query_latest(
+        self,
+        provider_id: UUID,
+        before: datetime | None = None,
+    ) -> FactRecord | None:
+        with self._lock:
+            col = self._map.collection_name("activity_facts")
+            f_pid = self._map.field_name("provider_id")
+            f_ts = self._map.field_name("timestamp")
+            if before is not None:
+                cursor = self._db.aql.execute(
+                    f"FOR doc IN {col} "
+                    f"  FILTER doc.{f_pid} == @provider_id "
+                    f"  FILTER doc.{f_ts} <= @before "
+                    f"  SORT doc.{f_ts} DESC "
+                    f"  LIMIT 1 "
+                    f"  RETURN doc",
+                    bind_vars={
+                        "provider_id": str(provider_id),
+                        "before": before.isoformat(),
+                    },
+                )
+            else:
+                cursor = self._db.aql.execute(
+                    f"FOR doc IN {col} "
+                    f"  FILTER doc.{f_pid} == @provider_id "
+                    f"  SORT doc.{f_ts} DESC "
+                    f"  LIMIT 1 "
+                    f"  RETURN doc",
+                    bind_vars={"provider_id": str(provider_id)},
+                )
+            docs = list(cursor)
+            if not docs:
+                return None
+            return self._doc_to_fact(docs[0])
+
+    def query_range(
+        self,
+        provider_id: UUID,
+        start: datetime | None = None,
+        end: datetime | None = None,
+    ) -> list[FactRecord]:
+        with self._lock:
+            col = self._map.collection_name("activity_facts")
+            f_pid = self._map.field_name("provider_id")
+            f_ts = self._map.field_name("timestamp")
+
+            filters = [f"doc.{f_pid} == @provider_id"]
+            bind_vars: dict = {"provider_id": str(provider_id)}
+
+            if start is not None:
+                filters.append(f"doc.{f_ts} >= @start")
+                bind_vars["start"] = start.isoformat()
+            if end is not None:
+                filters.append(f"doc.{f_ts} <= @end")
+                bind_vars["end"] = end.isoformat()
+
+            filter_clause = " FILTER ".join([""] + filters)
+            cursor = self._db.aql.execute(
+                f"FOR doc IN {col}"
+                f"  {filter_clause}"
+                f"  SORT doc.{f_ts} ASC"
+                f"  RETURN doc",
+                bind_vars=bind_vars,
+            )
+            return [self._doc_to_fact(doc) for doc in cursor]
+
+    # -- Anchor operations ---------------------------------------------
+
+    def store_anchor(self, anchor: MemoryAnchor) -> None:
+        with self._lock:
+            col = self._db.collection(self._map.collection_name("activity_anchors"))
+            key = str(anchor.handle)
+            if col.has(key):
+                raise ImmutabilityError(
+                    f"Anchor {anchor.handle} already exists. "
+                    "Anchors are immutable — advance, don't overwrite."
+                )
+            doc = anchor.model_dump(mode="json")
+            # Build mapped document
+            mapped_doc = {"_key": key}
+            for k, v in doc.items():
+                if k == "handle":
+                    continue  # moved to _key
+                elif k == "timestamp":
+                    mapped_doc[self._map.field_name(k)] = anchor.timestamp.isoformat()
+                elif k == "cursors":
+                    # Cursors contain model fields --- obfuscate nested dicts
+                    mapped_doc[self._map.field_name(k)] = [
+                        self._map.obfuscate_document(c) if isinstance(c, dict) else c
+                        for c in v
+                    ]
+                else:
+                    mapped_doc[self._map.field_name(k)] = v
+            col.insert(mapped_doc)
+
+    def get_anchor(self, handle: UUID) -> MemoryAnchor:
+        with self._lock:
+            col = self._db.collection(self._map.collection_name("activity_anchors"))
+            doc = col.get(str(handle))
+            if doc is None:
+                raise NotFoundError(f"Anchor {handle} not found.")
+            return self._doc_to_anchor(doc)
+
+    def get_latest_anchor(self) -> MemoryAnchor | None:
+        with self._lock:
+            col = self._map.collection_name("activity_anchors")
+            f_ts = self._map.field_name("timestamp")
+            cursor = self._db.aql.execute(
+                f"FOR doc IN {col} "
+                f"  SORT doc.{f_ts} DESC "
+                f"  LIMIT 1 "
+                f"  RETURN doc"
+            )
+            docs = list(cursor)
+            if not docs:
+                return None
+            return self._doc_to_anchor(docs[0])
+
+    # -- Discovery -----------------------------------------------------
+
+    def list_providers(self) -> list[UUID]:
+        with self._lock:
+            col = self._map.collection_name("activity_facts")
+            f_pid = self._map.field_name("provider_id")
+            cursor = self._db.aql.execute(
+                f"FOR doc IN {col} "
+                f"  COLLECT provider = doc.{f_pid} "
+                f"  RETURN provider"
+            )
+            return [UUID(p) for p in cursor]
+
+    def count_facts(self, provider_id: UUID | None = None) -> int:
+        with self._lock:
+            col = self._map.collection_name("activity_facts")
+            f_pid = self._map.field_name("provider_id")
+            if provider_id is not None:
+                cursor = self._db.aql.execute(
+                    f"RETURN LENGTH("
+                    f"  FOR doc IN {col} "
+                    f"    FILTER doc.{f_pid} == @provider_id "
+                    f"    RETURN 1"
+                    f")",
+                    bind_vars={"provider_id": str(provider_id)},
+                )
+            else:
+                cursor = self._db.aql.execute(
+                    f"RETURN LENGTH({col})"
+                )
+            results = list(cursor)
+            return results[0] if results else 0
+
+    # -- Internal helpers ──────────────────────────────────────────────
+
+    def _doc_to_fact(self, doc: dict) -> FactRecord:
+        """Convert an ArangoDB document to a FactRecord."""
+        # Reverse-map field names, then strip ArangoDB metadata
+        deobfuscated = self._map.deobfuscate_document(doc)
+        data = {k: v for k, v in deobfuscated.items() if not k.startswith("_")}
+        data["id"] = doc["_key"]
+        return FactRecord.model_validate(data)
+
+    def _doc_to_anchor(self, doc: dict) -> MemoryAnchor:
+        """Convert an ArangoDB document to a MemoryAnchor."""
+        deobfuscated = self._map.deobfuscate_document(doc)
+        data = {k: v for k, v in deobfuscated.items() if not k.startswith("_")}
+        data["handle"] = doc["_key"]
+        return MemoryAnchor.model_validate(data)