vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/types/attachments.py

@@ -0,0 +1,79 @@
+"""Provider-neutral contracts for explicit files supplied to future agent invocations.
+
+These models describe one immutable snapshot and its body-free output manifest. Filesystem
+access and provider-specific conversion belong to the I/O layer, not to these contracts.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class AttachmentKind(StrEnum):
+    """The two file forms the first shared attachment contract supports."""
+
+    TEXT = "text"
+    IMAGE = "image"
+
+
+class AgentAttachment(BaseModel):
+    """One validated file snapshot with provenance and integrity metadata."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    supplied_path: Path
+    resolved_path: Path
+    name: str = Field(min_length=1, max_length=256)
+    kind: AttachmentKind
+    size_bytes: int = Field(gt=0)
+    sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    content: str | None = None
+
+    @model_validator(mode="after")
+    def validate_content_shape(self) -> AgentAttachment:
+        # Images use the native path input; text attachments carry the captured body.
+        if self.kind is AttachmentKind.TEXT and not self.content:
+            raise ValueError("text attachments require content")
+        if self.kind is AttachmentKind.IMAGE and self.content is not None:
+            raise ValueError("image attachments cannot carry text content")
+        return self
+
+
+class AttachmentBundle(BaseModel):
+    """An ordered immutable attachment collection resolved for one invocation."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    items: tuple[AgentAttachment, ...] = ()
+    total_bytes: int = Field(default=0, ge=0)
+
+    @model_validator(mode="after")
+    def validate_totals_and_paths(self) -> AttachmentBundle:
+        # The bundle owns the aggregate invariants so programmatic callers cannot bypass limits.
+        sizes = sum(item.size_bytes for item in self.items)
+        if sizes != self.total_bytes:
+            raise ValueError("attachment total_bytes must equal the sum of item sizes")
+        paths = tuple(item.resolved_path for item in self.items)
+        if len(set(paths)) != len(paths):
+            raise ValueError("attachment resolved paths must be unique")
+        return self
+
+    def manifest(self) -> tuple[dict[str, object], ...]:
+        # Emits safe metadata only; attachment bodies never enter machine-facing manifests.
+        return tuple(
+            {
+                "supplied_path": str(item.supplied_path),
+                "resolved_path": str(item.resolved_path),
+                "name": item.name,
+                "kind": item.kind.value,
+                "size_bytes": item.size_bytes,
+                "sha256": item.sha256,
+            }
+            for item in self.items
+        )
+
+
+__all__ = ["AgentAttachment", "AttachmentBundle", "AttachmentKind"]

vidbyte_cli/types/ensemble.py

@@ -0,0 +1,189 @@
+"""Typed contracts for the same-host ensemble runtime primitive.
+
+`EnsembleInputs` is the whole command surface as one validated value, so a bound holds
+whether the value came from Click or from a programmatic caller. `RolePlan`, `RoleProposal`,
+and `SelectionRound` are the three structured-output schemas the agents themselves fill in;
+each is the only shape its stage can return, which is what makes the handoffs deterministic.
+
+Nothing here crosses the API boundary: the backend sees only admission metadata.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# The proposal band every role is held to, named once so the schema and the authored mandate
+# that tells the role about it cannot drift apart.
+APPROACHES_PER_ROLE_MIN = 5
+APPROACHES_PER_ROLE_MAX = 10
+
+# The largest roster the planner may be asked for, which also bounds RolePlan's own schema.
+ROLES_MIN = 3
+ROLES_MAX = 100
+
+
+class EnsembleHost(StrEnum):
+    """Native hosts the ensemble can actually run on today."""
+
+    CODEX = "codex"
+
+
+class EnsembleReasoningEffort(StrEnum):
+    """Reasoning-effort values the Codex integration accepts."""
+
+    NONE = "none"
+    MINIMAL = "minimal"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    XHIGH = "xhigh"
+
+
+class EnsembleConfidence(StrEnum):
+    """How strongly a role stands behind one approach it proposed."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class EnsembleInputs(BaseModel):
+    """Every caller-settable ensemble option, validated once as a single value."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    task: str = Field(min_length=1, max_length=20_000)
+    host: EnsembleHost = EnsembleHost.CODEX
+    roles: int = Field(default=3, ge=ROLES_MIN, le=ROLES_MAX)
+    model: str | None = Field(default=None, max_length=128)
+    reasoning_effort: EnsembleReasoningEffort | None = None
+    role_timeout_seconds: int = Field(default=300, ge=1, le=3600)
+
+
+class GeneratedRole(BaseModel):
+    """One role the planner invented, as the six sections its prompt is built from."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    name: str = Field(min_length=1, max_length=64)
+    identity: str = Field(min_length=1, max_length=4_000)
+    personality: str = Field(min_length=1, max_length=4_000)
+    expertise: str = Field(min_length=1, max_length=8_000)
+    knowledge: str = Field(min_length=1, max_length=8_000)
+    skills: str = Field(min_length=1, max_length=8_000)
+    goal: str = Field(min_length=1, max_length=4_000)
+
+
+class RolePlan(BaseModel):
+    """The planner turn's structured output: the ensemble's whole roster."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    task_analysis: str = Field(min_length=1, max_length=8_000)
+    roster_strategy: str = Field(min_length=1, max_length=8_000)
+    coverage_summary: str = Field(min_length=1, max_length=8_000)
+    roles: tuple[GeneratedRole, ...] = Field(min_length=1, max_length=ROLES_MAX)
+
+
+class ProposedApproach(BaseModel):
+    """One candidate way to do the task, weighed by the role that thought of it."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    title: str = Field(min_length=1, max_length=120)
+    approach: str = Field(min_length=1, max_length=8_000)
+    pros: tuple[str, ...] = Field(min_length=1, max_length=10)
+    cons: tuple[str, ...] = Field(min_length=1, max_length=10)
+    risks: tuple[str, ...] = Field(default=(), max_length=10)
+    files: tuple[str, ...] = Field(default=(), max_length=50)
+    confidence: EnsembleConfidence
+    assumptions: tuple[str, ...] = Field(min_length=1, max_length=20)
+    tradeoffs: tuple[str, ...] = Field(min_length=1, max_length=20)
+    validation_steps: tuple[str, ...] = Field(min_length=1, max_length=20)
+
+
+class RoleProposal(BaseModel):
+    """One read-only role's whole slate of candidate approaches, never an edit."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    role: str = Field(min_length=1, max_length=64)
+    task_analysis: str = Field(min_length=1, max_length=8_000)
+    role_strategy: str = Field(min_length=1, max_length=8_000)
+    approaches: tuple[ProposedApproach, ...] = Field(
+        min_length=APPROACHES_PER_ROLE_MIN, max_length=APPROACHES_PER_ROLE_MAX
+    )
+
+
+class CandidateVerdict(BaseModel):
+    """The selector's weighing of one candidate it chose to keep in a round."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    candidate_id: str = Field(min_length=1, max_length=32)
+    pros: tuple[str, ...] = Field(min_length=1, max_length=10)
+    cons: tuple[str, ...] = Field(min_length=1, max_length=10)
+    score: int = Field(ge=1, le=100)
+    rationale: str = Field(min_length=1, max_length=4_000)
+    evidence: tuple[str, ...] = Field(min_length=1, max_length=20)
+    uncertainties: tuple[str, ...] = Field(default=(), max_length=20)
+    implementation_guidance: str = Field(min_length=1, max_length=8_000)
+
+
+class SelectionRound(BaseModel):
+    """One narrowing round's structured output: who survived it, and who did not."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    round_summary: str = Field(min_length=1, max_length=8_000)
+    comparison_basis: tuple[str, ...] = Field(min_length=1, max_length=20)
+    kept: tuple[CandidateVerdict, ...] = Field(min_length=1, max_length=1_000)
+    eliminated: tuple[str, ...] = Field(default=(), max_length=1_000)
+
+
+class ApproachCandidate(BaseModel):
+    """One numbered approach on the selector's slate, joined to the role that proposed it.
+
+    The id is assigned by the service rather than by any agent, so the identifiers the
+    selector echoes back can be checked against the slate it was actually given.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    candidate_id: str
+    role: str
+    task_analysis: str
+    role_strategy: str
+    approach: ProposedApproach
+
+
+class SelectedApproach(BaseModel):
+    """The single approach the selector ended on, with the verdict that chose it."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    candidate: ApproachCandidate
+    verdict: CandidateVerdict
+    round_summary: str
+    comparison_basis: tuple[str, ...]
+
+
+class EnsembleRoleFailure(BaseModel):
+    """Why one role produced no proposal, in a closed machine-branchable vocabulary."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    role: str = Field(min_length=1, max_length=64)
+    reason: Literal["timeout", "host_error", "invalid_output"]
+
+
+class EnsembleResult(BaseModel):
+    """The complete outcome of one ensemble run, including its partial failures."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    task: str
+    host: EnsembleHost
+    roles: tuple[GeneratedRole, ...]
+    proposals: tuple[RoleProposal, ...]
+    failures: tuple[EnsembleRoleFailure, ...]
+    candidates: int
+    rounds: tuple[SelectionRound, ...]
+    selected: SelectedApproach
+    implementation: str
+    root_thread_id: str
+    selector_thread_id: str
+    implementer_thread_id: str
+    charged_cents: int

vidbyte_cli/types/provider.py

@@ -0,0 +1,62 @@
+"""Provider identity for BYOK runtime execution.
+
+Defines the closed set of providers a user can bring their own key for,
+plus probe and environment mappings. No networking or storage here.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class Provider(StrEnum):
+    """Every external provider this CLI can store a key for."""
+
+    OPENAI = "openai"
+    CLAUDE = "claude"
+    GROK = "grok"
+    DEEPSEEK = "deepseek"
+    GLM = "glm"
+    MUSE = "muse"
+    GEMINI = "gemini"
+
+
+PROVIDER_KEY_PREFIXES: dict[Provider, tuple[str, ...]] = {
+    Provider.OPENAI: ("sk-",),
+    Provider.CLAUDE: ("sk-ant-",),
+    Provider.GROK: (),
+    Provider.DEEPSEEK: ("sk-",),
+    Provider.GLM: (),
+    Provider.MUSE: ("LLM|",),
+    Provider.GEMINI: ("AIza",),
+}
+
+PROVIDER_ENV_VARS: dict[Provider, str] = {
+    Provider.OPENAI: "OPENAI_API_KEY",
+    Provider.CLAUDE: "ANTHROPIC_API_KEY",
+    Provider.GROK: "XAI_API_KEY",
+    Provider.DEEPSEEK: "DEEPSEEK_API_KEY",
+    Provider.GLM: "ZAI_API_KEY",
+    Provider.MUSE: "MODEL_API_KEY",
+    Provider.GEMINI: "GEMINI_API_KEY",
+}
+
+PROVIDER_DISPLAY: dict[Provider, str] = {
+    Provider.OPENAI: "OpenAI",
+    Provider.CLAUDE: "Claude",
+    Provider.GROK: "Grok",
+    Provider.DEEPSEEK: "DeepSeek",
+    Provider.GLM: "GLM",
+    Provider.MUSE: "Muse",
+    Provider.GEMINI: "Gemini",
+}
+
+PROVIDER_PROBE_URLS: dict[Provider, str] = {
+    Provider.OPENAI: "https://api.openai.com/v1/models",
+    Provider.CLAUDE: "https://api.anthropic.com/v1/models",
+    Provider.GROK: "https://api.x.ai/v1/models",
+    Provider.DEEPSEEK: "https://api.deepseek.com/v1/models",
+    Provider.GLM: "https://api.z.ai/api/paas/v4/models",
+    Provider.MUSE: "https://api.meta.ai/v1/models",
+    Provider.GEMINI: "https://generativelanguage.googleapis.com/v1beta/models",
+}

vidbyte_cli/types/research.py

@@ -0,0 +1,260 @@
+"""The research surface's wire shapes, its status vocabulary, and its two identifier guards.
+
+A thread has two identifiers and the API publishes only one of them. `encrypted_id` is the
+public share token every route accepts in a path; `thread_id` is internal and is rejected by
+path validation before any lookup. So the models here bind the CLI's `thread_id` field to the
+wire key `encrypted_id` by alias, deliberately leave `populate_by_name` off so the internal
+key cannot populate it, and set `extra="ignore"` so it is discarded on arrival instead.
+
+`ResearchRunStatus` declares no thread field at all, because the status route carries only
+the internal identifier — a field the CLI must never print, since a user would paste it back.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import date, datetime
+from enum import StrEnum
+from typing import Annotated, Literal
+from uuid import uuid4
+
+from pydantic import AfterValidator, BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from ..lib.errors.failures import ResearchIdempotencyKeyInvalid, ResearchThreadIdInvalid
+
+# The backend pins a thread share token to a UUIDv4 and matches path segments against it in
+# transport, so the same shape is checked locally before a request is ever spent.
+_THREAD_ID_PATTERN = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
+)
+_IDEMPOTENCY_KEY_PATTERN = re.compile(r"^[A-Za-z0-9._:-]{8,128}$")
+_MAX_PROMPT_CHARACTERS = 20_000
+
+
+class ResearchStatus(StrEnum):
+    """Every durable state a research run can report."""
+
+    ADMITTING = "admitting"
+    ACCEPTED = "accepted"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    PARTIAL = "partial"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    CREDIT_EXHAUSTED = "credit_exhausted"
+
+    def is_terminal(self) -> bool:
+        # True once the backend will not move this run again without a continuation.
+        return self in _TERMINAL_STATUSES
+
+    def is_resumable(self) -> bool:
+        # The three states the backend accepts a continuation from; anything else is a 409.
+        return self in _RESUMABLE_STATUSES
+
+
+_TERMINAL_STATUSES = frozenset(
+    {
+        ResearchStatus.COMPLETED,
+        ResearchStatus.PARTIAL,
+        ResearchStatus.FAILED,
+        ResearchStatus.CANCELLED,
+        ResearchStatus.CREDIT_EXHAUSTED,
+    }
+)
+_RESUMABLE_STATUSES = frozenset(
+    {ResearchStatus.PARTIAL, ResearchStatus.FAILED, ResearchStatus.CREDIT_EXHAUSTED}
+)
+
+
+class ResearchSize(StrEnum):
+    """Preset breadth for a run, when the caller does not size it by hand."""
+
+    SMALL = "small"
+    MEDIUM = "medium"
+    LARGE = "large"
+
+
+class ResearchKind(StrEnum):
+    """The resource kinds discovery is allowed to return."""
+
+    PAPER = "paper"
+    WEB = "web"
+
+
+class ThreadId:
+    """One public research thread share token, validated on construction."""
+
+    def __init__(self, value: str) -> None:
+        self.value = value
+
+    @classmethod
+    def parse(cls, value: str) -> ThreadId:
+        # Raises the usage failure locally rather than spending a request on a 422.
+        candidate = value.strip()
+        if not _THREAD_ID_PATTERN.fullmatch(candidate):
+            raise ResearchThreadIdInvalid()
+        return cls(candidate)
+
+    @classmethod
+    def normalize(cls, value: str) -> str:
+        # The pydantic entry point: validating and canonicalizing are one operation.
+        return str(cls.parse(value))
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class IdempotencyKey:
+    """The key that lets one priced mutation be retried without being charged twice."""
+
+    def __init__(self, value: str) -> None:
+        self.value = value
+
+    @classmethod
+    def create(cls, explicit: str | None) -> IdempotencyKey:
+        # A fresh key per invocation, unless the caller supplies one to replay a mutation.
+        if explicit is None:
+            return cls(str(uuid4()))
+        candidate = explicit.strip()
+        if not _IDEMPOTENCY_KEY_PATTERN.fullmatch(candidate):
+            raise ResearchIdempotencyKeyInvalid()
+        return cls(candidate)
+
+    def __str__(self) -> str:
+        return self.value
+
+
+NormalizedThreadId = Annotated[str, AfterValidator(ThreadId.normalize)]
+
+
+class ResearchRunCreateRequest(BaseModel):
+    """The body both `research start` and `research add` submit.
+
+    Mirrors the backend request DTO field for field. Every optional field defaults to None so
+    `exclude_none` drops it from the encoded body: the backend forbids unknown keys and
+    requires a non-empty `resource_kinds` when the key is present, so an unset option has to
+    be absent rather than null or empty.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    prompt: str = Field(min_length=1, max_length=_MAX_PROMPT_CHARACTERS)
+    # Version 2 is the backend default and the only version that carries reference artifacts.
+    request_schema_version: Literal[2] = 2
+    size: ResearchSize | None = None
+    target_sources: int | None = Field(default=None, ge=1, le=1_000)
+    search_calls: int | None = Field(default=None, ge=1, le=100)
+    resource_kinds: list[ResearchKind] | None = Field(default=None, min_length=1, max_length=2)
+    include_domains: list[str] | None = Field(default=None, max_length=50)
+    exclude_domains: list[str] | None = Field(default=None, max_length=50)
+    published_after: str | None = Field(default=None, pattern=r"^\d{4}-\d{2}-\d{2}$")
+    language: str | None = Field(default=None, min_length=2, max_length=12)
+    max_run_cost_cents: int | None = Field(default=None, ge=1, le=100_000)
+
+    @field_validator("prompt")
+    @classmethod
+    def normalize_prompt(cls, value: str) -> str:
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError("prompt cannot be blank")
+        return normalized
+
+    @field_validator("published_after")
+    @classmethod
+    def validate_published_after(cls, value: str | None) -> str | None:
+        # The pattern accepts 2025-13-45; the backend does not. Catching it here keeps a
+        # calendar typo from costing a request against a priced route.
+        if value is not None:
+            date.fromisoformat(value)
+        return value
+
+    @field_validator("include_domains", "exclude_domains", mode="before")
+    @classmethod
+    def normalize_domains(cls, value: object) -> object:
+        # The backend accepts hostnames only, so a pasted URL is corrected here, not there.
+        # Before the length bound, so a list that only exceeds 50 through duplicates passes.
+        if not isinstance(value, list):
+            return value
+        normalized: list[str] = []
+        for item in value:
+            host = str(item).strip().lower().rstrip(".")
+            if not host or "/" in host or ":" in host:
+                raise ValueError("domain filters must be hostname-only values")
+            if host not in normalized:
+                normalized.append(host)
+        return normalized
+
+    @field_validator("resource_kinds", mode="before")
+    @classmethod
+    def deduplicate_kinds(cls, value: object) -> object:
+        # Runs before the length bound: `--kind paper --kind paper --kind web` is three
+        # values and two kinds, and rejecting it for length would be a lie about the input.
+        if not isinstance(value, list):
+            return value
+        return list(dict.fromkeys(value))
+
+    @model_validator(mode="after")
+    def reject_contradictory_filters(self) -> ResearchRunCreateRequest:
+        # A domain in both lists can never match, so catch it before spending a request.
+        if set(self.include_domains or ()) & set(self.exclude_domains or ()):
+            raise ValueError("a domain cannot be both included and excluded")
+        return self
+
+
+class ResearchRunAccepted(BaseModel):
+    """The 202 identity returned by start, add, and resume."""
+
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+    thread_id: str = Field(alias="encrypted_id")
+    run_id: str
+    status: ResearchStatus
+
+
+class ResearchRunStatus(BaseModel):
+    """One run's durable progress.
+
+    The backend also sends the thread's internal identifier here. It is deliberately not
+    declared, so `extra="ignore"` drops it and no renderer can print an ID that would be
+    rejected the moment a user pasted it into `research add`.
+    """
+
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+    run_id: str
+    status: ResearchStatus
+    phase: str
+    continuation_count: int = Field(ge=0)
+    updated_at: datetime
+
+
+class ResearchThreadSummary(BaseModel):
+    """One row of the caller's thread portfolio."""
+
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+    thread_id: str = Field(alias="encrypted_id")
+    title: str
+    run_count: int = Field(ge=0)
+    source_count: int = Field(ge=0)
+    artifact_count: int = Field(ge=0)
+    latest_run_id: str | None = None
+    latest_run_status: ResearchStatus | None = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class ResearchThreadDetail(ResearchThreadSummary):
+    """One thread read on its own, which carries two fields a portfolio row omits."""
+
+    latest_run_phase: str | None = None
+    favorite: bool = False
+
+
+class ResearchPortfolioPage(BaseModel):
+    """One bounded page of threads and the cursor that continues it."""
+
+    model_config = ConfigDict(extra="ignore", frozen=True)
+
+    threads: list[ResearchThreadSummary]
+    next_cursor: str | None = None