autocontext 0.3.4__tar.gz → 0.3.6__tar.gz

{autocontext-0.3.4 → autocontext-0.3.6}/.gitignore

@@ -19,6 +19,10 @@ __pycache__/
 # Node
 node_modules/
 
+# Claude Code / superpowers workflow artifacts
+.claude/projects/
+docs/superpowers/
+
 # OS/editor
 .DS_Store
 

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

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

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

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

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

autocontext-0.3.6/src/autocontext/blobstore/__init__.py

@@ -0,0 +1,15 @@
+"""Deduplicated bucket-backed blob store (AC-518)."""
+
+from __future__ import annotations
+
+from autocontext.blobstore.factory import create_blob_store
+from autocontext.blobstore.ref import BlobRef
+from autocontext.blobstore.registry import BlobRegistry
+from autocontext.blobstore.store import BlobStore
+
+__all__ = [
+    "BlobRef",
+    "BlobRegistry",
+    "BlobStore",
+    "create_blob_store",
+]

autocontext-0.3.6/src/autocontext/blobstore/factory.py

@@ -0,0 +1,38 @@
+"""BlobStore factory (AC-518)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from autocontext.blobstore.store import BlobStore
+
+
+def create_blob_store(
+    backend: str,
+    root: str = "",
+    repo_id: str = "",
+    cache_dir: str = "",
+    **kwargs: object,
+) -> BlobStore:
+    """Create a BlobStore backend from configuration.
+
+    Args:
+        backend: "local" or "hf_bucket"
+        root: Root directory for local backend
+        repo_id: HF repo ID for hf_bucket backend
+        cache_dir: Local cache directory for hf_bucket backend
+    """
+    if backend == "local":
+        from autocontext.blobstore.local import LocalBlobStore
+
+        return LocalBlobStore(root=Path(root))
+
+    if backend == "hf_bucket":
+        from autocontext.blobstore.hf_bucket import HfBucketStore
+
+        return HfBucketStore(
+            repo_id=repo_id,
+            cache_dir=Path(cache_dir) if cache_dir else Path(root) / ".hf_cache",
+        )
+
+    raise ValueError(f"Unknown blob store backend: {backend!r}. Available: 'local', 'hf_bucket'")

autocontext-0.3.6/src/autocontext/blobstore/hf_bucket.py

@@ -0,0 +1,227 @@
+"""Hugging Face Bucket blob store backend (AC-518).
+
+Wraps ``huggingface-cli`` for upload/download. Uses a local cache
+directory for hydrated blobs.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from autocontext.blobstore.store import BlobStore, normalize_blob_key, prefix_matches, resolve_blob_path
+
+logger = logging.getLogger(__name__)
+_INDEX_KEY = ".autocontext/blob_index.json"
+
+
+class HfBucketStore(BlobStore):
+    """HF Buckets backend using huggingface-cli."""
+
+    def __init__(self, repo_id: str, cache_dir: Path, repo_type: str = "dataset") -> None:
+        self.repo_id = repo_id
+        self.cache_dir = cache_dir
+        self.repo_type = repo_type
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def put(self, key: str, data: bytes) -> str:
+        normalized_key = normalize_blob_key(key)
+        # Write to local cache first, then upload
+        cache_path = resolve_blob_path(self.cache_dir, normalized_key)
+        cache_path.parent.mkdir(parents=True, exist_ok=True)
+        cache_path.write_bytes(data)
+        digest = "sha256:" + hashlib.sha256(data).hexdigest()
+
+        self._run_hf_command(
+            [
+                "huggingface-cli",
+                "upload",
+                self.repo_id,
+                str(cache_path),
+                normalized_key,
+                "--repo-type",
+                self.repo_type,
+            ]
+        )
+        index = self._load_index()[1]
+        index[normalized_key] = {
+            "size_bytes": len(data),
+            "digest": digest,
+            "content_type": _guess_content_type(normalized_key),
+        }
+        self._save_index(index)
+        return digest
+
+    def get(self, key: str) -> bytes | None:
+        normalized_key = normalize_blob_key(key)
+        # Try cache first
+        cache_path = resolve_blob_path(self.cache_dir, normalized_key)
+        if cache_path.is_file():
+            return cache_path.read_bytes()
+
+        index_available, index = self._load_index()
+        if index_available and normalized_key not in index:
+            return None
+
+        # Download from remote
+        try:
+            cache_path.parent.mkdir(parents=True, exist_ok=True)
+            self._run_hf_command(
+                [
+                    "huggingface-cli",
+                    "download",
+                    self.repo_id,
+                    normalized_key,
+                    "--repo-type",
+                    self.repo_type,
+                    "--local-dir",
+                    str(cache_path.parent),
+                ]
+            )
+            if cache_path.is_file():
+                return cache_path.read_bytes()
+        except (RuntimeError, OSError):
+            pass
+        return None
+
+    def head(self, key: str) -> dict[str, Any] | None:
+        normalized_key = normalize_blob_key(key)
+        cache_path = resolve_blob_path(self.cache_dir, normalized_key)
+        if cache_path.is_file():
+            data = cache_path.read_bytes()
+            return {
+                "size_bytes": len(data),
+                "digest": "sha256:" + hashlib.sha256(data).hexdigest(),
+                "content_type": _guess_content_type(normalized_key),
+            }
+        index_available, index = self._load_index()
+        if index_available:
+            metadata = index.get(normalized_key)
+            if metadata is not None:
+                return dict(metadata)
+        return None
+
+    def list_prefix(self, prefix: str) -> list[str]:
+        index_available, index = self._load_index()
+        if index_available:
+            return sorted(key for key in index if prefix_matches(key, prefix))
+
+        # Fall back to local cache listing if index is unavailable.
+        try:
+            base = self.cache_dir / prefix.replace("\\", "/")
+            parent = base.parent if not base.is_dir() else base
+            if not parent.is_dir():
+                return []
+            return [
+                p.relative_to(self.cache_dir).as_posix()
+                for p in sorted(parent.rglob("*"))
+                if p.is_file() and prefix_matches(p.relative_to(self.cache_dir).as_posix(), prefix)
+            ]
+        except Exception:
+            return []
+
+    def delete(self, key: str) -> bool:
+        normalized_key = normalize_blob_key(key)
+        cache_path = resolve_blob_path(self.cache_dir, normalized_key)
+        index_available, index = self._load_index()
+        existed = normalized_key in index if index_available else False
+        if index_available and normalized_key in index:
+            del index[normalized_key]
+            self._save_index(index)
+        self._delete_remote_file(normalized_key)
+        if cache_path.is_file():
+            cache_path.unlink()
+            existed = True
+        return existed
+
+    def _load_index(self) -> tuple[bool, dict[str, dict[str, Any]]]:
+        index_path = resolve_blob_path(self.cache_dir, _INDEX_KEY)
+        if not index_path.is_file():
+            try:
+                self._run_hf_command(
+                    [
+                        "huggingface-cli",
+                        "download",
+                        self.repo_id,
+                        _INDEX_KEY,
+                        "--repo-type",
+                        self.repo_type,
+                        "--local-dir",
+                        str(index_path.parent),
+                    ]
+                )
+            except (RuntimeError, OSError):
+                return False, {}
+        if not index_path.is_file():
+            return False, {}
+        try:
+            data = json.loads(index_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            logger.warning("failed to parse HF blob index for %s", self.repo_id)
+            return False, {}
+        if not isinstance(data, dict):
+            return False, {}
+        index: dict[str, dict[str, Any]] = {}
+        for key, metadata in data.items():
+            if isinstance(key, str) and isinstance(metadata, dict):
+                index[key] = dict(metadata)
+        return True, index
+
+    def _save_index(self, index: dict[str, dict[str, Any]]) -> None:
+        index_path = resolve_blob_path(self.cache_dir, _INDEX_KEY)
+        index_path.parent.mkdir(parents=True, exist_ok=True)
+        index_path.write_text(json.dumps(index, indent=2, sort_keys=True), encoding="utf-8")
+        self._run_hf_command(
+            [
+                "huggingface-cli",
+                "upload",
+                self.repo_id,
+                str(index_path),
+                _INDEX_KEY,
+                "--repo-type",
+                self.repo_type,
+            ]
+        )
+
+    def _delete_remote_file(self, key: str) -> None:
+        try:
+            self._run_hf_command(
+                [
+                    "huggingface-cli",
+                    "repo-files",
+                    "delete",
+                    self.repo_id,
+                    key,
+                    "--repo-type",
+                    self.repo_type,
+                ]
+            )
+        except RuntimeError:
+            logger.info("remote delete not available for %s in %s", key, self.repo_id)
+
+    def _run_hf_command(self, cmd: list[str]) -> str:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+        if result.returncode != 0:
+            raise RuntimeError(f"HF command failed: {result.stderr.strip()}")
+        return result.stdout.strip()
+
+
+def _guess_content_type(key: str) -> str:
+    if key.endswith(".json"):
+        return "application/json"
+    if key.endswith(".ndjson"):
+        return "application/x-ndjson"
+    if key.endswith(".md"):
+        return "text/markdown"
+    if key.endswith(".txt"):
+        return "text/plain"
+    return "application/octet-stream"

autocontext-0.3.6/src/autocontext/blobstore/local.py

@@ -0,0 +1,98 @@
+"""Local filesystem blob store — content-addressed by SHA256 (AC-518)."""
+
+from __future__ import annotations
+
+import hashlib
+import shutil
+from pathlib import Path
+from typing import Any
+
+from autocontext.blobstore.store import BlobStore, prefix_matches, resolve_blob_path
+
+
+class LocalBlobStore(BlobStore):
+    """Content-addressed local filesystem backend.
+
+    Blobs are stored at ``root/<key>`` and their SHA256 digest is
+    computed on write. The same content stored under different keys
+    will have the same digest but occupy separate files (simplicity
+    over dedup for the local backend).
+    """
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def put(self, key: str, data: bytes) -> str:
+        digest = _sha256(data)
+        path = resolve_blob_path(self.root, key)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(data)
+        return digest
+
+    def get(self, key: str) -> bytes | None:
+        path = resolve_blob_path(self.root, key)
+        if not path.is_file():
+            return None
+        return path.read_bytes()
+
+    def head(self, key: str) -> dict[str, Any] | None:
+        path = resolve_blob_path(self.root, key)
+        if not path.is_file():
+            return None
+        data = path.read_bytes()
+        return {
+            "size_bytes": len(data),
+            "digest": _sha256(data),
+            "content_type": _guess_content_type(key),
+        }
+
+    def list_prefix(self, prefix: str) -> list[str]:
+        prefix_path = self.root / prefix.replace("\\", "/")
+        base = prefix_path.parent if not prefix_path.is_dir() else prefix_path
+        if not base.is_dir():
+            return []
+        results: list[str] = []
+        for path in sorted(base.rglob("*")):
+            if path.is_file():
+                rel = path.relative_to(self.root).as_posix()
+                if prefix_matches(rel, prefix):
+                    results.append(rel)
+        return results
+
+    def delete(self, key: str) -> bool:
+        path = resolve_blob_path(self.root, key)
+        if not path.is_file():
+            return False
+        path.unlink()
+        return True
+
+    def put_file(self, key: str, path: Path) -> str:
+        dest = resolve_blob_path(self.root, key)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(str(path), str(dest))
+        return _sha256(dest.read_bytes())
+
+    def get_file(self, key: str, dest: Path) -> bool:
+        src = resolve_blob_path(self.root, key)
+        if not src.is_file():
+            return False
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(str(src), str(dest))
+        return True
+
+
+def _sha256(data: bytes) -> str:
+    return "sha256:" + hashlib.sha256(data).hexdigest()
+
+
+def _guess_content_type(key: str) -> str:
+    if key.endswith(".json"):
+        return "application/json"
+    if key.endswith(".ndjson"):
+        return "application/x-ndjson"
+    if key.endswith(".md"):
+        return "text/markdown"
+    if key.endswith(".txt"):
+        return "text/plain"
+    return "application/octet-stream"

autocontext-0.3.6/src/autocontext/blobstore/ref.py

@@ -0,0 +1,52 @@
+"""BlobRef — structured artifact locator (AC-518)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(slots=True)
+class BlobRef:
+    """Reference to a blob artifact with optional local and remote locations."""
+
+    kind: str  # "trace", "checkpoint", "report", "model", "export", ...
+    digest: str  # "sha256:<hex>"
+    size_bytes: int
+    local_path: str = ""
+    remote_uri: str = ""  # e.g. "hf://org/repo/blobs/key"
+    content_type: str = ""
+    created_at: str = ""
+    retention_class: str = ""  # "ephemeral", "durable", "archive"
+
+    @property
+    def is_hydrated(self) -> bool:
+        """True if the blob is available locally."""
+        return bool(self.local_path) and Path(self.local_path).exists()
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "kind": self.kind,
+            "digest": self.digest,
+            "size_bytes": self.size_bytes,
+            "local_path": self.local_path,
+            "remote_uri": self.remote_uri,
+            "content_type": self.content_type,
+            "created_at": self.created_at,
+            "retention_class": self.retention_class,
+            "is_hydrated": self.is_hydrated,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> BlobRef:
+        return cls(
+            kind=data.get("kind", ""),
+            digest=data.get("digest", ""),
+            size_bytes=data.get("size_bytes", 0),
+            local_path=data.get("local_path", ""),
+            remote_uri=data.get("remote_uri", ""),
+            content_type=data.get("content_type", ""),
+            created_at=data.get("created_at", ""),
+            retention_class=data.get("retention_class", ""),
+        )

autocontext-0.3.6/src/autocontext/blobstore/registry.py

@@ -0,0 +1,45 @@
+"""BlobRegistry — tracks BlobRefs by run + artifact name (AC-518)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from autocontext.blobstore.ref import BlobRef
+
+
+class BlobRegistry:
+    """In-memory registry of BlobRefs, persistable to JSON."""
+
+    def __init__(self) -> None:
+        self._entries: dict[str, dict[str, BlobRef]] = {}  # run_id → {name → ref}
+
+    def register(self, run_id: str, name: str, ref: BlobRef) -> None:
+        if run_id not in self._entries:
+            self._entries[run_id] = {}
+        self._entries[run_id][name] = ref
+
+    def lookup(self, run_id: str, name: str) -> BlobRef | None:
+        return self._entries.get(run_id, {}).get(name)
+
+    def list_for_run(self, run_id: str) -> list[BlobRef]:
+        return list(self._entries.get(run_id, {}).values())
+
+    def save(self, path: Path) -> None:
+        data: dict[str, Any] = {}
+        for run_id, entries in self._entries.items():
+            data[run_id] = {name: ref.to_dict() for name, ref in entries.items()}
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+    @classmethod
+    def load(cls, path: Path) -> BlobRegistry:
+        registry = cls()
+        if not path.is_file():
+            return registry
+        data = json.loads(path.read_text(encoding="utf-8"))
+        for run_id, entries in data.items():
+            for name, ref_dict in entries.items():
+                registry.register(run_id, name, BlobRef.from_dict(ref_dict))
+        return registry

autocontext-0.3.6/src/autocontext/blobstore/store.py

@@ -0,0 +1,94 @@
+"""BlobStore abstract base class (AC-518).
+
+Backend-agnostic interface for large artifact storage. Implementations
+must handle put/get/head/list/delete of opaque byte blobs keyed by
+string paths.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path, PurePosixPath, PureWindowsPath
+from typing import Any
+
+
+class BlobStore(ABC):
+    """Abstract blob storage backend."""
+
+    @abstractmethod
+    def put(self, key: str, data: bytes) -> str:
+        """Store bytes at key. Returns digest string (e.g. 'sha256:...')."""
+
+    @abstractmethod
+    def get(self, key: str) -> bytes | None:
+        """Retrieve bytes by key. Returns None if not found."""
+
+    @abstractmethod
+    def head(self, key: str) -> dict[str, Any] | None:
+        """Return metadata (size_bytes, digest, content_type) or None."""
+
+    @abstractmethod
+    def list_prefix(self, prefix: str) -> list[str]:
+        """List all keys matching a prefix."""
+
+    @abstractmethod
+    def delete(self, key: str) -> bool:
+        """Delete a key. Returns True if deleted, False if not found."""
+
+    def put_file(self, key: str, path: Path) -> str:
+        """Store a file at key. Default: read and delegate to put()."""
+        return self.put(key, path.read_bytes())
+
+    def get_file(self, key: str, dest: Path) -> bool:
+        """Retrieve a blob to a file. Returns True on success."""
+        data = self.get(key)
+        if data is None:
+            return False
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_bytes(data)
+        return True
+
+
+def normalize_blob_key(key: str, *, allow_empty: bool = False) -> str:
+    """Normalize a blob key and reject absolute or escaping paths."""
+    if not key:
+        if allow_empty:
+            return ""
+        raise ValueError("blob key must not be empty")
+
+    for path_cls in (PurePosixPath, PureWindowsPath):
+        candidate = path_cls(key)
+        if candidate.is_absolute():
+            raise ValueError(f"invalid blob key: {key!r}")
+
+    normalized = key.replace("\\", "/")
+    parts = [part for part in PurePosixPath(normalized).parts if part not in ("", ".")]
+    if any(part == ".." for part in parts):
+        raise ValueError(f"invalid blob key: {key!r}")
+
+    joined = "/".join(parts)
+    if not joined and not allow_empty:
+        raise ValueError("blob key must not be empty")
+    return joined
+
+
+def resolve_blob_path(root: Path, key: str) -> Path:
+    """Resolve a normalized key under root and reject directory escapes."""
+    normalized = normalize_blob_key(key)
+    root_resolved = root.resolve()
+    candidate = (root / normalized).resolve()
+    try:
+        candidate.relative_to(root_resolved)
+    except ValueError as exc:
+        raise ValueError(f"invalid blob key: {key!r}") from exc
+    return candidate
+
+
+def prefix_matches(key: str, prefix: str) -> bool:
+    """Return True if a normalized key matches a normalized prefix."""
+    normalized_prefix = normalize_blob_key(prefix, allow_empty=True)
+    if not normalized_prefix:
+        return True
+    if prefix.endswith(("/", "\\")):
+        return key == normalized_prefix or key.startswith(normalized_prefix + "/")
+    return key.startswith(normalized_prefix)

autocontext-0.3.6/src/autocontext/bootstrap/__init__.py

@@ -0,0 +1,18 @@
+"""Environment snapshot bootstrapping (AC-503)."""
+
+from __future__ import annotations
+
+from autocontext.bootstrap.collector import collect_snapshot
+from autocontext.bootstrap.redactor import RedactionConfig, redact_snapshot
+from autocontext.bootstrap.renderer import render_full_json, render_prompt_section
+from autocontext.bootstrap.snapshot import EnvironmentSnapshot, PackageInfo
+
+__all__ = [
+    "EnvironmentSnapshot",
+    "PackageInfo",
+    "collect_snapshot",
+    "RedactionConfig",
+    "redact_snapshot",
+    "render_prompt_section",
+    "render_full_json",
+]