autolecture 0.1.0__tar.gz

autolecture-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+.venv/
+venv/
+.env
+.env.*
+*.log
+.DS_Store

autolecture-0.1.0/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.

autolecture-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,156 @@
+# 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/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "autolecture"
+version = "0.1.0"
+description = "Official Python SDK for AutoLecture (https://autolecture.ai). Generate explainer videos from script or audio via a clean HTTP client."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "scao7", email = "codescao7@gmail.com" }]
+keywords = ["autolecture", "video", "explainer", "manim", "remotion", "ai", "tts", "lecturetex", "videotex"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "respx>=0.21",
+    "mypy>=1.10",
+    "ruff>=0.6",
+]
+
+[project.urls]
+Homepage      = "https://autolecture.ai"
+Repository    = "https://github.com/scao7/autolecture-python"
+Documentation = "https://autolecture.ai/docs/dsl"
+Issues        = "https://github.com/scao7/autolecture-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/autolecture"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -q --strict-markers"
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "RUF"]
+ignore = ["E501"]  # line-length handled by formatter
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_ignores = true
+files = ["src/autolecture"]

autolecture-0.1.0/src/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__",
+]