Framework for creating AI agents to manage and interact with your media library.
View Demo »

Report Bug · Request Feature · New Agent Request

🧐 What is it?

Director provides a advance AI first framework for developing intelligent agents that can interact with your audio/video collection in natural language. Whether you're dealing with social content, lectures, movies, youtube videos, TV shows, talks, music, or other digital content, Director offers variety of tools to build powerful AI-powered assistants.

It uses the VideoDB’s scalable "video as data" infrastructure to create agentic workflows. For example, in natural language you can give commands like “upload this video and send the bullet point summary on my slack” and the agent will handle the rest. 📺 Watch: Intro video

director_demo_medium.mp4

⭐️ Key Features

• 🤖 AI Agent Framework: Build custom agents to perform tasks like summarization, search, indexing, clipping and library organization.

• 🎨 Innovative User Experience: Complete framework for interacting with your media library with chat based UI, Video player and next-gen interactions that can help you create the experience you need.

• 🔍 Media Analysis: Your video infra is taken care by VideoDB. Connect with popular LLMs, Databases, and GenAI APIs seamlessly.

• 🧩 Extensible Architecture: Easily add new capabilities through tools and modules. Run locally or deploy on your own cloud.

  

🏃 Getting Started

📺 Watch: Setup video

Prerequisites

• Python 3.9 or higher
• Node.js 22.8.0 or higher
• npm

Installation

1. Clone the repository:

git clone https://github.com/video-db/Director.git
cd Director

2. Run the setup script:

./setup.sh

This script will:

• Install nvm (Node Version Manager) if not already installed
• Install Node.js 22.8.0 using nvm
• Install Python and pip
• Set up virtual environments and install dependencies for frontend and backend

Supported platforms:

• Mac
• Linux
• Windows (WSL)

3. Configure the environment variables: Edit the .env files to add your API keys and other configuration options.

💬 Running the Application

To start both the backend and frontend servers:

make run

This will start the backend server on http://127.0.0.1:8000 and the frontend server on http://127.0.0.1:8080.

To run only the backend server: make run-be To just run the frontend development server: make run-fe

📖 Documentation

The project documentation is built using MkDocs. To serve the documentation locally on port 9000:

Activate the environment and install dependencies for development:

source backend/venv/bin/activate  
make install-be

mkdocs serve -a localhost:9000

To build the documentation:

mkdocs build

📘 Creating a New Agent

To create a new agent in Director, follow these steps:

1. Copy the template: Duplicate sample_agent.py in Director/backend/director/agents/ and rename it to your agent's name.

2. Update class details:

   • Rename the class (e.g., from SampleAgent to YourAgentName)
   • Update agent_name and description

3. Modify the run method:

   • Update parameters and docstring
   • Implement your agent's logic

4. Handle output and status updates:

   • Use appropriate content types (TextContent, VideoContent, ImageContent, SearchResultContent)
   • Update self.output_message.actions for progress indicators
   • Use push_update() to emit progress events
   • Set content status (progress, success, error) and messages

5. Implement error handling:

   • Set error status and messages if issues occur

6. Finalize the response:

   • Call self.output_message.publish() to emit final state and persist session
   • Return an AgentResponse with result, message, and data

7. Register the agent:

   • Import your new agent class in Director/backend/director/handler.py
   • Add it to the self.agents list in ChatHandler

Remember to consider creating reusable tools if your agent's functionality could be shared across multiple agents.

🤝 Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request