pydantic-ai-videogen 2.5.3__tar.gz

pydantic_ai_videogen-2.5.3/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.venv-test/
+.pytest_cache/

pydantic_ai_videogen-2.5.3/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: pydantic-ai-videogen
+Version: 2.5.3
+Summary: Official Pydantic AI tools for the VideoGen API. Generate videos, images, voiceovers, sound effects, music, and avatars from any Pydantic AI agent.
+Project-URL: Homepage, https://videogen.io
+Project-URL: Documentation, https://github.com/video-gen/video-workflow-recipes/tree/main/integrations/pydantic-ai-videogen#readme
+Project-URL: Repository, https://github.com/video-gen/video-workflow-recipes
+License: MIT
+Keywords: agents,ai,ai-video-generation,image-generation,pydantic,pydantic-ai,text-to-speech,text-to-video,tools,videogen
+Requires-Python: >=3.9
+Requires-Dist: pydantic-ai-slim>=0.0.30
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: videogen>=2.5.3
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pydantic-ai-videogen
+
+Official [Pydantic AI](https://ai.pydantic.dev) tools for the [VideoGen API](https://docs.videogen.io). Give any Pydantic AI agent the ability to turn a script into a finished narrated video, plus generate standalone images, video clips, voiceovers, sound effects, music, and talking-head avatars.
+
+Every tool wraps the official [`videogen`](https://pypi.org/project/videogen/) SDK and runs as the team that owns your API key.
+
+## Install
+
+```bash
+pip install pydantic-ai-videogen
+```
+
+## Setup
+
+Get an API key from [app.videogen.io/api](https://app.videogen.io/api) and set it as `VIDEOGEN_API_KEY`:
+
+```bash
+export VIDEOGEN_API_KEY="your_api_key"
+```
+
+## Usage
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai_videogen import create_videogen_tools
+
+agent = Agent(
+    "openai:gpt-4o",
+    tools=create_videogen_tools(),
+    system_prompt="You produce short narrated videos with VideoGen when asked.",
+)
+
+result = agent.run_sync(
+    "Make a short narrated video explaining why staying hydrated matters."
+)
+print(result.output)
+```
+
+By default each tool blocks until the workflow or tool execution finishes and returns the completed result.
+
+## Options
+
+```python
+from videogen import VideoGen
+from pydantic_ai_videogen import create_videogen_tools
+
+tools = create_videogen_tools(
+    # Provide a pre-configured client, or pass api_key / base_url, or rely on env.
+    client=VideoGen(api_key="your_api_key"),
+
+    # Return the run/execution id immediately instead of waiting.
+    wait=False,
+
+    # Only expose a subset of tools to the model.
+    include=["script_to_video", "generate_image", "text_to_speech"],
+)
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `client` | — | A pre-configured `VideoGen` client. |
+| `api_key` | `VIDEOGEN_API_KEY` | API key used to build a client when `client` is omitted. |
+| `base_url` | `VIDEOGEN_BASE_URL` or production | Override the API base URL. |
+| `wait` | `True` | Block until the operation finishes and return the result. |
+| `poll_interval_ms` | SDK default | Poll interval while waiting. |
+| `timeout_ms` | SDK default | Maximum time to wait before giving up. |
+| `include` | all tools | Restrict the returned tool set to these tool names. |
+
+## Tools
+
+<!-- BEGIN GENERATED PYTHON AGENT TOOLS -->
+- Workflows: `cancel_workflow_run`, `get_workflow_run`, `list_workflow_runs`, `prompt_to_video_clip`, `script_to_video`, `slideshow_to_video`, `storyboard_to_video`, `video_to_video`, `voiceover_to_video`.
+- Media generation: `cancel_tool_execution`, `generate_avatar`, `generate_image`, `generate_motion_graphic`, `generate_music`, `generate_sound_effect`, `generate_video_clip`, `get_tool_execution`, `image_3d_effect`, `list_tool_executions`, `remove_image_background`, `remove_video_background`, `text_to_speech`, `upscale_image`, `upscale_video`, `vectorize_image`.
+- Projects: `export_project`, `get_project`, `list_project_remix_actions`, `list_projects`, `remix_project`.
+- Files: `get_file`, `list_files`, `upload_file`.
+- Resources and account: `get_me`, `list_languages`, `list_tts_voices`.
+
+Avatar generation and supported video workflows use reusable actor entities. Pass `actor_entity_id` and set `avatar_quality` to `LOW`, `STANDARD`, `HIGH`, or `MAX`. Narrator changes are passed in `remix_actions` as `CHANGE_NARRATOR` action dictionaries.
+<!-- END GENERATED PYTHON AGENT TOOLS -->
+
+## Documentation
+
+- [Use with AI agents](https://docs.videogen.io/use-with-ai-agents)
+- [MCP server](https://docs.videogen.io/libraries/mcp)
+- [API reference](https://docs.videogen.io)
+
+## License
+
+MIT
+
+## Account and permissions
+
+Generation and editing use your VideoGen account credits. Obtain user approval before invoking credit-consuming tools. Restrict the `include` list when an agent only needs read access. Keep API keys in server-side environment variables and out of shared transcripts.
+
+[VideoGen](https://videogen.io/) · [MCP setup](https://videogen.io/videogen-mcp) · [Source](https://github.com/video-gen/video-workflow-recipes/tree/main/integrations/pydantic-ai-videogen)

pydantic_ai_videogen-2.5.3/README.md

@@ -0,0 +1,95 @@
+# pydantic-ai-videogen
+
+Official [Pydantic AI](https://ai.pydantic.dev) tools for the [VideoGen API](https://docs.videogen.io). Give any Pydantic AI agent the ability to turn a script into a finished narrated video, plus generate standalone images, video clips, voiceovers, sound effects, music, and talking-head avatars.
+
+Every tool wraps the official [`videogen`](https://pypi.org/project/videogen/) SDK and runs as the team that owns your API key.
+
+## Install
+
+```bash
+pip install pydantic-ai-videogen
+```
+
+## Setup
+
+Get an API key from [app.videogen.io/api](https://app.videogen.io/api) and set it as `VIDEOGEN_API_KEY`:
+
+```bash
+export VIDEOGEN_API_KEY="your_api_key"
+```
+
+## Usage
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai_videogen import create_videogen_tools
+
+agent = Agent(
+    "openai:gpt-4o",
+    tools=create_videogen_tools(),
+    system_prompt="You produce short narrated videos with VideoGen when asked.",
+)
+
+result = agent.run_sync(
+    "Make a short narrated video explaining why staying hydrated matters."
+)
+print(result.output)
+```
+
+By default each tool blocks until the workflow or tool execution finishes and returns the completed result.
+
+## Options
+
+```python
+from videogen import VideoGen
+from pydantic_ai_videogen import create_videogen_tools
+
+tools = create_videogen_tools(
+    # Provide a pre-configured client, or pass api_key / base_url, or rely on env.
+    client=VideoGen(api_key="your_api_key"),
+
+    # Return the run/execution id immediately instead of waiting.
+    wait=False,
+
+    # Only expose a subset of tools to the model.
+    include=["script_to_video", "generate_image", "text_to_speech"],
+)
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `client` | — | A pre-configured `VideoGen` client. |
+| `api_key` | `VIDEOGEN_API_KEY` | API key used to build a client when `client` is omitted. |
+| `base_url` | `VIDEOGEN_BASE_URL` or production | Override the API base URL. |
+| `wait` | `True` | Block until the operation finishes and return the result. |
+| `poll_interval_ms` | SDK default | Poll interval while waiting. |
+| `timeout_ms` | SDK default | Maximum time to wait before giving up. |
+| `include` | all tools | Restrict the returned tool set to these tool names. |
+
+## Tools
+
+<!-- BEGIN GENERATED PYTHON AGENT TOOLS -->
+- Workflows: `cancel_workflow_run`, `get_workflow_run`, `list_workflow_runs`, `prompt_to_video_clip`, `script_to_video`, `slideshow_to_video`, `storyboard_to_video`, `video_to_video`, `voiceover_to_video`.
+- Media generation: `cancel_tool_execution`, `generate_avatar`, `generate_image`, `generate_motion_graphic`, `generate_music`, `generate_sound_effect`, `generate_video_clip`, `get_tool_execution`, `image_3d_effect`, `list_tool_executions`, `remove_image_background`, `remove_video_background`, `text_to_speech`, `upscale_image`, `upscale_video`, `vectorize_image`.
+- Projects: `export_project`, `get_project`, `list_project_remix_actions`, `list_projects`, `remix_project`.
+- Files: `get_file`, `list_files`, `upload_file`.
+- Resources and account: `get_me`, `list_languages`, `list_tts_voices`.
+
+Avatar generation and supported video workflows use reusable actor entities. Pass `actor_entity_id` and set `avatar_quality` to `LOW`, `STANDARD`, `HIGH`, or `MAX`. Narrator changes are passed in `remix_actions` as `CHANGE_NARRATOR` action dictionaries.
+<!-- END GENERATED PYTHON AGENT TOOLS -->
+
+## Documentation
+
+- [Use with AI agents](https://docs.videogen.io/use-with-ai-agents)
+- [MCP server](https://docs.videogen.io/libraries/mcp)
+- [API reference](https://docs.videogen.io)
+
+## License
+
+MIT
+
+## Account and permissions
+
+Generation and editing use your VideoGen account credits. Obtain user approval before invoking credit-consuming tools. Restrict the `include` list when an agent only needs read access. Keep API keys in server-side environment variables and out of shared transcripts.
+
+[VideoGen](https://videogen.io/) · [MCP setup](https://videogen.io/videogen-mcp) · [Source](https://github.com/video-gen/video-workflow-recipes/tree/main/integrations/pydantic-ai-videogen)

pydantic_ai_videogen-2.5.3/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pydantic-ai-videogen"
+version = "2.5.3"
+description = "Official Pydantic AI tools for the VideoGen API. Generate videos, images, voiceovers, sound effects, music, and avatars from any Pydantic AI agent."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = [
+    "videogen",
+    "pydantic-ai",
+    "pydantic",
+    "ai",
+    "agents",
+    "tools",
+    "text-to-video",
+    "ai-video-generation",
+    "text-to-speech",
+    "image-generation",
+]
+
+dependencies = [
+    "videogen>=2.5.3",
+    "pydantic-ai-slim>=0.0.30",
+    "pydantic>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://videogen.io"
+Documentation = "https://github.com/video-gen/video-workflow-recipes/tree/main/integrations/pydantic-ai-videogen#readme"
+Repository = "https://github.com/video-gen/video-workflow-recipes"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pydantic_ai_videogen"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0"]
+
+[tool.pytest.ini_options]
+markers = [
+    "integration: live tests that call the VideoGen API (require VIDEOGEN_API_KEY)",
+]
+testpaths = ["tests"]

pydantic_ai_videogen-2.5.3/src/pydantic_ai_videogen/__init__.py

@@ -0,0 +1,18 @@
+"""Official Pydantic AI tools for the VideoGen API."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .client import resolve_client
+from .factory import create_videogen_tools
+from .operations import Controls
+
+__all__ = [
+    "Controls",
+    "create_videogen_tools",
+    "resolve_client",
+]
+
+try:
+    __version__ = version("pydantic-ai-videogen")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

pydantic_ai_videogen-2.5.3/src/pydantic_ai_videogen/client.py

@@ -0,0 +1,47 @@
+# AUTO-GENERATED from api/integrations/python-agent-templates/client.py. DO NOT EDIT.
+"""Client resolution for the VideoGen Pydantic AI integration."""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from videogen import VideoGen
+
+_DEFAULT_BASE_URL = "https://api.videogen.io"
+
+
+def resolve_client(
+    client: Optional[VideoGen] = None,
+    *,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> VideoGen:
+    """Resolve a VideoGen client from an explicit client, an explicit key, or the environment.
+
+    Every tool call is authenticated as the team that owns the key.
+
+    Args:
+        client: A pre-configured ``VideoGen`` client. Used as-is when provided.
+        api_key: API key. Falls back to the ``VIDEOGEN_API_KEY`` environment variable.
+        base_url: API base URL. Falls back to ``VIDEOGEN_BASE_URL``, then production.
+    """
+    if client is not None:
+        return client
+
+    resolved_key = api_key or os.environ.get("VIDEOGEN_API_KEY")
+
+    if resolved_key is None or resolved_key.strip() == "":
+        raise ValueError(
+            "No VideoGen API key found. Pass `client` or `api_key`, or set the "
+            "VIDEOGEN_API_KEY environment variable. Create a key at "
+            "https://app.videogen.io/api."
+        )
+
+    resolved_base_url = base_url or os.environ.get("VIDEOGEN_BASE_URL") or _DEFAULT_BASE_URL
+
+    return VideoGen(
+        api_key=resolved_key.strip(),
+        base_url=resolved_base_url,
+        client_id="pydantic-ai",
+    )

pydantic_ai_videogen-2.5.3/src/pydantic_ai_videogen/factory.py

@@ -0,0 +1,47 @@
+"""Factory for the VideoGen Pydantic AI integration."""
+
+from __future__ import annotations
+
+from typing import Iterable, List, Optional
+
+from pydantic_ai import Tool
+
+from videogen import VideoGen
+
+from .client import resolve_client
+from .operations import Controls
+from .tools import build_videogen_tools
+
+
+def create_videogen_tools(
+    client: Optional[VideoGen] = None,
+    *,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    wait: bool = True,
+    poll_interval_ms: Optional[int] = None,
+    timeout_ms: Optional[int] = None,
+    include: Optional[Iterable[str]] = None,
+) -> List[Tool]:
+    """Build VideoGen tools in Pydantic AI format, ready to pass to any Pydantic AI ``Agent``.
+
+    Args:
+        client: A pre-configured ``VideoGen`` client. When omitted, one is built
+            from ``api_key`` / ``base_url`` or the ``VIDEOGEN_API_KEY`` environment variable.
+        wait: When True (default), tools block until the workflow run or tool execution
+            finishes and return the completed result. Set False to return immediately
+            with the run/execution id for the caller to poll.
+        poll_interval_ms: Poll interval while waiting. Defaults to the SDK's default.
+        timeout_ms: Maximum time to wait before giving up. Defaults to the SDK's default.
+        include: Restrict the returned tool set to these tool names. Defaults to all tools.
+    """
+    resolved_client = resolve_client(client, api_key=api_key, base_url=base_url)
+    controls = Controls(wait=wait, poll_interval_ms=poll_interval_ms, timeout_ms=timeout_ms)
+
+    tools = build_videogen_tools(resolved_client, controls)
+
+    if include is None:
+        return tools
+
+    included = set(include)
+    return [tool for tool in tools if tool.name in included]

pydantic_ai_videogen-2.5.3/src/pydantic_ai_videogen/operations.py

@@ -0,0 +1,88 @@
+# AUTO-GENERATED from api/integrations/python-agent-templates/operations.py. DO NOT EDIT.
+"""Shared helpers for starting and polling VideoGen operations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Optional
+
+from videogen import VideoGen
+from videogen.poll_executed_tool import poll_executed_tool
+from videogen.poll_project_export import poll_project_export
+from videogen.poll_workflow_run import poll_workflow_run
+
+
+@dataclass
+class Controls:
+    """How the tools handle asynchronous VideoGen operations."""
+
+    wait: bool = True
+    poll_interval_ms: Optional[int] = None
+    timeout_ms: Optional[int] = None
+
+
+def to_dict(obj: Any) -> Any:
+    """Convert an SDK response model into a plain, JSON-serializable structure."""
+    model_dump = getattr(obj, "model_dump", None)
+    if callable(model_dump):
+        return model_dump(mode="json")
+    return obj
+
+
+def drop_none(values: Dict[str, Any]) -> Dict[str, Any]:
+    """Drop ``None``-valued keys so the SDK applies its own defaults."""
+    return {key: value for key, value in values.items() if value is not None}
+
+
+def _poll_kwargs(controls: Controls) -> Dict[str, int]:
+    kwargs: Dict[str, int] = {}
+    if controls.poll_interval_ms is not None:
+        kwargs["poll_interval_ms"] = controls.poll_interval_ms
+    if controls.timeout_ms is not None:
+        kwargs["timeout_ms"] = controls.timeout_ms
+    return kwargs
+
+
+def run_workflow(
+    client: VideoGen,
+    controls: Controls,
+    start: Callable[[], Any],
+) -> Any:
+    """Start a workflow and, unless ``wait`` is False, poll it to a terminal state."""
+    started = start()
+    if not controls.wait:
+        return to_dict(started)
+
+    run = poll_workflow_run(client, started["workflowRunId"], **_poll_kwargs(controls))
+    return to_dict(run)
+
+
+def run_tool(
+    client: VideoGen,
+    controls: Controls,
+    start: Callable[[], Any],
+) -> Any:
+    """Start a media tool execution and, unless ``wait`` is False, poll it to a terminal state."""
+    started = start()
+    if not controls.wait:
+        return to_dict(started)
+
+    execution = poll_executed_tool(client, started["toolExecutionId"], **_poll_kwargs(controls))
+    return to_dict(execution)
+
+
+def run_export(
+    client: VideoGen,
+    controls: Controls,
+    project_id: str,
+    start: Callable[[], Any],
+) -> Any:
+    """Start a project export and, unless ``wait`` is False, poll until the download URL is ready."""
+    started = start()
+    if not controls.wait:
+        return to_dict(started)
+
+    project_export = poll_project_export(
+        client, project_id, started["exportId"], **_poll_kwargs(controls)
+    )
+    return to_dict(project_export)