autocontext 0.3.3__tar.gz → 0.3.4__tar.gz

{autocontext-0.3.3 → autocontext-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autocontext
-Version: 0.3.3
+Version: 0.3.4
 Summary: autocontext control plane for iterative strategy evolution.
 Project-URL: Homepage, https://github.com/greyhaven-ai/autocontext
 Project-URL: Repository, https://github.com/greyhaven-ai/autocontext
@@ -60,7 +60,7 @@ The intended use is to hand the harness a real task in plain language, let it so
 pip install autocontext
 ```
 
-The current PyPI release line is `autocontext==0.3.3`.
+The current PyPI release line is `autocontext==0.3.4`.
 The PyPI package name is now `autocontext`. The CLI entrypoint remains `autoctx`.
 
 ## Working Directory

{autocontext-0.3.3 → autocontext-0.3.4}/README.md

@@ -10,7 +10,7 @@ The intended use is to hand the harness a real task in plain language, let it so
 pip install autocontext
 ```
 
-The current PyPI release line is `autocontext==0.3.3`.
+The current PyPI release line is `autocontext==0.3.4`.
 The PyPI package name is now `autocontext`. The CLI entrypoint remains `autoctx`.
 
 ## Working Directory

{autocontext-0.3.3 → autocontext-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "autocontext"
-version = "0.3.3"
+version = "0.3.4"
 description = "autocontext control plane for iterative strategy evolution."
 readme = "README.md"
 license = { text = "Apache-2.0" }

autocontext-0.3.4/src/autocontext/session/action_labels.py

@@ -0,0 +1,112 @@
+"""Compact action labels for timelines and event feeds (AC-513).
+
+Domain concept: ActionLabel is a value object — a short, scannable
+description of what just happened. Derived from events, not stored
+as primary data.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel
+
+from autocontext.session.coordinator import CoordinatorEventType
+from autocontext.session.types import SessionEventType
+
+if TYPE_CHECKING:
+    from autocontext.session.coordinator import Coordinator, CoordinatorEvent
+    from autocontext.session.types import SessionEvent
+
+_MAX_LABEL_LEN = 120
+
+_FAILURE_EVENT_TYPES = frozenset({
+    CoordinatorEventType.WORKER_FAILED.value,
+    SessionEventType.TURN_FAILED.value,
+    SessionEventType.TURN_INTERRUPTED.value,
+    SessionEventType.SESSION_FAILED.value,
+    SessionEventType.SESSION_CANCELED.value,
+})
+
+_EVENT_LABEL_MAP: dict[str, str] = {
+    "coordinator_created": "Coordinator started",
+    "worker_delegated": "Worker delegated",
+    "worker_started": "Worker started",
+    "worker_completed": "Worker completed",
+    "worker_failed": "Worker failed",
+    "worker_redirected": "Worker redirected",
+    "fan_out": "Fan-out dispatched",
+    "fan_in": "Fan-in collected",
+    "session_created": "Session started",
+    "session_paused": "Session paused",
+    "session_resumed": "Session resumed",
+    "session_completed": "Session completed",
+    "session_failed": "Session failed",
+    "session_canceled": "Session canceled",
+    "turn_submitted": "Turn submitted",
+    "turn_completed": "Turn completed",
+    "turn_interrupted": "Turn interrupted",
+    "turn_failed": "Turn failed",
+}
+
+
+class ActionLabel(BaseModel):
+    """Short, scannable description for timeline/event display.
+
+    Categories: action, tool, failure, noop, info
+    """
+
+    text: str
+    category: str = "action"
+
+    @classmethod
+    def create(cls, text: str, category: str = "action") -> ActionLabel:
+        truncated = _truncate(text)
+        return cls(text=truncated, category=category)
+
+    @classmethod
+    def noop(cls, reason: str = "No changes") -> ActionLabel:
+        return cls(text=_truncate(reason), category="noop")
+
+    model_config = {"frozen": True}
+
+
+def _truncate(text: str) -> str:
+    """Truncate to _MAX_LABEL_LEN with ellipsis."""
+    text = text.strip().replace("\n", " ")
+    if len(text) <= _MAX_LABEL_LEN:
+        return text
+    return text[: _MAX_LABEL_LEN - 1] + "…"
+
+
+def label_from_event(event: CoordinatorEvent | SessionEvent) -> ActionLabel:
+    """Derive a compact label from a coordinator or session event."""
+    event_type = event.event_type.value
+    base = _EVENT_LABEL_MAP.get(event_type, event_type.replace("_", " ").title())
+
+    # Enrich with payload details
+    payload = event.payload
+    detail_parts: list[str] = []
+    for key in ("task", "role", "reason", "error", "worker_id", "turn_id"):
+        val = payload.get(key)
+        if val:
+            detail_parts.append(f"{key}={str(val)[:40]}")
+
+    if detail_parts:
+        # Keep labels glanceable in narrow timeline views rather than dumping every payload field.
+        detail = ", ".join(detail_parts[:3])
+        text = f"{base}: {detail}"
+    else:
+        text = base
+
+    category = "failure" if event_type in _FAILURE_EVENT_TYPES else "action"
+    return ActionLabel.create(text, category=category)
+
+
+def labels_from_coordinator(
+    coordinator: Coordinator,
+    max_labels: int = 20,
+) -> list[ActionLabel]:
+    """Generate labels from the coordinator's recent events."""
+    events = coordinator.events[-max_labels:]
+    return [label_from_event(e) for e in events]

autocontext-0.3.4/src/autocontext/session/living_docs.py

@@ -0,0 +1,136 @@
+"""Opt-in living docs maintenance (AC-511).
+
+Domain concepts:
+- LivingDoc: entity tracking one opted-in document
+- DocMaintainer: discovers opted-in docs, runs maintenance at safe boundaries
+- DocUpdateResult: structured audit of what was checked and updated
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+_OPT_IN_MARKER = "<!-- living-doc: true -->"
+
+
+class LivingDoc:
+    """Entity tracking one opted-in document.
+
+    Docs opt in via a marker comment: <!-- living-doc: true -->
+    """
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self.is_opted_in = True
+        self.consultation_count = 0
+        self._content: str | None = None
+
+    @classmethod
+    def from_path(cls, path: Path) -> LivingDoc | None:
+        """Parse a file. Returns None if not opted in."""
+        if not path.exists():
+            return None
+        content = path.read_text(encoding="utf-8")
+        if _OPT_IN_MARKER not in content:
+            return None
+        doc = cls(path)
+        doc._content = content
+        return doc
+
+    def record_consultation(self) -> None:
+        self.consultation_count += 1
+
+    def read_content(self) -> str:
+        if self._content is None:
+            self._content = self.path.read_text(encoding="utf-8")
+        return self._content
+
+
+class DocUpdate(BaseModel):
+    """One update applied to a living doc."""
+
+    doc_path: str
+    summary: str
+    lines_changed: int = 0
+
+    model_config = {"frozen": True}
+
+
+class DocUpdateResult(BaseModel):
+    """Structured audit of a maintenance pass."""
+
+    docs_checked: int = 0
+    updates: list[DocUpdate] = Field(default_factory=list)
+    skipped: bool = False
+    reason: str = ""
+
+    model_config = {"frozen": True}
+
+
+class DocMaintainer:
+    """Discovers opted-in docs and runs maintenance.
+
+    Maintenance only runs when:
+    1. Feature is enabled
+    2. There are learnings to promote
+    3. Opted-in docs exist
+    """
+
+    def __init__(
+        self,
+        roots: list[Path] | None = None,
+        enabled: bool = True,
+    ) -> None:
+        self._roots = roots or []
+        self._enabled = enabled
+
+    def discover(self) -> list[LivingDoc]:
+        """Scan roots for opted-in markdown files."""
+        docs: list[LivingDoc] = []
+        for root in self._roots:
+            if not root.is_dir():
+                continue
+            for md in sorted(root.rglob("*.md")):
+                doc = LivingDoc.from_path(md)
+                if doc is not None:
+                    docs.append(doc)
+        return docs
+
+    def run(self, learnings: list[str]) -> DocUpdateResult:
+        """Execute a maintenance pass.
+
+        Returns structured result describing what was checked/updated.
+        """
+        if not self._enabled:
+            return DocUpdateResult(skipped=True, reason="disabled")
+
+        if not learnings:
+            return DocUpdateResult(skipped=True, reason="No learnings to promote")
+
+        docs = self.discover()
+        if not docs:
+            return DocUpdateResult(skipped=True, reason="No opted-in docs found")
+
+        updates: list[DocUpdate] = []
+        for doc in docs:
+            # In the first version, we identify docs that could benefit
+            # from updates based on learnings. Actual rewriting would
+            # use an LLM call — for now we produce the audit trail.
+            _content = doc.read_content()  # noqa: F841 — will be used by LLM rewriter
+            relevant = [item for item in learnings if len(item.strip()) > 10]
+            if relevant:
+                updates.append(DocUpdate(
+                    doc_path=str(doc.path),
+                    summary=f"Candidate for update with {len(relevant)} learning(s)",
+                ))
+
+        logger.info("living docs: checked %d docs, %d candidates", len(docs), len(updates))
+        return DocUpdateResult(
+            docs_checked=len(docs),
+            updates=updates,
+        )

autocontext-0.3.4/tests/test_action_labels.py

@@ -0,0 +1,111 @@
+"""Tests for compact action labels (AC-513).
+
+DDD: ActionLabel is a value object — a short, scannable description
+derived from events, tool calls, and step outcomes.
+"""
+
+from __future__ import annotations
+
+
+class TestActionLabel:
+    """ActionLabel value object for timeline/event display."""
+
+    def test_create_from_text(self) -> None:
+        from autocontext.session.action_labels import ActionLabel
+
+        label = ActionLabel.create("Wrote unit tests for auth module")
+        assert label.text == "Wrote unit tests for auth module"
+        assert label.category == "action"
+
+    def test_truncates_long_text(self) -> None:
+        from autocontext.session.action_labels import ActionLabel
+
+        label = ActionLabel.create("x" * 500)
+        assert len(label.text) <= 120
+        assert label.text.endswith("…")
+
+    def test_category_tagging(self) -> None:
+        from autocontext.session.action_labels import ActionLabel
+
+        assert ActionLabel.create("Ran tests", category="tool").category == "tool"
+        assert ActionLabel.create("Error: timeout", category="failure").category == "failure"
+
+    def test_noop_label(self) -> None:
+        from autocontext.session.action_labels import ActionLabel
+
+        label = ActionLabel.noop("No changes needed")
+        assert label.category == "noop"
+
+
+class TestLabelFromEvent:
+    """Labels derived from coordinator/session events."""
+
+    def test_from_coordinator_event(self) -> None:
+        from autocontext.session.action_labels import label_from_event
+        from autocontext.session.coordinator import CoordinatorEvent, CoordinatorEventType
+
+        event = CoordinatorEvent(
+            event_type=CoordinatorEventType.WORKER_COMPLETED,
+            payload={"worker_id": "w1", "coordinator_id": "c1"},
+        )
+        label = label_from_event(event)
+        assert "completed" in label.text.lower()
+        assert label.category == "action"
+
+    def test_from_session_event(self) -> None:
+        from autocontext.session.action_labels import label_from_event
+        from autocontext.session.types import SessionEvent, SessionEventType
+
+        event = SessionEvent(
+            event_type=SessionEventType.TURN_COMPLETED,
+            payload={"session_id": "s1", "turn_id": "t1", "tokens_used": 150},
+        )
+        label = label_from_event(event)
+        assert label.text
+        assert label.category == "action"
+
+    def test_failure_event_gets_failure_category(self) -> None:
+        from autocontext.session.action_labels import label_from_event
+        from autocontext.session.coordinator import CoordinatorEvent, CoordinatorEventType
+
+        event = CoordinatorEvent(
+            event_type=CoordinatorEventType.WORKER_FAILED,
+            payload={"worker_id": "w1", "error": "timeout"},
+        )
+        label = label_from_event(event)
+        assert label.category == "failure"
+
+
+class TestLabelBatch:
+    """Batch labeling for timeline display."""
+
+    def test_label_batch_from_coordinator(self) -> None:
+        from autocontext.session.action_labels import labels_from_coordinator
+        from autocontext.session.coordinator import Coordinator
+
+        coord = Coordinator.create(session_id="s1", goal="test")
+        w = coord.delegate(task="Research auth", role="researcher")
+        w.start()
+        coord.complete_worker(w.worker_id, result="done")
+
+        labels = labels_from_coordinator(coord, max_labels=10)
+        assert len(labels) == len(coord.events) == 3
+        assert labels[0].text == "Coordinator started"
+        assert labels[1].text.startswith("Worker delegated:")
+        assert "task=Research auth" in labels[1].text
+        assert "role=researcher" in labels[1].text
+        assert "worker_id=" in labels[1].text
+        assert labels[2].text.startswith("Worker completed:")
+        assert "worker_id=" in labels[2].text
+
+    def test_max_labels_respected(self) -> None:
+        from autocontext.session.action_labels import labels_from_coordinator
+        from autocontext.session.coordinator import Coordinator
+
+        coord = Coordinator.create(session_id="s1", goal="test")
+        for i in range(20):
+            coord.delegate(task=f"task-{i}", role="r1")
+
+        labels = labels_from_coordinator(coord, max_labels=5)
+        assert len(labels) == 5
+        assert all(label.text.startswith("Worker delegated") for label in labels)

autocontext-0.3.4/tests/test_living_docs.py

@@ -0,0 +1,87 @@
+"""Tests for opt-in living docs maintenance (AC-511).
+
+DDD: LivingDoc is an entity tracking an opted-in document.
+DocMaintainer orchestrates updates at safe boundaries.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def _write_doc(root: Path, name: str, *, opted_in: bool = True, content: str = "") -> Path:
+    path = root / name
+    path.parent.mkdir(parents=True, exist_ok=True)
+    marker = "<!-- living-doc: true -->" if opted_in else ""
+    path.write_text(f"{marker}\n# {name}\n\n{content or 'Initial content.'}\n", encoding="utf-8")
+    return path
+
+
+class TestLivingDoc:
+    """Entity tracking one opted-in document."""
+
+    def test_detect_opted_in(self, tmp_path: Path) -> None:
+        from autocontext.session.living_docs import LivingDoc
+
+        path = _write_doc(tmp_path, "ARCHITECTURE.md", opted_in=True)
+        doc = LivingDoc.from_path(path)
+        assert doc is not None
+        assert doc.is_opted_in
+
+    def test_skip_non_opted_in(self, tmp_path: Path) -> None:
+        from autocontext.session.living_docs import LivingDoc
+
+        path = _write_doc(tmp_path, "README.md", opted_in=False)
+        doc = LivingDoc.from_path(path)
+        assert doc is None
+
+    def test_tracks_consultation(self, tmp_path: Path) -> None:
+        from autocontext.session.living_docs import LivingDoc
+
+        path = _write_doc(tmp_path, "ARCH.md")
+        doc = LivingDoc.from_path(path)
+        assert doc.consultation_count == 0
+        doc.record_consultation()
+        assert doc.consultation_count == 1
+
+
+class TestDocMaintainer:
+    """Orchestrates doc updates at safe boundaries."""
+
+    def test_discover_opted_in_docs(self, tmp_path: Path) -> None:
+        from autocontext.session.living_docs import DocMaintainer
+
+        _write_doc(tmp_path, "ARCHITECTURE.md", opted_in=True)
+        _write_doc(tmp_path, "README.md", opted_in=False)
+        _write_doc(tmp_path, "docs/ONBOARDING.md", opted_in=True)
+
+        maintainer = DocMaintainer(roots=[tmp_path])
+        docs = maintainer.discover()
+        assert len(docs) == 2
+
+    def test_skip_when_disabled(self, tmp_path: Path) -> None:
+        from autocontext.session.living_docs import DocMaintainer
+
+        _write_doc(tmp_path, "ARCH.md", opted_in=True)
+        maintainer = DocMaintainer(roots=[tmp_path], enabled=False)
+        result = maintainer.run(learnings=["new finding"])
+        assert result.skipped
+        assert "disabled" in result.reason
+
+    def test_skip_when_no_learnings(self, tmp_path: Path) -> None:
+        from autocontext.session.living_docs import DocMaintainer
+
+        _write_doc(tmp_path, "ARCH.md", opted_in=True)
+        maintainer = DocMaintainer(roots=[tmp_path])
+        result = maintainer.run(learnings=[])
+        assert result.skipped
+        assert "no learnings" in result.reason.lower()
+
+    def test_produces_audit_trail(self, tmp_path: Path) -> None:
+        from autocontext.session.living_docs import DocMaintainer
+
+        _write_doc(tmp_path, "ARCH.md", opted_in=True, content="Old architecture info.")
+        maintainer = DocMaintainer(roots=[tmp_path])
+        result = maintainer.run(learnings=["Auth now uses OAuth2"])
+        assert not result.skipped
+        assert len(result.updates) >= 0  # may or may not produce updates depending on signal

{autocontext-0.3.3 → autocontext-0.3.4}/uv.lock

@@ -72,7 +72,7 @@ wheels = [
 
 [[package]]
 name = "autocontext"
-version = "0.3.3"
+version = "0.3.4"
 source = { editable = "." }
 dependencies = [
     { name = "anthropic" },