llamagen-python 0.1.0__tar.gz

llamagen_python-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+/.pycache/
+/build/
+/dist/
+/*.egg-info/
+/.pytest_cache/
+/.ruff_cache/
+/.mypy_cache/
+/.venv/
+__pycache__/
+*.py[cod]

llamagen_python-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 llamagen.ai
+
+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.

llamagen_python-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: llamagen-python
+Version: 0.1.0
+Summary: Official Python SDK for LlamaGen Comic API and Animation API
+Project-URL: Homepage, https://llamagen.ai/comic-api
+Project-URL: Documentation, https://llamagen.ai/comic-api/docs
+Project-URL: Source, https://github.com/LlamaGenAI/llamagen-python
+Project-URL: Issues, https://github.com/LlamaGenAI/llamagen-python/issues
+Author-email: "llamagen.ai" <support@llamagen.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,ai comic api,animation,comic,image-to-video,llamagen,sdk,text-to-video
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# llamagen-python
+
+Official Python SDK for LlamaGen's Comic API and Animation API.
+
+Homepage: <https://llamagen.ai/comic-api>
+
+## Install
+
+```bash
+pip install llamagen-python
+```
+
+## Quick Start
+
+```python
+import os
+from llamagen import LlamaGenClient
+
+llamagen = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])
+
+created = llamagen.comic.create({
+    "prompt": "A 4-panel comic about Leo finding a glowing key in a quiet library.",
+    "style": "manga",
+    "fixPanelNum": 4,
+})
+
+done = llamagen.comic.wait_for_completion(created["id"])
+print(done["status"], done.get("comics"))
+```
+
+## Client
+
+```python
+llamagen = LlamaGenClient(
+    api_key="YOUR_API_KEY",
+    base_url="https://api.llamagen.ai/v1",
+    timeout_ms=30000,
+    max_retries=2,
+    retry_delay_ms=500,
+)
+```
+
+The SDK uses Python's standard library HTTP stack and does not require runtime
+dependencies.
+
+## Comic API
+
+Use `llamagen.comic` to create comics, manga, webtoons, storyboards,
+consistent-character pages, and panel edits.
+
+```python
+generation = llamagen.comic.create({
+    "prompt": "The Little Prince meets the Fox in a luminous desert.",
+    "style": "storybook manga",
+    "size": "1024x1024",
+    "pagination": {"totalPages": 2, "panelsPerPage": 4},
+    "comicRoles": [
+        {
+            "name": "The Little Prince",
+            "image": "https://example.com/prince.png",
+            "clothing": "green coat and yellow scarf",
+        }
+    ],
+    "attachments": [{"type": "image", "url": "https://example.com/reference.png"}],
+    "language": "en",
+    "upscale": "2K",
+})
+```
+
+Comic methods:
+
+- `llamagen.comic.create(params)` calls `POST /v1/comics/generations`.
+- `llamagen.comic.get(id, page=None, panel=None)` calls `GET /v1/comics/generations/{id}`.
+- `llamagen.comic.continue_write(id, params)` extends an existing comic.
+- `llamagen.comic.update_panel(id, params)` regenerates one panel.
+- `llamagen.comic.usage()` calls `GET /v1/comics/usage`.
+- `llamagen.comic.upload(file, filename=None)` calls `POST /v1/comics/upload`.
+- `llamagen.comic.wait_for_completion(id, **options)` polls until a terminal status.
+- `llamagen.comic.create_and_wait(params, **options)` creates and polls.
+- `llamagen.comic.create_batch(params_list, concurrency=3)` submits many jobs.
+- `llamagen.comic.wait_for_many(ids, concurrency=3)` polls many jobs.
+
+JavaScript-style aliases are also available: `createComic`, `getComic`,
+`continueComic`, `regeneratePanel`, `updateComicPanel`, `waitForCompletion`,
+`createAndWait`, and `waitForMany`.
+
+## Animation API
+
+```python
+video = llamagen.animation.create({
+    "prompt": "A heroic fox detective walks through neon rain, cinematic camera move.",
+    "videoOptions": {
+        "duration": 5,
+        "resolution": "720p",
+        "aspect_ratio": "16:9",
+        "image": "https://example.com/first-frame.png",
+        "last_frame_image": "https://example.com/last-frame.png",
+        "reference_images": ["https://example.com/character.png"],
+    },
+})
+
+finished = llamagen.animation.wait_for_completion(
+    video["id"],
+    interval_ms=5000,
+    timeout_ms=300000,
+)
+```
+
+Animation methods:
+
+- `llamagen.animation.create(params)` calls `POST /v1/artworks/generations`.
+- `llamagen.animation.get(id)` calls `GET /v1/artworks/generations/{id}`.
+- `llamagen.animation.wait_for_completion(id, **options)` polls video status.
+- `llamagen.animation.create_and_wait(params, **options)` creates and polls.
+
+`llamagen.animations` is an alias for `llamagen.animation`.
+
+## Webhooks
+
+```python
+from llamagen import construct_webhook_event
+
+event = construct_webhook_event(
+    payload=raw_body,
+    headers=request_headers,
+    secret=os.environ["LLAMAGEN_WEBHOOK_SECRET"],
+)
+```
+
+The helper verifies `X-Llama-Webhook-Timestamp` and
+`X-Llama-Webhook-Signature` with HMAC SHA-256 and a default 5-minute tolerance.
+
+## Publishing
+
+Detailed release notes are in [`docs/RELEASE.md`](docs/RELEASE.md).
+
+1. Update `version` in `pyproject.toml`.
+2. Run tests and packaging checks:
+
+```bash
+python -m unittest discover -s tests
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+```
+
+3. Publish to TestPyPI first:
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+4. Install from TestPyPI in a clean environment and smoke-test:
+
+```bash
+python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ llamagen-python
+```
+
+5. Publish to PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+Use a PyPI API token through `TWINE_USERNAME=__token__` and
+`TWINE_PASSWORD=pypi-...` or configure a trusted publisher in PyPI for GitHub
+Actions.
+
+## Local Dev
+
+```bash
+python -m unittest discover -s tests
+python -m compileall src tests
+```

llamagen_python-0.1.0/README.md

@@ -0,0 +1,174 @@
+# llamagen-python
+
+Official Python SDK for LlamaGen's Comic API and Animation API.
+
+Homepage: <https://llamagen.ai/comic-api>
+
+## Install
+
+```bash
+pip install llamagen-python
+```
+
+## Quick Start
+
+```python
+import os
+from llamagen import LlamaGenClient
+
+llamagen = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])
+
+created = llamagen.comic.create({
+    "prompt": "A 4-panel comic about Leo finding a glowing key in a quiet library.",
+    "style": "manga",
+    "fixPanelNum": 4,
+})
+
+done = llamagen.comic.wait_for_completion(created["id"])
+print(done["status"], done.get("comics"))
+```
+
+## Client
+
+```python
+llamagen = LlamaGenClient(
+    api_key="YOUR_API_KEY",
+    base_url="https://api.llamagen.ai/v1",
+    timeout_ms=30000,
+    max_retries=2,
+    retry_delay_ms=500,
+)
+```
+
+The SDK uses Python's standard library HTTP stack and does not require runtime
+dependencies.
+
+## Comic API
+
+Use `llamagen.comic` to create comics, manga, webtoons, storyboards,
+consistent-character pages, and panel edits.
+
+```python
+generation = llamagen.comic.create({
+    "prompt": "The Little Prince meets the Fox in a luminous desert.",
+    "style": "storybook manga",
+    "size": "1024x1024",
+    "pagination": {"totalPages": 2, "panelsPerPage": 4},
+    "comicRoles": [
+        {
+            "name": "The Little Prince",
+            "image": "https://example.com/prince.png",
+            "clothing": "green coat and yellow scarf",
+        }
+    ],
+    "attachments": [{"type": "image", "url": "https://example.com/reference.png"}],
+    "language": "en",
+    "upscale": "2K",
+})
+```
+
+Comic methods:
+
+- `llamagen.comic.create(params)` calls `POST /v1/comics/generations`.
+- `llamagen.comic.get(id, page=None, panel=None)` calls `GET /v1/comics/generations/{id}`.
+- `llamagen.comic.continue_write(id, params)` extends an existing comic.
+- `llamagen.comic.update_panel(id, params)` regenerates one panel.
+- `llamagen.comic.usage()` calls `GET /v1/comics/usage`.
+- `llamagen.comic.upload(file, filename=None)` calls `POST /v1/comics/upload`.
+- `llamagen.comic.wait_for_completion(id, **options)` polls until a terminal status.
+- `llamagen.comic.create_and_wait(params, **options)` creates and polls.
+- `llamagen.comic.create_batch(params_list, concurrency=3)` submits many jobs.
+- `llamagen.comic.wait_for_many(ids, concurrency=3)` polls many jobs.
+
+JavaScript-style aliases are also available: `createComic`, `getComic`,
+`continueComic`, `regeneratePanel`, `updateComicPanel`, `waitForCompletion`,
+`createAndWait`, and `waitForMany`.
+
+## Animation API
+
+```python
+video = llamagen.animation.create({
+    "prompt": "A heroic fox detective walks through neon rain, cinematic camera move.",
+    "videoOptions": {
+        "duration": 5,
+        "resolution": "720p",
+        "aspect_ratio": "16:9",
+        "image": "https://example.com/first-frame.png",
+        "last_frame_image": "https://example.com/last-frame.png",
+        "reference_images": ["https://example.com/character.png"],
+    },
+})
+
+finished = llamagen.animation.wait_for_completion(
+    video["id"],
+    interval_ms=5000,
+    timeout_ms=300000,
+)
+```
+
+Animation methods:
+
+- `llamagen.animation.create(params)` calls `POST /v1/artworks/generations`.
+- `llamagen.animation.get(id)` calls `GET /v1/artworks/generations/{id}`.
+- `llamagen.animation.wait_for_completion(id, **options)` polls video status.
+- `llamagen.animation.create_and_wait(params, **options)` creates and polls.
+
+`llamagen.animations` is an alias for `llamagen.animation`.
+
+## Webhooks
+
+```python
+from llamagen import construct_webhook_event
+
+event = construct_webhook_event(
+    payload=raw_body,
+    headers=request_headers,
+    secret=os.environ["LLAMAGEN_WEBHOOK_SECRET"],
+)
+```
+
+The helper verifies `X-Llama-Webhook-Timestamp` and
+`X-Llama-Webhook-Signature` with HMAC SHA-256 and a default 5-minute tolerance.
+
+## Publishing
+
+Detailed release notes are in [`docs/RELEASE.md`](docs/RELEASE.md).
+
+1. Update `version` in `pyproject.toml`.
+2. Run tests and packaging checks:
+
+```bash
+python -m unittest discover -s tests
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+```
+
+3. Publish to TestPyPI first:
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+4. Install from TestPyPI in a clean environment and smoke-test:
+
+```bash
+python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ llamagen-python
+```
+
+5. Publish to PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+Use a PyPI API token through `TWINE_USERNAME=__token__` and
+`TWINE_PASSWORD=pypi-...` or configure a trusted publisher in PyPI for GitHub
+Actions.
+
+## Local Dev
+
+```bash
+python -m unittest discover -s tests
+python -m compileall src tests
+```

llamagen_python-0.1.0/docs/RELEASE.md

@@ -0,0 +1,230 @@
+# Release Guide
+
+This package publishes as `llamagen-python` and imports as `llamagen`.
+
+## Prerequisites
+
+- A PyPI account with permission to publish `llamagen-python`.
+- A TestPyPI account for release rehearsals.
+- Either PyPI API tokens or trusted publishing configured in PyPI.
+
+Install release tools:
+
+```bash
+python -m pip install --upgrade build twine
+```
+
+## Preflight
+
+Run from the `llamagen-python` directory:
+
+```bash
+python -m unittest discover -s tests
+python -m compileall src tests
+```
+
+If macOS system Python tries to write bytecode outside the workspace, direct the
+cache into the project:
+
+```bash
+PYTHONPYCACHEPREFIX=.pycache python -m compileall src tests
+```
+
+## Version
+
+Update both version declarations:
+
+- `pyproject.toml` under `[project].version`
+- `src/llamagen/__init__.py` under `__version__`
+
+Use semantic versioning:
+
+- Patch: compatible bug fixes.
+- Minor: new endpoints or helpers with backward compatibility.
+- Major: breaking API changes.
+
+## Build
+
+Remove old build artifacts, then build source and wheel distributions:
+
+```bash
+rm -rf dist build *.egg-info
+python -m build
+python -m twine check dist/*
+```
+
+## TestPyPI
+
+Publish a rehearsal release:
+
+```bash
+TWINE_USERNAME=__token__ TWINE_PASSWORD=testpypi-... \
+  python -m twine upload --repository testpypi dist/*
+```
+
+Install and smoke-test from a clean virtual environment:
+
+```bash
+python -m venv /tmp/llamagen-python-smoke
+. /tmp/llamagen-python-smoke/bin/activate
+python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ llamagen-python
+python - <<'PY'
+from llamagen import LlamaGenClient
+
+client = LlamaGenClient(api_key="test")
+print(type(client).__name__)
+PY
+```
+
+## PyPI
+
+Publish the production release:
+
+```bash
+TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-... \
+  python -m twine upload dist/*
+```
+
+After publishing, verify metadata and installability:
+
+```bash
+python -m venv /tmp/llamagen-python-pypi-smoke
+. /tmp/llamagen-python-pypi-smoke/bin/activate
+python -m pip install llamagen-python
+python -c "import llamagen; print(llamagen.__version__)"
+```
+
+## Recommended GitHub Actions Publishing
+
+For long-term maintenance, configure PyPI trusted publishing instead of storing
+API tokens in repository secrets. Create a GitHub release workflow that:
+
+1. Checks out the repository.
+2. Sets up Python.
+3. Runs unittest and compileall.
+4. Builds with `python -m build`.
+5. Publishes with `pypa/gh-action-pypi-publish`.
+
+# 中文发布说明
+
+这个项目发布到 PyPI 时的包名是 `llamagen-python`，用户安装后在代码里通过
+`import llamagen` 或 `from llamagen import LlamaGenClient` 使用。
+
+## 准备工作
+
+发布前需要确认这些条件已经满足：
+
+- 拥有 `llamagen-python` 这个 PyPI 项目的发布权限。
+- 拥有 TestPyPI 账号，用来先做一次预发布演练。
+- 已准备 PyPI API Token，或者已经在 PyPI 上配置 Trusted Publisher。
+
+安装本地发布工具：
+
+```bash
+python -m pip install --upgrade build twine
+```
+
+## 发布前检查
+
+进入项目目录：
+
+```bash
+cd /Users/zuoxd/work/all/llamagen-python
+```
+
+运行测试和语法编译检查：
+
+```bash
+python -m unittest discover -s tests
+python -m compileall src tests examples
+```
+
+如果 macOS 系统 Python 尝试把缓存写到用户 Library 目录并被权限拦截，可以把
+pycache 指向项目内：
+
+```bash
+PYTHONPYCACHEPREFIX=.pycache python -m compileall src tests examples
+```
+
+## 更新版本号
+
+每次发布前同时更新两个位置：
+
+- `pyproject.toml` 里的 `[project].version`
+- `src/llamagen/__init__.py` 里的 `__version__`
+
+版本号建议遵循语义化版本：
+
+- Patch：兼容的 bug 修复，例如 `0.1.1`。
+- Minor：新增兼容能力，例如新 endpoint 或新 helper，例如 `0.2.0`。
+- Major：破坏性变更，例如 `1.0.0` 到 `2.0.0`。
+
+## 构建发布产物
+
+先清理旧产物，再构建源码包和 wheel：
+
+```bash
+rm -rf dist build *.egg-info
+python -m build
+python -m twine check dist/*
+```
+
+`twine check` 必须通过。它会检查 README、metadata 和分发包格式是否能被 PyPI
+正常解析。
+
+## 先发布到 TestPyPI
+
+推荐每次正式发布前先发布到 TestPyPI：
+
+```bash
+TWINE_USERNAME=__token__ TWINE_PASSWORD=testpypi-... \
+  python -m twine upload --repository testpypi dist/*
+```
+
+然后新建一个干净环境，从 TestPyPI 安装并做 smoke test：
+
+```bash
+python -m venv /tmp/llamagen-python-smoke
+. /tmp/llamagen-python-smoke/bin/activate
+python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ llamagen-python
+python - <<'PY'
+from llamagen import LlamaGenClient
+
+client = LlamaGenClient(api_key="test")
+print(type(client).__name__)
+PY
+```
+
+能正常输出 `LlamaGenClient`，说明包名、导入名和 wheel 内容基本正确。
+
+## 正式发布到 PyPI
+
+确认 TestPyPI 没问题后，再上传正式 PyPI：
+
+```bash
+TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-... \
+  python -m twine upload dist/*
+```
+
+发布后建议再用一个干净环境从正式 PyPI 安装验证：
+
+```bash
+python -m venv /tmp/llamagen-python-pypi-smoke
+. /tmp/llamagen-python-pypi-smoke/bin/activate
+python -m pip install llamagen-python
+python -c "import llamagen; print(llamagen.__version__)"
+```
+
+## 推荐的长期发布方式
+
+长期维护时，推荐使用 PyPI Trusted Publisher 配合 GitHub Actions，而不是把
+PyPI Token 存进仓库 Secrets。标准流程是：
+
+1. 在 PyPI 项目设置中配置 GitHub Trusted Publisher。
+2. GitHub Actions checkout 代码。
+3. 设置 Python 环境。
+4. 运行 `python -m unittest discover -s tests`。
+5. 运行 `python -m build`。
+6. 使用 `pypa/gh-action-pypi-publish` 发布。
+
+这样可以减少 token 泄露风险，也更适合团队协作和自动化 release。

llamagen_python-0.1.0/examples/quickstart.py

@@ -0,0 +1,17 @@
+import os
+
+from llamagen import LlamaGenClient
+
+
+client = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])
+
+created = client.comic.create(
+    {
+        "prompt": "A 4-panel comic about Leo finding a glowing key in a quiet library.",
+        "style": "manga",
+        "fixPanelNum": 4,
+    }
+)
+
+done = client.comic.wait_for_completion(created["id"])
+print(done["status"])

llamagen_python-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "llamagen-python"
+version = "0.1.0"
+description = "Official Python SDK for LlamaGen Comic API and Animation API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "llamagen.ai", email = "support@llamagen.ai" }]
+keywords = [
+  "llamagen",
+  "comic",
+  "animation",
+  "ai comic api",
+  "text-to-video",
+  "image-to-video",
+  "sdk",
+  "ai"
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://llamagen.ai/comic-api"
+Documentation = "https://llamagen.ai/comic-api/docs"
+Source = "https://github.com/LlamaGenAI/llamagen-python"
+Issues = "https://github.com/LlamaGenAI/llamagen-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/llamagen"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]