openvideokit 0.1.0__py3-none-any.whl

openvideokit/__init__.py

@@ -0,0 +1,7 @@
+"""OpenVideoKit — installable CLI + SSR/agentic server.
+
+`pip install openvideokit` → `ovk serve` runs the FastAPI server on :8000
+(serves the editor SPA + stamped HF compositions for <hyperframes-player>).
+"""
+
+__version__ = "0.1.0"

openvideokit/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m openvideokit` → `ovk`."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

openvideokit/ai/__init__.py

@@ -0,0 +1,9 @@
+"""OpenVideoKit AI subsystem — a LangGraph agent that edits the project by
+emitting ``EditOp`` proposals the frontend ``EditBus`` dispatches on Accept.
+
+See ``docs/ai.md`` for the full implementation contract.
+"""
+
+from __future__ import annotations
+
+__all__ = ["config", "ops", "events", "context", "llm", "graph", "server"]

openvideokit/ai/config.py

@@ -0,0 +1,121 @@
+"""Runtime configuration for the AI subsystem.
+
+Three-tier resolver (highest wins):
+    1. Real env vars / .env (already merged into ``os.environ`` by python-dotenv
+       at the top-level ``config.py`` import)
+    2. ``~/.openvideokit/config.toml`` under ``[ai]``
+    3. Hardcoded defaults below
+
+Standard OpenAI-compatible env names (``OPENAI_BASE_URL`` / ``OPENAI_API_KEY``)
+so any compliant endpoint works without custom config: OpenAI, OpenRouter
+(``https://openrouter.ai/api/v1``), Ollama (``http://localhost:11434/v1``),
+vLLM, LM Studio.
+"""
+
+from __future__ import annotations
+
+import os
+
+from ..user_config import load_user_config
+
+_USER_CONFIG = load_user_config()
+
+
+def _resolve(group: str, key: str, env_var: str, default, cast=str):
+    raw = os.environ.get(env_var)
+    if raw is not None and raw != "":
+        try:
+            return cast(raw)
+        except (TypeError, ValueError):
+            pass
+    user_val = _USER_CONFIG.get(group, {}).get(key) if isinstance(_USER_CONFIG, dict) else None
+    if user_val is not None:
+        return user_val
+    return default
+
+
+def _resolve_bool(group: str, key: str, env_var: str, default: bool) -> bool:
+    raw = os.environ.get(env_var, "").lower()
+    if raw in ("1", "true", "yes", "on"):
+        return True
+    if raw in ("0", "false", "no", "off"):
+        return False
+    user_val = _USER_CONFIG.get(group, {}).get(key) if isinstance(_USER_CONFIG, dict) else None
+    if isinstance(user_val, bool):
+        return user_val
+    return default
+
+
+# OpenAI-compatible endpoint. Default assumes openai itself.
+OPENAI_BASE_URL = _resolve(
+    "ai", "openai_base_url", "OPENAI_BASE_URL", "https://api.openai.com/v1"
+)
+
+# API key. Required to use AI; an empty key yields a graceful ``error`` event
+# from the agent runner (no crash).
+OPENAI_API_KEY = _resolve("ai", "openai_api_key", "OPENAI_API_KEY", "")
+
+# Default (Tier-1) chat model id — whatever the chosen endpoint accepts.
+OVK_AI_MODEL = _resolve("ai", "model", "OVK_AI_MODEL", "gpt-5.4-nano")
+
+# Reserved for future per-tool coding-model routing (Tier-2 / set_slide_html).
+# Falls back to OVK_AI_MODEL when empty.
+OVK_AI_TIER2_MODEL = _resolve(
+    "ai", "tier2_model", "OVK_AI_TIER2_MODEL", OVK_AI_MODEL
+)
+
+# Sampling temperature for the agent.
+OVK_AI_TEMPERATURE = _resolve(
+    "ai", "temperature", "OVK_AI_TEMPERATURE", 0.3, cast=float
+)
+
+# Cap on agent tool-calling steps per turn (bounds cost + latency).
+OVK_AI_MAX_STEPS = _resolve("ai", "max_steps", "OVK_AI_MAX_STEPS", 50, cast=int)
+
+# Reasoning effort for reasoning-capable models ("low" / "medium" / "high").
+# Empty = don't send (correct for non-reasoning models like gpt-4o-mini).
+# Only set this if OVK_AI_MODEL is a reasoning model (gpt-5, o1, o3, gpt-oss, …).
+OVK_AI_REASONING_EFFORT = _resolve(
+    "ai", "reasoning_effort", "OVK_AI_REASONING_EFFORT", ""
+)
+
+# Web tools (web_search + web_fetch). The tools are always registered so the
+# agent always knows they exist; this flag controls runtime execution. When
+# false, calls return a "disabled" notice the agent relays to the user.
+OVK_ENABLE_WEB = _resolve_bool("ai", "enable_web", "OVK_ENABLE_WEB", True)
+
+
+def is_web_enabled() -> bool:
+    """True iff the flag is on AND both required libs import successfully.
+
+    Tools stay registered regardless; this gate decides whether a call actually
+    hits the network or returns a disabled notice.
+    """
+    if not OVK_ENABLE_WEB:
+        return False
+    try:
+        import crawl4ai  # noqa: F401
+        import ddgs  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+def web_disabled_reason() -> str:
+    """Human-readable reason the web tools refused — used as their return value."""
+    if not OVK_ENABLE_WEB:
+        return (
+            "Web tools are disabled. Set OVK_ENABLE_WEB=true in .env or "
+            "[ai].enable_web=true in ~/.openvideokit/config.toml to enable "
+            "web_search/web_fetch."
+        )
+    return (
+        "Web tools are unavailable: required packages not installed "
+        "(run `uv sync`)."
+    )
+
+
+def is_configured() -> bool:
+    """True iff an API key is present (i.e. AI is usable)."""
+    return bool(OPENAI_API_KEY)

openvideokit/ai/context.py

@@ -0,0 +1,64 @@
+"""OKVContext — per-request context bound into every tool via closure.
+
+Carries the read-only project snapshot the tools validate against + the ids
+the agent's read tools resolve paths through. The agent itself is stateless
+per request; this is the only per-request state.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class Pin:
+    """A user-pinned reference injected into the prompt as context."""
+
+    kind: str  # "slide" | "field" | "asset"
+    value: str  # slideId / "slideId.fieldId" / asset ref
+
+
+@dataclass
+class OVKContext:
+    project_id: str
+    project: dict[str, Any]  # the bundle: {root, slides, slideHtml}
+    active_slide_id: str | None = None
+    pins: list[Pin] = field(default_factory=list)
+
+    # ── Convenience accessors ────────────────────────────────────────────
+
+    @property
+    def root(self) -> dict[str, Any]:
+        return self.project.get("root", {})
+
+    @property
+    def slides(self) -> dict[str, Any]:
+        return self.project.get("slides", {})
+
+    @property
+    def slide_ids(self) -> list[str]:
+        return list(self.root.get("slides", []))
+
+    @property
+    def project_dir(self) -> Path:
+        # Delegate to store._project_dir so the project_id regex gate (the
+        # primary path-safety defense) fires here too — tools infer
+        # project_id from the chat URL, and MCP will pass it as a tool arg.
+        from ..store import _project_dir
+
+        return _project_dir(self.project_id)
+
+    def slide_dir(self, slide_id: str) -> Path:
+        # Delegate to store._slide_dir so slide_id is validated too (not just
+        # project_id). Raw concat here would bypass the path-safety gate.
+        from ..store import _slide_dir
+
+        return _slide_dir(self.project_id, slide_id)
+
+    def slide_exists(self, slide_id: str) -> bool:
+        return slide_id in self.slides
+
+    def slide_html(self, slide_id: str) -> str:
+        return self.project.get("slideHtml", {}).get(slide_id, "")

openvideokit/ai/events.py

@@ -0,0 +1,78 @@
+"""AIStreamEvent — the SSE event contract between the Python agent and the
+frontend ``AIDock`` / ``HttpSseProvider``.
+
+Serialized as SSE ``data: <json>\\n\\n`` lines by :func:`event_to_sse`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Literal, TypedDict
+
+
+class TokenEvent(TypedDict):
+    type: Literal["token"]
+    text: str
+
+
+class ThinkingEvent(TypedDict):
+    type: Literal["thinking"]
+    text: str
+
+
+class ToolStartEvent(TypedDict):
+    type: Literal["tool_start"]
+    tool: str
+    args: dict[str, Any]
+
+
+class ToolEndEvent(TypedDict):
+    type: Literal["tool_end"]
+    tool: str
+    ok: bool
+    result: Any
+
+
+class ProposalEvent(TypedDict):
+    type: Literal["proposal"]
+    edit: dict[str, Any]  # EditProposalPayload (see ops.py)
+
+
+class DoneEvent(TypedDict):
+    type: Literal["done"]
+
+
+class ErrorEvent(TypedDict):
+    type: Literal["error"]
+    message: str
+
+
+AIStreamEvent = (
+    TokenEvent
+    | ThinkingEvent
+    | ToolStartEvent
+    | ToolEndEvent
+    | ProposalEvent
+    | DoneEvent
+    | ErrorEvent
+)
+
+
+def event_to_sse(event: AIStreamEvent) -> str:
+    """Serialize an event to one SSE ``data:`` block (with trailing blank line)."""
+    return f"data: {json.dumps(event, ensure_ascii=False)}\n\n"
+
+
+def parse_sse(block: str) -> AIStreamEvent | None:
+    """Parse one SSE ``data: ...`` block back into an event dict.
+
+    Returns ``None`` for keepalive/comments. Used by tests for round-trip.
+    """
+    line = block.strip()
+    if not line or line.startswith(":"):
+        return None
+    if line.startswith("data:"):
+        line = line[5:].strip()
+    if not line:
+        return None
+    return json.loads(line)

openvideokit/ai/graph.py

@@ -0,0 +1,35 @@
+"""LangGraph agent — a ReAct agent over the OVK tool set.
+
+Uses ``langchain.agents.create_agent`` (the non-deprecated successor to
+``langgraph.prebuilt.create_react_agent``). The agent is stateless per request;
+``build_tools(ctx)`` binds the project context into every tool via closure.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from langchain_core.language_models import BaseChatModel
+
+    from .context import OVKContext
+
+from .prompts import build_system_prompt
+from .tools import build_tools
+
+
+def build_agent(model: BaseChatModel, ctx: OVKContext):
+    """Compile the ReAct agent for one request.
+
+    The system prompt is assembled from the modular ``ai/prompts/`` sections,
+    including the auto-generated tool list (zero drift vs the real tools).
+    """
+    from langchain.agents import create_agent
+
+    tools = build_tools(ctx)
+    system_prompt = build_system_prompt(ctx)
+    return create_agent(
+        model=model,
+        tools=tools,
+        system_prompt=system_prompt,
+    )

openvideokit/ai/llm.py

@@ -0,0 +1,87 @@
+"""LLM factory — builds the OpenAI-compatible chat model from env.
+
+A single ``ChatOpenAI`` configured via ``OPENAI_BASE_URL`` / ``OPENAI_API_KEY``
+covers OpenAI, OpenRouter, Requesty, native DeepSeek, Ollama, vLLM, and LM
+Studio. Provider-specific reasoning/thinking handling lives in
+``providers.py``; this module just wires its output into ``ChatOpenAI``.
+"""
+
+from __future__ import annotations
+
+# ── Monkey-patch: preserve reasoning/thinking tokens ───────────────────
+# langchain-openai's _convert_delta_to_message_chunk drops the streaming
+# reasoning fields before they reach additional_kwargs. We wrap it to copy
+# whatever the provider emits into additional_kwargs["reasoning_content"],
+# which _extract_text_and_thinking in server.py already reads.
+import langchain_openai.chat_models.base as _lc_base  # noqa: E402
+from langchain_openai import ChatOpenAI
+
+from . import config
+from .providers import (
+    APP_HEADERS,
+    detect_provider,
+    extract_thinking,
+    reasoning_request,
+)
+
+_orig_convert = _lc_base._convert_delta_to_message_chunk
+
+
+def _patched_convert(_dict, default_class):  # type: ignore[no-untyped-def]
+    chunk = _orig_convert(_dict, default_class)
+    reasoning = extract_thinking(_dict)
+    if reasoning:
+        chunk.additional_kwargs["reasoning_content"] = reasoning
+    return chunk
+
+
+_lc_base._convert_delta_to_message_chunk = _patched_convert
+
+
+def build_model(
+    *,
+    model: str = "",
+    streaming: bool = True,
+    timeout: float | None = None,
+) -> ChatOpenAI:
+    """The default (Tier-1) chat model.
+
+    ``model`` overrides ``OVK_AI_MODEL`` when given (used by the CLI
+    ``--model`` flag). ``timeout`` bounds a single request (None = provider
+    default); the CLI diagnostic passes a finite timeout so it can't hang on
+    unreachable hosts.
+
+    ``reasoning_effort`` is forwarded only when ``OVK_AI_REASONING_EFFORT``
+    is set — passing it to a non-reasoning model raises, so it's opt-in.
+    The exact request shape (OpenRouter ``reasoning`` dict, DeepSeek
+    ``thinking`` toggle, etc.) is picked by ``providers.reasoning_request``.
+    """
+    model_id = model or config.OVK_AI_MODEL
+    base_url = config.OPENAI_BASE_URL
+
+    kwargs: dict = {
+        "model": model_id,
+        "api_key": config.OPENAI_API_KEY,
+        "base_url": base_url,
+        "temperature": config.OVK_AI_TEMPERATURE,
+        "streaming": streaming,
+        "timeout": timeout,
+        "default_headers": APP_HEADERS,
+    }
+
+    if config.OVK_AI_REASONING_EFFORT:
+        provider = detect_provider(base_url)
+        kwargs.update(
+            reasoning_request(provider, model_id, config.OVK_AI_REASONING_EFFORT)
+        )
+
+    return ChatOpenAI(**kwargs)
+
+
+def build_tier2_model(*, streaming: bool = True) -> ChatOpenAI:
+    """The Tier-2 (coding) model — reserved for set_slide_html routing.
+
+    v1 uses the same model as Tier-1 (see docs/ai.md §15); this factory exists
+    so a future per-tool routing refinement can swap it independently.
+    """
+    return build_model(model=config.OVK_AI_TIER2_MODEL, streaming=streaming)

openvideokit/ai/monitor/__init__.py

@@ -0,0 +1,18 @@
+"""AI monitoring subpackage — observability for the LangGraph agent.
+
+Public surface is intentionally tiny: callers import :func:`observe_run` and
+get back either a real :class:`RunObserver` (when ``OVK_AI_MONITORING=true``)
+or a :class:`NullObserver` no-op (the prod default). The route handler then
+calls ``observer.on_event(sse_line)`` for every line streamed by
+``run_agent`` and ``observer.close()`` at the end. That is the entire
+integration contract.
+
+See ``docs/ai-monitoring.md`` for the design, file layout, and how to extend
+the sink set (FileSink today; S3 / OTLP / HTTP planned).
+"""
+
+from __future__ import annotations
+
+from .observer import NullObserver, RunObserver, observe_run
+
+__all__ = ["observe_run", "RunObserver", "NullObserver"]

openvideokit/ai/monitor/config.py

@@ -0,0 +1,80 @@
+"""Monitor configuration — self-contained, three-tier resolver.
+
+Kept separate from ``ai/config.py`` so the monitor subpackage stays an
+optional, pluggable concern: disabling monitoring removes every import-time
+side effect from this module's callers.
+
+Priority (highest wins):
+    1. Real env vars / .env
+    2. ``~/.openvideokit/config.toml`` under ``[ai_monitoring]``
+    3. Hardcoded defaults below
+"""
+
+from __future__ import annotations
+
+import os
+
+from ...user_config import load_user_config
+
+_USER_CONFIG = load_user_config()
+
+
+def _resolve_bool(group: str, key: str, env_var: str, default: bool) -> bool:
+    raw = os.environ.get(env_var, "").lower()
+    if raw in ("1", "true", "yes", "on"):
+        return True
+    if raw in ("0", "false", "no", "off"):
+        return False
+    user_val = _USER_CONFIG.get(group, {}).get(key) if isinstance(_USER_CONFIG, dict) else None
+    if isinstance(user_val, bool):
+        return user_val
+    return default
+
+
+def _resolve_int(group: str, key: str, env_var: str, default: int) -> int:
+    raw = os.environ.get(env_var)
+    if raw is not None and raw != "":
+        try:
+            return int(raw)
+        except ValueError:
+            pass
+    user_val = _USER_CONFIG.get(group, {}).get(key) if isinstance(_USER_CONFIG, dict) else None
+    if isinstance(user_val, int) and not isinstance(user_val, bool):
+        return user_val
+    return default
+
+
+# Master switch. When false, ``observe_run`` returns a NullObserver and no
+# file I/O, allocations, or prompt/tool assembly happen. Zero prod overhead.
+OVK_AI_MONITORING = _resolve_bool(
+    "ai_monitoring", "enabled", "OVK_AI_MONITORING", True
+)
+
+
+def _resolve_sinks() -> list[str]:
+    """Resolve the sink list from env (comma-separated) or config.toml (array)."""
+    raw = os.environ.get("OVK_AI_MONITORING_SINKS")
+    if raw is not None and raw != "":
+        return [s.strip() for s in raw.split(",") if s.strip()]
+    user_val = (
+        _USER_CONFIG.get("ai_monitoring", {}).get("sinks")
+        if isinstance(_USER_CONFIG, dict)
+        else None
+    )
+    if isinstance(user_val, list) and user_val:
+        return [str(s) for s in user_val]
+    return ["file"]
+
+
+# Comma-separated sink list (env) or TOML array (config.toml). v1 ships only
+# ``file``; the parsing happens once per request in ``observer._build_sinks_from_env``
+# so future sinks (s3, otlp, http, langsmith) register without touching
+# existing code. Unknown names raise at first use so typos fail loud.
+OVK_AI_MONITORING_SINKS = _resolve_sinks()
+
+# Per-tool-result truncation cap (chars). Mirrors the agent's own
+# ``server._truncate`` default so trace filesizes stay bounded; set 0 to
+# disable truncation entirely.
+OVK_AI_MONITORING_TOOL_LIMIT = _resolve_int(
+    "ai_monitoring", "tool_limit", "OVK_AI_MONITORING_TOOL_LIMIT", 8000
+)