Metadata-Version: 2.5
Name: flmkr
Version: 0.1.4
Summary: AI Filmmaking Harness — an autonomous, terminal-native agent for planning, generating, validating, editing, and completing films.
Project-URL: Homepage, https://github.com/dreampixelsforge/flmkr
Project-URL: Repository, https://github.com/dreampixelsforge/flmkr
Project-URL: Documentation, https://flmkr.dreampixelsforge.com
Project-URL: Issues, https://github.com/dreampixelsforge/flmkr/issues
Author: Dream Pixels Forge
License-Expression: MIT
Keywords: agent,ai,cli,film,production,video
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.10
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: cattrs>=24.1
Requires-Dist: click>=8.1.7
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0
Requires-Dist: orjson>=3.10
Requires-Dist: pathspec>=0.12
Requires-Dist: pydantic-settings>=2.5
Requires-Dist: pydantic>=2.8
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.9
Requires-Dist: sqlalchemy>=2.0.36
Requires-Dist: structlog>=24.4
Requires-Dist: tenacity>=9.0
Requires-Dist: uuid-utils>=0.9
Requires-Dist: watchdog>=5.0
Provides-Extra: dev
Requires-Dist: bandit>=1.7; extra == 'dev'
Requires-Dist: coverage[toml]>=7.6; extra == 'dev'
Requires-Dist: freezegun>=1.5; extra == 'dev'
Requires-Dist: hypothesis>=6.120; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: redis
Requires-Dist: arq>=0.26; extra == 'redis'
Requires-Dist: redis>=5.2; extra == 'redis'
Provides-Extra: ui
Requires-Dist: textual>=1.0; extra == 'ui'
Description-Content-Type: text/markdown

# FLMKR — AI Filmmaking Harness

An autonomous, terminal-native AI filmmaking agent that transforms creative ideas into complete audiovisual productions.

## What It Is

FLMKR is an **agent harness for filmmaking** — not a video generator, not a prompt engine, not a GUI wrapper. It's the environment that allows an autonomous agent to perform complex filmmaking work:

- Plan productions from ideas, screenplays, or treatments
- Create and maintain a Production Bible (characters, locations, style, continuity)
- Generate shots through provider-agnostic adapters (Agnes, Kling, MiniMax, Runway)
- Run QA at chunk/shot/scene levels with continuity checking
- Recover from failures without restarting the entire production
- Render final films with editorial assembly

## Install

```bash
pip install flmkr
```

Development install (with test & lint tooling):

```bash
pip install -e ".[dev]"
```

Verify:

```bash
flmkr --version
# flmkr, version 0.1.0
```

## Quickstart

```bash
# Create a new film project from an idea
flmkr create "A woman discovers her autonomous car is taking her somewhere she never asked to go."

# Inspect the auto-generated Production Bible
flmkr bible

# Dry-run the production plan (estimates shots, cost, runtime)
flmkr plan

# Generate all assets
flmkr generate

# View progress
flmkr status
flmkr shots
flmkr events

# Open the interactive TUI to review and approve shots
flmkr review

# Render the final assembled film
flmkr render

# Resume after an interruption
flmkr resume
```

See [docs/getting-started.md](docs/getting-started.md) for a full 5-minute tutorial.

## MCP Usage

FLMKR exposes an MCP server for integration with AI coding agents (Claude Code, Codex CLI, MiMoCode, etc.):

```bash
python -m flmkr.mcp_server --project ./my-film
```

Available tools:

| Tool | Description |
|------|-------------|
| `flmkr_status` | Get current production status |
| `flmkr_list_scenes` | List scenes with status and runtime |
| `flmkr_list_shots` | List shots in a scene |
| `flmkr_generate_shot` | Generate video for a shot |
| `flmkr_run_qa` | Run quality assurance on assets |
| `flmkr_get_bible` | Read the Production Bible |
| `flmkr_plan` | Dry-run production plan |
| `flmkr_create` | Create a new film project |
| `flmkr_resume` | Resume an interrupted production |
| `flmkr_render` | Render the final film |
| `flmkr_cost` | Show cost breakdown |

## Architecture

```
┌──────────────────────────────────────────────────────┐
│                    CLI / TUI                         │
│              (click / textual)                       │
└───────────────────────┬──────────────────────────────┘
                        │
┌───────────────────────▼──────────────────────────────┐
│              Producer Orchestrator                     │
│         (flmkr.orchestrator.Orchestrator)              │
│                                                        │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐     │
│  │   Story    │  │ Character  │  │Cinematog-  │     │
│  │   Agent    │  │   Agent    │  │   raphy    │     │
│  └────────────┘  └────────────┘  └────────────┘     │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐     │
│  │ Generation │  │    QA      │  │ Editorial  │     │
│  │   Agent    │  │   Agent    │  │   Agent    │     │
│  └────────────┘  └────────────┘  └────────────┘     │
└───────────────────────┬──────────────────────────────┘
                        │
┌───────────────────────▼──────────────────────────────┐
│              Provider Adapters                       │
│   (Agnes · Kling · MiniMax · Runway · custom)        │
└───────────────────────┬──────────────────────────────┘
                        │
┌───────────────────────▼──────────────────────────────┐
│              Production Bible                        │
│   (Bible → Characters · Locations · Style · Scenes)  │
└───────────────────────┬──────────────────────────────┘
                        │
┌───────────────────────▼──────────────────────────────┐
│              Event Store                             │
│        (SQLite — durable, resumable)                 │
└──────────────────────────────────────────────────────┘
```

### Data Flow

```
Idea / Screenplay
       ↓
  Project.init()
       ↓
  Bible generation (story, characters, locations, style)
       ↓
  Scene & shot planning
       ↓
  Generation (provider-agnostic, with retry & recovery)
       ↓
  QA (continuity, narrative, technical)
       ↓
  Editorial assembly
       ↓
  Final film render
```

## Project Structure

```
flmkr/
├── __init__.py      # Package entry
├── cli.py           # Click CLI commands
├── config.py        # Pydantic settings
├── models.py        # Core data models (Bible, Shot, Scene, etc.)
├── agents.py        # Agent framework
├── providers.py     # Provider adapters
├── orchestrator.py  # Producer/Orchestrator
├── qa.py            # QA engine
├── editorial.py     # Editorial/timeline engine
├── project.py       # Project state container
├── event_store.py   # SQLite event log
├── events.py        # Event types
├── exceptions.py    # Error types
├── llm.py           # LLM interaction layer
├── mcp_server.py    # MCP server for AI agent integration
└── tui.py           # Rich terminal UI
```

## Examples

| Example | Description |
|---------|-------------|
| [`examples/basic_film/bible.yaml`](examples/basic_film/bible.yaml) | Minimal production bible — characters, locations, style |
| [`examples/shot_list/screenplay.md`](examples/shot_list/screenplay.md) | Screenplay-to-shots workflow with annotated shot list |

## Requirements

- Python 3.11+
- SQLite (bundled with Python)
- Internet connection for provider APIs

## License

MIT
