autolecture 0.1.0__py3-none-any.whl

autolecture/__init__.py

@@ -0,0 +1,88 @@
+r"""autolecture — Official Python SDK for AutoLecture (https://autolecture.ai).
+
+Quickstart:
+
+    from autolecture import Client
+
+    al = Client(api_key="al_live_…")   # mint at https://autolecture.ai/account
+    project = al.create_project(name="My first video")
+    al.upload_asset(project["id"], "./recording.mp3")
+    al.put_tex(project["id"], "main.tex", r'''
+        \title{Demo}
+        \begin{videotex}
+        \begin{view}\say{Hello, AutoLecture!}\end{view}
+        \end{videotex}
+    ''')
+    job = al.compile(project["id"], on_progress=lambda j: print(j["progress_pct"], "%"))
+    al.download_preview(project["id"], dest="./out.mp4")
+
+Errors raised by the SDK all inherit from `AutoLectureError`. The
+common subclasses (`InsufficientCreditsError`, `QuotaExceededError`,
+`RateLimitError`, `CompileFailedError`, …) carry the server's
+structured-error fields as attributes — no need to re-parse JSON.
+"""
+from autolecture.client import Client
+from autolecture.exceptions import (
+    APIError,
+    AuthenticationError,
+    AutoLectureError,
+    CompileCancelledError,
+    CompileFailedError,
+    InsufficientCreditsError,
+    NotFoundError,
+    PermissionError,
+    QuotaExceededError,
+    RateLimitError,
+    ServerError,
+)
+from autolecture.types import (
+    ApiKeyMintResult,
+    ApiKeyStatus,
+    Asset,
+    Balance,
+    CompileBlockInfo,
+    CompileJob,
+    CompileStatus,
+    CreditTopup,
+    Project,
+    ProjectFull,
+    ProjectQuota,
+    Quota,
+    Usage,
+    VoiceSampleStatus,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # client
+    "Client",
+    # exceptions
+    "APIError",
+    "AuthenticationError",
+    "AutoLectureError",
+    "CompileCancelledError",
+    "CompileFailedError",
+    "InsufficientCreditsError",
+    "NotFoundError",
+    "PermissionError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "ServerError",
+    # types
+    "ApiKeyMintResult",
+    "ApiKeyStatus",
+    "Asset",
+    "Balance",
+    "CompileBlockInfo",
+    "CompileJob",
+    "CompileStatus",
+    "CreditTopup",
+    "Project",
+    "ProjectFull",
+    "ProjectQuota",
+    "Quota",
+    "Usage",
+    "VoiceSampleStatus",
+    "__version__",
+]

autolecture/_http.py

@@ -0,0 +1,209 @@
+"""Internal HTTP layer — owns the `httpx.Client`, auth header injection,
+and the response → exception mapping. Public API never touches this
+directly; `client.py` calls `_HTTP.request(...)` and trusts it to either
+return a parsed JSON body or raise the right exception subclass.
+
+Why a wrapper instead of using `httpx.Client` directly:
+  - Centralizes the Bearer token logic (one header, every call)
+  - Centralizes the response → exception mapping (one switch, every
+    call) — keeps `client.py` focused on the API surface
+  - One natural place to add retries / observability later
+
+Retries: not added by default. The AutoLecture backend's 5xx are
+usually deterministic engine failures (e.g. Manim couldn't compile),
+not transient. Retrying would just burn API credits. Callers that
+DO want retries wrap individual methods themselves.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from autolecture.exceptions import (
+    APIError,
+    AuthenticationError,
+    AutoLectureError,
+    InsufficientCreditsError,
+    NotFoundError,
+    PermissionError,
+    QuotaExceededError,
+    RateLimitError,
+    ServerError,
+)
+
+
+# Map (status_code, code) → exception class. The 402 line is two-headed
+# because the backend uses 402 for both quota and credits gates with
+# different `code` fields. `None` means "match any code for that status".
+_DISPATCH: dict[tuple[int, str | None], type[AutoLectureError]] = {
+    (401, None):                              AuthenticationError,
+    (403, None):                              PermissionError,
+    (404, None):                              NotFoundError,
+    (402, "project_quota_exceeded"):          QuotaExceededError,
+    (402, "insufficient_credits"):            InsufficientCreditsError,
+    (429, None):                              RateLimitError,
+}
+
+
+def _classify(status_code: int, code: str) -> type[AutoLectureError]:
+    """Pick the most specific exception class for this (status, code)."""
+    if (status_code, code) in _DISPATCH:
+        return _DISPATCH[(status_code, code)]
+    if (status_code, None) in _DISPATCH:
+        return _DISPATCH[(status_code, None)]
+    if status_code >= 500:
+        return ServerError
+    return APIError
+
+
+def _parse_detail(body: Any) -> tuple[str, str, dict[str, Any]]:
+    """Coerce whatever the server sent into (code, message, full_dict).
+
+    Three shapes we handle:
+      1. `{"detail": {"code": "...", "message": "...", ...}}` — structured
+      2. `{"detail": "plain string"}` — FastAPI default
+      3. `<anything else>` — fall back to repr
+
+    Returns:
+        (code, message, response_dict). The response_dict is the inner
+        body (so exception classes can read extra fields like
+        `.balance`, `.limit`, ...).
+    """
+    if isinstance(body, dict):
+        detail = body.get("detail")
+        if isinstance(detail, dict):
+            return (
+                str(detail.get("code", "unknown")),
+                str(detail.get("message", "")),
+                detail,
+            )
+        if isinstance(detail, str):
+            return ("unknown", detail, {})
+    return ("unknown", str(body), {})
+
+
+class _HTTP:
+    """Thin wrapper around `httpx.Client`. Owns the auth header and the
+    response → exception mapping.
+
+    `request()` is what `client.py` uses for JSON endpoints — body is
+    decoded, errors are raised. `stream_to_file()` is the streaming
+    variant for video / audio downloads.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        *,
+        timeout: float = 30.0,
+        user_agent: str = "autolecture-python/0.1.0",
+    ) -> None:
+        # Strip trailing slash so callers can pass `https://autolecture.ai`
+        # or `https://autolecture.ai/` and we always build paths the same.
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "User-Agent": user_agent,
+                "Accept": "application/json",
+            },
+        )
+
+    # ── core request ────────────────────────────────────────────────
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any | None = None,
+        files: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+    ) -> Any:
+        """Make a request, return parsed JSON, raise on non-2xx.
+
+        Args:
+            method: HTTP verb.
+            path: leading-slash path (`/api/v2/projects`). Concatenated
+                onto `base_url`.
+            params: query string.
+            json: JSON body (mutually exclusive with `files` / `data`).
+            files: multipart upload (FastAPI's `UploadFile` expects this).
+            data: multipart form fields alongside `files`.
+        """
+        url = f"{self._base_url}{path}"
+        response = self._client.request(
+            method, url, params=params, json=json, files=files, data=data,
+        )
+        self._raise_for_status(response)
+        # 204 / empty body — return None so callers don't have to guard.
+        if not response.content:
+            return None
+        # Some endpoints (e.g. raw file streams) come back with non-JSON
+        # content-type; callers using `request()` for those is a bug.
+        # Trust the JSON parse to raise if so.
+        return response.json()
+
+    # ── streaming download ──────────────────────────────────────────
+
+    def stream_to_file(self, path: str, dest: Any) -> None:
+        """GET `path` and stream the body to `dest` (str / Path / file
+        object). Used for /preview mp4 downloads — avoids loading the
+        whole file into memory.
+        """
+        from pathlib import Path
+
+        url = f"{self._base_url}{path}"
+        with self._client.stream("GET", url) as response:
+            self._raise_for_status(response)
+            if isinstance(dest, (str, Path)):
+                with open(dest, "wb") as f:
+                    for chunk in response.iter_bytes(chunk_size=64 * 1024):
+                        f.write(chunk)
+            else:
+                # File-like object the caller already opened.
+                for chunk in response.iter_bytes(chunk_size=64 * 1024):
+                    dest.write(chunk)
+
+    # ── error mapping ───────────────────────────────────────────────
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response) -> None:
+        if response.is_success:
+            return
+        # Best-effort body parse. A 502 from a proxy might be HTML —
+        # `_parse_detail` falls back to repr in that case.
+        body: Any
+        try:
+            body = response.json()
+        except Exception:
+            body = response.text
+        code, message, detail = _parse_detail(body)
+        # Stream responses haven't read the body — _raise_for_status
+        # for streams runs BEFORE we start iter_bytes, so we must
+        # consume now to free the connection. Cheap (error bodies are
+        # small) and safe (httpx no-ops if already read).
+        if not message:
+            message = f"HTTP {response.status_code} ({response.reason_phrase or 'error'})"
+        cls = _classify(response.status_code, code)
+        raise cls(
+            message,
+            code=code,
+            status_code=response.status_code,
+            response=detail,
+        )
+
+    # ── lifecycle ───────────────────────────────────────────────────
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "_HTTP":
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()

autolecture/_polling.py

@@ -0,0 +1,79 @@
+"""Internal poll-until-terminal helper for compile jobs.
+
+Used by `Client.compile()` to block until the job reaches a terminal
+state (`succeeded` / `failed` / `cancelled`), invoking an optional
+progress callback after each poll.
+
+Kept separate from `client.py` so a clock-injecting test can verify
+polling logic without real sleeps.
+
+Backoff:
+  No backoff today. The backend's GET `/compile/jobs/{id}` is a cheap
+  one-row SELECT; polling at a fixed 2s interval is fine for the
+  expected job-runtimes (30s – 30min). Add backoff if we ever see
+  the polling endpoint show up in slow-query logs.
+
+Cancellation:
+  Caller cancels by raising KeyboardInterrupt (Ctrl+C) — Python
+  propagates it through `time.sleep`. The poll loop will exit
+  cleanly without retrying.
+"""
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from autolecture.exceptions import CompileCancelledError, CompileFailedError
+from autolecture.types import CompileJob
+
+if TYPE_CHECKING:
+    from autolecture._http import _HTTP
+
+
+_TERMINAL_STATES: frozenset[str] = frozenset({"succeeded", "failed", "cancelled"})
+
+
+def poll_compile_job(
+    http: "_HTTP",
+    job_id: str,
+    *,
+    on_progress: Callable[[CompileJob], None] | None = None,
+    poll_interval: float = 2.0,
+    _sleep: Callable[[float], None] = time.sleep,
+) -> CompileJob:
+    """Poll `/compile/jobs/{job_id}` until terminal, return the final job.
+
+    Args:
+        http: the SDK's internal HTTP wrapper.
+        job_id: the compile job id (UUID string).
+        on_progress: callback invoked after each poll with the latest
+            CompileJob dict. Use to drive a progress bar / log line.
+        poll_interval: seconds between polls. Default 2s.
+        _sleep: injectable for tests — defaults to `time.sleep`.
+
+    Returns:
+        The final CompileJob with status == "succeeded".
+
+    Raises:
+        CompileFailedError: when status terminates as "failed".
+        CompileCancelledError: when status terminates as "cancelled".
+    """
+    while True:
+        job: CompileJob = http.request("GET", f"/api/v2/compile/jobs/{job_id}")
+        if on_progress is not None:
+            on_progress(job)
+        status = job["status"]
+        if status in _TERMINAL_STATES:
+            if status == "failed":
+                raise CompileFailedError(
+                    f"compile job {job_id} failed: {job.get('error_log') or '(no log)'}",
+                    job=job,
+                )
+            if status == "cancelled":
+                raise CompileCancelledError(
+                    f"compile job {job_id} was cancelled",
+                    job=job,
+                )
+            return job  # succeeded
+        _sleep(poll_interval)

autolecture/client.py

@@ -0,0 +1,349 @@
+"""The `Client` class — the public surface of the SDK.
+
+Every method maps to a single AutoLecture HTTP endpoint with one
+exception: `compile()` (high-level) wraps `start_compile()` +
+polling + on-success return. Use `start_compile()` + `get_compile_job()`
+directly when you need to drive the loop yourself.
+
+All methods raise subclasses of `AutoLectureError` on failure — see
+`exceptions.py` for the hierarchy. No `try / except` swallowing.
+
+The Client is sync-only in v0.1 (httpx.Client). Async variant deferred
+to v0.2 if a real use case appears.
+
+Thread safety:
+    Underlying `httpx.Client` is thread-safe for concurrent requests.
+    Sharing one `Client` across threads is fine.
+
+Resource management:
+    Use as a context manager when possible to close the underlying
+    HTTP connection pool:
+
+        with Client(api_key="al_live_…") as al:
+            al.list_projects()
+"""
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import IO, Any
+
+from autolecture._http import _HTTP
+from autolecture._polling import poll_compile_job
+from autolecture.types import (
+    ApiKeyMintResult,
+    ApiKeyStatus,
+    Asset,
+    Balance,
+    CompileJob,
+    Project,
+    ProjectFull,
+    Quota,
+    Usage,
+    VoiceSampleStatus,
+)
+
+
+class Client:
+    """AutoLecture API client.
+
+    Args:
+        api_key: An `al_live_…` token minted at https://autolecture.ai/account.
+            (Legacy JWTs from the web-UI login also work — the backend
+            sniffs the prefix — but API keys are the supported path
+            for SDK callers.)
+        base_url: Server base URL. Defaults to production. Override to
+            `https://dev.autolecture.ai` for the dev backend, or
+            `http://localhost:8000` / `:8001` for local development.
+        timeout: Per-request timeout in seconds. Default 30s. Downloads
+            (which can be long) use this for the connect timeout only;
+            streaming bodies are not bounded by it.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://autolecture.ai",
+        timeout: float = 30.0,
+    ) -> None:
+        self._http = _HTTP(api_key=api_key, base_url=base_url, timeout=timeout)
+
+    # ── lifecycle ──────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+    # ── Projects ───────────────────────────────────────────────────────
+
+    def list_projects(self, *, archived: bool = False) -> list[Project]:
+        """GET /api/v2/projects."""
+        params = {"archived": "true"} if archived else None
+        payload = self._http.request("GET", "/api/v2/projects", params=params)
+        return payload["projects"]
+
+    def create_project(self, name: str, *, template: str = "blank") -> Project:
+        """POST /api/v2/projects. `template` is one of the built-in
+        template ids ("blank", "ai_drama", …) — defaults to blank."""
+        return self._http.request(
+            "POST", "/api/v2/projects",
+            json={"name": name, "template": template},
+        )
+
+    def create_project_from_zip(self, zip_path: Path | str, *, name: str | None = None) -> Project:
+        """POST /api/v2/projects/from-zip. Overleaf-style import:
+        unpacks the zip, registers every file as an Asset, auto-wires
+        `main.tex`."""
+        zip_path = Path(zip_path)
+        files: dict[str, Any] = {"zipfile": (zip_path.name, zip_path.read_bytes(), "application/zip")}
+        data = {"name": name} if name else None
+        return self._http.request(
+            "POST", "/api/v2/projects/from-zip",
+            files=files, data=data,
+        )
+
+    def get_project(self, project_id: str) -> ProjectFull:
+        """GET /api/v2/projects/{id} — includes `main_tex`."""
+        return self._http.request("GET", f"/api/v2/projects/{project_id}")
+
+    def update_project(
+        self, project_id: str, *, name: str | None = None, main_tex: str | None = None,
+    ) -> None:
+        """PATCH /api/v2/projects/{id}. Pass `name` or `main_tex` (or
+        both). Returns nothing — re-fetch with `get_project` if needed."""
+        body: dict[str, Any] = {}
+        if name is not None:
+            body["name"] = name
+        if main_tex is not None:
+            body["main_tex"] = main_tex
+        self._http.request("PATCH", f"/api/v2/projects/{project_id}", json=body)
+
+    def delete_project(self, project_id: str) -> None:
+        """DELETE /api/v2/projects/{id} — hard delete, cascades to
+        assets / compile jobs / cache."""
+        self._http.request("DELETE", f"/api/v2/projects/{project_id}")
+
+    def archive_project(self, project_id: str) -> None:
+        """POST /api/v2/projects/{id}/archive — soft delete; freed
+        quota slot. Reverse with `unarchive_project`."""
+        self._http.request("POST", f"/api/v2/projects/{project_id}/archive")
+
+    def unarchive_project(self, project_id: str) -> None:
+        """POST /api/v2/projects/{id}/unarchive — re-enforces project quota."""
+        self._http.request("POST", f"/api/v2/projects/{project_id}/unarchive")
+
+    def duplicate_project(self, project_id: str) -> Project:
+        """POST /api/v2/projects/{id}/duplicate — clone project + assets."""
+        return self._http.request("POST", f"/api/v2/projects/{project_id}/duplicate")
+
+    # ── Tex source ─────────────────────────────────────────────────────
+
+    def get_tex(self, project_id: str, *, path: str = "main.tex") -> str:
+        """GET /api/v2/projects/{id}/tex?path=…"""
+        payload = self._http.request(
+            "GET", f"/api/v2/projects/{project_id}/tex",
+            params={"path": path},
+        )
+        return payload["content"]
+
+    def put_tex(self, project_id: str, path: str, content: str) -> None:
+        """PUT /api/v2/projects/{id}/tex — write any `.tex` file under
+        the project (`main.tex` and any `\\input{...}` sub-tex)."""
+        self._http.request(
+            "PUT", f"/api/v2/projects/{project_id}/tex",
+            json={"path": path, "content": content},
+        )
+
+    # ── Assets ─────────────────────────────────────────────────────────
+
+    def upload_asset(
+        self, project_id: str, file: Path | str, *, rel_path: str | None = None,
+    ) -> Asset:
+        """POST /api/v2/projects/{id}/assets — multipart upload.
+
+        `rel_path` defaults to the file's basename. Use it to put
+        assets in subfolders: `rel_path="scenes/v1.py"`."""
+        p = Path(file)
+        files: dict[str, Any] = {"file": (p.name, p.read_bytes(), "application/octet-stream")}
+        data = {"rel_path": rel_path} if rel_path else None
+        return self._http.request(
+            "POST", f"/api/v2/projects/{project_id}/assets",
+            files=files, data=data,
+        )
+
+    def list_assets(self, project_id: str) -> list[Asset]:
+        """GET /api/v2/projects/{id}/assets."""
+        payload = self._http.request("GET", f"/api/v2/projects/{project_id}/assets")
+        return payload["assets"]
+
+    def delete_asset(self, project_id: str, rel_path: str) -> None:
+        """DELETE /api/v2/projects/{id}/assets?rel_path=…"""
+        self._http.request(
+            "DELETE", f"/api/v2/projects/{project_id}/assets",
+            params={"rel_path": rel_path},
+        )
+
+    # ── Compile ────────────────────────────────────────────────────────
+
+    def compile(
+        self,
+        project_id: str,
+        *,
+        tex_path: str = "main.tex",
+        only_block_index: int | None = None,
+        only_block_hash: str | None = None,
+        force_rerender: bool = False,
+        on_progress: Callable[[CompileJob], None] | None = None,
+        poll_interval: float = 2.0,
+    ) -> CompileJob:
+        """High-level: start a compile, poll until terminal, return
+        the final job (or raise CompileFailedError / CompileCancelledError).
+
+        Args:
+            project_id: project to compile.
+            tex_path: which .tex within the project (default `main.tex`).
+            only_block_index: render just one view (0-indexed). Useful
+                for iterating on a single scene.
+            only_block_hash: render just one view by hash (preferred over
+                index because indexes shift when blocks are added/removed).
+            force_rerender: skip the cache; re-render every selected block.
+            on_progress: callback invoked after each poll with the latest
+                CompileJob. Use to drive a progress bar / log line.
+            poll_interval: seconds between polls. Default 2s.
+
+        Returns:
+            The final CompileJob with `status == "succeeded"`.
+
+        Raises:
+            CompileFailedError / CompileCancelledError on terminal failure.
+        """
+        job = self.start_compile(
+            project_id,
+            tex_path=tex_path,
+            only_block_index=only_block_index,
+            only_block_hash=only_block_hash,
+            force_rerender=force_rerender,
+        )
+        return poll_compile_job(
+            self._http, job["id"] if "id" in job else job["job_id"],
+            on_progress=on_progress,
+            poll_interval=poll_interval,
+        )
+
+    def start_compile(
+        self,
+        project_id: str,
+        *,
+        tex_path: str = "main.tex",
+        only_block_index: int | None = None,
+        only_block_hash: str | None = None,
+        force_rerender: bool = False,
+    ) -> dict[str, Any]:
+        """Low-level: POST /api/v2/projects/{id}/compile and return the
+        creation response (`{status, job_id, blocks_count, est_cost_credits, ...}`)
+        immediately. Use `get_compile_job()` to poll yourself."""
+        body: dict[str, Any] = {"tex_path": tex_path, "force_rerender": force_rerender}
+        if only_block_index is not None:
+            body["only_block_index"] = only_block_index
+        if only_block_hash is not None:
+            body["only_block_hash"] = only_block_hash
+        return self._http.request(
+            "POST", f"/api/v2/projects/{project_id}/compile", json=body,
+        )
+
+    def get_compile_job(self, job_id: str) -> CompileJob:
+        """GET /api/v2/compile/jobs/{job_id} — single poll."""
+        return self._http.request("GET", f"/api/v2/compile/jobs/{job_id}")
+
+    def cancel_compile(self, job_id: str) -> CompileJob:
+        """POST /api/v2/compile/jobs/{job_id}/cancel. Cooperative —
+        the in-flight block finishes; later blocks are skipped."""
+        return self._http.request("POST", f"/api/v2/compile/jobs/{job_id}/cancel")
+
+    # ── Preview / download ─────────────────────────────────────────────
+
+    def download_preview(self, project_id: str, dest: Path | str | IO[bytes]) -> None:
+        """GET /api/v2/projects/{id}/preview — stream final.mp4 to `dest`."""
+        self._http.stream_to_file(
+            f"/api/v2/projects/{project_id}/preview", dest=dest,
+        )
+
+    def download_block_preview(
+        self, project_id: str, block_hash: str, dest: Path | str | IO[bytes],
+    ) -> None:
+        """GET /api/v2/projects/{id}/blocks/by-hash/{hash}/preview —
+        stream a single block's mp4."""
+        self._http.stream_to_file(
+            f"/api/v2/projects/{project_id}/blocks/by-hash/{block_hash}/preview",
+            dest=dest,
+        )
+
+    # ── Voice clone ────────────────────────────────────────────────────
+
+    def upload_voice_sample(
+        self, file: Path | str, *, ref_text: str | None = None,
+    ) -> dict[str, Any]:
+        """POST /api/v2/me/voice-sample — register voice for `\\say[voice=mine]`.
+        Auto-enrolls with the cloud TTS provider on success."""
+        p = Path(file)
+        files: dict[str, Any] = {"file": (p.name, p.read_bytes(), "application/octet-stream")}
+        data = {"ref_text": ref_text} if ref_text else None
+        return self._http.request(
+            "POST", "/api/v2/me/voice-sample", files=files, data=data,
+        )
+
+    def get_voice_sample(self) -> VoiceSampleStatus:
+        """GET /api/v2/me/voice-sample — registration status."""
+        return self._http.request("GET", "/api/v2/me/voice-sample")
+
+    def delete_voice_sample(self) -> None:
+        """DELETE /api/v2/me/voice-sample — removes sample + cloud enrollment."""
+        self._http.request("DELETE", "/api/v2/me/voice-sample")
+
+    # ── Account ────────────────────────────────────────────────────────
+
+    def get_balance(self) -> Balance:
+        """GET /api/v2/me/balance — credit balance + recent topups."""
+        return self._http.request("GET", "/api/v2/me/balance")
+
+    def get_quota(self) -> Quota:
+        """GET /api/v2/me/quota — plan limits + current consumption."""
+        return self._http.request("GET", "/api/v2/me/quota")
+
+    def get_usage(self, *, range: str = "month") -> Usage:  # noqa: A002 — `range` matches API
+        """GET /api/v2/me/usage?range=… ('day' / 'week' / 'month' / 'all')."""
+        return self._http.request(
+            "GET", "/api/v2/me/usage", params={"range": range},
+        )
+
+    # ── API key management ────────────────────────────────────────────
+    # NOTE: minting requires a different bearer (you can't mint a key with
+    # an unauthenticated client). These two methods are here for completeness
+    # so a script can rotate its own key — the caller still needs the
+    # currently-active key in hand to call mint_api_key.
+
+    def mint_api_key(self) -> ApiKeyMintResult:
+        """POST /api/v2/me/api-key — mint or rotate the user's API key.
+
+        The full secret is in the response's `api_key` field; this is
+        the ONLY time the server returns it. Subsequent calls to
+        `get_api_key_status` return only `last4` + `created_at`."""
+        return self._http.request("POST", "/api/v2/me/api-key")
+
+    def get_api_key_status(self) -> ApiKeyStatus:
+        """GET /api/v2/me/api-key — status only (last4 / created_at)."""
+        return self._http.request("GET", "/api/v2/me/api-key")
+
+    def revoke_api_key(self) -> None:
+        """DELETE /api/v2/me/api-key — revoke the current key.
+
+        Note: this revokes the key the SDK is currently authenticated
+        with. Subsequent calls on this Client will 401. You need to
+        re-authenticate (e.g. with a fresh JWT) to mint a new one."""
+        self._http.request("DELETE", "/api/v2/me/api-key")

autolecture/exceptions.py

@@ -0,0 +1,184 @@
+"""SDK exception hierarchy.
+
+Maps the AutoLecture backend's structured error envelope
+(`{detail: {code, message, **extra}}`) to a typed exception per HTTP
+status / scenario. Callers can switch on `.code`, branch on subclass,
+or just print `str(err)`.
+
+The base `AutoLectureError` carries the raw response dict (`.response`)
+so callers that hit a code we don't yet have a subclass for can still
+inspect everything the server sent without re-parsing JSON.
+
+The mapping happens in `_http.py::_raise_for_status`. Add a new
+subclass + a row in that dispatch table when the backend grows a new
+404/409/410 code worth surfacing — never raise the bare base.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+class AutoLectureError(Exception):
+    """Base — every SDK exception inherits from this so callers can
+    catch `AutoLectureError` once and not miss anything.
+
+    Args:
+        message: human-readable text (from the server's `message` field
+            or a fallback we synthesize when the body isn't structured).
+        code: stable identifier the server sent (`insufficient_credits`,
+            `email_not_verified`, ...). Defaults to `"unknown"` for
+            non-structured errors (plain-string `detail` responses).
+        status_code: HTTP status. Always set when the error originated
+            from an HTTP response; None for client-side issues like a
+            broken poll loop.
+        response: raw response dict (parsed JSON body) so callers can
+            inspect fields we don't surface as attributes yet.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "unknown",
+        status_code: int | None = None,
+        response: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        self.response = response or {}
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(code={self.code!r}, "
+            f"status_code={self.status_code!r}, message={self.message!r})"
+        )
+
+
+class AuthenticationError(AutoLectureError):
+    """401 — bad / missing / revoked API key (or expired JWT)."""
+
+
+class PermissionError(AutoLectureError):  # noqa: A001 — shadow std `PermissionError` intentionally
+    """403 — authenticated but not allowed. Includes the
+    `email_not_verified` gate (`.code == "email_not_verified"`)."""
+
+
+class NotFoundError(AutoLectureError):
+    """404 — resource does not exist (or you can't see it)."""
+
+
+class QuotaExceededError(AutoLectureError):
+    """402 with `code == "project_quota_exceeded"`.
+
+    Extra attrs: `.plan`, `.used`, `.limit` (mirrors the server payload).
+    """
+
+    plan: str | None
+    used: int | None
+    limit: int | None
+
+    def __init__(self, message: str, **kw: Any) -> None:
+        super().__init__(message, **kw)
+        self.plan = self.response.get("plan")
+        self.used = self.response.get("used")
+        self.limit = self.response.get("limit")
+
+
+class InsufficientCreditsError(AutoLectureError):
+    """402 with `code == "insufficient_credits"`.
+
+    Extra attrs: `.balance`, `.needed`, `.shortfall` (in credits, ✦).
+    """
+
+    balance: int | None
+    needed: int | None
+    shortfall: int | None
+
+    def __init__(self, message: str, **kw: Any) -> None:
+        super().__init__(message, **kw)
+        self.balance = self.response.get("balance")
+        self.needed = self.response.get("needed")
+        self.shortfall = self.response.get("shortfall")
+
+
+class RateLimitError(AutoLectureError):
+    """429 — daily / monthly spend cap, or compile concurrency cap.
+
+    Extra attrs: `.window` (`"daily"` / `"monthly"` / concurrency),
+    `.used`, `.limit`.
+    """
+
+    window: str | None
+    used: int | None
+    limit: int | None
+
+    def __init__(self, message: str, **kw: Any) -> None:
+        super().__init__(message, **kw)
+        self.window = self.response.get("window")
+        self.used = self.response.get("used")
+        self.limit = self.response.get("limit")
+
+
+class ServerError(AutoLectureError):
+    """5xx — something failed on the AutoLecture side. Retry policy is
+    caller's choice; the SDK does NOT auto-retry by default because most
+    of our 5xx are deterministic engine failures, not flakes."""
+
+
+class CompileFailedError(AutoLectureError):
+    """Polling finished and the compile job's `.status == "failed"`.
+
+    Extra attrs: `.job` (the final CompileJob TypedDict), `.error_log`
+    (raw stderr tail, may be empty)."""
+
+    job: dict[str, Any]
+    error_log: str | None
+
+    def __init__(self, message: str, *, job: dict[str, Any]) -> None:
+        super().__init__(
+            message,
+            code="compile_failed",
+            status_code=None,
+            response={"job": job},
+        )
+        self.job = job
+        self.error_log = job.get("error_log")
+
+
+class CompileCancelledError(AutoLectureError):
+    """Polling finished and the compile job's `.status == "cancelled"`."""
+
+    job: dict[str, Any]
+
+    def __init__(self, message: str, *, job: dict[str, Any]) -> None:
+        super().__init__(
+            message,
+            code="compile_cancelled",
+            status_code=None,
+            response={"job": job},
+        )
+        self.job = job
+
+
+class APIError(AutoLectureError):
+    """Catch-all for HTTP failures we don't have a more specific class
+    for (400 generic validation, 409 conflict, 410 gone, 413 too large,
+    503 service unavailable, ...). Inspect `.status_code` + `.code` to
+    branch on the specifics."""
+
+
+__all__ = [
+    "APIError",
+    "AuthenticationError",
+    "AutoLectureError",
+    "CompileCancelledError",
+    "CompileFailedError",
+    "InsufficientCreditsError",
+    "NotFoundError",
+    "PermissionError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "ServerError",
+]

autolecture/types.py

@@ -0,0 +1,192 @@
+"""Typed shapes for backend responses.
+
+These mirror the v2 API's JSON shapes 1:1, kept as TypedDicts (not
+dataclasses) so they're zero-runtime-cost — what the server emits is
+exactly what the SDK hands back, no copying / no conversion. IDEs +
+mypy still get full typing.
+
+The server keeps these shapes stable as part of the public API
+contract; if a field starts coming back missing or renamed, that's a
+breaking change on the server side, not here.
+
+Datetimes come through as ISO-8601 strings (no parsing on our side —
+caller chooses `datetime.fromisoformat` vs leaving as string vs
+something else). UUIDs come through as plain strings.
+"""
+from __future__ import annotations
+
+from typing import Any, Literal, NotRequired, TypedDict
+
+
+# ── Projects ───────────────────────────────────────────────────────
+
+class Project(TypedDict):
+    """Summary returned by `/projects` list + create endpoints."""
+
+    id: str
+    name: str
+    created_at: str
+    updated_at: str
+    has_compiled_video: bool
+    last_compile_hash: NotRequired[str | None]
+
+
+class ProjectFull(Project):
+    """Full project — the only extra field over `Project` is `main_tex`.
+    Returned by `GET /projects/{id}`."""
+
+    main_tex: str
+
+
+class ProjectQuota(TypedDict):
+    """Mirror of backend ProjectQuota — surfaces in list_projects()."""
+
+    plan: str
+    used: int
+    limit: int | None  # None = unlimited (paid plans)
+
+
+# ── Compile ────────────────────────────────────────────────────────
+
+CompileStatus = Literal["pending", "running", "succeeded", "failed", "cancelled"]
+
+
+class CompileBlockInfo(TypedDict, total=False):
+    """Live "current block" info while a compile is mid-run. All
+    optional because the server omits this between blocks."""
+
+    index: int
+    type: str
+    hash: str
+
+
+class CompileJob(TypedDict):
+    """Polling shape returned by `/compile/jobs/{job_id}`."""
+
+    id: str
+    project_id: str
+    status: CompileStatus
+    blocks_total: NotRequired[int | None]
+    blocks_done: int
+    blocks_failed: int
+    blocks_cached: int
+    progress_pct: NotRequired[int]
+    current_block: NotRequired[CompileBlockInfo | None]
+    queue_position: NotRequired[int | None]
+    est_cost_credits: int
+    actual_cost_credits: int
+    error_log: NotRequired[str | None]
+    elapsed_ms: NotRequired[int | None]
+    created_at: str
+    started_at: NotRequired[str | None]
+    finished_at: NotRequired[str | None]
+    has_archive: NotRequired[bool]
+
+
+# ── Assets ─────────────────────────────────────────────────────────
+
+class Asset(TypedDict):
+    """One file under a project's assets/ directory."""
+
+    rel_path: str
+    mime: str | None
+    sha1: str
+    size_bytes: int
+    duration_sec: NotRequired[float | None]
+
+
+# ── Voice clone ────────────────────────────────────────────────────
+
+class VoiceSampleStatus(TypedDict, total=False):
+    """Status returned by GET /me/voice-sample."""
+
+    registered: bool
+    uploaded_at: str | None
+    ref_text: str | None
+    size_bytes: int
+
+
+# ── Account / billing-adjacent ─────────────────────────────────────
+
+class CreditTopup(TypedDict, total=False):
+    id: str
+    package_id: str
+    amount_paid_cents: int
+    credits_added: int
+    status: str
+    created_at: str
+    completed_at: str | None
+
+
+class Balance(TypedDict, total=False):
+    """Returned by GET /me/balance."""
+
+    credits_balance: int
+    plan: str
+    is_admin: bool
+    recent_topups: list[CreditTopup]
+
+
+class Quota(TypedDict, total=False):
+    """Mirror of backend QuotaResponse (loosely typed — fields differ
+    across plans; treat as advisory)."""
+
+    plan: str
+    is_admin: bool
+    daily_used: int
+    daily_limit: int
+    monthly_used: int
+    monthly_limit: int
+    can_spend_more: bool
+    blocking_window: str | None
+
+
+class Usage(TypedDict, total=False):
+    """Aggregated spend returned by GET /me/usage."""
+
+    range: str
+    range_start: str
+    range_end: str
+    total_credits: int
+    by_kind: dict[str, int]
+    by_provider: dict[str, int]
+    by_day: list[dict[str, Any]]
+
+
+# ── API key (mint endpoint returns the only place we ever surface
+#    the plaintext secret) ────────────────────────────────────────────
+
+class ApiKeyMintResult(TypedDict):
+    """Response from POST /me/api-key — the ONLY place the plaintext
+    secret appears. Store it immediately; subsequent GETs return only
+    `last4` + `created_at`."""
+
+    api_key: str   # full `al_live_<32 url-safe bytes>` — show once, never again
+    created_at: str
+    warning: str   # human-readable "store this now"
+
+
+class ApiKeyStatus(TypedDict):
+    """GET /me/api-key — never returns the plaintext."""
+
+    registered: bool
+    last4: str | None
+    created_at: str | None
+
+
+__all__ = [
+    "ApiKeyMintResult",
+    "ApiKeyStatus",
+    "Asset",
+    "Balance",
+    "CompileBlockInfo",
+    "CompileJob",
+    "CompileStatus",
+    "CreditTopup",
+    "Project",
+    "ProjectFull",
+    "ProjectQuota",
+    "Quota",
+    "Usage",
+    "VoiceSampleStatus",
+]

autolecture-0.1.0.dist-info/METADATA

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: autolecture
+Version: 0.1.0
+Summary: Official Python SDK for AutoLecture (https://autolecture.ai). Generate explainer videos from script or audio via a clean HTTP client.
+Project-URL: Homepage, https://autolecture.ai
+Project-URL: Repository, https://github.com/scao7/autolecture-python
+Project-URL: Documentation, https://autolecture.ai/docs/dsl
+Project-URL: Issues, https://github.com/scao7/autolecture-python/issues
+Author-email: scao7 <codescao7@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,autolecture,explainer,lecturetex,manim,remotion,tts,video,videotex
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# autolecture — Python SDK
+
+Official Python SDK for [AutoLecture](https://autolecture.ai) — author
+explainer videos as a `.tex` source, render them on the server,
+download an mp4. The SDK wraps the v2 HTTP API end-to-end: projects,
+assets, tex source, compile jobs (with polling), final-video download,
+voice clone, billing-adjacent reads.
+
+The SDK is the supported way to drive AutoLecture from outside the web
+UI — built for CLIs, Claude Code skills, and any service-to-service
+use case where a JWT login flow doesn't fit.
+
+## Install
+
+```bash
+pip install autolecture
+```
+
+Python 3.10+. The SDK depends only on `httpx>=0.27`.
+
+## Auth
+
+Every call needs an API key. To mint one:
+
+1. Sign in at <https://autolecture.ai>.
+2. Open <https://autolecture.ai/account>, find the **API Keys** section.
+3. Click **Generate** — copy the `al_live_…` string **immediately**, it's
+   only shown once.
+
+Pass it to the `Client` constructor (or read from `AUTOLECTURE_API_KEY`
+env var in your own code — the SDK doesn't read env vars itself, that's
+caller-side).
+
+## Quickstart
+
+```python
+from pathlib import Path
+from autolecture import Client
+
+with Client(api_key="al_live_…") as al:
+    # 1. Create a project.
+    project = al.create_project(name="My first AutoLecture video")
+    pid = project["id"]
+
+    # 2. Upload a script + any assets you want to reference.
+    al.upload_asset(pid, Path("./recording.mp3"))
+
+    # 3. Write the VideoTeX source. See https://autolecture.ai/docs/dsl.
+    al.put_tex(pid, "main.tex", r"""
+        \title{Demo}
+        \aspect{16:9}
+        \begin{videotex}
+            \begin{view}
+                \say{Hello, AutoLecture!}
+                \image[engine=gemini]{a duck explaining a concept on a chalkboard}
+            \end{view}
+        \end{videotex}
+    """.strip())
+
+    # 4. Compile. `compile()` blocks until the job terminates;
+    #    `on_progress` fires after each poll for progress UI.
+    job = al.compile(
+        pid,
+        on_progress=lambda j: print(f"  [{j['blocks_done']}/{j['blocks_total'] or '?'}] {j['status']}"),
+    )
+    print(f"Compile finished — {job['actual_cost_credits']} ✦ spent")
+
+    # 5. Download the final mp4.
+    al.download_preview(pid, dest="./out.mp4")
+    print("Saved to ./out.mp4")
+```
+
+## Errors
+
+Every SDK exception inherits from `AutoLectureError`. The common
+subclasses carry the backend's structured-error fields as attributes:
+
+```python
+from autolecture import (
+    AutoLectureError, AuthenticationError, PermissionError,
+    QuotaExceededError, InsufficientCreditsError, RateLimitError,
+    CompileFailedError, NotFoundError, APIError,
+)
+
+try:
+    al.compile(pid)
+except InsufficientCreditsError as e:
+    print(f"Need {e.shortfall} more ✦. Balance: {e.balance}, needed: {e.needed}")
+except QuotaExceededError as e:
+    print(f"Plan {e.plan} caps at {e.limit} projects (you have {e.used}).")
+except CompileFailedError as e:
+    print(f"Render failed:\n{e.error_log}")
+except AutoLectureError as e:
+    # Catch-all — every SDK error inherits from this.
+    print(f"[{e.code}] {e.message}")
+```
+
+For a less specific error (e.g. an HTTP status we don't have a subclass
+for yet), you get a generic `APIError` with `.status_code` and `.code`.
+
+## What's in `Client`
+
+| Area | Methods |
+|---|---|
+| Projects | `list_projects` / `create_project` / `create_project_from_zip` / `get_project` / `update_project` / `delete_project` / `archive_project` / `unarchive_project` / `duplicate_project` |
+| Tex source | `get_tex` / `put_tex` |
+| Assets | `upload_asset` / `list_assets` / `delete_asset` |
+| Compile | `compile` (high-level + polling) / `start_compile` / `get_compile_job` / `cancel_compile` |
+| Preview | `download_preview` / `download_block_preview` |
+| Voice clone | `upload_voice_sample` / `get_voice_sample` / `delete_voice_sample` |
+| Account | `get_balance` / `get_quota` / `get_usage` |
+| API key | `mint_api_key` / `get_api_key_status` / `revoke_api_key` |
+
+See the docstrings — every public method maps 1:1 to a documented
+HTTP endpoint at <https://autolecture.ai/api/v2/...>.
+
+## Pointing at a different server
+
+Most users won't need this. For local development or staging:
+
+```python
+al = Client(api_key="al_live_…", base_url="https://dev.autolecture.ai")
+# or
+al = Client(api_key="al_live_…", base_url="http://localhost:8000")
+```
+
+## Async?
+
+v0.1 is sync-only — `httpx.Client`, no `await`. An async variant
+(`AsyncClient`) is on the roadmap for v0.2 if there's demand; the
+typical "script in a Claude Code skill" use case is sync-friendly,
+so async hasn't been a priority.
+
+## Development
+
+```bash
+git clone https://github.com/scao7/autolecture-python
+cd autolecture-python
+pip install -e ".[dev]"
+pytest -q
+ruff check src tests
+mypy src
+```
+
+Tests use `respx` to mock the backend HTTP — nothing reaches the network.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Links
+
+- AutoLecture web app — <https://autolecture.ai>
+- DSL reference — <https://autolecture.ai/docs/dsl>
+- Companion Claude Code skill — <https://github.com/scao7/autolecture-claude-skill>
+- Backend repo — <https://github.com/scao7/autolecture>

autolecture-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+autolecture/__init__.py,sha256=EXO_4PrEPgeXQW7yKu5one8pBZ6ZxkqOnXlN7DpugkA,2144
+autolecture/_http.py,sha256=BX5JxA912J8lwnqq0oKc4YVmbKgOzy4N99CkeuAj9aQ,8102
+autolecture/_polling.py,sha256=lOKWPL7xd4RnBipRhmneKjcRXpDe-92Rz_Hxse0Cc8E,2753
+autolecture/client.py,sha256=ZACfqdfPhB85P9_H43P_zm3i4KcQcwGlzll_iiFd_tU,15407
+autolecture/exceptions.py,sha256=TNmPcjunEUH18SAuJoNQWMdt5pzBN9hWbyNyFXdTFO0,5878
+autolecture/types.py,sha256=3ARv-Qwwavv3hzcGItyZvrs3VY87StiBubCvFJv3JgU,5588
+autolecture-0.1.0.dist-info/METADATA,sha256=NXv-N6SgxpBEv2HyWct-VnCAESVOMAcRAda5spolO4M,6547
+autolecture-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+autolecture-0.1.0.dist-info/licenses/LICENSE,sha256=qI6QMnWQp1r3t77w1mbVghM0GFwYxEubRnAcLkC-Snw,1062
+autolecture-0.1.0.dist-info/RECORD,,

autolecture-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

autolecture-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 scao7
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.