Dirigent AI - Meta-Orchestration System

A sophisticated meta-orchestration system that enables users to create complex AI workflows through natural language descriptions called "vibes". The system uses a Kiro-based "Dirigent" agent to analyze user goals and dynamically generate YAML configurations for specialized CrewAI agent teams.

🚀 Quick Start

Prerequisites

Python 3.11 or higher
OpenAI API key
Serper API key (optional, for web search functionality)

Installation

Clone and setup the project:

git clone <repository-url>
cd dirigent-ai
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

Configure environment variables:

cp .env.template .env
# Edit .env file with your API keys:
# OPENAI_API_KEY=your_openai_api_key_here
# SERPER_API_KEY=your_serper_api_key_here (optional)

Run system diagnostics:

python -m dirigent_ai.main --diagnostics

Basic Usage

Run with a vibe file:

python -m dirigent_ai.main --vibe-file vibes/gamebook_creation.txt --execute

Run with direct text input:

python -m dirigent_ai.main --vibe-text "Create a comprehensive market research report on electric vehicles" --execute

Validation mode (no crew execution):

python -m dirigent_ai.main --vibe-file vibes/real_estate_search.txt

🏗️ System Architecture

Dirigent AI implements a meta-orchestration pattern with two main components:

1. Dirigent Agent (Kiro-based)

Purpose: Intelligent configuration generator
Input: Natural language "vibes" (user goals)
Output: Valid YAML configurations for CrewAI teams
Location: Kiro steering document (.kiro/steering/dirigent-agent.md)

2. Skeleton Runner (Python)

Purpose: Universal execution engine
Input: YAML configurations from Dirigent Agent
Output: Executed AI workflows and results
Location: dirigent_ai/skeleton_runner.py

Workflow Pipeline

User Vibe → Skeleton Runner → Dirigent Agent → YAML Config → CrewAI Execution → Results

📁 Project Structure

dirigent-ai/
├── dirigent_ai/                    # Main package
│   ├── __init__.py
│   ├── main.py                     # Entry point
│   ├── config.py                   # Configuration management
│   ├── skeleton_runner.py          # Core orchestration logic
│   ├── kiro_interface.py          # Kiro agent communication
│   ├── crew_manager.py            # CrewAI management
│   ├── tool_registry.py           # Available tools registry
│   ├── vibe_loader.py             # Input handling
│   ├── yaml_config.py             # YAML processing
│   ├── setup.py                   # Installation script
│   ├── requirements.txt           # Dependencies
│   └── README.md                  # Package documentation
├── vibes/                         # Example vibe files
│   ├── gamebook_creation.txt
│   ├── real_estate_search.txt
│   └── test_simple.txt
├── output/                        # Generated results
├── logs/                          # Application logs
├── .kiro/                         # Kiro configuration
│   ├── specs/dirigent-ai/         # Project specifications
│   └── steering/dirigent-agent.md # Dirigent agent configuration
├── .env.template                  # Environment template
├── requirements.txt               # Project dependencies
└── README.md                      # This file

🛠️ Available Tools

The system includes the following CrewAI tools that can be assigned to agents:

Tool Name	Purpose	Use Cases
`web_search`	SerperDevTool for web searching	Market research, fact-checking, current events
`website_scraper`	WebsiteSearchTool for content extraction	Specific site analysis, data collection
`file_reader`	FileReadTool for reading files	Document analysis, data processing
`doc_writer`	FileWriteTool for writing documents	Report generation, content creation

📋 Command Line Options

python -m dirigent_ai.main [OPTIONS]

Options:
  --vibe-file, -f PATH     Path to text file containing vibe description
  --vibe-text, -t TEXT     Vibe description as direct text argument
  --output, -o PATH        Output file path for results (optional)
  --execute               Execute the generated crew (default: validation only)
  --verbose, -v           Enable verbose logging and save YAML config
  --diagnostics           Display comprehensive system diagnostics
  --help, -h              Show help message

🎯 Example Vibes

Gamebook Creation

Create an interactive fantasy gamebook with multiple storylines, character development, and meaningful choices that affect the narrative outcome. Include at least 3 different character classes and branching paths based on player decisions.

Market Research

Conduct comprehensive market research on the electric vehicle industry, including current market leaders, emerging technologies, consumer trends, and future projections for the next 5 years.

Real Estate Analysis

Find and analyze the top 10 residential properties in Austin, Texas under $500,000, including neighborhood analysis, price trends, and investment potential.

🔧 Configuration

Environment Variables

Required:

OPENAI_API_KEY: Your OpenAI API key for LLM functionality

Optional:

SERPER_API_KEY: Your Serper API key for web search capabilities
DIRIGENT_LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR)
DIRIGENT_TIMEOUT: Timeout for Kiro agent calls (default: 300 seconds)
DIRIGENT_MAX_RETRIES: Maximum retry attempts (default: 3)

Configuration Files

.env: Environment variables (create from .env.template)
dirigent_ai/config.py: System configuration and defaults
.kiro/steering/dirigent-agent.md: Dirigent agent behavior configuration

🧪 Testing and Validation

System Health Check

python -m dirigent_ai.main --diagnostics

Validation Mode

Run without --execute flag to validate YAML generation without crew execution:

python -m dirigent_ai.main --vibe-file vibes/test_simple.txt --verbose

Integration Tests

python test_dirigent_ai_integration.py
python test_integration_workflows.py

🐛 Troubleshooting

Common Issues

1. "Kiro agent communication error"

Verify Kiro agent is accessible and running
Check network connectivity
Review .kiro/steering/dirigent-agent.md configuration

2. "Invalid YAML configuration"

Check Dirigent agent output format
Verify tool names match registry
Ensure agent names are properly referenced in tasks

3. "Missing API keys"

Verify .env file exists and contains required keys
Check environment variable names match exactly
Ensure API keys are valid and have sufficient credits

4. "Tool not found in registry"

Check available tools with --diagnostics flag
Verify tool names in YAML match registry exactly
Review dirigent_ai/tool_registry.py for available tools

Debug Mode

Enable verbose logging for detailed troubleshooting:

python -m dirigent_ai.main --vibe-file your_vibe.txt --verbose --diagnostics

Log Files

Application logs: logs/dirigent.log
System logs: docs-meta/system.log
Error logs: docs-meta/error_log.txt

📚 Documentation

Technical Documentation

Requirements: .kiro/specs/dirigent-ai/requirements.md
Design: .kiro/specs/dirigent-ai/design.md
Implementation Tasks: .kiro/specs/dirigent-ai/tasks.md
System Architecture: docs-meta/05_system_description.md

Development Documentation

Current Status: docs-meta/02_functional_components.md
Known Issues: docs-meta/01_current_problems.md
Setup Guide: docs-meta/03_run_manual.md
Code Overview: docs-meta/04_code_orientation.md

🤝 Contributing

This project follows the Dirigent AI specification. See the design and requirements documents in .kiro/specs/dirigent-ai/ for detailed implementation guidelines.

Development Status

✅ Core infrastructure and tool registry
✅ Vibe input loading and CLI interface
✅ Kiro Dirigent Agent integration
✅ YAML configuration generation and validation
✅ Dynamic CrewAI object creation
✅ Complete workflow orchestration
✅ Demonstration scenarios (gamebook, real estate)
🔄 Integration testing and validation
🔄 Comprehensive documentation

📄 License

[Add your license information here]

🆘 Support

For issues and questions:

Check the troubleshooting section above
Review the documentation in docs-meta/
Check existing issues in the project repository
Create a new issue with detailed error information and logs

Name		Name	Last commit message	Last commit date
.kiro		.kiro
__pycache__		__pycache__
dirigent_ai		dirigent_ai
docs-meta		docs-meta
documentation_system		documentation_system
logs		logs
output		output
vibes		vibes
.env.example		.env.example
.gitignore		.gitignore
DEPLOYMENT_GUIDE.md		DEPLOYMENT_GUIDE.md
EXAMPLES_AND_TROUBLESHOOTING.md		EXAMPLES_AND_TROUBLESHOOTING.md
README.md		README.md
TableOfContent.md		TableOfContent.md
doc_cli.py		doc_cli.py
documentation.md		documentation.md
main.py		main.py
progress.md		progress.md
requirements.txt		requirements.txt
test_dirigent_ai_integration.py		test_dirigent_ai_integration.py
test_dirigent_integration.py		test_dirigent_integration.py
test_filesystem_layer.py		test_filesystem_layer.py
test_gamebook_workflow.py		test_gamebook_workflow.py
test_integration_workflows.py		test_integration_workflows.py
test_real_estate_workflow.py		test_real_estate_workflow.py
test_system_validation.py		test_system_validation.py
test_unit_core_components.py		test_unit_core_components.py

Latest commit

History

Folders and files

Repository files navigation