🚀 Convergio — AI Command Center powered by Multi‑Agent Orchestration

Human purpose. AI momentum.

Convergio turns a team’s intent into coordinated execution by orchestrating 40+ specialized AI agents. You set the goal; the system assembles experts (finance, architecture, PM, security, design, analytics) to plan, decide, and deliver.

---

🗞️ What this is (and why it matters)

• Convergio is a unified, production‑leaning reference implementation of a multi‑agent platform built on top of Microsoft AutoGen. It is one of the first large‑scale, end‑to‑end implementations of AutoGen in an open repository, showing how to compose dozens of purpose‑built agents into reliable workflows. See Microsoft AutoGen on GitHub: https://github.com/microsoft/autogen
• Our north star is the Agentic Manifesto and inclusive design. Start here:
  • Agentic Manifesto: AgenticManifesto/AgenticManifesto.md
  • What is Convergio: AgenticManifesto/WhatIsConvergio.md
  • Built for Mario — AI‑First Interface: AgenticManifesto/💜 For Mario - AI-First Interface.md
• Communication meets engineering: this README is both a product primer and a practical guide to run the stack locally.

---

🏗️ Architecture (truth, no buzzwords)

• Backend: FastAPI (Python 3.11), SQLAlchemy 2.x (async), PostgreSQL, Redis, Prometheus metrics
• Frontend: SvelteKit + TypeScript + TailwindCSS (dev server on port 4000, proxy to backend 9000)
• AI Orchestration: Multi‑agent system using Microsoft AutoGen 0.7.x (autogen-core, autogen-agentchat, autogen-ext)
• Streaming & coordination: internal streaming orchestrator with typed protocols and runners
• Security: security headers, CORS, JWT scaffolding (RS256), optional rate‑limit middleware (currently disabled in code)

No Docker/Kubernetes manifests are provided in this repo. Local developer setup runs with system Postgres + Redis or containers you manage yourself.

Key capabilities

• Multi‑agent conversations with tool use, memory, and specialization
• GraphFlow for generating workflows from natural language
• Cost tracking, analytics endpoints, and observability hooks
• Vector search utilities for RAG‑style enrichment
• Dynamic Theme System: Light/dark/system mode with persistent preferences

---

🚀 Quick Start

Prerequisites

• Python 3.11+
• Node.js 18+
• PostgreSQL 14+
• Redis 6+

Installation

1. Clone the repository

git clone https://github.com/Roberdan/Convergio.git
cd convergio

2. Backend Setup

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Configure environment (see example below)
# Initialize DB with provided SQL (see commands below)
# Start backend
uvicorn src.main:app --reload --port 9000

3. Frontend Setup

cd frontend
npm install

# Start frontend (dev server on :4000)
npm run dev

4. Access the application

• Frontend: http://localhost:4000
• Backend API: http://localhost:9000
• API Documentation: http://localhost:9000/docs

---

📚 Documentation

Core Documentation

• Implementation Report: docs/IMPLEMENTATION_COMPLETE.md - Complete implementation details
• System Verification: docs/COMPREHENSIVE_VERIFICATION_REPORT_AUG2025.md
• Agent Definitions: docs/AGENTS.md - All 48 agents documented
• Database Schema: docs/DataBaseSchema.md
• Security System: docs/SECURE_COST_SYSTEM_VERIFICATION.md

Agent System

• Agent Definitions: backend/src/agents/definitions/
• Orchestrators & resilience: backend/src/agents/orchestrators/
• Ali Proactive Intelligence: backend/src/agents/ali_ceo.py

Enterprise Features

• Cost Management: docs/cost-tracking-system.md
• Multi-tenancy: Complete SaaS platform with Stripe billing
• Real Data Integrations: docs/REAL_DATA_INTEGRATIONS.md
• Security Compliance: OWASP Top 10 compliance and comprehensive audit trail

Live Documentation

• Swagger UI: http://localhost:9000/docs
• ReDoc: http://localhost:9000/redoc

---

🤖 Multi‑agent ecosystem

Convergio features a comprehensive multi‑agent system of specialized agents organized into functional domains:

Leadership & Strategy (6 agents)

• Ali - Chief of Staff & Proactive Intelligence Engine
• Amy - Chief Financial Officer
• Satya - Board of Directors Representative
• Antonio - Strategy Expert
• Matteo - Strategic Business Architect
• Domik - McKinsey Strategic Decision Maker

Project Management & Operations (8 agents)

• Davide - Project Manager
• Oliver - Project Manager
• Marcus - Project Manager
• Luke - Program Manager
• Wanda - Workflow Orchestrator
• Taskmaster - Strategic Task Decomposition Master
• Dave - Change Management Specialist
• Xavier - Coordination Patterns Expert

Technology & Engineering (6 agents)

• Dan - Engineering General Manager
• Baccio - Tech Architect
• Marco - DevOps Engineer
• Luca - Security Expert
• Guardian - AI Security Validator
• Thor - Quality Assurance Guardian

Data & Analytics (6 agents)

• Angela - Data Analyst
• Ethan - Data Analyst
• Ethan IC6 - Senior Data Analyst
• Omri - Data Scientist
• Ava - Analytics Insights Virtuoso
• Diana - Performance Dashboard Expert

Business Development & Sales (4 agents)

• Fabio - Sales & Business Development
• Michael - Venture Capitalist
• Wiz - Investor & Venture Capital
• Sam - Startup Expert

Human Resources & Culture (4 agents)

• Giulia - HR Talent Acquisition
• Coach - Team Coach
• Behice - Cultural Coach
• Jenny - Inclusive Accessibility Champion

Creative & Communication (5 agents)

• Sara - UX/UI Designer
• Jony - Creative Director
• Riccardo - Storyteller
• Steve - Executive Communication Strategist
• Sofia - Marketing Strategist

Customer Success & Compliance (5 agents)

• Andrea - Customer Success Manager
• Elena - Legal Compliance Expert
• Dr. Enzo - Healthcare Compliance Manager
• Sophia - Government Affairs
• Enrico - Business Process Engineer

AI & Optimization (4 agents)

• PO - Prompt Optimizer
• Marcus - Context Memory Keeper
• Socrates - First Principles Reasoning
• Stefano - Design Thinking Facilitator

Each agent is powered by advanced AI capabilities including:

• Context-aware reasoning with per-turn RAG
• Tool execution with intelligent selection
• Memory persistence across conversations
• Security validation and compliance checks
• Cost optimization and rate limiting
• Real-time collaboration and coordination

---

🧪 Testing

Test Suite Status (August 2025)

✅ All test scripts systematically fixed and optimized

Backend Tests

• Unit Tests: 97/97 passing ✅
• Integration Tests: 117/118 passing (99.2%) ✅
• E2E Tests: 4/5 passing (database session issues resolved) ✅
• Security Tests: All core security validations passing ✅
• Performance Tests: Load testing and metrics collection working ✅

Frontend Tests

• Unit Tests (Vitest): Core functionality tests passing ✅
• E2E Tests (Playwright): 30+ core tests passing ✅
• Accessibility Tests: All 11 accessibility requirements met ✅
• Component Tests: Dashboard, agents, navigation all working ✅

Quick Test Execution

# Run all backend tests
cd backend
pytest tests/ -v

# Run all frontend tests
cd frontend
npm run test        # Unit tests
npm run test:e2e    # E2E tests

# Run specific test categories
./08_test_frontend_e2e.sh    # Frontend E2E (optimized)
./09_test_master_runner.sh   # Master test orchestration
./10_test_go_backend.sh      # Go backend tests
./11_test_backend_top_level.sh # Top-level Python tests

Test Scripts (All Fixed & Optimized)

Production-Ready Test Scripts:

• ✅ ./08_test_frontend_e2e.sh - Frontend E2E with Playwright (fixed strict mode issues)
• ✅ ./09_test_master_runner.sh - Master test orchestration (Redis async fixes)
• ✅ ./10_test_go_backend.sh - Go backend tests (handles no Go files gracefully)
• ✅ ./11_test_backend_top_level.sh - Top-level tests (macOS compatibility fixed)

Additional Test Categories:

• ./01_test_backend_unit.sh - Backend unit tests
• ./02_test_backend_integration.sh - Backend integration tests
• ./03_test_backend_e2e.sh - Backend E2E tests
• ./04_test_security.sh - Security validation tests
• ./05_test_performance.sh - Performance and load tests

---

🎨 UI/UX Features (August 2025)

Dynamic Theme System

• Light/Dark/System Mode: Automatic OS theme detection with manual override
• Persistent Preferences: Theme choice saved in localStorage
• Surface Color System: surface-0 to surface-950 with dark mode variants
• Component Theming: 800+ hardcoded colors replaced with dynamic theme classes

User Interface

• Ali Assistant: Floating chat interface with real-time AI coordination
• Project Management: Gantt charts and Kanban boards with dynamic theming
• Analytics Dashboard: Real-time metrics and cost tracking
• Agent Management: Visual agent orchestration and status monitoring

Theme Toggle

Access theme controls via the toggle in the top-right header (next to cost display):

• 🌞 Light mode
• 🌙 Dark mode
• 🖥️ System (follows OS preference)

---

Additional Test Categories

• ./06_test_frontend_unit.sh - Frontend unit tests (Vitest)
• ./07_test_frontend_storybook.sh - Storybook component tests

Recent Test Improvements (August 2025)

Frontend E2E Optimizations:

• Fixed Playwright strict mode violations in dashboard tests
• Updated agent selector strategies for dynamic UI elements
• Improved navigation test flexibility for responsive design
• Skipped complex AI orchestration tests pending full implementation

Backend Test Stabilization:

• Resolved SQLAlchemy async session management issues
• Fixed Redis connection handling with proper async/await patterns
• Enhanced database test isolation and cleanup procedures
• Improved cross-platform shell script compatibility

Test Infrastructure:

• All test scripts now handle edge cases gracefully
• Enhanced error reporting and debugging capabilities
• Optimized test execution times with parallel processing
• Added comprehensive test coverage reporting

Tips & Best Practices

# Continue-on-error mode
FAIL_FAST=false ./08_test_frontend_e2e.sh

# Verbose output for debugging
VERBOSE=true ./09_test_master_runner.sh

# Run specific test patterns
npx playwright test --grep "dashboard" # Frontend specific tests
pytest tests/ -k "cost_tracking"       # Backend specific tests

---

⚙️ Environment variables (backend/.env)

Minimal set to get running locally:

# Environment
ENVIRONMENT=development
DEBUG=true

# Security (generate strong JWT secret for production)
JWT_SECRET=your_super_secure_jwt_secret_that_should_be_very_long_and_random_at_least_64_chars
JWT_ALGORITHM=RS256

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=convergio_db
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=1

# Network Configuration
DEFAULT_HOST=localhost
FRONTEND_PORT=4000
BACKEND_PORT=9000
API_PORT=9000
ADMIN_PORT=9001

# User Configuration
DEFAULT_USER_ID=system_user
DEFAULT_ANONYMOUS_USER=system_anonymous
DEFAULT_TEST_USER=system_test_user

# Feature Configuration
REFERENCE_AGENT_TRUNCATE_LENGTH=3000
RATE_LIMIT_ENABLED=true
RATE_LIMIT_PER_MINUTE_API=100

# AI providers
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GRAPHFLOW=true

# Health Monitoring
HEALTH_CHECK_ENABLED=true
LOG_LEVEL=INFO

📝 Note: For a complete list of all available environment variables with detailed explanations, see .env.example in the project root.

---

🤝 Contributing

We welcome contributions! Please see docs/CONTRIBUTING.md for guidelines.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Standards

• Python: Black + Ruff + mypy
• TypeScript: ESLint + Prettier
• Commits: Conventional Commits specification
• Tests: Required for all new features

---

📊 Observability & performance

• Prometheus metrics exposed at /metrics
• Structured logs (JSON) via structlog; configure via LOG_LEVEL, LOG_FORMAT
• Connection pooling for Postgres and Redis; tune via DB_* and REDIS_* settings

---

📄 License

This project is licensed under the Business Source License 1.1 - see the LICENSE file for details.

After the change date (2027-01-01), this software will be available under the Apache 2.0 license.

---

🙏 Acknowledgments

• Microsoft AutoGen team for the amazing multi-agent framework
• OpenAI for GPT models powering our agents
• The open-source community for invaluable tools and libraries

---

📞 Support

• Issues: https://github.com/Roberdan/Convergio/issues
• Discussions: https://github.com/Roberdan/Convergio/discussions

---

🚀 Roadmap

Q4 2025

• Advanced AI agents marketplace
• Mobile applications (iOS/Android)
• Advanced workflow templates library
• Enhanced multi-language support

Q1 2026

• AI model fine-tuning capabilities
• Advanced analytics dashboard
• Enterprise SSO integration
• Compliance certifications (SOC2, ISO)

---

Built with ❤️ by the Convergio Team

Making AI work for humans, not the other way around.