ff-toolkit 0.1.0__tar.gz

ff_toolkit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

ff_toolkit-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+env/
+.env
+*.so
+.DS_Store
+Thumbs.db

ff_toolkit-0.1.0/LICENSE

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

ff_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: ff-toolkit
+Version: 0.1.0
+Summary: FFmpeg operations as LLM-callable tools — clip, merge, extract audio, add subtitles, transcode.
+Project-URL: Homepage, https://github.com/inthepond/ff-kit
+Project-URL: Repository, https://github.com/inthepond/ff-kit
+Project-URL: Issues, https://github.com/inthepond/ff-kit/issues
+Author-email: Dekko <dekko.etangs@outlook.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,audio,ffmpeg,llm,mcp,tool-calling,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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ff-kit
+
+FFmpeg operations as LLM-callable tools.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/inthepond/ff-kit/main/docs/demo.svg" alt="ff-kit demo" width="720">
+</p>
+
+> **Stop hand-writing FFmpeg subprocess calls and JSON tool schemas.**
+> `ff-kit` gives you 5 production-ready media operations, dual-format LLM schemas (OpenAI + Anthropic), and an MCP server — all in one `pip install`.
+
+## Real-World Use Cases
+
+**"My agent pipeline needs to process uploaded videos"** — Give your agent `openai_tools()` or `anthropic_tools()` and let it decide how to clip, transcode, or extract audio. The `dispatch()` function handles execution.
+
+**"I need to batch-extract 16kHz WAV for ASR"** — One line: `extract_audio("video.mp4", "out.wav", codec="pcm_s16le", sample_rate=16000, channels=1)`
+
+**"I want FFmpeg tools in Claude Desktop / Cursor"** — Add the MCP server config (3 lines of JSON) and Claude can edit your videos directly.
+
+**"I'm tired of writing the same FFmpeg commands"** — Use the CLI: `ffkit clip input.mp4 output.mp4 --start 00:01:00 --duration 30`
+
+## 60-Second Quick Start
+
+```bash
+# Install (requires FFmpeg on PATH)
+pip install ff-toolkit
+
+# Verify it works — no API keys needed
+ffkit probe some_video.mp4
+
+# Or run the full demo with a generated test video
+python -m ff_kit.examples.local
+```
+
+### Python API
+
+```python
+from ff_kit import clip, extract_audio, merge, transcode
+
+# Trim seconds 60-90
+clip("raw.mp4", "highlight.mp4", start="00:01:00", duration="30")
+
+# Extract 16kHz mono audio for Whisper/Paraformer
+extract_audio("raw.mp4", "speech.wav", codec="pcm_s16le", sample_rate=16000, channels=1)
+
+# Concatenate intro + main + outro
+merge(["intro.mp4", "main.mp4", "outro.mp4"], "final.mp4")
+
+# Compress to 720p WebM for web delivery
+transcode("raw.mp4", "web.webm", video_codec="libvpx-vp9", resolution="1280x720", crf=30)
+```
+
+### CLI
+
+```bash
+ffkit clip raw.mp4 highlight.mp4 --start 00:01:00 --duration 30
+ffkit extract-audio raw.mp4 speech.wav --codec pcm_s16le --sample-rate 16000 --channels 1
+ffkit merge intro.mp4 main.mp4 outro.mp4 -o final.mp4
+ffkit transcode raw.mp4 web.webm --video-codec libvpx-vp9 --resolution 1280x720 --crf 30
+ffkit probe video.mp4
+```
+
+### With OpenAI (3 lines to integrate)
+
+```python
+from ff_kit.schemas.openai import openai_tools
+from ff_kit.dispatch import dispatch
+
+# 1. Pass tools to the model
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=messages,
+    tools=openai_tools(),       # ← that's it
+)
+
+# 2. Execute whatever the model calls
+tc = response.choices[0].message.tool_calls[0]
+result = dispatch(tc.function.name, json.loads(tc.function.arguments))
+```
+
+### With Anthropic (3 lines to integrate)
+
+```python
+from ff_kit.schemas.anthropic import anthropic_tools
+from ff_kit.dispatch import dispatch
+
+response = client.messages.create(
+    model="claude-sonnet-4-20250514",
+    max_tokens=1024,
+    tools=anthropic_tools(),    # ← that's it
+    messages=messages,
+)
+
+for block in response.content:
+    if block.type == "tool_use":
+        result = dispatch(block.name, block.input)
+```
+
+### As an MCP Server (Claude Desktop / Cursor)
+
+Add to your config (`claude_desktop_config.json` or Cursor settings):
+
+```json
+{
+  "mcpServers": {
+    "ff-kit": {
+      "command": "ffkit-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+That's it. Claude can now clip, merge, extract audio, add subtitles, and transcode your files.
+
+## Operations
+
+| Tool | What it does | Example |
+|------|-------------|---------|
+| `ffkit_clip` | Trim a segment by start + end/duration | Cut highlight reel from raw footage |
+| `ffkit_merge` | Concatenate multiple files | Join intro + content + outro |
+| `ffkit_extract_audio` | Extract audio, optionally re-encode | Get 16kHz WAV for speech recognition |
+| `ffkit_add_subtitles` | Burn or embed subtitles (.srt/.ass/.vtt) | Hard-sub a translated SRT into video |
+| `ffkit_transcode` | Convert format, codec, resolution, bitrate | Compress 4K MP4 to 720p WebM for web |
+
+## How It Works
+
+```
+Your Agent                    ff-kit                         FFmpeg
+    │                           │                              │
+    ├─ openai_tools() ──────────┤                              │
+    │  or anthropic_tools()     │                              │
+    │                           │                              │
+    ├─ LLM returns tool call ──►│                              │
+    │                           │                              │
+    ├─ dispatch(name, args) ───►├─ validates & builds cmd ────►│
+    │                           │                              │
+    │◄── FFmpegResult ─────────┤◄── subprocess result ────────┤
+    │                           │                              │
+```
+
+## Project Structure
+
+```
+ff-kit/
+├── src/ff_kit/
+│   ├── __init__.py          # Public API: clip, merge, extract_audio, ...
+│   ├── cli.py               # CLI entry point (ffkit command)
+│   ├── executor.py          # FFmpeg subprocess runner + probe
+│   ├── dispatch.py          # Tool name → function router
+│   ├── core/                # One module per operation
+│   │   ├── clip.py
+│   │   ├── merge.py
+│   │   ├── extract_audio.py
+│   │   ├── add_subtitles.py
+│   │   └── transcode.py
+│   ├── schemas/             # LLM tool definitions
+│   │   ├── openai.py        # OpenAI function-calling format
+│   │   └── anthropic.py     # Anthropic tool-use format
+│   └── mcp/                 # MCP server (stdio JSON-RPC)
+│       └── server.py
+├── examples/
+│   ├── local_example.py     # ← Run this first! No API key needed
+│   ├── openai_example.py
+│   ├── anthropic_example.py
+│   └── agent_loop_example.py
+└── tests/                   # 30 tests, all mocked (no FFmpeg needed)
+```
+
+## Development
+
+```bash
+git clone https://github.com/inthepond/ff-kit.git
+cd ff-kit
+pip install -e ".[dev]"
+pytest -v                    # 30 tests, runs in <1s
+```
+
+## FAQ
+
+**Q: Do I need FFmpeg installed?**
+Yes, for actual media operations. Tests are fully mocked and don't need FFmpeg. Install it from [ffmpeg.org/download](https://ffmpeg.org/download.html) or `brew install ffmpeg` / `apt install ffmpeg`.
+
+**Q: Can I add custom operations?**
+Yes — add a function in `core/`, register it in `dispatch.py`'s `_REGISTRY`, and add schema entries in `schemas/openai.py` and `schemas/anthropic.py`. See any existing operation as a template.
+
+**Q: Why not just use LangChain / CrewAI tools?**
+Those frameworks are great, but they're heavy dependencies. ff-kit is zero-dependency (beyond Python stdlib) and works with any LLM provider. You can use it inside LangChain if you want, or standalone.
+
+**Q: What about streaming / progress callbacks?**
+Not in v0.1. FFmpeg progress parsing is planned for v0.2.
+
+## License
+
+MIT

ff_toolkit-0.1.0/README.md

@@ -0,0 +1,195 @@
+# ff-kit
+
+FFmpeg operations as LLM-callable tools.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/inthepond/ff-kit/main/docs/demo.svg" alt="ff-kit demo" width="720">
+</p>
+
+> **Stop hand-writing FFmpeg subprocess calls and JSON tool schemas.**
+> `ff-kit` gives you 5 production-ready media operations, dual-format LLM schemas (OpenAI + Anthropic), and an MCP server — all in one `pip install`.
+
+## Real-World Use Cases
+
+**"My agent pipeline needs to process uploaded videos"** — Give your agent `openai_tools()` or `anthropic_tools()` and let it decide how to clip, transcode, or extract audio. The `dispatch()` function handles execution.
+
+**"I need to batch-extract 16kHz WAV for ASR"** — One line: `extract_audio("video.mp4", "out.wav", codec="pcm_s16le", sample_rate=16000, channels=1)`
+
+**"I want FFmpeg tools in Claude Desktop / Cursor"** — Add the MCP server config (3 lines of JSON) and Claude can edit your videos directly.
+
+**"I'm tired of writing the same FFmpeg commands"** — Use the CLI: `ffkit clip input.mp4 output.mp4 --start 00:01:00 --duration 30`
+
+## 60-Second Quick Start
+
+```bash
+# Install (requires FFmpeg on PATH)
+pip install ff-toolkit
+
+# Verify it works — no API keys needed
+ffkit probe some_video.mp4
+
+# Or run the full demo with a generated test video
+python -m ff_kit.examples.local
+```
+
+### Python API
+
+```python
+from ff_kit import clip, extract_audio, merge, transcode
+
+# Trim seconds 60-90
+clip("raw.mp4", "highlight.mp4", start="00:01:00", duration="30")
+
+# Extract 16kHz mono audio for Whisper/Paraformer
+extract_audio("raw.mp4", "speech.wav", codec="pcm_s16le", sample_rate=16000, channels=1)
+
+# Concatenate intro + main + outro
+merge(["intro.mp4", "main.mp4", "outro.mp4"], "final.mp4")
+
+# Compress to 720p WebM for web delivery
+transcode("raw.mp4", "web.webm", video_codec="libvpx-vp9", resolution="1280x720", crf=30)
+```
+
+### CLI
+
+```bash
+ffkit clip raw.mp4 highlight.mp4 --start 00:01:00 --duration 30
+ffkit extract-audio raw.mp4 speech.wav --codec pcm_s16le --sample-rate 16000 --channels 1
+ffkit merge intro.mp4 main.mp4 outro.mp4 -o final.mp4
+ffkit transcode raw.mp4 web.webm --video-codec libvpx-vp9 --resolution 1280x720 --crf 30
+ffkit probe video.mp4
+```
+
+### With OpenAI (3 lines to integrate)
+
+```python
+from ff_kit.schemas.openai import openai_tools
+from ff_kit.dispatch import dispatch
+
+# 1. Pass tools to the model
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=messages,
+    tools=openai_tools(),       # ← that's it
+)
+
+# 2. Execute whatever the model calls
+tc = response.choices[0].message.tool_calls[0]
+result = dispatch(tc.function.name, json.loads(tc.function.arguments))
+```
+
+### With Anthropic (3 lines to integrate)
+
+```python
+from ff_kit.schemas.anthropic import anthropic_tools
+from ff_kit.dispatch import dispatch
+
+response = client.messages.create(
+    model="claude-sonnet-4-20250514",
+    max_tokens=1024,
+    tools=anthropic_tools(),    # ← that's it
+    messages=messages,
+)
+
+for block in response.content:
+    if block.type == "tool_use":
+        result = dispatch(block.name, block.input)
+```
+
+### As an MCP Server (Claude Desktop / Cursor)
+
+Add to your config (`claude_desktop_config.json` or Cursor settings):
+
+```json
+{
+  "mcpServers": {
+    "ff-kit": {
+      "command": "ffkit-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+That's it. Claude can now clip, merge, extract audio, add subtitles, and transcode your files.
+
+## Operations
+
+| Tool | What it does | Example |
+|------|-------------|---------|
+| `ffkit_clip` | Trim a segment by start + end/duration | Cut highlight reel from raw footage |
+| `ffkit_merge` | Concatenate multiple files | Join intro + content + outro |
+| `ffkit_extract_audio` | Extract audio, optionally re-encode | Get 16kHz WAV for speech recognition |
+| `ffkit_add_subtitles` | Burn or embed subtitles (.srt/.ass/.vtt) | Hard-sub a translated SRT into video |
+| `ffkit_transcode` | Convert format, codec, resolution, bitrate | Compress 4K MP4 to 720p WebM for web |
+
+## How It Works
+
+```
+Your Agent                    ff-kit                         FFmpeg
+    │                           │                              │
+    ├─ openai_tools() ──────────┤                              │
+    │  or anthropic_tools()     │                              │
+    │                           │                              │
+    ├─ LLM returns tool call ──►│                              │
+    │                           │                              │
+    ├─ dispatch(name, args) ───►├─ validates & builds cmd ────►│
+    │                           │                              │
+    │◄── FFmpegResult ─────────┤◄── subprocess result ────────┤
+    │                           │                              │
+```
+
+## Project Structure
+
+```
+ff-kit/
+├── src/ff_kit/
+│   ├── __init__.py          # Public API: clip, merge, extract_audio, ...
+│   ├── cli.py               # CLI entry point (ffkit command)
+│   ├── executor.py          # FFmpeg subprocess runner + probe
+│   ├── dispatch.py          # Tool name → function router
+│   ├── core/                # One module per operation
+│   │   ├── clip.py
+│   │   ├── merge.py
+│   │   ├── extract_audio.py
+│   │   ├── add_subtitles.py
+│   │   └── transcode.py
+│   ├── schemas/             # LLM tool definitions
+│   │   ├── openai.py        # OpenAI function-calling format
+│   │   └── anthropic.py     # Anthropic tool-use format
+│   └── mcp/                 # MCP server (stdio JSON-RPC)
+│       └── server.py
+├── examples/
+│   ├── local_example.py     # ← Run this first! No API key needed
+│   ├── openai_example.py
+│   ├── anthropic_example.py
+│   └── agent_loop_example.py
+└── tests/                   # 30 tests, all mocked (no FFmpeg needed)
+```
+
+## Development
+
+```bash
+git clone https://github.com/inthepond/ff-kit.git
+cd ff-kit
+pip install -e ".[dev]"
+pytest -v                    # 30 tests, runs in <1s
+```
+
+## FAQ
+
+**Q: Do I need FFmpeg installed?**
+Yes, for actual media operations. Tests are fully mocked and don't need FFmpeg. Install it from [ffmpeg.org/download](https://ffmpeg.org/download.html) or `brew install ffmpeg` / `apt install ffmpeg`.
+
+**Q: Can I add custom operations?**
+Yes — add a function in `core/`, register it in `dispatch.py`'s `_REGISTRY`, and add schema entries in `schemas/openai.py` and `schemas/anthropic.py`. See any existing operation as a template.
+
+**Q: Why not just use LangChain / CrewAI tools?**
+Those frameworks are great, but they're heavy dependencies. ff-kit is zero-dependency (beyond Python stdlib) and works with any LLM provider. You can use it inside LangChain if you want, or standalone.
+
+**Q: What about streaming / progress callbacks?**
+Not in v0.1. FFmpeg progress parsing is planned for v0.2.
+
+## License
+
+MIT

ff_toolkit-0.1.0/docs/demo.svg

@@ -0,0 +1,113 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="720" height="460">
+  <defs>
+    <style>
+      text { font-family: 'SFMono-Regular', 'SF Mono', 'Menlo', 'Consolas', 'Liberation Mono', monospace; font-size: 13px; }
+    </style>
+  </defs>
+
+  <!-- Terminal window background -->
+  <rect fill="#1e1e2e" width="720" height="460" rx="10" />
+  <rect fill="#313244" width="720" height="32" rx="10" />
+  <rect fill="#313244" width="720" height="16" y="16" />
+  <circle fill="#f38ba8" cx="20" cy="16" r="6" />
+  <circle fill="#f9e2af" cx="40" cy="16" r="6" />
+  <circle fill="#a6e3a1" cx="60" cy="16" r="6" />
+  <text x="320" y="21" text-anchor="middle" fill="#a6adc8" font-size="12">ff-kit demo</text>
+
+  <!-- Line 1: install command -->
+  <g opacity="0">
+    <set attributeName="opacity" to="1" begin="0.5s" fill="freeze" />
+    <text fill="#89b4fa" x="16" y="60">$</text>
+    <text fill="#cdd6f4" x="30" y="60">pip install ff-toolkit</text>
+  </g>
+
+  <!-- Line 2: install success -->
+  <g opacity="0">
+    <set attributeName="opacity" to="1" begin="1.0s" fill="freeze" />
+    <text fill="#a6e3a1" x="16" y="80">Successfully installed ff-toolkit-0.1.0</text>
+  </g>
+
+  <!-- Line 3: comment -->
+  <g opacity="0">
+    <set attributeName="opacity" to="1" begin="1.5s" fill="freeze" />
+    <text fill="#6c7086" x="16" y="108"># Clip the first 30 seconds from a video</text>
+  </g>
+
+  <!-- Line 4: clip command -->
+  <g opacity="0">
+    <set attributeName="opacity" to="1" begin="2.2s" fill="freeze" />
+    <text fill="#89b4fa" x="16" y="128">$</text>
+    <text fill="#cdd6f4" x="30" y="128">ffkit clip raw.mp4 intro.mp4 --start 0 --duration 30</text>
+  </g>
+
+  <!-- Line 5: clip output -->
+  <g opacity="0">
+    <set attributeName="opacity" to="1" begin="2.7s" fill="freeze" />
+    <text fill="#a6e3a1" x="16" y="148">Done: intro.mp4</text>
+  </g>
+
+  <!-- Line 6: comment -->
+  <g opacity="0">
+    <set attributeName="opacity" to="1" begin="3.2s" fill="freeze" />
+    <text fill="#6c7086" x="16" y="176"># Extract 16kHz mono WAV for Whisper/Paraformer</text>
+  </g>
+
+  <!-- Line 7: extract command -->
+  <g opacity="0">
+    <set attributeName="opacity" to="1" begin="3.5s" fill="freeze" />
+    <text fill="#89b4fa" x="16" y="196">$</text>
+    <text fill="#cdd6f4" x="30" y="196">ffkit extract-audio raw.mp4 speech.wav --codec pcm_s16le --sample-rate 16000</text>
+  </g>
+
+  <!-- Line 8: extract output -->
+  <g opacity="0">
+    <set attributeName="opacity" to="1" begin="4.2s" fill="freeze" />
+    <text fill="#a6e3a1" x="16" y="216">Done: speech.wav</text>
+  </g>
+
+  <!-- Line 9: comment -->
+  <g opacity="0">
+    <set attributeName="opacity" to="1" begin="4.7s" fill="freeze" />
+    <text fill="#6c7086" x="16" y="244"># Print tool schemas for your LLM agent</text>
+  </g>
+
+  <!-- Line 10: list-tools command -->
+  <g opacity="0">
+    <set attributeName="opacity" to="1" begin="5.2s" fill="freeze" />
+    <text fill="#89b4fa" x="16" y="264">$</text>
+    <text fill="#cdd6f4" x="30" y="264">ffkit list-tools --format openai | head -8</text>
+  </g>
+
+  <!-- JSON output lines -->
+  <g opacity="0">
+    <set attributeName="opacity" to="1" begin="5.5s" fill="freeze" />
+    <text fill="#a6adc8" x="16" y="284">[{</text>
+  </g>
+  <g opacity="0">
+    <set attributeName="opacity" to="1" begin="5.7s" fill="freeze" />
+    <text fill="#a6adc8" x="16" y="304">  "type": "function",</text>
+  </g>
+  <g opacity="0">
+    <set attributeName="opacity" to="1" begin="5.9s" fill="freeze" />
+    <text fill="#a6adc8" x="16" y="324">  "function": {</text>
+  </g>
+  <g opacity="0">
+    <set attributeName="opacity" to="1" begin="6.1s" fill="freeze" />
+    <text fill="#a6adc8" x="16" y="344">    "name": </text>
+    <text fill="#f9e2af" x="118" y="344">"ffkit_clip"</text>
+    <text fill="#a6adc8" x="210" y="344">,</text>
+  </g>
+  <g opacity="0">
+    <set attributeName="opacity" to="1" begin="6.3s" fill="freeze" />
+    <text fill="#a6adc8" x="16" y="364">    "description": "Trim a segment from a media file..."</text>
+  </g>
+
+  <!-- Final prompt with blinking cursor -->
+  <g opacity="0">
+    <set attributeName="opacity" to="1" begin="7.0s" fill="freeze" />
+    <text fill="#89b4fa" x="16" y="400">$</text>
+    <rect fill="#cdd6f4" x="30" y="389" width="8" height="16">
+      <animate attributeName="opacity" values="1;0;1" dur="1s" repeatCount="indefinite" begin="7.0s" />
+    </rect>
+  </g>
+</svg>

ff_toolkit-0.1.0/examples/agent_loop_example.py

@@ -0,0 +1,84 @@
+"""
+Example: a minimal agent loop with ff-kit — no framework needed.
+
+This shows how to build a simple tool-calling loop using ff-kit's
+dispatch() and schema system. Works with OpenAI, but the pattern
+is the same for any provider.
+
+    export OPENAI_API_KEY=sk-...
+    python examples/agent_loop_example.py
+"""
+
+from __future__ import annotations
+
+import json
+from openai import OpenAI
+from ff_kit.schemas.openai import openai_tools
+from ff_kit.dispatch import dispatch
+
+client = OpenAI()
+tools = openai_tools()
+
+SYSTEM = (
+    "You are a video editing assistant. You have access to ffkit tools "
+    "for clipping, merging, extracting audio, adding subtitles, and "
+    "transcoding media files. When the user asks for a media operation, "
+    "call the appropriate tool. You can chain multiple tools for complex "
+    "workflows (e.g., extract audio then transcode it)."
+)
+
+
+def run_agent(user_message: str, max_turns: int = 5) -> str:
+    """
+    Run a simple tool-calling agent loop.
+
+    The LLM can call multiple tools across multiple turns.
+    Returns the final text response.
+    """
+    messages = [
+        {"role": "system", "content": SYSTEM},
+        {"role": "user", "content": user_message},
+    ]
+
+    for turn in range(max_turns):
+        response = client.chat.completions.create(
+            model="gpt-4o",
+            messages=messages,
+            tools=tools,
+        )
+        msg = response.choices[0].message
+
+        # If no tool calls, we're done
+        if not msg.tool_calls:
+            return msg.content or ""
+
+        # Execute each tool call
+        messages.append(msg.model_dump())
+        for tc in msg.tool_calls:
+            print(f"  [Turn {turn + 1}] Calling {tc.function.name}...")
+            args = json.loads(tc.function.arguments)
+            result = dispatch(tc.function.name, args)
+            print(f"  [Turn {turn + 1}] Result: {result['status']}")
+
+            messages.append({
+                "role": "tool",
+                "tool_call_id": tc.id,
+                "content": json.dumps(result),
+            })
+
+    return "Agent reached max turns without a final response."
+
+
+if __name__ == "__main__":
+    # Try some real-world prompts:
+    prompts = [
+        "Extract the audio from meeting.mp4 as a 16kHz mono WAV file for transcription.",
+        "Clip the first 60 seconds of raw_footage.mp4 and transcode it to 720p WebM.",
+        "Merge intro.mp4, main.mp4, and outro.mp4 into final_video.mp4",
+    ]
+
+    for prompt in prompts:
+        print(f"\nUser: {prompt}")
+        print("-" * 60)
+        answer = run_agent(prompt)
+        print(f"Assistant: {answer}\n")