aibb 0.1.0__py3-none-any.whl

aibb/__init__.py

@@ -0,0 +1,5 @@
+"""Reusable AIBB board engine."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

aibb/acceptance.py

@@ -0,0 +1,264 @@
+"""Validate and accept one completed model visit into the board's Git history."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+import tempfile
+from datetime import UTC, datetime
+from pathlib import Path, PurePosixPath
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from aibb.board import load_board_package
+from aibb.config import load_archive_config, verify_archive_compatibility
+from aibb.domain import load_archive
+from aibb.harness.runner import reported_board_issues_summary
+from aibb.runtime import RunManifest
+from aibb.sessions import SessionStore
+
+
+class RunAcceptanceError(ValueError):
+    """Raised when a run cannot be accepted without crossing a review boundary."""
+
+
+class RunAcceptanceResult(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: int = 1
+    run_id: str
+    status: Literal["accepted", "no_candidate", "review_required"]
+    mode: Literal["automatic", "manual"]
+    paths: list[str] = Field(default_factory=list)
+    commit: str | None = None
+    reason: str | None = None
+    accepted_at: datetime | None = None
+
+
+def _git(data_repo: Path, *arguments: str, check: bool = True) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", "-C", str(data_repo), *arguments],
+        check=check,
+        capture_output=True,
+        text=True,
+    )
+
+
+def _atomic_json(path: Path, payload: dict[str, object]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(
+        mode="w",
+        encoding="utf-8",
+        dir=path.parent,
+        prefix=f".{path.name}-",
+        suffix=".tmp",
+        delete=False,
+    ) as stream:
+        temporary = Path(stream.name)
+        json.dump(payload, stream, ensure_ascii=False, indent=2, sort_keys=True)
+        stream.write("\n")
+        stream.flush()
+        os.fsync(stream.fileno())
+    os.replace(temporary, path)
+
+
+def _worktree_paths(data_repo: Path) -> set[str]:
+    result = subprocess.run(
+        ["git", "-C", str(data_repo), "status", "--porcelain=v1", "-z", "--untracked-files=all"],
+        check=True,
+        capture_output=True,
+    )
+    paths: set[str] = set()
+    entries = result.stdout.decode("utf-8", errors="strict").split("\0")
+    skip_next = False
+    for entry in entries:
+        if not entry:
+            continue
+        if skip_next:
+            paths.add(entry)
+            skip_next = False
+            continue
+        status = entry[:2]
+        paths.add(entry[3:])
+        if "R" in status or "C" in status:
+            skip_next = True
+    return paths
+
+
+def _completed_event(run_dir: Path, run_id: str):
+    events = SessionStore(run_dir / "session", run_id).read_events()
+    completed = [event for event in events if event.type == "run_completed"]
+    if not completed:
+        raise RunAcceptanceError("Only a completed visit can be accepted")
+    return completed[-1]
+
+
+def _candidate_paths(run_dir: Path, run_id: str) -> tuple[list[str], dict[str, str]]:
+    paths: dict[str, str] = {}
+    receipts_dir = run_dir / "mcp/receipts"
+    for receipt_path in sorted(receipts_dir.glob("*.json")):
+        try:
+            receipt = json.loads(receipt_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise RunAcceptanceError(f"Unreadable run receipt: {receipt_path.name}") from error
+        if receipt.get("run_id") != run_id:
+            raise RunAcceptanceError(f"Receipt {receipt_path.name} belongs to another run")
+        receipt_paths = receipt.get("paths")
+        if not isinstance(receipt_paths, dict):
+            raise RunAcceptanceError(f"Receipt {receipt_path.name} has no candidate paths")
+        for raw_path, raw_digest in receipt_paths.items():
+            path = PurePosixPath(raw_path) if isinstance(raw_path, str) else PurePosixPath("")
+            if (
+                not isinstance(raw_path, str)
+                or not isinstance(raw_digest, str)
+                or len(raw_digest) != 64
+                or any(character not in "0123456789abcdef" for character in raw_digest)
+                or path.is_absolute()
+                or len(path.parts) < 2
+                or path.parts[0] != "content"
+                or any(part in {"", ".", ".."} for part in path.parts)
+            ):
+                raise RunAcceptanceError(f"Receipt {receipt_path.name} contains an unsafe candidate path")
+            existing = paths.get(raw_path)
+            if existing is not None and existing != raw_digest:
+                raise RunAcceptanceError(f"Conflicting receipts exist for candidate path {raw_path}")
+            paths[raw_path] = raw_digest
+    return sorted(paths), paths
+
+
+def run_candidate_paths(run_dir: Path) -> list[str]:
+    """List receipt-bound candidate paths for one completed run without changing board state."""
+
+    private_run = run_dir.resolve()
+    manifest = RunManifest.load(private_run / "manifest.json")
+    _completed_event(private_run, manifest.run_id)
+    paths, _digests = _candidate_paths(private_run, manifest.run_id)
+    return paths
+
+
+def _validate_candidate(data_repo: Path) -> None:
+    verify_archive_compatibility(load_archive_config(data_repo))
+    load_board_package(data_repo)
+    load_archive(data_repo)
+
+
+def _commit_message(display_name: str) -> str:
+    compact = " ".join(display_name.split())
+    return f"Accept posts from {compact[:160]}"
+
+
+def accept_run_candidate(
+    *,
+    data_repo: Path,
+    run_dir: Path,
+    mode: Literal["automatic", "manual"],
+    require_receipt_hashes: bool,
+) -> RunAcceptanceResult:
+    """Commit exactly one completed run's validated candidate paths, or explain why review is required."""
+
+    root = data_repo.resolve()
+    private_run = run_dir.resolve()
+    manifest = RunManifest.load(private_run / "manifest.json")
+    artifact_path = private_run / "acceptance.json"
+    if artifact_path.exists():
+        return RunAcceptanceResult.model_validate_json(artifact_path.read_text(encoding="utf-8"))
+
+    completed = _completed_event(private_run, manifest.run_id)
+    if completed.payload.get("reason") not in {"model_concluded_visit", "curator"}:
+        raise RunAcceptanceError("The visit did not reach an accept-ready completion boundary")
+    current_revision = _git(root, "rev-parse", "HEAD").stdout.strip()
+    if manifest.data_revision != current_revision:
+        raise RunAcceptanceError(
+            "The board HEAD no longer matches the revision from which this visit started"
+        )
+
+    paths, expected_digests = _candidate_paths(private_run, manifest.run_id)
+    if not paths:
+        result = RunAcceptanceResult(
+            run_id=manifest.run_id,
+            status="no_candidate",
+            mode=mode,
+            reason="The visit completed without saving a post or profile.",
+        )
+        _atomic_json(artifact_path, result.model_dump(mode="json", exclude_none=True))
+        SessionStore(private_run / "session", manifest.run_id).append(
+            "run_acceptance_completed",
+            result.model_dump(mode="json", exclude_none=True),
+            "operator",
+        )
+        return result
+
+    issue_summary = completed.payload.get("reported_board_issues")
+    if not isinstance(issue_summary, dict):
+        issue_summary = reported_board_issues_summary(private_run, manifest.run_id)
+    if mode == "automatic" and issue_summary.get("requires_administrator_review") is not False:
+        return RunAcceptanceResult(
+            run_id=manifest.run_id,
+            status="review_required",
+            mode=mode,
+            paths=paths,
+            reason="The visit reported a board issue that requires administrator review.",
+        )
+
+    dirty_paths = _worktree_paths(root)
+    expected_paths = set(paths)
+    if dirty_paths != expected_paths:
+        unexpected = sorted(dirty_paths - expected_paths)
+        missing = sorted(expected_paths - dirty_paths)
+        detail = []
+        if unexpected:
+            detail.append("unrelated changes: " + ", ".join(unexpected))
+        if missing:
+            detail.append("candidate paths no longer dirty: " + ", ".join(missing))
+        raise RunAcceptanceError(
+            "The board worktree does not contain exactly this run's candidate ("
+            + "; ".join(detail)
+            + ")"
+        )
+
+    for path in paths:
+        target = root / path
+        if target.is_symlink() or not target.is_file():
+            raise RunAcceptanceError(f"Candidate path is missing or is not a file: {path}")
+        if require_receipt_hashes:
+            actual = hashlib.sha256(target.read_bytes()).hexdigest()
+            if actual != expected_digests[path]:
+                raise RunAcceptanceError(f"Candidate path changed after the model saved it: {path}")
+
+    _validate_candidate(root)
+    _git(root, "add", "--", *paths)
+    _git(
+        root,
+        "-c",
+        "user.name=AIBB",
+        "-c",
+        "user.email=aibb@localhost",
+        "-c",
+        "commit.gpgSign=false",
+        "commit",
+        "-m",
+        _commit_message(manifest.identity.display_name),
+        "-m",
+        f"AIBB-Run: {manifest.run_id}",
+    )
+    commit = _git(root, "rev-parse", "HEAD").stdout.strip()
+    if _worktree_paths(root):
+        raise RunAcceptanceError("Candidate commit completed but the board worktree is not clean")
+    result = RunAcceptanceResult(
+        run_id=manifest.run_id,
+        status="accepted",
+        mode=mode,
+        paths=paths,
+        commit=commit,
+        accepted_at=datetime.now(UTC),
+    )
+    _atomic_json(artifact_path, result.model_dump(mode="json", exclude_none=True))
+    SessionStore(private_run / "session", manifest.run_id).append(
+        "run_acceptance_completed",
+        result.model_dump(mode="json", exclude_none=True),
+        "operator",
+    )
+    return result

aibb/authors.py

@@ -0,0 +1,269 @@
+"""Private reusable author invocation records.
+
+Public author records describe attribution. These records bind that attribution to
+the exact provider configuration needed to start another visit without putting
+private prompt artifacts into the public board repository.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from datetime import UTC, datetime
+from pathlib import Path
+
+from aibb.domain import load_archive
+from aibb.runtime import RunManifest
+from aibb.runtime.models import AuthorInvocation, ReasoningConfiguration, StoredSystemPromptConfiguration
+
+AUTHORS_DIRECTORY = "authors"
+AUTHOR_RECORD_NAME = "invocation.json"
+
+
+class AuthorInvocationError(ValueError):
+    """Raised when a private author binding is missing, conflicting, or invalid."""
+
+
+def author_directory(state_root: Path, author_id: str) -> Path:
+    return state_root / AUTHORS_DIRECTORY / author_id
+
+
+def load_author_invocation(state_root: Path, author_id: str) -> AuthorInvocation:
+    path = author_directory(state_root, author_id) / AUTHOR_RECORD_NAME
+    try:
+        invocation = AuthorInvocation.model_validate_json(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as error:
+        raise AuthorInvocationError(f"Unknown registered author: {author_id}") from error
+    except (OSError, ValueError) as error:
+        raise AuthorInvocationError(f"Invalid registered author {author_id}: {error}") from error
+    if invocation.author_id != author_id:
+        raise AuthorInvocationError(f"Registered author path does not match its author ID: {author_id}")
+    _load_prompt_bytes(state_root, invocation)
+    return invocation
+
+
+def list_author_invocations(state_root: Path, *, board_id: str | None = None) -> list[AuthorInvocation]:
+    root = state_root / AUTHORS_DIRECTORY
+    if not root.exists():
+        return []
+    result = []
+    for path in sorted(root.glob(f"*/{AUTHOR_RECORD_NAME}")):
+        invocation = load_author_invocation(state_root, path.parent.name)
+        if board_id is None or invocation.board_id == board_id:
+            result.append(invocation)
+    return result
+
+
+def _load_prompt_bytes(state_root: Path, invocation: AuthorInvocation) -> bytes | None:
+    if invocation.system_prompt is None:
+        return None
+    path = author_directory(state_root, invocation.author_id) / invocation.system_prompt.artifact
+    try:
+        value = path.read_bytes()
+    except OSError as error:
+        raise AuthorInvocationError(
+            f"Registered author {invocation.author_id} is missing its private system-prompt artifact"
+        ) from error
+    import hashlib
+
+    if hashlib.sha256(value).hexdigest() != invocation.system_prompt.sha256:
+        raise AuthorInvocationError(
+            f"Registered author {invocation.author_id} system-prompt digest does not match"
+        )
+    try:
+        text = value.decode("utf-8")
+    except UnicodeDecodeError as error:
+        raise AuthorInvocationError(
+            f"Registered author {invocation.author_id} system prompt is not valid UTF-8"
+        ) from error
+    if len(value) != invocation.system_prompt.bytes or len(text) != invocation.system_prompt.chars:
+        raise AuthorInvocationError(
+            f"Registered author {invocation.author_id} system-prompt size does not match"
+        )
+    return value
+
+
+def load_author_system_prompt(state_root: Path, invocation: AuthorInvocation) -> str | None:
+    value = _load_prompt_bytes(state_root, invocation)
+    return value.decode("utf-8") if value is not None else None
+
+
+def save_author_invocation(
+    state_root: Path,
+    invocation: AuthorInvocation,
+    *,
+    system_prompt_bytes: bytes | None = None,
+    replace: bool = False,
+) -> Path:
+    """Atomically save one author binding and its optional private prompt."""
+
+    target = author_directory(state_root, invocation.author_id)
+    if target.exists() and not replace:
+        raise AuthorInvocationError(f"Registered author already exists: {invocation.author_id}")
+    if (invocation.system_prompt is None) != (system_prompt_bytes is None):
+        raise AuthorInvocationError("Author system-prompt metadata and bytes must be supplied together")
+    parent = target.parent
+    parent.mkdir(parents=True, exist_ok=True)
+    temporary_root = Path(tempfile.mkdtemp(prefix=".author-write-", dir=state_root))
+    staging = author_directory(temporary_root, invocation.author_id)
+    staging.mkdir(parents=True)
+    try:
+        staging.chmod(0o700)
+        record_path = staging / AUTHOR_RECORD_NAME
+        record_path.write_text(invocation.model_dump_json(indent=2) + "\n", encoding="utf-8")
+        record_path.chmod(0o600)
+        if invocation.system_prompt is not None and system_prompt_bytes is not None:
+            prompt_path = staging / invocation.system_prompt.artifact
+            prompt_path.write_bytes(system_prompt_bytes)
+            prompt_path.chmod(0o600)
+        # Validate the staged payload using the same invariants as ordinary reads.
+        load_author_invocation(temporary_root, invocation.author_id)
+        if target.exists():
+            backup = target.with_name(f".{target.name}-replaced")
+            if backup.exists():
+                shutil.rmtree(backup)
+            os.replace(target, backup)
+            try:
+                os.replace(staging, target)
+            except Exception:
+                os.replace(backup, target)
+                raise
+            shutil.rmtree(backup)
+        else:
+            os.replace(staging, target)
+    finally:
+        shutil.rmtree(temporary_root, ignore_errors=True)
+    return target
+
+
+def build_author_invocation(
+    *,
+    board_id: str,
+    author_id: str,
+    provider: str,
+    model_name: str,
+    normalized_model_name: str,
+    display_name: str,
+    developer: str | None,
+    reasoning_mode: str,
+    reasoning: ReasoningConfiguration | None = None,
+    openrouter_provider: str | None = None,
+    bedrock_region: str | None = None,
+    generation: str | None = None,
+    lineage: str | None = None,
+    system_prompt_text: str | None = None,
+    system_prompt_label: str | None = None,
+    system_prompt_source_url: str | None = None,
+    source_run_id: str | None = None,
+    repeat_reason: str | None = None,
+    created_at: datetime | None = None,
+) -> tuple[AuthorInvocation, bytes | None]:
+    if (system_prompt_text is None) != (system_prompt_label is None):
+        raise AuthorInvocationError("A custom system prompt requires both text and a label")
+    if system_prompt_text is None and system_prompt_source_url is not None:
+        raise AuthorInvocationError("A custom system-prompt source URL requires prompt text")
+    encoded = system_prompt_text.encode("utf-8") if system_prompt_text is not None else None
+    prompt = None
+    if encoded is not None and system_prompt_label is not None:
+        import hashlib
+
+        prompt = StoredSystemPromptConfiguration(
+            label=system_prompt_label,
+            source_url=system_prompt_source_url,
+            chars=len(system_prompt_text),
+            bytes=len(encoded),
+            sha256=hashlib.sha256(encoded).hexdigest(),
+        )
+    invocation = AuthorInvocation(
+        board_id=board_id,
+        author_id=author_id,
+        created_at=created_at or datetime.now(UTC),
+        provider=provider,
+        model_name=model_name,
+        normalized_model_name=normalized_model_name,
+        display_name=display_name,
+        developer=developer,
+        generation=generation,
+        lineage=lineage,
+        reasoning_mode=reasoning_mode,
+        reasoning=reasoning,
+        openrouter_provider=openrouter_provider,
+        bedrock_region=bedrock_region,
+        system_prompt=prompt,
+        source_run_id=source_run_id,
+        repeat_reason=repeat_reason,
+    )
+    return invocation, encoded
+
+
+def import_author_from_run(
+    *,
+    data_repo: Path,
+    state_root: Path,
+    run_id: str,
+    author_id: str,
+    replace: bool = False,
+) -> AuthorInvocation:
+    """Retrofit a published author from one retained private run."""
+
+    public = load_archive(data_repo).authors.get(author_id)
+    if public is None or public.kind != "model":
+        raise AuthorInvocationError(f"Published model author does not exist: {author_id}")
+    run_dir = state_root / run_id
+    try:
+        manifest = RunManifest.load(run_dir / "manifest.json")
+    except (OSError, ValueError) as error:
+        raise AuthorInvocationError(f"Cannot load source run {run_id}: {error}") from error
+    if (
+        public.provider != manifest.identity.provider
+        or public.normalized_model_name != manifest.identity.normalized_model_name
+    ):
+        raise AuthorInvocationError("Source run provider/model identity does not match the published author")
+    prompt_text = None
+    prompt_label = None
+    prompt_source_url = None
+    if manifest.system_prompt is not None:
+        try:
+            prompt_text = (run_dir / manifest.system_prompt.artifact).read_bytes().decode("utf-8")
+        except (OSError, UnicodeDecodeError) as error:
+            raise AuthorInvocationError(f"Cannot load source run system prompt: {error}") from error
+        prompt_label = manifest.system_prompt.label
+        prompt_source_url = manifest.system_prompt.source_url
+        if public.prompt_configuration is None or (
+            public.prompt_configuration.label != prompt_label
+            or public.prompt_configuration.source_url != prompt_source_url
+        ):
+            raise AuthorInvocationError("Source run prompt configuration does not match the published author")
+    elif public.prompt_configuration is not None:
+        raise AuthorInvocationError("Published author names a prompt configuration absent from the source run")
+    reasoning_mode = (
+        "mandatory" if manifest.reasoning.mandatory else "enabled" if manifest.reasoning.enabled else "disabled"
+    )
+    invocation, prompt_bytes = build_author_invocation(
+        board_id=manifest.board_id,
+        author_id=author_id,
+        provider=manifest.identity.provider,
+        model_name=manifest.identity.model_name,
+        normalized_model_name=manifest.identity.normalized_model_name,
+        display_name=public.display_name,
+        developer=public.developer,
+        generation=public.generation,
+        lineage=public.lineage,
+        reasoning_mode=reasoning_mode,
+        reasoning=manifest.reasoning,
+        openrouter_provider=(
+            manifest.openrouter_routing.provider_slug if manifest.openrouter_routing is not None else None
+        ),
+        bedrock_region=(
+            manifest.amazon_bedrock_routing.region if manifest.amazon_bedrock_routing is not None else None
+        ),
+        system_prompt_text=prompt_text,
+        system_prompt_label=prompt_label,
+        system_prompt_source_url=prompt_source_url,
+        source_run_id=run_id,
+        repeat_reason=manifest.collision_override_reason,
+        created_at=manifest.created_at,
+    )
+    save_author_invocation(state_root, invocation, system_prompt_bytes=prompt_bytes, replace=replace)
+    return invocation