vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/services/suggestions/sdk.py

@@ -0,0 +1,228 @@
+"""Lazily binds the suggestion service to Vidbyte SDK Codex agents.
+
+This is the only module that imports SDK symbols. It constructs read-only,
+structured-output agents, places one validated stage context primitive in
+each fresh context manager, and wraps each CLI message tool as an SDK tool.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Any, Literal, Protocol, cast
+
+from ...lib.errors.failures import SuggestionSdkUnavailable
+from ...lib.io.codex_attachments import CodexAttachmentInputBuilder
+from ...types.attachments import AttachmentBundle
+from ...types.suggestions import SuggestionAgentContext
+from .message_tools import SuggestionMessageTool
+
+_CODEX_MODULE = "vidbyte.agents.codex"
+_CONTEXT_MODULE = "vidbyte.context"
+_ERRORS_MODULE = "vidbyte.lib.errors"
+_TOOLS_MODULE = "vidbyte.tools"
+_REQUIRED = (
+    "CodexAgentSettings",
+    "CodexApprovalMode",
+    "CodexHarnessAgentSettings",
+    "CodexRunInput",
+    "CodexSandbox",
+    "CodexThreadSettings",
+    "CodexTurnSettings",
+)
+_TOOL_SYMBOLS = ("BaseTool", "ToolParameter", "ToolResult", "ToolSpec")
+_PROVIDER_MAP = {"openai": "openai"}
+
+
+@dataclass(frozen=True, slots=True)
+class SuggestionSdkBindings:
+    """Validated SDK classes and errors resolved together by the lazy loader."""
+
+    symbols: Mapping[str, Any]
+    agent_type: type
+    provider_error_type: type[Exception]
+    schema_error_type: type[Exception]
+
+    def __post_init__(self) -> None:
+        expected = frozenset((*_REQUIRED, *_TOOL_SYMBOLS, "ContextManager"))
+        if frozenset(self.symbols) != expected:
+            raise ValueError("Suggestion SDK bindings do not match the required surface.")
+        if any(not callable(symbol) for symbol in self.symbols.values()):
+            raise TypeError("Every suggestion SDK binding must be callable.")
+        if not isinstance(self.agent_type, type):
+            raise TypeError("Suggestion SDK agent_type must be a class.")
+        for field_name in ("provider_error_type", "schema_error_type"):
+            value = getattr(self, field_name)
+            if not isinstance(value, type) or not issubclass(value, Exception):
+                raise TypeError(f"Suggestion SDK {field_name} must be an Exception class.")
+        object.__setattr__(self, "symbols", MappingProxyType(dict(self.symbols)))
+
+
+@dataclass(frozen=True, slots=True)
+class SuggestionAgentSettingsInput:
+    """Strict local input for one generator or critic Codex configuration."""
+
+    role: Literal["generator", "critic"]
+    system_prompt: str
+    context: SuggestionAgentContext
+    output_schema: type | Mapping[str, Any]
+    provider: str | None = None
+    model: str | None = None
+    tools: tuple[SuggestionMessageTool, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.role not in ("generator", "critic"):
+            raise ValueError("Suggestion agent role must be generator or critic.")
+        if type(self.system_prompt) is not str or not self.system_prompt.strip():
+            raise ValueError("Suggestion agent system_prompt must be non-empty.")
+        if not isinstance(self.context, SuggestionAgentContext):
+            raise TypeError("Suggestion agent context must be SuggestionAgentContext.")
+        if not isinstance(self.output_schema, (type, Mapping)):
+            raise TypeError("Suggestion agent output_schema must be a class or mapping.")
+        if not isinstance(self.tools, tuple) or any(
+            not isinstance(tool, SuggestionMessageTool) for tool in self.tools
+        ):
+            raise TypeError("Suggestion agent tools must be a tuple of SuggestionMessageTool.")
+        for name, value in (("provider", self.provider), ("model", self.model)):
+            if value is not None and (type(value) is not str or not value.strip()):
+                raise ValueError(f"Suggestion agent {name} must be None or non-empty.")
+
+
+@dataclass(frozen=True, slots=True)
+class SuggestionTextInput:
+    """Strict local input for the single text turn used by this workflow."""
+
+    prompt: str
+    attachments: AttachmentBundle = field(default_factory=AttachmentBundle)
+
+    def __post_init__(self) -> None:
+        if type(self.prompt) is not str or not self.prompt.strip():
+            raise ValueError("Suggestion text prompt must be non-empty.")
+
+
+class SuggestionAgent(Protocol):
+    """Subset of CodexHarnessAgent driven by the suggestion workflow."""
+
+    thread_id: str
+
+    async def arun(self, request: Any) -> Any: ...
+
+
+class SuggestionSdk:
+    """Translates strict local values into fresh, read-only Codex agents."""
+
+    def __init__(self, bindings: SuggestionSdkBindings) -> None:
+        self._bindings = bindings
+
+    @classmethod
+    def load(cls) -> SuggestionSdk:
+        """Resolve the pinned SDK only when a model-backed operation needs it."""
+        try:
+            codex = __import__(_CODEX_MODULE, fromlist=["*"])
+            context = __import__(_CONTEXT_MODULE, fromlist=["ContextManager"])
+            errors = __import__(_ERRORS_MODULE, fromlist=["*"])
+            tools = __import__(_TOOLS_MODULE, fromlist=["*"])
+            symbols = {name: getattr(codex, name) for name in _REQUIRED}
+            symbols.update({name: getattr(tools, name) for name in _TOOL_SYMBOLS})
+            symbols["ContextManager"] = context.ContextManager
+            bindings = SuggestionSdkBindings(
+                symbols=symbols,
+                agent_type=codex.CodexHarnessAgent,
+                provider_error_type=errors.CodexAgentError,
+                schema_error_type=errors.OutputSchemaViolationError,
+            )
+        except (ImportError, AttributeError, TypeError, ValueError) as error:
+            raise SuggestionSdkUnavailable(error) from error
+        return cls(bindings)
+
+    def agent(self, settings: Any) -> SuggestionAgent:
+        """Construct one new SDK agent from already validated settings."""
+        return cast(SuggestionAgent, self._bindings.agent_type(settings))
+
+    def run_input(self, request: SuggestionTextInput) -> Any:
+        """Translate one local text request into the SDK's typed input."""
+        if not isinstance(request, SuggestionTextInput):
+            raise TypeError("run_input requires SuggestionTextInput.")
+        return CodexAttachmentInputBuilder().build(request.prompt, request.attachments)
+
+    def is_provider_error(self, error: Exception) -> bool:
+        """Identify SDK transport/host failures without importing SDK types elsewhere."""
+        return isinstance(error, self._bindings.provider_error_type)
+
+    def is_schema_error(self, error: Exception) -> bool:
+        """Identify a provider reply that violated the declared output schema."""
+        return isinstance(error, self._bindings.schema_error_type)
+
+    def agent_settings(self, request: SuggestionAgentSettingsInput) -> Any:
+        """Build the exact read-only SDK settings for one independent context window."""
+        if not isinstance(request, SuggestionAgentSettingsInput):
+            raise TypeError("agent_settings requires SuggestionAgentSettingsInput.")
+        symbols = self._bindings.symbols
+        provider = "" if request.provider is None else _PROVIDER_MAP.get(request.provider)
+        if request.provider is not None and provider is None:
+            raise ValueError(f"Unsupported suggestion provider: {request.provider}")
+        sandbox = symbols["CodexSandbox"].READ_ONLY
+        deny = symbols["CodexApprovalMode"].DENY_ALL
+        codex = symbols["CodexAgentSettings"](
+            thread=symbols["CodexThreadSettings"](
+                model=request.model or "",
+                model_provider=provider or "",
+                sandbox=sandbox,
+                approval_mode=deny,
+            ),
+            turn=symbols["CodexTurnSettings"](
+                model=request.model or "",
+                sandbox=sandbox,
+                approval_mode=deny,
+            ),
+        )
+        manager = symbols["ContextManager"]()
+        manager.place_after_system_prompt(request.context)
+        return symbols["CodexHarnessAgentSettings"](
+            name=f"suggestion-{request.role}",
+            system_prompt=request.system_prompt,
+            codex=codex,
+            context_manager=manager,
+            output_schema=request.output_schema,
+            tools=tuple(self._message_tool(tool) for tool in request.tools),
+        )
+
+    def _message_tool(self, tool: SuggestionMessageTool) -> Any:
+        # Codex runs custom tools as SDK BaseTools, so each CLI tool gets a thin BaseTool
+        # whose spec is its authored text and whose execute delivers the model's message.
+        symbols = self._bindings.symbols
+        spec = symbols["ToolSpec"](
+            name=tool.name,
+            description=tool.description,
+            parameters=(
+                symbols["ToolParameter"](
+                    name="message", type="string", description=tool.message_description
+                ),
+            ),
+        )
+        result = symbols["ToolResult"]
+        base: Any = symbols["BaseTool"]
+
+        # The base class is only known after the lazy SDK import, so mypy sees it as Any.
+        class _MessageTool(base):  # type: ignore[misc]
+            def spec(self) -> Any:
+                return spec
+
+            async def execute(self, call: Any) -> Any:
+                # An invalid message is returned to the model so it can retry the call.
+                try:
+                    return result.success(tool.name, tool.deliver(call.arguments.get("message")))
+                except ValueError as error:
+                    return result.error(tool.name, str(error))
+
+        return _MessageTool()
+
+
+__all__ = [
+    "SuggestionAgent",
+    "SuggestionAgentSettingsInput",
+    "SuggestionSdk",
+    "SuggestionSdkBindings",
+    "SuggestionTextInput",
+]

vidbyte_cli/services/suggestions/selection.py

@@ -0,0 +1,78 @@
+"""Validates eligibility, ranking, and redundancy for candidate ideas.
+
+Exact duplicates are removed in code by normalized title; semantic overlap is
+left to the generator's revision, guided by the critic's review. Selection
+never invents evidence: every evidence ref must already exist in the run's
+context manifest.
+"""
+
+from __future__ import annotations
+
+from ...types.suggestions import SuggestionIdea
+
+
+class SuggestionSelection:
+    """Applies deterministic selection rules over reviewed candidates."""
+
+    def __init__(self) -> None:
+        # Stateless across runs; all inputs arrive per call.
+        pass
+
+    def validate_evidence(
+        self, ideas: tuple[SuggestionIdea, ...], allowed: set[str]
+    ) -> tuple[SuggestionIdea, ...]:
+        # Drops ideas that cite refs the manifest never issued.
+        return tuple(idea for idea in ideas if set(idea.evidence_refs) <= allowed)
+
+    def validate_categories(
+        self, ideas: tuple[SuggestionIdea, ...], allowed: set[str]
+    ) -> tuple[SuggestionIdea, ...]:
+        # Category ids are checked after model output so a provider cannot invent a lens.
+        return tuple(
+            idea
+            for idea in ideas
+            if idea.primary_category in allowed and set(idea.secondary_categories) <= allowed
+        )
+
+    def deduplicate(self, ideas: tuple[SuggestionIdea, ...]) -> tuple[SuggestionIdea, ...]:
+        # Keeps the first idea per normalized title so ordering stays stable.
+        seen: set[str] = set()
+        kept: list[SuggestionIdea] = []
+        for idea in ideas:
+            key = " ".join(idea.title.lower().split())
+            if key in seen:
+                continue
+            seen.add(key)
+            kept.append(idea)
+        return tuple(kept)
+
+    def suppress_rejected(
+        self, ideas: tuple[SuggestionIdea, ...], rejected: tuple[str, ...]
+    ) -> tuple[SuggestionIdea, ...]:
+        # Removes ideas whose title or summary echoes caller-rejected directions.
+        needles = [item.lower() for item in rejected if item.strip()]
+        if not needles:
+            return ideas
+        kept: list[SuggestionIdea] = []
+        for idea in ideas:
+            haystack = (
+                f"{idea.title} {idea.summary} {idea.first_action} "
+                f"{' '.join(idea.suggested_actions)}"
+            ).lower()
+            if any(needle and needle in haystack for needle in needles):
+                continue
+            kept.append(idea)
+        return tuple(kept)
+
+    def rank(self, ideas: tuple[SuggestionIdea, ...], limit: int) -> tuple[SuggestionIdea, ...]:
+        # Reassigns rank sequentially after trimming to the requested maximum.
+        return tuple(
+            idea.model_copy(update={"rank": index}) for index, idea in enumerate(ideas[:limit], 1)
+        )
+
+    def coverage(self, ideas: tuple[SuggestionIdea, ...]) -> dict[str, int]:
+        # Counts primary categories represented in the final slate.
+        counts: dict[str, int] = {}
+        for idea in ideas:
+            counts[idea.primary_category] = counts.get(idea.primary_category, 0) + 1
+        return counts