vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/services/suggestions/context.py

@@ -0,0 +1,222 @@
+"""Builds the bounded context snapshot for one suggestion run.
+
+Only explicitly supplied files are read; nothing scans the repository or the
+Codex history. File contents are treated as task data, never as instructions,
+and omissions or truncations are reported in the manifest rather than hidden.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+from ...types.suggestions import (
+    MAX_CONTEXT_CHARS,
+    ContextManifestEntry,
+    SuggestionContextItem,
+)
+
+ManifestStatus = Literal["included", "truncated", "omitted", "not_supplied"]
+
+_MAX_FILE_CHARS = MAX_CONTEXT_CHARS
+_MAX_TOTAL_CHARS = MAX_CONTEXT_CHARS
+_SUPPORTED_SUFFIXES = {".txt", ".md", ".json"}
+
+
+@dataclass(frozen=True)
+class ContextSnapshot:
+    """Resolved items plus the manifest and warnings the result must carry."""
+
+    items: tuple[SuggestionContextItem, ...]
+    manifest: tuple[ContextManifestEntry, ...]
+    warnings: tuple[str, ...]
+    by_ref: dict[str, str]
+
+
+@dataclass
+class _ContextAccumulator:
+    """Mutable construction state kept private to one context build."""
+
+    items: list[SuggestionContextItem] = field(default_factory=list)
+    manifest: list[ContextManifestEntry] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    total: int = 0
+    counter: int = 0
+
+    def next_ref(self) -> str:
+        self.counter += 1
+        return f"ctx-{self.counter:03d}"
+
+
+class SuggestionContextBuilder:
+    """Reads explicit inputs into stable refs with hashing and limit enforcement."""
+
+    def __init__(self) -> None:
+        # No state across runs; the counter below is per-build and starts at zero.
+        pass
+
+    def build(self, fields: dict[str, tuple[str, ...]], files: tuple[Path, ...]) -> ContextSnapshot:
+        # Resolves text fields first, then files, so refs stay deterministic per run.
+        return self._assemble(fields, files)
+
+    def _assemble(
+        self, fields: dict[str, tuple[str, ...]], files: tuple[Path, ...]
+    ) -> ContextSnapshot:
+        # Keeps the orchestration small while each helper owns one input shape.
+        state = _ContextAccumulator()
+        self._append_fields(state, fields)
+        self._append_files(state, files)
+        if self._contradicts(fields):
+            state.warnings.append(
+                "Supplied context marks one statement both completed "
+                "and in-progress; both are preserved."
+            )
+        return ContextSnapshot(
+            items=tuple(state.items),
+            manifest=tuple(state.manifest),
+            warnings=tuple(state.warnings),
+            by_ref={item.ref: item.content for item in state.items},
+        )
+
+    def _append_fields(
+        self, state: _ContextAccumulator, fields: dict[str, tuple[str, ...]]
+    ) -> None:
+        # Preserves the caller's field order, which makes refs and manifests stable.
+        for kind, values in fields.items():
+            for value in values:
+                self._append_field(state, kind, value)
+
+    def _append_field(self, state: _ContextAccumulator, kind: str, value: str) -> None:
+        # Bounds repeated flag values before Pydantic sees them.
+        original = value.strip()
+        if not original:
+            return
+        ref = state.next_ref()
+        body, status, note = self._bound_text(original, f"{kind} context")
+        if not self._fits(state, len(body)):
+            state.manifest.append(self._manifest_entry(ref, kind, f"flag:{kind}", body, "omitted"))
+            state.warnings.append(f"Omitted {kind} context: total context budget exceeded.")
+            return
+        state.items.append(
+            SuggestionContextItem(
+                ref=ref,
+                kind=kind,
+                label=kind,
+                description="Caller-supplied context value.",
+                content=body,
+                source=f"flag:{kind}",
+                caller_supplied=True,
+            )
+        )
+        state.manifest.append(self._manifest_entry(ref, kind, f"flag:{kind}", body, status))
+        if status == "truncated":
+            state.warnings.append(note)
+        state.total += len(body)
+
+    def _append_files(self, state: _ContextAccumulator, files: tuple[Path, ...]) -> None:
+        # Reads files only after all repeated flag values have been accounted for.
+        for path in files:
+            self._append_file(state, path)
+
+    def _append_file(self, state: _ContextAccumulator, path: Path) -> None:
+        # Rejects invalid files before adding an item or charging the total budget.
+        ref = state.next_ref()
+        body, status, note = self._read_one(path)
+        if not body:
+            state.manifest.append(self._manifest_entry(ref, "file", str(path), body, "omitted"))
+            state.warnings.append(f"Omitted empty context file: {path}.")
+            return
+        if not self._fits(state, len(body)):
+            state.manifest.append(self._manifest_entry(ref, "file", str(path), body, "omitted"))
+            state.warnings.append(f"Omitted {path}: total context budget exceeded.")
+            return
+        state.items.append(
+            SuggestionContextItem(
+                ref=ref,
+                kind="file",
+                label=path.name,
+                description="Caller-supplied file content.",
+                content=body,
+                source=str(path),
+                caller_supplied=False,
+            )
+        )
+        entry_status: ManifestStatus = "truncated" if status == "truncated" else "included"
+        state.manifest.append(self._manifest_entry(ref, "file", str(path), body, entry_status))
+        if status == "truncated":
+            state.warnings.append(note)
+        state.total += len(body)
+
+    def _fits(self, state: _ContextAccumulator, chars: int) -> bool:
+        # Keeps the aggregate body budget independent from prompt and metadata text.
+        return state.total + chars <= _MAX_TOTAL_CHARS
+
+    def _manifest_entry(
+        self,
+        ref: str,
+        kind: str,
+        source: str,
+        body: str,
+        status: ManifestStatus,
+    ) -> ContextManifestEntry:
+        # Hashes the exact bounded body that the agent will receive.
+        return ContextManifestEntry(
+            ref=ref,
+            kind=kind,
+            source=source,
+            chars=len(body),
+            sha256=hashlib.sha256(body.encode("utf-8")).hexdigest()[:16],
+            status=status,
+        )
+
+    def _bound_text(self, text: str, label: str) -> tuple[str, ManifestStatus, str]:
+        # Applies the same generous per-item cap to repeated flag values as to files.
+        if len(text) <= _MAX_FILE_CHARS:
+            return text, "included", ""
+        kept = text[:_MAX_FILE_CHARS]
+        return kept, "truncated", f"Truncated {label} to {_MAX_FILE_CHARS} chars."
+
+    def _read_one(self, path: Path) -> tuple[str, ManifestStatus, str]:
+        # Rejects directories, missing paths, and non-text shapes before reading.
+        if path.is_dir():
+            raise ValueError(f"context path is a directory: {path}")
+        if not path.exists():
+            raise ValueError(f"context file not found: {path}")
+        if path.suffix.lower() not in _SUPPORTED_SUFFIXES:
+            raise ValueError(f"unsupported context file type: {path}")
+        try:
+            text = path.read_text(encoding="utf-8-sig")
+        except OSError as error:
+            raise ValueError(f"unreadable context file: {path}") from error
+        if path.suffix.lower() == ".json":
+            try:
+                parsed = json.loads(text)
+            except json.JSONDecodeError as error:
+                raise ValueError(f"malformed JSON context file: {path}") from error
+            if (
+                isinstance(parsed, dict)
+                and "schema_version" in parsed
+                and parsed["schema_version"] != 1
+            ):
+                raise ValueError(f"unsupported schema version in: {path}")
+            text = json.dumps(parsed, indent=2, sort_keys=True)
+        if len(text) > _MAX_FILE_CHARS:
+            kept = text[:_MAX_FILE_CHARS]
+            return kept, "truncated", f"Truncated {path} to {_MAX_FILE_CHARS} chars."
+        return text, "included", ""
+
+    def _contradicts(self, fields: dict[str, tuple[str, ...]]) -> bool:
+        # Surfaces exact-statement overlap between completed and in-progress lists.
+        completed = {
+            value.strip().lower() for value in fields.get("completed", ()) if value.strip()
+        }
+        in_progress = {
+            value.strip().lower() for value in fields.get("in_progress", ()) if value.strip()
+        }
+        return bool(completed & in_progress)
+
+
+__all__ = ["ContextSnapshot", "SuggestionContextBuilder"]

vidbyte_cli/services/suggestions/extra_compute.py

@@ -0,0 +1,53 @@
+"""Runs one isolated generator context per selected category in parallel."""
+
+from __future__ import annotations
+
+import asyncio
+import math
+from collections.abc import Awaitable, Callable
+from typing import Literal
+
+from ...types.suggestions import (
+    SuggestionAgentContext,
+    SuggestionCandidateBatch,
+    SuggestionDraft,
+    SuggestionRequest,
+)
+from .categories import SuggestionCategories
+from .prompts.library import SuggestionPrompts
+
+AgentCall = Callable[
+    [Literal["generator", "critic"], str, SuggestionAgentContext, str | None],
+    Awaitable[SuggestionCandidateBatch],
+]
+
+
+class ExtraComputeService:
+    """Fans out focused category windows and combines their typed drafts stably."""
+
+    def __init__(self, categories: SuggestionCategories, prompts: SuggestionPrompts) -> None:
+        self._categories = categories
+        self._prompts = prompts
+
+    async def generate(
+        self,
+        request: SuggestionRequest,
+        category_ids: tuple[str, ...],
+        pool_size: int,
+        call: AgentCall,
+    ) -> tuple[SuggestionDraft, ...]:
+        per_category = max(1, math.ceil(pool_size / len(category_ids)))
+
+        async def run_one(category_id: str) -> SuggestionCandidateBatch:
+            context = SuggestionAgentContext.for_stage(
+                request.context, self._categories.prompt_section((category_id,))
+            )
+            prompt = self._prompts.generator_turn(request.goal, per_category)
+            return await call("generator", prompt, context, None)
+
+        batches = await asyncio.gather(*(run_one(category) for category in category_ids))
+        drafts = tuple(draft for batch in batches for draft in batch.ideas)
+        return drafts[:pool_size]
+
+
+__all__ = ["AgentCall", "ExtraComputeService"]

vidbyte_cli/services/suggestions/handoff.py

@@ -0,0 +1,173 @@
+"""Builds deterministic execution handoffs from validated suggestion fields."""
+
+from __future__ import annotations
+
+from ...types.suggestions import (
+    SuggestionDraft,
+    SuggestionHandoff,
+    SuggestionHandoffEvidence,
+    SuggestionIdea,
+    SuggestionRequest,
+)
+
+
+class SuggestionHandoffBuilder:
+    """Builds one self-contained action packet without another model call."""
+
+    def build(self, idea: SuggestionIdea, request: SuggestionRequest) -> SuggestionHandoff:
+        """Rebuild a handoff from the idea fields so the prompt cannot drift."""
+        return self._build(
+            idea_id=idea.id,
+            revision=idea.revision,
+            title=idea.title,
+            summary=idea.summary,
+            actions=idea.suggested_actions,
+            decisions=idea.decision_points,
+            considerations=idea.considerations,
+            evidence_refs=idea.evidence_refs,
+            completion=idea.completion_criteria,
+            dependencies=idea.dependencies,
+            why_now=idea.why_now,
+            request=request,
+        )
+
+    def build_draft(
+        self, draft: SuggestionDraft, request: SuggestionRequest, idea_id: str, revision: int
+    ) -> SuggestionHandoff:
+        """Build the provisional handoff used when the critic sees generated candidates."""
+        return self._build(
+            idea_id=idea_id,
+            revision=revision,
+            title=draft.title,
+            summary=draft.summary,
+            actions=draft.suggested_actions,
+            decisions=draft.decision_points,
+            considerations=draft.considerations,
+            evidence_refs=draft.evidence_refs,
+            completion=draft.completion_criteria,
+            dependencies=draft.dependencies,
+            why_now=draft.why_now,
+            request=request,
+        )
+
+    def _build(
+        self,
+        *,
+        idea_id: str,
+        revision: int,
+        title: str,
+        summary: str,
+        actions: tuple[str, ...],
+        decisions: tuple[str, ...],
+        considerations: tuple[str, ...],
+        evidence_refs: tuple[str, ...],
+        completion: str,
+        dependencies: tuple[str, ...],
+        why_now: str,
+        request: SuggestionRequest,
+    ) -> SuggestionHandoff:
+        handoff = SuggestionHandoff(
+            idea_id=idea_id,
+            idea_revision=revision,
+            original_goal=request.goal,
+            title=title,
+            summary=summary,
+            suggested_actions=actions,
+            decisions_along_way=decisions,
+            considerations=considerations,
+            evidence=self._evidence(evidence_refs, request, why_now),
+            completion_checks=(completion,),
+            dependencies=dependencies,
+            warnings=self._warnings(request),
+            forbidden_actions=self._context_values(request, "forbidden"),
+            stop_conditions=(
+                "The completion checks pass.",
+                "Evidence contradicts the proposed action.",
+                "Required authority is missing.",
+                "Required prerequisites are missing.",
+            ),
+            return_report=(
+                "Report actions taken, decisions made, evidence observed, completion checks, "
+                "and unresolved follow-ups to the calling agent."
+            ),
+            execution_prompt="pending",
+        )
+        return handoff.model_copy(update={"execution_prompt": self.render_prompt(handoff)})
+
+    def render_prompt(self, handoff: SuggestionHandoff) -> str:
+        """Render only validated fields in a stable order."""
+        lines = [
+            f"Goal: {handoff.original_goal}",
+            f"Suggested action: {handoff.title}",
+            f"Summary: {handoff.summary}",
+            "Actions:",
+            *self._lines(handoff.suggested_actions),
+            "Decisions along the way:",
+            *self._lines(handoff.decisions_along_way),
+            "Things to consider:",
+            *self._lines(handoff.considerations),
+            "Evidence:",
+            *self._evidence_lines(handoff.evidence),
+            "Completion checks:",
+            *self._lines(handoff.completion_checks),
+            "Dependencies:",
+            *self._lines(handoff.dependencies),
+            "Warnings:",
+            *self._lines(handoff.warnings),
+            "Forbidden actions:",
+            *self._lines(handoff.forbidden_actions),
+            "Stop when:",
+            *self._lines(handoff.stop_conditions),
+            f"Authority: {handoff.authority}",
+            f"Report: {handoff.return_report}",
+        ]
+        return "\n".join(lines)
+
+    def _evidence(
+        self, refs: tuple[str, ...], request: SuggestionRequest, why_now: str
+    ) -> tuple[SuggestionHandoffEvidence, ...]:
+        items_by_ref = {item.ref: item for item in request.context_items}
+        return tuple(
+            SuggestionHandoffEvidence(
+                ref=ref,
+                source=items_by_ref[ref].source,
+                content=items_by_ref[ref].content[:4096],
+                relevance=f"Supports why this action matters now: {why_now}",
+            )
+            for ref in refs
+            if ref in items_by_ref
+        )
+
+    def _warnings(self, request: SuggestionRequest) -> tuple[str, ...]:
+        warnings = list(request.context_warnings)
+        for item in request.context_items:
+            if item.kind == "mistake":
+                parts = tuple(part.strip() for part in item.content.split("|"))
+                if len(parts) == 3 and all(parts):
+                    warnings.append(
+                        f"Past mistake lesson: {parts[2]} (failure: {parts[0]}; cause: {parts[1]})"
+                    )
+                else:
+                    warnings.append(item.content)
+            elif item.kind == "risk" or (
+                item.kind == "hypothesis" and item.content.lower().startswith("low:")
+            ):
+                warnings.append(item.content)
+        return tuple(dict.fromkeys(warnings))
+
+    def _context_values(self, request: SuggestionRequest, kind: str) -> tuple[str, ...]:
+        return tuple(item.content for item in request.context_items if item.kind == kind)
+
+    def _lines(self, values: tuple[str, ...]) -> list[str]:
+        return [f"- {value}" for value in values] or ["- none supplied"]
+
+    def _evidence_lines(self, evidence: tuple[SuggestionHandoffEvidence, ...]) -> list[str]:
+        if not evidence:
+            return ["- none cited"]
+        return [
+            f"- [{item.ref}] {item.content} (source: {item.source}; {item.relevance})"
+            for item in evidence
+        ]
+
+
+__all__ = ["SuggestionHandoffBuilder"]

vidbyte_cli/services/suggestions/message_tools.py

@@ -0,0 +1,47 @@
+"""Stop-and-message tools that let one suggestion agent end its turn with a message.
+
+This module owns the CLI side of each tool: its model-facing text, the message
+validation, and the stop signal the service waits on. It never imports the SDK;
+`sdk.py` wraps each tool as an SDK `BaseTool` so Codex can call it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Literal
+
+from ...types.suggestions import MAX_AGENT_MESSAGE_CHARS
+from .prompts.library import SuggestionPrompts
+
+MessageToolName = Literal["message_parent", "message_generator"]
+
+
+class SuggestionMessageTool:
+    """One agent's route to another agent: the first valid message stops its turn."""
+
+    def __init__(self, name: MessageToolName, prompts: SuggestionPrompts) -> None:
+        # One instance serves exactly one agent, so its message and signal are never shared.
+        self.name = name
+        self.description = prompts.message_tool(name)
+        self.message_description = prompts.message_argument(name)
+        self._receipt = prompts.message_receipt()
+        self.message: str | None = None
+        self.stopped = asyncio.Event()
+
+    def deliver(self, message: object) -> str:
+        """Record the model's message, signal the stop, and return the tool receipt."""
+        if not isinstance(message, str) or not message.strip():
+            raise ValueError(f"{self.name} requires a non-empty message string.")
+        text = message.strip()
+        if len(text) > MAX_AGENT_MESSAGE_CHARS:
+            raise ValueError(
+                f"{self.name} messages must be at most {MAX_AGENT_MESSAGE_CHARS} characters."
+            )
+        # A second call in the same turn cannot replace the message already being delivered.
+        if self.message is None:
+            self.message = text
+            self.stopped.set()
+        return self._receipt
+
+
+__all__ = ["MessageToolName", "SuggestionMessageTool"]