autocontext 0.3.2__tar.gz → 0.3.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autocontext
-Version: 0.3.2
+Version: 0.3.3
 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.2`.
+The current PyPI release line is `autocontext==0.3.3`.
 The PyPI package name is now `autocontext`. The CLI entrypoint remains `autoctx`.
 
 ## Working Directory

{autocontext-0.3.2 → autocontext-0.3.3}/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.2`.
+The current PyPI release line is `autocontext==0.3.3`.
 The PyPI package name is now `autocontext`. The CLI entrypoint remains `autoctx`.
 
 ## Working Directory

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

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

autocontext-0.3.3/src/autocontext/agentos/__init__.py

@@ -0,0 +1,5 @@
+"""Optional agentOS integration (AC-517)."""
+
+from autocontext.agentos.types import AgentOsConfig, AgentOsPermissions, AgentOsRuntimePort
+
+__all__ = ["AgentOsConfig", "AgentOsPermissions", "AgentOsRuntimePort"]

autocontext-0.3.3/src/autocontext/agentos/types.py

@@ -0,0 +1,71 @@
+"""agentOS integration types (AC-517).
+
+Port types that define the boundary between autocontext's session
+domain and agentOS's VM runtime.
+
+The runtime port is a Protocol — no direct dependency on
+@rivet-dev/agent-os-core. Python side defines the contract;
+TS side provides the primary implementation.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from pydantic import BaseModel, Field
+
+DEFAULT_SANDBOX_KEYWORDS = [
+    "browser",
+    "playwright",
+    "puppeteer",
+    "selenium",
+    "dev server",
+    "port",
+    "localhost",
+    "gui",
+    "native build",
+    "docker",
+    "container",
+]
+
+
+@runtime_checkable
+class AgentOsRuntimePort(Protocol):
+    """Port interface for agentOS runtime.
+
+    This is the ONLY surface autocontext depends on.
+    Implementors can use real AgentOs or a stub.
+    """
+
+    async def create_session(self, agent_type: str) -> dict[str, Any]: ...
+    async def prompt(self, session_id: str, prompt: str) -> None: ...
+    async def close_session(self, session_id: str) -> None: ...
+    async def dispose(self) -> None: ...
+
+
+class AgentOsPermissions(BaseModel):
+    """Security permissions for the agentOS VM."""
+
+    network: bool = False
+    filesystem: str = "readonly"  # "none" | "readonly" | "readwrite"
+    processes: bool = False
+    max_memory_mb: int = 512
+
+    model_config = {"frozen": True}
+
+
+class AgentOsConfig(BaseModel):
+    """Configuration for optional agentOS integration."""
+
+    enabled: bool = False
+    agent_type: str = "pi"
+    workspace_path: str = ""
+    permissions: AgentOsPermissions = Field(default_factory=AgentOsPermissions)
+    sandbox_escalation_keywords: list[str] = Field(default_factory=lambda: list(DEFAULT_SANDBOX_KEYWORDS))
+
+    model_config = {"frozen": True}
+
+    def needs_sandbox(self, task_description: str) -> bool:
+        """Heuristic: does this task need a full sandbox instead of agentOS?"""
+        lower = task_description.lower()
+        return any(kw in lower for kw in self.sandbox_escalation_keywords)

{autocontext-0.3.2 → autocontext-0.3.3}/src/autocontext/cli.py

@@ -160,6 +160,12 @@ def _write_json_stderr(message: str) -> None:
     sys.stderr.write(json.dumps({"error": message}) + "\n")
 
 
+def _check_json_exit(result: dict[str, Any]) -> None:
+    """Raise SystemExit(1) if JSON result has status=failed (AC-520)."""
+    if isinstance(result, dict) and result.get("status") == "failed":
+        raise SystemExit(1)
+
+
 def _is_agent_task(scenario_name: str) -> bool:
     """Check if a scenario should use the direct agent-task execution path."""
     if scenario_name not in SCENARIO_REGISTRY:
@@ -996,8 +1002,7 @@ def export_cmd(
 
     sqlite = SQLiteStore(resolved_db)
     migrations_dir = Path(__file__).resolve().parents[2] / "migrations"
-    if migrations_dir.exists():
-        sqlite.migrate(migrations_dir)
+    sqlite.migrate(migrations_dir)
     artifacts = ArtifactStore(
         runs_root=resolved_runs,
         knowledge_root=resolved_knowledge,
@@ -1103,6 +1108,7 @@ def simulate(
         result = export_simulation(id=export_id, knowledge_root=settings.knowledge_root, format=export_format)
         if json_output:
             _write_json_stdout(result)
+            _check_json_exit(result)
         elif result["status"] == "failed":
             console.print(f"[red]Export failed:[/red] {result.get('error')}")
             raise typer.Exit(code=1)
@@ -1115,6 +1121,7 @@ def simulate(
         result = engine.compare(left=compare_left, right=compare_right)
         if json_output:
             _write_json_stdout(result)
+            _check_json_exit(result)
         elif result["status"] == "failed":
             console.print(f"[red]Compare failed:[/red] {result.get('error')}")
             raise typer.Exit(code=1)
@@ -1131,6 +1138,7 @@ def simulate(
         )
         if json_output:
             _write_json_stdout(result)
+            _check_json_exit(result)
         elif result["status"] == "failed":
             console.print(f"[red]Replay failed:[/red] {result.get('error')}")
             raise typer.Exit(code=1)
@@ -1159,6 +1167,7 @@ def simulate(
 
     if json_output:
         _write_json_stdout(result)
+        _check_json_exit(result)
     elif result["status"] == "failed":
         console.print(f"[red]Simulation failed:[/red] {result.get('error')}")
         raise typer.Exit(code=1)
@@ -1298,8 +1307,7 @@ def import_package_cmd(
     resolved_db = Path(db_path) if db_path is not None else settings.db_path
     sqlite = SQLiteStore(resolved_db)
     migrations_dir = Path(__file__).resolve().parents[2] / "migrations"
-    if migrations_dir.exists():
-        sqlite.migrate(migrations_dir)
+    sqlite.migrate(migrations_dir)
     artifacts = ArtifactStore(
         runs_root=settings.runs_root,
         knowledge_root=Path(knowledge_root) if knowledge_root else settings.knowledge_root,
@@ -1344,8 +1352,7 @@ def wait(
     settings = load_settings()
     store = SQLiteStore(settings.db_path)
     migrations_dir = Path(__file__).resolve().parents[2] / "migrations"
-    if migrations_dir.exists():
-        store.migrate(migrations_dir)
+    store.migrate(migrations_dir)
 
     # Check condition exists
     condition = store.get_monitor_condition(condition_id)
@@ -1496,8 +1503,7 @@ def queue(
     settings = load_settings()
     store = _sqlite_from_settings(settings)
     migrations_dir = Path(__file__).resolve().parents[2] / "migrations"
-    if migrations_dir.exists():
-        store.migrate(migrations_dir)
+    store.migrate(migrations_dir)
 
     task_id = enqueue_task(store=store, spec_name=spec, priority=priority)
 

{autocontext-0.3.2 → autocontext-0.3.3}/src/autocontext/mcp/_base.py

@@ -28,8 +28,7 @@ class MtsToolContext:
         self.settings = settings
         self.sqlite = SQLiteStore(settings.db_path)
         migrations_dir = Path(__file__).resolve().parents[3] / "migrations"
-        if migrations_dir.exists():
-            self.sqlite.migrate(migrations_dir)
+        self.sqlite.migrate(migrations_dir)
         self.artifacts = ArtifactStore(
             settings.runs_root,
             settings.knowledge_root,

autocontext-0.3.3/src/autocontext/research/consultation.py

@@ -0,0 +1,132 @@
+"""Research consultation — goal decomposition and brief assembly (AC-499).
+
+Domain service: ResearchConsultant decomposes a goal into targeted queries,
+executes them through a ResearchEnabledSession, filters weak signals, deduplicates
+citations, and packages everything into a ResearchBrief value object.
+
+ResearchBrief is a frozen value object suitable for downstream prompt injection.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+
+from pydantic import BaseModel, Field
+
+from autocontext.research.runtime import ResearchEnabledSession
+from autocontext.research.types import Citation, ResearchQuery, ResearchResult, Urgency
+
+logger = logging.getLogger(__name__)
+
+
+class ResearchBrief(BaseModel):
+    """Immutable snapshot of research findings for a goal.
+
+    Produced by ResearchConsultant, consumed by prompt wiring (AC-501).
+    """
+
+    goal: str
+    findings: list[ResearchResult] = Field(default_factory=list)
+    unique_citations: list[Citation] = Field(default_factory=list)
+
+    model_config = {"frozen": True}
+
+    @property
+    def avg_confidence(self) -> float:
+        if not self.findings:
+            return 0.0
+        return sum(f.confidence for f in self.findings) / len(self.findings)
+
+    @classmethod
+    def from_results(
+        cls,
+        goal: str,
+        results: Sequence[ResearchResult],
+        min_confidence: float = 0.0,
+    ) -> ResearchBrief:
+        filtered = [r for r in results if r.confidence >= min_confidence]
+        citations = _dedupe_citations(filtered)
+        return cls(goal=goal, findings=list(filtered), unique_citations=citations)
+
+    @classmethod
+    def empty(cls, goal: str) -> ResearchBrief:
+        return cls(goal=goal)
+
+    def to_markdown(self) -> str:
+        if not self.findings:
+            return f"## Research Brief: {self.goal}\n\nNo findings available.\n"
+
+        parts = [f"## Research Brief: {self.goal}\n"]
+        for f in self.findings:
+            parts.append(f"### {f.query_topic} (confidence: {f.confidence:.0%})\n")
+            parts.append(f"{f.summary}\n")
+            for c in f.citations:
+                label = f"[{c.source}]({c.url})" if c.url else c.source
+                parts.append(f"- {label}")
+                if c.snippet:
+                    parts.append(f"  > {c.snippet}")
+            parts.append("")
+        return "\n".join(parts)
+
+
+def _dedupe_citations(results: Sequence[ResearchResult]) -> list[Citation]:
+    """Collect unique citations across results, keyed by (source, url)."""
+    seen: set[tuple[str, str]] = set()
+    unique: list[Citation] = []
+    for r in results:
+        for c in r.citations:
+            key = (c.source, c.url)
+            if key not in seen:
+                seen.add(key)
+                unique.append(c)
+    return unique
+
+
+class ResearchConsultant:
+    """Domain service: decompose goal → queries → brief.
+
+    Stateless — create one and call .consult() per research need.
+    """
+
+    def __init__(
+        self,
+        urgency: Urgency = Urgency.NORMAL,
+        min_confidence: float = 0.0,
+    ) -> None:
+        self._urgency = urgency
+        self._min_confidence = min_confidence
+
+    def consult(
+        self,
+        session: ResearchEnabledSession,
+        topics: Sequence[str],
+        context: str = "",
+    ) -> ResearchBrief:
+        """Execute research queries and return a packaged brief.
+
+        Respects the session's budget — stops when budget is exhausted.
+        Filters results below min_confidence.
+        """
+        if not session.has_research:
+            logger.debug("No research adapter attached — returning empty brief")
+            return ResearchBrief.empty(session.goal)
+
+        results: list[ResearchResult] = []
+        for topic in topics:
+            query = ResearchQuery(
+                topic=topic,
+                context=context,
+                urgency=self._urgency,
+            )
+            result = session.research(query)
+            if result is None:
+                logger.debug("Budget exhausted after %d queries", len(results))
+                break
+            results.append(result)
+
+        return ResearchBrief.from_results(
+            goal=session.goal,
+            results=results,
+            min_confidence=self._min_confidence,
+        )

autocontext-0.3.3/src/autocontext/research/evaluation.py

@@ -0,0 +1,117 @@
+"""Research A/B evaluation — compare augmented vs baseline (AC-502).
+
+Domain service: ResearchEvaluator pairs baseline and research-augmented
+outputs, scores them with a pluggable score function, and measures
+improvement and citation coverage.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from pydantic import BaseModel
+
+from autocontext.research.consultation import ResearchBrief
+
+logger = logging.getLogger(__name__)
+
+ScoreFn = Callable[[str], float]
+
+
+class EvalResult(BaseModel):
+    """Result of comparing one baseline/augmented pair."""
+
+    baseline_score: float = 0.0
+    augmented_score: float = 0.0
+    improvement: float = 0.0
+    citation_coverage: float = 0.0
+    sample_size: int = 1
+
+    model_config = {"frozen": True}
+
+    @property
+    def is_improvement(self) -> bool:
+        return self.improvement > 0
+
+    @property
+    def relative_gain(self) -> float:
+        if self.baseline_score == 0.0:
+            return float("inf") if self.improvement > 0 else 0.0
+        return self.improvement / self.baseline_score
+
+
+class BatchSummary(BaseModel):
+    """Aggregated summary over multiple eval pairs."""
+
+    sample_size: int = 0
+    avg_baseline: float = 0.0
+    avg_augmented: float = 0.0
+    avg_improvement: float = 0.0
+    win_rate: float = 0.0  # fraction where augmented > baseline
+
+    model_config = {"frozen": True}
+
+
+def _citation_coverage(brief: ResearchBrief, text: str) -> float:
+    """Fraction of unique citation sources mentioned in text."""
+    if not brief.unique_citations:
+        return 0.0
+    mentioned = sum(1 for c in brief.unique_citations if _source_mentioned(c.source, text))
+    return mentioned / len(brief.unique_citations)
+
+
+def _source_mentioned(source: str, text: str) -> bool:
+    """Return True when `source` appears as a distinct mention in `text`."""
+    pattern = rf"(?<!\w){re.escape(source)}(?!\w)"
+    return re.search(pattern, text, flags=re.IGNORECASE) is not None
+
+
+class ResearchEvaluator:
+    """Compares research-augmented vs baseline outputs."""
+
+    def evaluate_pair(
+        self,
+        brief: ResearchBrief,
+        baseline_output: str,
+        augmented_output: str,
+        score_fn: ScoreFn,
+    ) -> EvalResult:
+        baseline_score = score_fn(baseline_output)
+        augmented_score = score_fn(augmented_output)
+        return EvalResult(
+            baseline_score=baseline_score,
+            augmented_score=augmented_score,
+            improvement=augmented_score - baseline_score,
+            citation_coverage=_citation_coverage(brief, augmented_output),
+        )
+
+    def evaluate_batch(
+        self,
+        pairs: Sequence[dict[str, Any]],
+        score_fn: ScoreFn,
+    ) -> BatchSummary:
+        if not pairs:
+            return BatchSummary()
+
+        results: list[EvalResult] = []
+        for p in pairs:
+            r = self.evaluate_pair(
+                brief=p["brief"],
+                baseline_output=p["baseline"],
+                augmented_output=p["augmented"],
+                score_fn=score_fn,
+            )
+            results.append(r)
+
+        n = len(results)
+        wins = sum(1 for r in results if r.is_improvement)
+        return BatchSummary(
+            sample_size=n,
+            avg_baseline=sum(r.baseline_score for r in results) / n,
+            avg_augmented=sum(r.augmented_score for r in results) / n,
+            avg_improvement=sum(r.improvement for r in results) / n,
+            win_rate=wins / n,
+        )

autocontext-0.3.3/src/autocontext/research/persistence.py

@@ -0,0 +1,104 @@
+"""Research evidence persistence — JSON-file store (AC-500).
+
+Persists ResearchBrief snapshots for audit trail, cross-session learning,
+and prompt context windows. Uses one JSON file per brief, indexed by a
+lightweight manifest.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import uuid
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+from autocontext.research.consultation import ResearchBrief
+
+logger = logging.getLogger(__name__)
+
+BRIEFS_DIR = "research_briefs"
+MANIFEST_FILE = "manifest.json"
+
+
+class BriefRef(BaseModel):
+    """Pointer to a persisted brief."""
+
+    brief_id: str
+    session_id: str
+    goal: str
+    created_at: str
+    finding_count: int = 0
+
+    model_config = {"frozen": True}
+
+
+class ResearchStore:
+    """File-backed research brief persistence.
+
+    Layout:
+        root/
+          research_briefs/
+            manifest.json          — [{brief_id, session_id, goal, ...}]
+            <brief_id>.json        — serialized ResearchBrief
+    """
+
+    def __init__(self, root: Path) -> None:
+        self._dir = root / BRIEFS_DIR
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._manifest_path = self._dir / MANIFEST_FILE
+
+    def save_brief(self, session_id: str, brief: ResearchBrief) -> BriefRef:
+        brief_id = uuid.uuid4().hex[:12]
+        ref = BriefRef(
+            brief_id=brief_id,
+            session_id=session_id,
+            goal=brief.goal,
+            created_at=datetime.now(UTC).isoformat(),
+            finding_count=len(brief.findings),
+        )
+
+        brief_path = self._dir / f"{brief_id}.json"
+        brief_path.write_text(brief.model_dump_json(indent=2), encoding="utf-8")
+
+        manifest = self._load_manifest()
+        manifest.append(ref.model_dump())
+        self._write_manifest(manifest)
+
+        logger.debug("Saved brief %s for session %s (%d findings)", brief_id, session_id, len(brief.findings))
+        return ref
+
+    def load_brief(self, brief_id: str) -> ResearchBrief | None:
+        brief_path = self._dir / f"{brief_id}.json"
+        if not brief_path.exists():
+            return None
+        data = json.loads(brief_path.read_text(encoding="utf-8"))
+        return ResearchBrief.model_validate(data)
+
+    def list_briefs(self, session_id: str) -> list[BriefRef]:
+        manifest = self._load_manifest()
+        return [BriefRef.model_validate(e) for e in manifest if e["session_id"] == session_id]
+
+    def brief_count(self) -> int:
+        return len(self._load_manifest())
+
+    def delete_brief(self, brief_id: str) -> bool:
+        brief_path = self._dir / f"{brief_id}.json"
+        if not brief_path.exists():
+            return False
+        brief_path.unlink()
+        manifest = [e for e in self._load_manifest() if e["brief_id"] != brief_id]
+        self._write_manifest(manifest)
+        return True
+
+    def _load_manifest(self) -> list[dict[str, Any]]:
+        if not self._manifest_path.exists():
+            return []
+        data: list[dict[str, Any]] = json.loads(self._manifest_path.read_text(encoding="utf-8"))
+        return data
+
+    def _write_manifest(self, manifest: list[dict[str, Any]]) -> None:
+        self._manifest_path.write_text(json.dumps(manifest, indent=2), encoding="utf-8")

autocontext-0.3.3/src/autocontext/research/prompt_wiring.py

@@ -0,0 +1,75 @@
+"""Research prompt wiring — format briefs for LLM injection (AC-501).
+
+ResearchPromptInjector formats a ResearchBrief into a prompt section,
+handling truncation to a char budget, confidence-based ordering, and
+citation formatting. Supports placeholder injection or append-to-base.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from autocontext.research.consultation import ResearchBrief
+
+logger = logging.getLogger(__name__)
+
+RESEARCH_PLACEHOLDER = "{research}"
+DEFAULT_MAX_CHARS = 4000
+
+
+class ResearchPromptInjector:
+    """Formats research briefs and injects them into prompt templates."""
+
+    def __init__(self, max_chars: int = DEFAULT_MAX_CHARS) -> None:
+        self._max_chars = max_chars
+
+    def format_brief(self, brief: ResearchBrief) -> str:
+        """Render a brief as a markdown section, truncated to budget.
+
+        Findings are ordered by confidence (highest first).
+        Returns empty string if brief has no findings.
+        """
+        if not brief.findings:
+            return ""
+
+        sorted_findings = sorted(brief.findings, key=lambda f: f.confidence, reverse=True)
+
+        parts: list[str] = [f"## External Research: {brief.goal}\n"]
+        budget = self._max_chars - len(parts[0])
+
+        for f in sorted_findings:
+            block_lines = [f"**{f.query_topic}** (confidence: {f.confidence:.0%})"]
+            block_lines.append(f.summary)
+            for c in f.citations:
+                if c.url:
+                    block_lines.append(f"- [{c.source}]({c.url})")
+                else:
+                    block_lines.append(f"- {c.source}")
+            block_lines.append("")
+            block = "\n".join(block_lines)
+
+            if len(block) > budget:
+                if len(parts) == 1:
+                    # At least include one truncated finding
+                    parts.append(block[:budget])
+                break
+            parts.append(block)
+            budget -= len(block)
+
+        return "\n".join(parts)
+
+    def inject(self, base_prompt: str, brief: ResearchBrief) -> str:
+        """Inject formatted brief into a prompt template.
+
+        If base_prompt contains {research}, replaces it.
+        Otherwise appends the section after the base.
+        Returns base_prompt unchanged if brief is empty.
+        """
+        section = self.format_brief(brief)
+        if not section:
+            return base_prompt
+
+        if RESEARCH_PLACEHOLDER in base_prompt:
+            return base_prompt.replace(RESEARCH_PLACEHOLDER, section)
+
+        return f"{base_prompt}\n\n{section}"