FIBO AutoDirector Agent

Transform structured data into cinematic, controllable visuals. AutoDirector uses FIBO’s JSON-native generation to create consistent, reproducible images at scale.

Comment

Inspiration

As a solo developer working on production image generation workflows, I was frustrated by the unpredictability of text-to-image AI. Every prompt run could produce different results, making it impossible to reproduce specific outputs or maintain consistency across batches. When I discovered Bria FIBO's JSON-native approach, I saw an opportunity to build something that production teams actually need: deterministic, reproducible, auditable image generation.

The core insight: instead of fighting with prompt engineering, what if every creative decision was an explicit, versioned JSON parameter? What if the same JSON always produced the same output? That's the foundation of FIBO AutoDirector Agent.

What it does

FIBO AutoDirector Agent transforms structured inputs (CSV files, storyboards, product specs) into deterministic, controllable visual outputs using Bria FIBO's JSON-native generation.

Key Features:

  • JSON-first architecture: No prompts, no randomness, no drift. Every parameter is explicit.
  • Deterministic reproducibility: Same JSON → same SHA256 hash → same output. Always.
  • Versioned creative decisions: Track every change with parent_hash lineage and JSON patch diffs.
  • Automated batch processing: Upload CSV → plan → render → review → export in one workflow.
  • Explainable generation: Every shot can explain how it was generated, what rules were applied, and why.

The Workflow:

  1. Ingest structured data (CSV with product info)
  2. Plan using agent-based rules to expand rows into FIBO-compliant JSON
  3. Render with async job queue and hash-based caching
  4. Review with approve/reject workflow and notes
  5. Rerender with JSON patches for iterative refinement
  6. Compare versions side-by-side to see exact parameter changes
  7. Export complete bundles with manifest, report, and images

Example Use Case: An e-commerce team uploads a CSV with 100 products. The system automatically generates consistent product shots with brand-aligned lighting, camera angles, and color palettes. If they need to adjust the FOV for all electronics, they patch the JSON and rerender. Every decision is tracked, every output is reproducible.

How I built it

Built as a solo developer over the hackathon period, focusing on production-ready architecture from day one.

Architecture:

  • FastAPI backend with async/await patterns for scalability
  • Provider abstraction (Mock for testing, Bria for production) with clean protocol-based design
  • Background worker with asyncio.Queue and configurable concurrency for batch processing
  • Deterministic hashing using SHA256 of normalized JSON for cache keys
  • Version management with parent_hash lineage tracking and JSON patch support
  • In-memory storage (dicts) for simplicity, with export to disk for persistence

Key Technical Decisions:

  1. JSON Normalization: Implemented custom normalize_json() that sorts keys and uses consistent formatting, ensuring the same logical JSON always produces the same hash.

  2. Provider Pattern: Created FiboProvider protocol so the system can work with mock data during development and switch to real Bria FIBO API with a single environment variable.

  3. Version Lineage: Each shot version stores parent_hash, enabling full audit trails. The /shots/{id}/compare endpoint shows exact parameter diffs between versions.

  4. Rules Engine: The expand_record_to_shot() function applies business logic (e.g., "if finish=glossy, reduce key light intensity") and tracks all rules in rules_applied for explainability.

  5. Async Job Queue: Built custom worker using asyncio.Queue and ThreadPoolExecutor to handle blocking FIBO API calls without blocking the event loop.

Integration with Bria FIBO:

  • Properly serializes FIBO structured_prompt format as JSON string
  • Handles multiple endpoint patterns with fallback logic
  • Supports both sync and async rendering modes
  • Includes real integration proof in docs/real-fibo-example/ with actual request/response

Code Structure:

apps/api/src/api/
  ├── main.py          # FastAPI app with health/metrics
  ├── routes.py        # All API endpoints
  ├── fibo_provider.py # Mock and Bria providers
  ├── rules.py         # CSV → FIBO JSON expansion
  ├── storage.py       # In-memory data management
  ├── worker.py        # Async render job processor
  ├── hashutil.py      # Deterministic JSON hashing
  └── models.py        # Pydantic request/response models

Challenges I ran into

1. Deterministic Hashing The biggest challenge was ensuring that semantically identical JSON always produced the same hash. Python dicts don't guarantee key order, and JSON serialization can vary. Solution: built normalize_json() that sorts keys and uses consistent separators.

2. Async Provider Integration Bria FIBO API calls are blocking HTTP requests, but I wanted non-blocking async endpoints. Solution: used ThreadPoolExecutor to run blocking calls in thread pool while keeping the FastAPI event loop responsive.

3. Version Comparison Comparing deeply nested JSON structures to show what changed between versions was tricky. Solution: recursive _compare_dicts() function that tracks paths and handles nested objects.

4. FIBO API Endpoint Discovery The exact FIBO endpoint format wasn't immediately clear from docs. Solution: implemented multiple endpoint fallback patterns and proper error handling to try different auth/endpoint combinations.

5. Solo Development Constraints Building a production-ready system alone meant making trade-offs. I focused on core workflow (ingest → plan → render → review → export) rather than building a UI, prioritizing API-first design that could integrate with existing tools.

Accomplishments that I am proud of

1. True Reproducibility The hash-based caching system ensures that re-rendering the same JSON returns the cached result instantly. This is the foundation of deterministic generation—something most AI image tools can't claim.

2. Complete Production Workflow Not just image generation, but a full pipeline: batch ingestion, planning, rendering, review, versioning, comparison, and export. This is what production teams actually need.

3. Explainability The /shots/{id}/explain endpoint shows exactly how each shot was generated: what rules were applied, what parameters were derived, and why. This transparency is crucial for enterprise adoption.

4. Real FIBO Integration Successfully integrated with live Bria FIBO API, with proof in docs/real-fibo-example/ showing actual request/response and generated images.

5. Clean Architecture As a solo developer, I prioritized maintainable code: protocol-based providers, clear separation of concerns, comprehensive error handling, and async patterns throughout.

6. Comprehensive Documentation Built complete documentation including architecture decisions, smoke tests with curl commands, and real-world examples—making it easy for judges and future users to understand and use.

What I learned

1. JSON-Native is the Future Working with FIBO's structured approach showed me that explicit parameters beat prompts for production workflows. The ability to version, patch, and reproduce outputs is transformative.

2. Deterministic Systems are Powerful The hash-based caching and versioning system proved that reproducibility isn't just nice-to-have—it's essential for enterprise adoption. Same input → same output is a game-changer.

3. Solo Development Forces Focus Building alone meant making hard choices. I focused on API-first design and core workflow rather than UI, which actually made the system more flexible and integrable.

4. Async Patterns Matter Using proper async/await with thread pools for blocking I/O kept the API responsive even during long FIBO API calls. This architecture scales.

5. Explainability Builds Trust The rules tracking and explain endpoints showed me that transparency in AI systems isn't just ethical—it's practical. Teams need to understand why outputs look the way they do.

6. Provider Abstraction is Essential The mock provider let me develop and test without API keys, while the Bria provider handles real production. This pattern should be standard.

What's next for FIBO AutoDirector Agent

Short-term:

  • Web UI: Build a React frontend for visual shot comparison and parameter editing
  • More Presets: Expand preset library with warm, vibrant, minimalist, and industry-specific styles
  • Database Backend: Replace in-memory storage with PostgreSQL for production persistence
  • HDR/16-bit Support: Add support for high dynamic range and 16-bit color space (mentioned in hackathon criteria)

Medium-term:

  • LLM Integration: Use FIBO's LLM translator to convert natural language requests into structured JSON
  • ControlNet Support: Integrate with FIBO's ControlNet for reference image-based generation
  • Batch Templates: Pre-built templates for common workflows (e-commerce, real estate, product photography)
  • API Rate Limiting: Add rate limiting and quota management for multi-tenant deployments

Long-term:

  • Multi-tenant SaaS: Deploy as a hosted service with user accounts and project management
  • ComfyUI Integration: Build ComfyUI nodes for visual workflow design
  • Nuke Integration: Professional tool integration for VFX pipelines
  • Enterprise Features: SSO, audit logs, compliance reporting, and SLA guarantees

Vision: FIBO AutoDirector Agent becomes the standard tool for production image generation workflows. Teams upload their data, define their brand parameters, and get consistent, reproducible, auditable outputs—no prompt engineering required.

Built with

Languages & Frameworks:

  • Python 3.10+
  • FastAPI (async web framework)
  • Pydantic (data validation)
  • Uvicorn (ASGI server)

APIs & Services:

  • Bria FIBO API (JSON-native image generation)
  • Requests (HTTP client for FIBO integration)

Libraries:

  • python-dotenv (environment configuration)
  • Pillow (image processing for mock provider)
  • asyncio (async job processing)

Architecture Patterns:

  • Protocol-based provider abstraction
  • Async/await with ThreadPoolExecutor
  • Deterministic hashing (SHA256)
  • Version management with parent_hash lineage
  • In-memory storage with disk export

Development Tools:

  • pyproject.toml (modern Python packaging)
  • Markdown documentation
  • curl-based smoke tests

Try it out

GitHub Repository: https://github.com/prabhakaran-jm/fibo-autodirector-agent

Quick Start:

# Clone the repo
git clone https://github.com/prabhakaran-jm/fibo-autodirector-agent
cd fibo-autodirector-agent

# Install dependencies
cd apps/api
pip install -e .

# Run the server
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

# Test it
curl http://localhost:8000/health

Example Workflow: See docs/smoke-test.md for complete curl-based examples, or check out docs/real-fibo-example/ for proof of live Bria FIBO integration.

Built With

  • async/await-patterns
  • asyncio
  • bria-fibo-api
  • deterministic-hashing-(sha256)
  • fastapi
  • parent-hash
  • pillow
  • protocol-based-provider-abstraction
  • pydantic
  • python-3.10+
  • python-dotenv
  • requests
  • uvicorn
Share this project:

Updates