deeptutor-server 1.7.0__py3-none-any.whl

deeptutor/api/contracts/__init__.py

@@ -0,0 +1,21 @@
+"""Public API and WebSocket contract models."""
+
+from .turn_protocol import (
+    ErrorEnvelope,
+    RuntimeStatus,
+    StreamEvent,
+    StreamEventType,
+    TurnFailureCode,
+    TurnProtocolDocument,
+    TurnStatus,
+)
+
+__all__ = [
+    "ErrorEnvelope",
+    "RuntimeStatus",
+    "StreamEvent",
+    "StreamEventType",
+    "TurnFailureCode",
+    "TurnProtocolDocument",
+    "TurnStatus",
+]

deeptutor/api/contracts/export.py

@@ -0,0 +1,110 @@
+"""Deterministically export backend-owned browser contracts."""
+
+from __future__ import annotations
+
+import argparse
+from copy import deepcopy
+import json
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+from deeptutor.app.contracts import TurnRequest
+
+from .turn_protocol import (
+    ErrorEnvelope,
+    RuntimeStatus,
+    SessionDetail,
+    SessionSummary,
+    TurnProtocolDocument,
+)
+
+PROJECT_ROOT = Path(__file__).resolve().parents[3]
+DEFAULT_OUTPUT_DIR = PROJECT_ROOT / "web" / "contracts" / "schema"
+HTTP_METHODS = {"delete", "get", "head", "options", "patch", "post", "put", "trace"}
+
+
+def _json_text(payload: dict[str, Any]) -> str:
+    return json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+
+
+def _merge_model_schema(components: dict[str, Any], model: type[BaseModel]) -> None:
+    schema = model.model_json_schema(ref_template="#/components/schemas/{model}")
+    definitions = schema.pop("$defs", {})
+    components.update(definitions)
+    components[model.__name__] = schema
+
+
+def _assert_unique_operation_ids(openapi: dict[str, Any]) -> None:
+    """Reject router defects instead of hiding them in generated artifacts."""
+
+    seen: dict[str, tuple[str, str]] = {}
+    duplicates: list[str] = []
+    for path, path_item in openapi.get("paths", {}).items():
+        for method, operation in path_item.items():
+            if method not in HTTP_METHODS or not isinstance(operation, dict):
+                continue
+            operation_id = operation.get("operationId")
+            if not operation_id:
+                continue
+            previous = seen.get(operation_id)
+            if previous is None:
+                seen[operation_id] = (path, method)
+                continue
+            duplicates.append(
+                f"{operation_id}: {previous[1].upper()} {previous[0]} and {method.upper()} {path}"
+            )
+    if duplicates:
+        raise RuntimeError("Duplicate OpenAPI operation IDs:\n" + "\n".join(duplicates))
+
+
+def render_contracts() -> dict[str, str]:
+    from deeptutor.api.main import app
+
+    openapi = deepcopy(app.openapi())
+    _assert_unique_operation_ids(openapi)
+    schemas = openapi.setdefault("components", {}).setdefault("schemas", {})
+    for model in (TurnRequest, RuntimeStatus, SessionSummary, SessionDetail, ErrorEnvelope):
+        _merge_model_schema(schemas, model)
+    openapi["x-deeptutor-web-protocol-version"] = "2.0"
+
+    protocol = TurnProtocolDocument.model_json_schema()
+    return {
+        "openapi.json": _json_text(openapi),
+        "turn-protocol.json": _json_text(protocol),
+    }
+
+
+def write_contracts(output_dir: Path, *, check: bool = False) -> list[str]:
+    rendered = render_contracts()
+    changed: list[str] = []
+    for filename, content in rendered.items():
+        target = output_dir / filename
+        current = target.read_text(encoding="utf-8") if target.exists() else None
+        if current == content:
+            continue
+        changed.append(filename)
+        if not check:
+            output_dir.mkdir(parents=True, exist_ok=True)
+            target.write_text(content, encoding="utf-8")
+    return changed
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check", action="store_true", help="fail when artifacts drift")
+    parser.add_argument("--output-dir", type=Path, default=DEFAULT_OUTPUT_DIR)
+    args = parser.parse_args(argv)
+
+    changed = write_contracts(args.output_dir, check=args.check)
+    if args.check and changed:
+        print("Frontend contract drift: " + ", ".join(changed))
+        return 1
+    if changed:
+        print("Updated frontend contracts: " + ", ".join(changed))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

deeptutor/api/contracts/turn_protocol.py

@@ -0,0 +1,313 @@
+"""Canonical v2 wire models for the browser turn protocol."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from deeptutor.app.contracts import TurnRequest
+
+PROTOCOL_VERSION: Literal["2.0"] = "2.0"
+MINIMUM_WEB_PROTOCOL_VERSION: Literal["2.0"] = "2.0"
+
+
+class TurnStatus(str, Enum):
+    QUEUED = "queued"
+    RUNNING = "running"
+    WAITING_INPUT = "waiting_input"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class TurnQueryState(str, Enum):
+    """Client observation state, including server-side recovery windows."""
+
+    QUEUED = "queued"
+    RUNNING = "running"
+    WAITING_INPUT = "waiting_input"
+    RECOVERING = "recovering"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class TurnFailureCode(str, Enum):
+    WORKER_LOST = "worker_lost"
+    LEASE_LOST = "lease_lost"
+    COORDINATION_UNAVAILABLE = "coordination_unavailable"
+    PROVIDER_ERROR = "provider_error"
+    INTERNAL_ERROR = "internal_error"
+    REJECTED = "rejected"
+    SERVER_SHUTDOWN = "server_shutdown"
+
+
+class StreamEventType(str, Enum):
+    STAGE_START = "stage_start"
+    STAGE_END = "stage_end"
+    THINKING = "thinking"
+    OBSERVATION = "observation"
+    CONTENT = "content"
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    PROGRESS = "progress"
+    SOURCES = "sources"
+    RESULT = "result"
+    ERROR = "error"
+    SESSION = "session"
+    SESSION_META = "session_meta"
+    WAIT_FOR_INPUT = "wait_for_input"
+    DONE = "done"
+
+
+class WireModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class StartTurnCommand(TurnRequest):
+    type: Literal["message", "start_turn"] = "start_turn"
+    protocol_version: Literal["2.0"]
+
+
+class SubscribeTurnCommand(WireModel):
+    type: Literal["subscribe_turn"] = "subscribe_turn"
+    turn_id: str = Field(min_length=1)
+    after_seq: int = Field(default=0, ge=0)
+    protocol_version: Literal["2.0"]
+
+
+class SubscribeSessionCommand(WireModel):
+    type: Literal["subscribe_session"] = "subscribe_session"
+    session_id: str = Field(min_length=1)
+    after_seq: int = Field(default=0, ge=0)
+    protocol_version: Literal["2.0"]
+
+
+class ResumeTurnCommand(WireModel):
+    type: Literal["resume_from"] = "resume_from"
+    turn_id: str = Field(min_length=1)
+    seq: int = Field(default=0, ge=0)
+    protocol_version: Literal["2.0"]
+
+
+class UnsubscribeCommand(WireModel):
+    type: Literal["unsubscribe"] = "unsubscribe"
+    turn_id: str | None = None
+    session_id: str | None = None
+    protocol_version: Literal["2.0"]
+
+    @model_validator(mode="after")
+    def _has_target(self) -> "UnsubscribeCommand":
+        if not self.turn_id and not self.session_id:
+            raise ValueError("unsubscribe requires turn_id or session_id")
+        return self
+
+
+class CancelTurnCommand(WireModel):
+    type: Literal["cancel_turn"] = "cancel_turn"
+    turn_id: str = Field(min_length=1)
+    command_id: str = Field(min_length=1)
+    protocol_version: Literal["2.0"]
+
+
+class RegenerateCommand(WireModel):
+    type: Literal["regenerate"] = "regenerate"
+    session_id: str = Field(min_length=1)
+    overrides: dict[str, Any] = Field(default_factory=dict)
+    protocol_version: Literal["2.0"]
+
+
+class UserAnswer(WireModel):
+    questionId: str = Field(min_length=1)
+    text: str = ""
+
+
+class SubmitUserReplyCommand(WireModel):
+    type: Literal["submit_user_reply"] = "submit_user_reply"
+    turn_id: str = Field(min_length=1)
+    text: str | None = None
+    answers: list[UserAnswer] | None = None
+    command_id: str = Field(min_length=1)
+    protocol_version: Literal["2.0"]
+
+    @model_validator(mode="after")
+    def _has_reply(self) -> "SubmitUserReplyCommand":
+        if self.text is None and not self.answers:
+            raise ValueError("submit_user_reply requires text or answers")
+        return self
+
+
+class UserInputCommand(WireModel):
+    """A message for a turn that is still running, read at its next step."""
+
+    type: Literal["user_input"] = "user_input"
+    turn_id: str = Field(min_length=1)
+    content: str
+    command_id: str = Field(min_length=1)
+    # The command id of an earlier, still unread ``user_input`` to take back.
+    withdraw: str | None = None
+    protocol_version: Literal["2.0"]
+
+
+class CheckActiveTurnCommand(WireModel):
+    type: Literal["check_active_turn"] = "check_active_turn"
+    session_id: str = Field(min_length=1)
+    protocol_version: Literal["2.0"]
+
+
+class PingCommand(WireModel):
+    type: Literal["ping"] = "ping"
+    protocol_version: Literal["2.0"]
+
+
+ClientCommand = Annotated[
+    StartTurnCommand
+    | SubscribeTurnCommand
+    | SubscribeSessionCommand
+    | ResumeTurnCommand
+    | UnsubscribeCommand
+    | CancelTurnCommand
+    | RegenerateCommand
+    | SubmitUserReplyCommand
+    | UserInputCommand
+    | CheckActiveTurnCommand
+    | PingCommand,
+    Field(discriminator="type"),
+]
+
+
+class StreamEvent(WireModel):
+    type: StreamEventType
+    source: str = ""
+    stage: str = ""
+    content: str = ""
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    session_id: str = ""
+    turn_id: str = ""
+    seq: int = Field(default=0, ge=0)
+    timestamp: float
+    protocol_version: Literal["2.0"] = PROTOCOL_VERSION
+
+
+class ActiveTurnInfo(WireModel):
+    type: Literal["active_turn_info"] = "active_turn_info"
+    turn_id: str = ""
+    status: TurnQueryState | Literal["none"] = "none"
+    owner_id: str = ""
+    protocol_version: Literal["2.0"] = PROTOCOL_VERSION
+
+
+class PongEvent(WireModel):
+    type: Literal["pong"] = "pong"
+    protocol_version: Literal["2.0"] = PROTOCOL_VERSION
+
+
+class CommandAckEvent(WireModel):
+    type: Literal["command_ack"] = "command_ack"
+    command_id: str = Field(min_length=1)
+    command_type: Literal["cancel_turn", "submit_user_reply", "user_input"]
+    accepted: bool
+    turn_id: str = ""
+    error_code: str = ""
+    message: str = ""
+    protocol_version: Literal["2.0"] = PROTOCOL_VERSION
+
+
+class ProtocolErrorEvent(WireModel):
+    type: Literal["protocol_error"] = "protocol_error"
+    error_code: str = Field(min_length=1)
+    message: str
+    retryable: bool = False
+    session_id: str = ""
+    turn_id: str = ""
+    protocol_version: Literal["2.0"] = PROTOCOL_VERSION
+
+
+ServerEvent = StreamEvent | ActiveTurnInfo | PongEvent | CommandAckEvent | ProtocolErrorEvent
+
+
+class TurnSummary(WireModel):
+    id: str
+    session_id: str
+    status: TurnStatus
+    query_state: TurnQueryState | None = None
+    capability: str = ""
+    owner_id: str = ""
+    last_seq: int = Field(default=0, ge=0)
+    error: str = ""
+    error_code: TurnFailureCode | None = None
+    retryable: bool = False
+    created_at: float | None = None
+    updated_at: float | None = None
+
+
+class SessionSummary(WireModel):
+    id: str
+    title: str
+    created_at: float | None = None
+    updated_at: float | None = None
+    active_turn: TurnSummary | None = None
+
+
+class SessionDetail(SessionSummary):
+    messages: list[dict[str, Any]] = Field(default_factory=list)
+    preferences: dict[str, Any] = Field(default_factory=dict)
+
+
+class RuntimeStatus(WireModel):
+    worker_id: str
+    worker_count: int = Field(ge=1)
+    coordination_mode: Literal["memory", "redis"]
+    redis_configured: bool
+    redis_status: Literal["ok", "unavailable", "not_configured"]
+    leader_id: str | None = None
+    leader_healthy: bool | None = None
+    owner_turn_count: int = Field(default=0, ge=0)
+    recovery_backlog: int = Field(default=0, ge=0)
+    lease_ttl_seconds: int = Field(ge=1)
+    renew_interval_seconds: int = Field(ge=1)
+    recovery_interval_seconds: int = Field(ge=1)
+    protocol_version: Literal["2.0"] = PROTOCOL_VERSION
+    minimum_web_protocol_version: Literal["2.0"] = MINIMUM_WEB_PROTOCOL_VERSION
+
+
+class ErrorEnvelope(WireModel):
+    error_code: str
+    message: str
+    retryable: bool = False
+    correlation_id: str | None = None
+
+
+class TurnProtocolDocument(WireModel):
+    protocol_version: Literal["2.0"] = PROTOCOL_VERSION
+    minimum_web_protocol_version: Literal["2.0"] = MINIMUM_WEB_PROTOCOL_VERSION
+    client_command: ClientCommand
+    server_event: ServerEvent
+    runtime_status: RuntimeStatus
+    session_summary: SessionSummary
+    session_detail: SessionDetail
+    error: ErrorEnvelope
+
+
+__all__ = [
+    "ActiveTurnInfo",
+    "ClientCommand",
+    "CommandAckEvent",
+    "ErrorEnvelope",
+    "MINIMUM_WEB_PROTOCOL_VERSION",
+    "PROTOCOL_VERSION",
+    "ProtocolErrorEvent",
+    "RuntimeStatus",
+    "ServerEvent",
+    "SessionDetail",
+    "SessionSummary",
+    "StreamEvent",
+    "StreamEventType",
+    "TurnFailureCode",
+    "TurnProtocolDocument",
+    "TurnQueryState",
+    "TurnStatus",
+    "TurnSummary",
+]