flmkr 0.1.0__py3-none-any.whl

flmkr/__init__.py

@@ -0,0 +1,20 @@
+"""FLMKR — AI Filmmaking Harness."""
+
+from flmkr.exceptions import (
+    FLMKRError,
+    InvalidSpec,
+    ProviderError,
+    QARejection,
+    RetryExhausted,
+    StateConflict,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "FLMKRError",
+    "ProviderError",
+    "QARejection",
+    "StateConflict",
+    "RetryExhausted",
+    "InvalidSpec",
+]

flmkr/agents.py

@@ -0,0 +1,530 @@
+"""Abstract agent interface and concrete agent implementations for FLMKR."""
+
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+from flmkr.llm import LLMMessage, get_llm
+from flmkr.models import Bible, NarrFunction
+
+
+@dataclass
+class AgentTask:
+    """Input contract for any agent invocation."""
+
+    task_id: str
+    project_id: str
+    agent: str
+    objective: str
+    relevant_bible: dict[str, Any] = field(default_factory=dict)
+    context: dict[str, Any] = field(default_factory=dict)
+    constraints: dict[str, Any] = field(default_factory=dict)
+    dependencies: list[str] = field(default_factory=list)
+
+
+@dataclass
+class AgentResult:
+    """Output contract for any agent invocation."""
+
+    task_id: str
+    status: str  # "completed", "failed", "needs_review"
+    result: dict[str, Any] = field(default_factory=dict)
+    artifacts: list[str] = field(default_factory=list)
+    bible_delta: dict[str, Any] = field(default_factory=dict)
+    new_entities: list[dict[str, Any]] = field(default_factory=list)
+    risks: list[str] = field(default_factory=list)
+    questions: list[str] = field(default_factory=list)
+    recommendations: list[str] = field(default_factory=list)
+
+
+class BaseAgent(ABC):
+    """Abstract base for all FLMKR agents."""
+
+    name: str = "base"
+    identity: str = ""
+    capabilities: list[str] = []
+    bible_permissions: dict[str, str] = field(default_factory=dict)  # "read" / "write"
+    retry_policy: dict[str, Any] = field(default_factory=dict)
+
+    @abstractmethod
+    async def execute(self, task: AgentTask, bible: Bible) -> AgentResult:
+        """Execute the agent's task against the production bible."""
+        ...
+
+    def validate_output(self, result: AgentResult) -> bool:
+        """Validate agent output conforms to schema requirements."""
+        return bool(result.status and result.task_id)
+
+
+class ProducerAgent(BaseAgent):
+    """Top-level orchestrator agent — coordinates all other agents."""
+
+    name = "producer"
+    identity = "Producer / Director"
+    capabilities = [
+        "orchestrate",
+        "plan",
+        "approve",
+        "escalate",
+        "resume",
+        "recover",
+        "cost_track",
+        "runtime_budget",
+    ]
+    bible_permissions = {
+        "story": "read",
+        "characters": "read",
+        "world": "read",
+        "style": "read",
+        "shots": "read",
+        "assets": "read",
+        "decisions": "write",
+    }
+
+    async def execute(self, task: AgentTask, bible: Bible) -> AgentResult:
+        return AgentResult(
+            task_id=task.task_id,
+            status="completed",
+            result={"message": "Producer coordination complete"},
+        )
+
+
+class StoryAgent(BaseAgent):
+    """Responsible for screenplay normalization and scene creation."""
+
+    name = "story"
+    identity = "Story Agent"
+    capabilities = ["normalize", "screenplay", "scenes", "beats", "dialogue"]
+    bible_permissions = {
+        "story": "write",
+        "characters": "read",
+        "world": "read",
+    }
+
+    async def execute(self, task: AgentTask, bible: Bible) -> AgentResult:
+        return AgentResult(
+            task_id=task.task_id,
+            status="completed",
+            result={"message": "Story normalization complete"},
+            bible_delta={"story": {"title": bible.title, "logline": bible.logline}},
+        )
+
+
+class CharacterAgent(BaseAgent):
+    """Defines characters, visual identity, and continuity."""
+
+    name = "character"
+    identity = "Casting / Character Agent"
+    capabilities = ["define_character", "create_reference", "wardrobe", "arc"]
+    bible_permissions = {
+        "characters": "write",
+        "story": "read",
+        "style": "read",
+    }
+
+    async def execute(self, task: AgentTask, bible: Bible) -> AgentResult:
+        return AgentResult(
+            task_id=task.task_id,
+            status="completed",
+            result={"message": "Character definitions complete"},
+        )
+
+
+class CinematographyAgent(BaseAgent):
+    """Converts scenes to shot lists with camera language."""
+
+    name = "cinematography"
+    identity = "Cinematography / Blocking Agent"
+    capabilities = ["shot_plan", "framing", "camera_motion", "blocking", "lens"]
+    bible_permissions = {
+        "story": "read",
+        "characters": "read",
+        "locations": "read",
+        "style": "read",
+        "shots": "write",
+    }
+
+    async def execute(self, task: AgentTask, bible: Bible) -> AgentResult:
+        scene_description = task.objective or ""
+        context_chars = list(bible.characters.values())
+        context_locs = list(bible.locations.values())
+        existing_shots = bible.shot_ledger
+        scene_id = task.context.get("scene_id", "")
+        scene = bible.scenes.get(scene_id) if scene_id else None
+        scene_info = (
+            f"Scene {scene.id}: '{scene.title}' - {scene.synopsis} "
+            f"(target {scene.target_duration:.1f}s)"
+            if scene
+            else "Unassigned scene"
+        )
+
+        system_prompt = (
+            "You are a Cinematography Director planning shots for a film production.\n"
+            "Output a JSON array of shot objects. Each shot must have:\n"
+            "- id: format 'SXX_SHYY' (e.g. S01_SH01), auto-increment from existing shots\n"
+            "- scene_id: the scene this shot belongs to\n"
+            "- description: one-line visual description\n"
+            "- framing: wide | medium | close-up | extreme-close-up | two-shot\n"
+            "- duration: float in seconds (sum should respect target_duration when provided)\n"
+            "- camera_motion: static | pan | tilt | dolly | truck | zoom | handheld | crane | orbital\n"
+            "- lens: e.g. '35mm anamorphic', '85mm prime', '24mm wide'\n"
+            "- lighting: concise lighting description\n"
+            "- narrative_function: establish | reveal | conflict | response | transition | emotion | info | climax\n"
+            "- characters: list of character IDs present in this shot\n"
+            "- location_id: the location ID for this shot\n"
+            "Constraints:\n"
+            "- Be visually specific and cinematic.\n"
+            "- Match the style constraints in the scene synopsis and character descriptions.\n"
+            "- Do not repeat identical framings consecutively without a clear reason.\n"
+            "- Return ONLY valid JSON, no markdown fences."
+        )
+
+        chars_part = (
+            "; ".join(
+                f"{c.name}({c.id}) - {c.physical_description or c.consistency_token}"
+                for c in context_chars
+            )
+            or "(none defined)"
+        )
+        locs_part = (
+            "; ".join(f"{loc.name}({loc.id}) - {loc.description}" for loc in context_locs)
+            or "(none defined)"
+        )
+        existing_ids = "; ".join(s.id for s in existing_shots[-10:]) if existing_shots else "(none)"
+
+        user_prompt = (
+            f"Project: {bible.title}\n"
+            f"Logline: {bible.logline}\n"
+            f"Tone: {bible.tone} | Genre: {bible.genre}\n"
+            f"Target runtime: {bible.target_runtime}s\n"
+            f"Aspect ratio: {bible.style.aspect_ratio}\n"
+            f"Style guide: {bible.style.visual_language}\n"
+            f"{scene_info}\n"
+            f"Scene description / directive: {scene_description}\n"
+            f"Characters ({len(context_chars)}): {chars_part}\n"
+            f"Locations ({len(context_locs)}): {locs_part}\n"
+            f"Existing shots in ledger ({len(existing_shots)}): {existing_ids}\n"
+            "\nPlan the shots now."
+        )
+
+        llm = get_llm(provider="agnes")
+        messages = [
+            LLMMessage(role="system", content=system_prompt),
+            LLMMessage(role="user", content=user_prompt),
+        ]
+
+        try:
+            result_json = await llm.chat_json(
+                messages,
+                schema={"type": "array", "items": {"type": "object"}},
+            )
+            shots_data: list[dict[str, Any]] = result_json if isinstance(result_json, list) else []
+            if not shots_data:
+                shots_data = self._fallback_shot_plan(scene_description, bible, scene)
+
+            return AgentResult(
+                task_id=task.task_id,
+                status="completed",
+                result={"message": f"Shot plan complete - {len(shots_data)} shots generated"},
+                bible_delta={"shots": shots_data},
+            )
+        except Exception as exc:
+            fallback = self._fallback_shot_plan(scene_description, bible, scene)
+            return AgentResult(
+                task_id=task.task_id,
+                status="completed",
+                result={
+                    "message": f"Shot plan complete (LLM error: {exc}; used fallback)",
+                    "llm_error": str(exc),
+                },
+                bible_delta={"shots": fallback},
+                risks=[f"LLM unavailable during cinematography planning: {exc}"],
+            )
+
+    @staticmethod
+    def _fallback_shot_plan(
+        scene_desc: str, bible: Bible, scene: Any | None
+    ) -> list[dict[str, Any]]:
+        """Deterministic fallback when LLM is unavailable."""
+        target = scene.target_duration if scene else 10.0
+        scene_num = int(target // 5) + 1
+        base_id = f"S{scene_num:02d}"
+        shots: list[dict[str, Any]] = [
+            {
+                "id": f"{base_id}_SH01",
+                "scene_id": scene.id if scene else "S01",
+                "description": scene_desc[:80] if scene_desc else "Establishing shot",
+                "framing": "wide",
+                "duration": max(3.0, target * 0.3),
+                "camera_motion": "static",
+                "lens": "35mm anamorphic",
+                "lighting": bible.style.lighting or "neutral",
+                "narrative_function": NarrFunction.ESTABLISH.value,
+                "characters": [],
+                "location_id": "",
+            },
+            {
+                "id": f"{base_id}_SH02",
+                "scene_id": scene.id if scene else "S01",
+                "description": "Medium shot - action continues",
+                "framing": "medium",
+                "duration": max(3.0, target * 0.4),
+                "camera_motion": "dolly",
+                "lens": "50mm prime",
+                "lighting": bible.style.lighting or "neutral",
+                "narrative_function": NarrFunction.REVEAL.value,
+                "characters": [],
+                "location_id": "",
+            },
+            {
+                "id": f"{base_id}_SH03",
+                "scene_id": scene.id if scene else "S01",
+                "description": "Close-up - emotional beat",
+                "framing": "close-up",
+                "duration": max(3.0, target * 0.3),
+                "camera_motion": "static",
+                "lens": "85mm prime",
+                "lighting": bible.style.lighting or "neutral",
+                "narrative_function": NarrFunction.EMOTION.value,
+                "characters": [],
+                "location_id": "",
+            },
+        ]
+        return shots
+
+
+class ArtStyleAgent(BaseAgent):
+    """Defines visual identity, palette, lighting, production design."""
+
+    name = "art_style"
+    identity = "Art / Style Agent"
+    capabilities = ["visual_identity", "palette", "lighting", "production_design"]
+    bible_permissions = {
+        "style": "write",
+        "locations": "read",
+        "story": "read",
+    }
+
+    async def execute(self, task: AgentTask, bible: Bible) -> AgentResult:
+        existing_style = bible.style
+        style_override = task.context.get("style_override", {})
+        user_input = task.objective or ""
+
+        system_prompt = (
+            "You are a Cinematographer and Art Director defining the visual identity of a film.\n"
+            "Output a JSON object with these exact keys (all values are strings unless noted):\n"
+            "- visual_language: one-sentence description of the film's visual grammar\n"
+            "- cinematography: camera philosophy (movement, framing ethos, shot rhythm)\n"
+            "- lighting: signature lighting approach (palette, contrast ratio, source logic)\n"
+            "- color_palette: comma-separated hex colors or color names\n"
+            "- aspect_ratio: e.g. '2.39:1', '16:9', '4:3'\n"
+            "- lens_language: preferred lens choices and their narrative effect\n"
+            "- production_design: key art-direction pillars (sets, props, texture)\n"
+            "- recurring_motifs: 3-5 visual motifs that recur throughout the film\n"
+            "Be specific, cinematic, and actionable for a generation pipeline.\n"
+            "Return ONLY valid JSON, no markdown fences."
+        )
+
+        style_section = (
+            f"\nExisting style bible (override where needed):\n"
+            f"  visual_language: {existing_style.visual_language or '(empty)'}\n"
+            f"  cinematography: {existing_style.cinematography or '(empty)'}\n"
+            f"  lighting: {existing_style.lighting or '(empty)'}\n"
+            f"  color_palette: {existing_style.color_palette or '(empty)'}\n"
+            f"  aspect_ratio: {existing_style.aspect_ratio or '(empty)'}\n"
+            f"  lens_language: {existing_style.lens_language or '(empty)'}\n"
+            f"  production_design: {existing_style.production_design or '(empty)'}\n"
+            f"  recurring_motifs: {existing_style.recurring_motifs or '(empty)'}\n"
+        )
+        override_section = (
+            f"\nExplicit overrides from user context:\n{json.dumps(style_override, indent=2)}\n"
+            if style_override
+            else ""
+        )
+
+        user_prompt = (
+            f"Project: {bible.title}\n"
+            f"Logline: {bible.logline}\n"
+            f"Genre: {bible.genre} | Tone: {bible.tone}\n"
+            f"Target runtime: {bible.target_runtime}s\n"
+            f"User creative brief: {user_input}\n"
+            + style_section
+            + override_section
+            + "\nDefine the complete style bible now."
+        )
+
+        llm = get_llm(provider="agnes")
+        messages = [
+            LLMMessage(role="system", content=system_prompt),
+            LLMMessage(role="user", content=user_prompt),
+        ]
+
+        try:
+            result_json = await llm.chat_json(
+                messages,
+                schema={
+                    "type": "object",
+                    "properties": {
+                        "visual_language": {"type": "string"},
+                        "cinematography": {"type": "string"},
+                        "lighting": {"type": "string"},
+                        "color_palette": {"type": "array", "items": {"type": "string"}},
+                        "aspect_ratio": {"type": "string"},
+                    },
+                },
+            )
+
+            if isinstance(result_json, dict) and "_parse_error" not in result_json:
+                merged = self._merge_style(existing_style, result_json)
+                bible_delta = {"style": merged.model_dump()}
+            else:
+                merged = self._merge_style(existing_style, style_override)
+                bible_delta = {"style": merged.model_dump()}
+        except Exception as exc:
+            merged = self._merge_style(existing_style, style_override)
+            bible_delta = {"style": merged.model_dump()}
+            return AgentResult(
+                task_id=task.task_id,
+                status="completed",
+                result={
+                    "message": f"Style bible complete (LLM error: {exc}; used fallback)",
+                    "llm_error": str(exc),
+                },
+                bible_delta=bible_delta,
+                risks=[f"LLM unavailable during art-style planning: {exc}"],
+            )
+
+        return AgentResult(
+            task_id=task.task_id,
+            status="completed",
+            result={"message": "Style bible complete"},
+            bible_delta=bible_delta,
+        )
+
+    @staticmethod
+    def _merge_style(existing: Any, override: dict[str, Any]) -> Any:
+        """Deep-merge partial style dict into existing Style model."""
+        data = existing.model_dump() if hasattr(existing, "model_dump") else dict(existing)
+        for key, value in override.items():
+            if value not in (None, "", []) and key in data:
+                data[key] = value
+        return data
+
+
+class GenerationAgent(BaseAgent):
+    """Converts approved shot specs into provider generation jobs."""
+
+    name = "generation"
+    identity = "Generation Agent"
+    capabilities = ["image_gen", "video_gen", "audio_gen", "prompt_compile", "provider_select"]
+    bible_permissions = {
+        "style": "read",
+        "characters": "read",
+        "shots": "read",
+        "assets": "write",
+    }
+
+    async def execute(self, task: AgentTask, bible: Bible) -> AgentResult:
+        return AgentResult(
+            task_id=task.task_id,
+            status="completed",
+            result={"message": "Generation jobs submitted"},
+        )
+
+
+class QAAgent(BaseAgent):
+    """Quality assurance — checks assets against bible constraints."""
+
+    name = "qa"
+    identity = "QA / Continuity Agent"
+    capabilities = [
+        "technical_qa",
+        "visual_qa",
+        "character_qa",
+        "continuity_qa",
+        "narrative_qa",
+        "reject",
+        "approve",
+    ]
+    bible_permissions = {
+        "shots": "read",
+        "characters": "read",
+        "style": "read",
+        "assets": "read",
+    }
+
+    async def execute(self, task: AgentTask, bible: Bible) -> AgentResult:
+        return AgentResult(
+            task_id=task.task_id,
+            status="completed",
+            result={"message": "QA complete"},
+        )
+
+
+class EditorialAgent(BaseAgent):
+    """Assembles approved shots into scenes and sequences."""
+
+    name = "editorial"
+    identity = "Editorial Agent"
+    capabilities = ["assemble", "timeline", "pacing", "transitions"]
+    bible_permissions = {
+        "shots": "read",
+        "scenes": "write",
+        "assets": "read",
+    }
+
+    async def execute(self, task: AgentTask, bible: Bible) -> AgentResult:
+        return AgentResult(
+            task_id=task.task_id,
+            status="completed",
+            result={"message": "Editorial assembly complete"},
+        )
+
+
+class SoundAgent(BaseAgent):
+    """Handles dialogue, ambience, score, and audio continuity."""
+
+    name = "sound"
+    identity = "Sound Agent"
+    capabilities = ["dialogue", "ambience", " Foley", "score", "mix"]
+    bible_permissions = {
+        "sound": "write",
+        "scenes": "read",
+        "shots": "read",
+    }
+
+    async def execute(self, task: AgentTask, bible: Bible) -> AgentResult:
+        return AgentResult(
+            task_id=task.task_id,
+            status="completed",
+            result={"message": "Sound design complete"},
+        )
+
+
+# ─── Agent registry ──────────────────────────────────────────────────────────
+
+_AGENT_REGISTRY: dict[str, type[BaseAgent]] = {
+    "producer": ProducerAgent,
+    "story": StoryAgent,
+    "character": CharacterAgent,
+    "cinematography": CinematographyAgent,
+    "art_style": ArtStyleAgent,
+    "generation": GenerationAgent,
+    "qa": QAAgent,
+    "editorial": EditorialAgent,
+    "sound": SoundAgent,
+}
+
+
+def get_agent(name: str) -> BaseAgent:
+    cls = _AGENT_REGISTRY.get(name)
+    if cls is None:
+        raise ValueError(f"Unknown agent: {name}. Available: {list(_AGENT_REGISTRY.keys())}")
+    return cls()
+
+
+def list_agents() -> list[str]:
+    return list(_AGENT_REGISTRY.keys())