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>
