Fable Lab ADK (Agent Development Kit)

This repository contains the intelligent backend for Fable Lab, powered by Google ADK (Agent Development Kit) and Gemini 2.0 Flash Native Audio. It hosts specialized AI agents that drive the platform's content generation and real-time interaction capabilities.

🧠 Agents

This project defines two primary agent systems:

1. 📚 fable_agent_p5 (Multi-Agent Generators)

A sophisticated pipeline designed to generating high-quality, structured educational content. It uses a Teacher-Researcher-Designer workflow.

Architecture:

• Orchestrator: Parses user intent (Topic, Age Group, Scene Count) and coordinates the workflow.
• Librarian: Structures the lesson plan and pedagogy.
• Parallel Workers:
  • Plotter: Writes the narrative story, defines characters, and generates consistent image prompts.
  • ExperimentPipeline: A 5-step sub-chain to build p5.js simulations:
    1. Researcher: Reads p5.js documentation to find the best functions.
    2. ExperimentDesigner: Plans the interaction flow (Observe -> Explore -> Test).
    3. InteractionDesigner: Layouts the UI controls.
    4. CodeGenerator: Writes the actual p5.js code.
    5. Assembler: packages everything.
• Finisher: Validates output and signals completion to the frontend.

2. ⚡ playground_agent (Real-Time Voice)

A high-speed, single-agent system optimized for the Gemini Multimodal Live API.

• Purpose: Enabling the "Voice Coding Playground" where users talk to build apps.
• Capabilities:
  • Bidi-streaming (Native Audio in/out).
  • Real-time tool calling (create_experiment, evolve_experiment).
  • <100ms latency for conversational coding.

🛠️ Tech Stack

• Language: Python 3.10+
• Framework: Google ADK (Agent Development Kit)
• Models: Gemini 2.0 Flash (Preview & Live)
• Server: FastAPI / Uvicorn (for standard endpoints) & WebSockets (for Live API)

🚀 Getting Started

Prerequisites

• Python 3.10 or higher
• A Google Cloud Project with Gemini API access

Installation

1. Navigate to the directory:

   cd fable-lab-adk

2. Create a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Environment Setup: Create a .env file with your Google Cloud credentials and ADK configuration.

   GOOGLE_API_KEY=your_key_here
   GOOGLE_CLOUD_PROJECT=your_project_id

Running the Agents

You can run the agents using the ADK CLI or directly via Python.

Run the Playground Agent (Live API):

# Serves the agent on port 8000/websocket
python main.py

Run the Generation Agent (Workflow):

# Typically triggered via API, but can be tested with ADK CLI
adk run fable_agent_p5

📂 Project Structure

fable-lab-adk/
├── fable_agent_p5/       # Multi-agent generation pipeline
│   ├── agent.py          # Workflow definitions
│   ├── prompts/          # System instructions & p5.js docs
│   └── tools/            # Custom tools (Context7 docs, etc.)
├── playground_agent/     # Real-time voice agent
│   ├── agent.py          # Single-agent configuration
│   └── tools/            # Experiment manipulation tools
├── requirements.txt      # Dependencies
└── main.py               # Entry point for backend server