content-sdk 0.2.0__py3-none-any.whl

content_sdk/__init__.py

@@ -0,0 +1,71 @@
+"""Content SDK — the official Python client for the Content engine.
+
+The single client every consumer (CLI, MCP, applications) speaks through. It
+fully encapsulates the REST API; nothing else duplicates the engine's rules.
+
+    from content_sdk import ContentClient
+    from content_sdk import outputs
+
+    with ContentClient("http://localhost:8010") as client:
+        analysis = client.analyze(outputs.url_source("https://…"))  # sources or id
+        caps = client.get_capabilities(analysis.id)
+        job = client.generate(analysis.id, [outputs.audio_output()])
+        job.wait()
+        for artifact in job.artifacts:
+            print(artifact.filename)
+"""
+
+from __future__ import annotations
+
+from . import models as outputs  # builders live in models; alias for ergonomics
+from .aio import AsyncAnalysis, AsyncContentClient, AsyncJob
+from .client import ContentClient
+from .errors import (
+    APIError,
+    Conflict,
+    ContentError,
+    Gone,
+    NotFound,
+    TransportError,
+    ValidationError,
+)
+from .models import (
+    AnalysisData,
+    AnalyzedSource,
+    ArtifactData,
+    CapabilitiesData,
+    Capability,
+    Event,
+    JobData,
+    SourceCapabilities,
+)
+from .resources import Analysis, Job
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "APIError",
+    "Analysis",
+    # data models
+    "AnalysisData",
+    "AnalyzedSource",
+    "ArtifactData",
+    "AsyncAnalysis",
+    "AsyncContentClient",
+    "AsyncJob",
+    "CapabilitiesData",
+    "Capability",
+    "Conflict",
+    "ContentClient",
+    # errors
+    "ContentError",
+    "Event",
+    "Gone",
+    "Job",
+    "JobData",
+    "NotFound",
+    "SourceCapabilities",
+    "TransportError",
+    "ValidationError",
+    "outputs",
+]

content_sdk/_transport.py

@@ -0,0 +1,167 @@
+"""HTTP transport: one httpx-based layer for both the sync and async clients.
+
+Responsibilities: build `/api/v1` URLs, map non-2xx → typed exceptions, and
+apply a **conservative** retry policy. Retries happen ONLY on transport-level
+failures (the request provably did not get a response) and on 5xx for **safe**
+methods (GET). Creations (`POST /analyses`, `POST /jobs`) are never retried
+unless the caller explicitly opts in via an idempotency mechanism.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from dataclasses import dataclass
+
+import httpx
+
+from .errors import TransportError, error_for
+
+DEFAULT_BASE_URL = "http://localhost:8010"
+DEFAULT_TIMEOUT = 130.0
+
+
+@dataclass(frozen=True)
+class RetryConfig:
+    retries: int = 2  # extra attempts after the first
+    backoff: float = 0.2  # seconds; doubled each attempt
+
+
+def resolve_base_url(base_url: str | None) -> str:
+    return (base_url or os.getenv("CONTENT_API_URL", DEFAULT_BASE_URL)).rstrip("/")
+
+
+def _api_url(base_url: str, path: str) -> str:
+    return f"{base_url}/api/v1{path}"
+
+
+def _raise_for(resp: httpx.Response) -> None:
+    if resp.is_success:
+        return
+    try:
+        body: object = resp.json()
+    except ValueError:
+        body = resp.text
+    raise error_for(resp.status_code, body)
+
+
+def _attempts(method: str, retry: RetryConfig, idempotent: bool) -> int:
+    safe = method.upper() == "GET"
+    return retry.retries if (safe or idempotent) else 0
+
+
+def _retry_status(status: int) -> bool:
+    return status >= 500
+
+
+class SyncTransport:
+    def __init__(
+        self,
+        base_url: str,
+        timeout: float,
+        retry: RetryConfig,
+        client: httpx.Client | None = None,
+    ):
+        self.base_url = base_url
+        self._retry = retry
+        self._client = client or httpx.Client(timeout=timeout)
+        self._owns_client = client is None
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict | None = None,
+        params: dict | None = None,
+        idempotent: bool = False,
+    ) -> httpx.Response:
+        url = _api_url(self.base_url, path)
+        attempts = _attempts(method, self._retry, idempotent)
+        for attempt in range(attempts + 1):
+            try:
+                resp = self._client.request(method, url, json=json, params=params)
+            except httpx.TransportError as exc:
+                if attempt < attempts:
+                    time.sleep(self._retry.backoff * (2**attempt))
+                    continue
+                raise TransportError(str(exc)) from exc
+            if _retry_status(resp.status_code) and attempt < attempts:
+                time.sleep(self._retry.backoff * (2**attempt))
+                continue
+            _raise_for(resp)
+            return resp
+        raise TransportError("retries exhausted")  # pragma: no cover
+
+    def get(self, path: str, params: dict | None = None) -> object:
+        return self.request("GET", path, params=params).json()
+
+    def post(
+        self, path: str, json: dict | None = None, idempotent: bool = False
+    ) -> object:
+        return self.request("POST", path, json=json, idempotent=idempotent).json()
+
+    def content(self, path: str) -> bytes:
+        return self.request("GET", path).content
+
+
+class AsyncTransport:
+    def __init__(
+        self,
+        base_url: str,
+        timeout: float,
+        retry: RetryConfig,
+        client: httpx.AsyncClient | None = None,
+    ):
+        self.base_url = base_url
+        self._retry = retry
+        self._client = client or httpx.AsyncClient(timeout=timeout)
+        self._owns_client = client is None
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict | None = None,
+        params: dict | None = None,
+        idempotent: bool = False,
+    ) -> httpx.Response:
+        url = _api_url(self.base_url, path)
+        attempts = _attempts(method, self._retry, idempotent)
+        for attempt in range(attempts + 1):
+            try:
+                resp = await self._client.request(method, url, json=json, params=params)
+            except httpx.TransportError as exc:
+                if attempt < attempts:
+                    await asyncio.sleep(self._retry.backoff * (2**attempt))
+                    continue
+                raise TransportError(str(exc)) from exc
+            if _retry_status(resp.status_code) and attempt < attempts:
+                await asyncio.sleep(self._retry.backoff * (2**attempt))
+                continue
+            _raise_for(resp)
+            return resp
+        raise TransportError("retries exhausted")  # pragma: no cover
+
+    async def get(self, path: str, params: dict | None = None) -> object:
+        return (await self.request("GET", path, params=params)).json()
+
+    async def post(
+        self, path: str, json: dict | None = None, idempotent: bool = False
+    ) -> object:
+        return (
+            await self.request("POST", path, json=json, idempotent=idempotent)
+        ).json()
+
+    async def content(self, path: str) -> bytes:
+        return (await self.request("GET", path)).content

content_sdk/aio.py

@@ -0,0 +1,255 @@
+"""The asynchronous Content client — the async mirror of ContentClient.
+
+Same surface, awaitable. `AsyncAnalysis`/`AsyncJob` are the behavioural objects;
+`AsyncJob.wait()` polls until the job is terminal. Use as an async context
+manager so the underlying httpx client is closed cleanly.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Self
+
+from ._transport import DEFAULT_TIMEOUT, AsyncTransport, RetryConfig, resolve_base_url
+from .client import _source_body, _sources_list
+from .models import (
+    SCHEMA_VERSION,
+    AnalysisData,
+    AnalyzedSource,
+    ArtifactData,
+    CapabilitiesData,
+    Event,
+    JobData,
+)
+from .resources import TERMINAL_STATUSES
+
+
+class AsyncAnalysis:
+    def __init__(self, data: AnalysisData, client: AsyncContentClient):
+        self.data = data
+        self._client = client
+
+    @property
+    def id(self) -> str:
+        return self.data.analysis_id
+
+    @property
+    def sources(self) -> list[AnalyzedSource]:
+        return self.data.sources
+
+    @property
+    def expires_at(self) -> str | None:
+        return self.data.expires_at
+
+    async def capabilities(self, constraints: dict[str, Any] | None = None):
+        return await self._client.get_capabilities(self.id, constraints=constraints)
+
+    async def generate(self, outputs, **kwargs) -> AsyncJob:
+        return await self._client.generate(self.id, outputs, **kwargs)
+
+
+class AsyncJob:
+    def __init__(self, data: JobData, client: AsyncContentClient):
+        self.data = data
+        self._client = client
+
+    @property
+    def id(self) -> str:
+        return self.data.job_id
+
+    @property
+    def status(self) -> str:
+        return self.data.status
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.data.status in TERMINAL_STATUSES
+
+    @property
+    def succeeded(self) -> bool:
+        return self.data.status in ("succeeded", "partially_succeeded")
+
+    async def refresh(self) -> AsyncJob:
+        self.data = (await self._client.get_job(self.id)).data
+        return self
+
+    async def wait(
+        self, *, timeout: float = 600.0, poll_interval: float = 1.0
+    ) -> AsyncJob:
+        loop = asyncio.get_event_loop()
+        deadline = loop.time() + timeout
+        while True:
+            await self.refresh()
+            if self.is_terminal:
+                return self
+            if loop.time() >= deadline:
+                raise TimeoutError(
+                    f"job {self.id} still {self.status!r} after {timeout}s"
+                )
+            await asyncio.sleep(poll_interval)
+
+    async def artifacts(self) -> list[ArtifactData]:
+        return await self._client.artifacts(self.id)
+
+    async def events(self, after_sequence: int = 0) -> list[Event]:
+        return await self._client.events(self.id, after_sequence=after_sequence)
+
+    async def cancel(self) -> dict[str, Any]:
+        return await self._client.cancel(self.id)
+
+    async def retry(self) -> AsyncJob:
+        return await self._client.retry(self.id)
+
+
+class AsyncContentClient:
+    def __init__(
+        self,
+        base_url: str | None = None,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        retry: RetryConfig | None = None,
+        http_client=None,
+    ):
+        self._t = AsyncTransport(
+            resolve_base_url(base_url),
+            timeout,
+            retry or RetryConfig(),
+            client=http_client,
+        )
+
+    @property
+    def base_url(self) -> str:
+        return self._t.base_url
+
+    async def aclose(self) -> None:
+        await self._t.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.aclose()
+
+    # --- system / observability ------------------------------------------------
+
+    async def health(self) -> dict[str, Any]:
+        return await self._t.get("/health")
+
+    async def system(self) -> dict[str, Any]:
+        return await self._t.get("/system")
+
+    async def config(self) -> dict[str, Any]:
+        return await self._t.get("/config")
+
+    async def catalog(self) -> dict[str, Any]:
+        return await self._t.get("/catalog")
+
+    async def storage(self) -> dict[str, Any]:
+        return await self._t.get("/storage")
+
+    async def cache(self) -> dict[str, Any]:
+        return await self._t.get("/cache")
+
+    async def purge_cache(self) -> dict[str, Any]:
+        return await self._t.post("/cache/purge")
+
+    async def folders(self) -> list[str]:
+        return (await self._t.get("/folders")).get("folders", [])
+
+    # --- analysis / capabilities -----------------------------------------------
+
+    async def analyze(self, sources: Any) -> AsyncAnalysis:
+        data = await self._t.post("/analyses", {"sources": _sources_list(sources)})
+        return AsyncAnalysis(AnalysisData.model_validate(data), self)
+
+    async def get_analysis(self, analysis_id: str) -> AsyncAnalysis:
+        data = await self._t.get(f"/analyses/{analysis_id}")
+        return AsyncAnalysis(AnalysisData.model_validate(data), self)
+
+    async def get_capabilities(
+        self, target: Any, constraints: dict[str, Any] | None = None
+    ) -> CapabilitiesData:
+        body = _source_body(
+            target if not isinstance(target, AsyncAnalysis) else target.id
+        )
+        if constraints:
+            body["constraints"] = constraints
+        data = await self._t.post("/capabilities", body)
+        return CapabilitiesData.model_validate(data)
+
+    async def generate(
+        self,
+        target: Any,
+        outputs: Any,
+        *,
+        preferences: dict[str, Any] | None = None,
+        constraints: dict[str, Any] | None = None,
+        execution: dict[str, Any] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> AsyncJob:
+        resolved = target.id if isinstance(target, AsyncAnalysis) else target
+        body: dict[str, Any] = {
+            "schema_version": SCHEMA_VERSION,
+            "outputs": [outputs] if isinstance(outputs, dict) else list(outputs),
+            **_source_body(resolved),
+        }
+        for key, value in (
+            ("preferences", preferences),
+            ("constraints", constraints),
+            ("execution", execution),
+            ("metadata", metadata),
+        ):
+            if value:
+                body[key] = value
+        idempotent = bool(execution and execution.get("idempotency_key"))
+        data = await self._t.post("/jobs", body, idempotent=idempotent)
+        return AsyncJob(JobData.model_validate(data), self)
+
+    async def submit(self, request: dict[str, Any]) -> AsyncJob:
+        """Submit a pre-built GenerationRequest (raw contract dict)."""
+        idempotent = bool((request.get("execution") or {}).get("idempotency_key"))
+        data = await self._t.post("/jobs", request, idempotent=idempotent)
+        return AsyncJob(JobData.model_validate(data), self)
+
+    # --- jobs / artifacts -------------------------------------------------------
+
+    async def list_jobs(
+        self, *, status: str | None = None, limit: int = 30
+    ) -> list[JobData]:
+        params: dict[str, Any] = {"limit": limit}
+        if status:
+            params["status"] = status
+        rows = await self._t.get("/jobs", params=params)
+        return [JobData.model_validate(r) for r in rows]
+
+    async def get_job(self, job_id: str) -> AsyncJob:
+        data = await self._t.get(f"/jobs/{job_id}")
+        return AsyncJob(JobData.model_validate(data), self)
+
+    async def cancel(self, job_id: str) -> dict[str, Any]:
+        return await self._t.post(f"/jobs/{job_id}/cancel")
+
+    async def retry(self, job_id: str) -> AsyncJob:
+        data = await self._t.post(f"/jobs/{job_id}/retry")
+        return AsyncJob(JobData.model_validate(data), self)
+
+    async def events(self, job_id: str, after_sequence: int = 0) -> list[Event]:
+        rows = await self._t.get(
+            f"/jobs/{job_id}/events", params={"after_sequence": after_sequence}
+        )
+        return [Event.model_validate(r) for r in rows]
+
+    async def logs(self, job_id: str, tail: int = 400) -> dict[str, Any]:
+        return await self._t.get(f"/jobs/{job_id}/logs", params={"tail": tail})
+
+    async def artifacts(self, job_id: str) -> list[ArtifactData]:
+        rows = await self._t.get(f"/jobs/{job_id}/artifacts")
+        return [ArtifactData.model_validate(r) for r in rows]
+
+    async def get_artifact(self, artifact_id: str) -> ArtifactData:
+        return ArtifactData.model_validate(
+            await self._t.get(f"/artifacts/{artifact_id}")
+        )
+
+    async def artifact_bytes(self, artifact_id: str) -> bytes:
+        return await self._t.content(f"/artifacts/{artifact_id}/content")

content_sdk/client.py

@@ -0,0 +1,193 @@
+"""The synchronous Content client — the official way to speak to the engine.
+
+Wraps every `/api/v1` endpoint, returns natural Python objects, and maps errors
+to typed exceptions. `analyze/get_capabilities/generate` accept **either** an
+`analysis_id`/`Analysis` **or** inline sources (ADR 0014).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Self
+
+from ._transport import DEFAULT_TIMEOUT, RetryConfig, SyncTransport, resolve_base_url
+from .models import (
+    SCHEMA_VERSION,
+    AnalysisData,
+    ArtifactData,
+    CapabilitiesData,
+    Event,
+    JobData,
+)
+from .resources import Analysis, Job
+
+# Accepts an Analysis, an analysis_id string, a single source dict, or a list of
+# source dicts — resolved to the request fragment the API expects.
+SourceInput = "Analysis | str | dict[str, Any] | list[dict[str, Any]]"
+
+
+def _sources_list(sources: Any) -> list[dict[str, Any]]:
+    return [sources] if isinstance(sources, dict) else list(sources)
+
+
+def _source_body(target: Any) -> dict[str, Any]:
+    """Map a target to the `sources` XOR `analysis_id` request fragment."""
+    if isinstance(target, Analysis):
+        return {"analysis_id": target.id}
+    if isinstance(target, str):
+        return {"analysis_id": target}
+    return {"sources": _sources_list(target)}
+
+
+class ContentClient:
+    def __init__(
+        self,
+        base_url: str | None = None,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        retry: RetryConfig | None = None,
+        http_client=None,
+    ):
+        self._t = SyncTransport(
+            resolve_base_url(base_url),
+            timeout,
+            retry or RetryConfig(),
+            client=http_client,
+        )
+
+    @property
+    def base_url(self) -> str:
+        return self._t.base_url
+
+    def close(self) -> None:
+        self._t.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    # --- system / observability ------------------------------------------------
+
+    def health(self) -> dict[str, Any]:
+        return self._t.get("/health")
+
+    def system(self) -> dict[str, Any]:
+        return self._t.get("/system")
+
+    def config(self) -> dict[str, Any]:
+        return self._t.get("/config")
+
+    def catalog(self) -> dict[str, Any]:
+        return self._t.get("/catalog")
+
+    def storage(self) -> dict[str, Any]:
+        return self._t.get("/storage")
+
+    def cache(self) -> dict[str, Any]:
+        return self._t.get("/cache")
+
+    def purge_cache(self) -> dict[str, Any]:
+        return self._t.post("/cache/purge")
+
+    def notifications(self) -> list[dict[str, Any]]:
+        """What the instance wants to tell its operator (a newer release, a
+        stale yt-dlp). The engine decides what is worth saying; see
+        ``content_sdk.notifications`` for the UI-side helpers."""
+        return self._t.get("/notifications").get("notifications", [])
+
+    def folders(self) -> list[str]:
+        return self._t.get("/folders").get("folders", [])
+
+    # --- analysis / capabilities -----------------------------------------------
+
+    def analyze(self, sources: Any) -> Analysis:
+        data = self._t.post("/analyses", {"sources": _sources_list(sources)})
+        return Analysis(AnalysisData.model_validate(data), self)
+
+    def get_analysis(self, analysis_id: str) -> Analysis:
+        data = self._t.get(f"/analyses/{analysis_id}")
+        return Analysis(AnalysisData.model_validate(data), self)
+
+    def get_capabilities(
+        self, target: Any, constraints: dict[str, Any] | None = None
+    ) -> CapabilitiesData:
+        body = _source_body(target)
+        if constraints:
+            body["constraints"] = constraints
+        data = self._t.post("/capabilities", body)
+        return CapabilitiesData.model_validate(data)
+
+    def generate(
+        self,
+        target: Any,
+        outputs: Any,
+        *,
+        preferences: dict[str, Any] | None = None,
+        constraints: dict[str, Any] | None = None,
+        execution: dict[str, Any] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Job:
+        body: dict[str, Any] = {
+            "schema_version": SCHEMA_VERSION,
+            "outputs": [outputs] if isinstance(outputs, dict) else list(outputs),
+            **_source_body(target),
+        }
+        for key, value in (
+            ("preferences", preferences),
+            ("constraints", constraints),
+            ("execution", execution),
+            ("metadata", metadata),
+        ):
+            if value:
+                body[key] = value
+        # Retry POST /jobs only when the caller made it idempotent (refinement 4).
+        idempotent = bool(execution and execution.get("idempotency_key"))
+        data = self._t.post("/jobs", body, idempotent=idempotent)
+        return Job(JobData.model_validate(data), self)
+
+    def submit(self, request: dict[str, Any]) -> Job:
+        """Submit a pre-built GenerationRequest (raw contract dict) — the escape
+        hatch for full control; `generate()` is the ergonomic path."""
+        idempotent = bool((request.get("execution") or {}).get("idempotency_key"))
+        data = self._t.post("/jobs", request, idempotent=idempotent)
+        return Job(JobData.model_validate(data), self)
+
+    # --- jobs -------------------------------------------------------------------
+
+    def list_jobs(self, *, status: str | None = None, limit: int = 30) -> list[JobData]:
+        params: dict[str, Any] = {"limit": limit}
+        if status:
+            params["status"] = status
+        rows = self._t.get("/jobs", params=params)
+        return [JobData.model_validate(r) for r in rows]
+
+    def get_job(self, job_id: str) -> Job:
+        return Job(JobData.model_validate(self._t.get(f"/jobs/{job_id}")), self)
+
+    def cancel(self, job_id: str) -> dict[str, Any]:
+        return self._t.post(f"/jobs/{job_id}/cancel")
+
+    def retry(self, job_id: str) -> Job:
+        return Job(JobData.model_validate(self._t.post(f"/jobs/{job_id}/retry")), self)
+
+    def events(self, job_id: str, after_sequence: int = 0) -> list[Event]:
+        rows = self._t.get(
+            f"/jobs/{job_id}/events", params={"after_sequence": after_sequence}
+        )
+        return [Event.model_validate(r) for r in rows]
+
+    def logs(self, job_id: str, tail: int = 400) -> dict[str, Any]:
+        return self._t.get(f"/jobs/{job_id}/logs", params={"tail": tail})
+
+    # --- artifacts --------------------------------------------------------------
+
+    def artifacts(self, job_id: str) -> list[ArtifactData]:
+        rows = self._t.get(f"/jobs/{job_id}/artifacts")
+        return [ArtifactData.model_validate(r) for r in rows]
+
+    def get_artifact(self, artifact_id: str) -> ArtifactData:
+        return ArtifactData.model_validate(self._t.get(f"/artifacts/{artifact_id}"))
+
+    def artifact_bytes(self, artifact_id: str) -> bytes:
+        return self._t.content(f"/artifacts/{artifact_id}/content")