/ README.md
README.md
1 # ECHO - Executive Coordination & Hierarchical Organization 2 3 **An AI-powered organizational model with autonomous role-based agents communicating via MCP protocol** 4 5 [](https://opensource.org/licenses/MIT) 6 [](https://elixir-lang.org/) 7 [](https://modelcontextprotocol.io/) 8 9 ## 🎯 Vision 10 11 ECHO enables future tech companies to operate with AI workers that: 12 - **Make autonomous decisions** within their authority 13 - **Collaborate through consensus** when needed 14 - **Escalate to appropriate authority** levels 15 - **Require human approval** for critical decisions 16 - **Communicate naturally** across organizational hierarchies 17 18 ## 🏗️ Architecture 19 20 Each organizational role runs as an **independent MCP server** that Claude Desktop (or any MCP client) can connect to: 21 22 ``` 23 Claude Desktop / MCP Client 24 ├──> mcp-server-ceo 25 ├──> mcp-server-cto 26 ├──> mcp-server-chro 27 ├──> mcp-server-operations 28 ├──> mcp-server-product-manager 29 ├──> mcp-server-architect 30 ├──> mcp-server-uiux 31 ├──> mcp-server-developer 32 └──> mcp-server-test-lead 33 34 All agents share: 35 ├── PostgreSQL (organizational memory) 36 └── Redis (message bus) 37 ``` 38 39 ## 📊 Monitoring Dashboard 40 41 **NEW**: Real-time Phoenix LiveView dashboard for monitoring agent activities! 42 43 ```bash 44 cd monitor 45 ./start.sh 46 # Open http://localhost:4000 47 ``` 48 49 Features: 50 - 📈 **Overview**: Daily agent activity summary 51 - 🔗 **Power Delegation**: Decision flow tracking 52 - 📊 **Performance**: Agent metrics and efficiency 53 - ⏱️ **Timeline**: Real-time activity feed 54 55 See [MONITORING_DASHBOARD_GUIDE.md](MONITORING_DASHBOARD_GUIDE.md) for details. 56 57 ## 🚀 Quick Start 58 59 ### Prerequisites 60 61 - Elixir 1.18+ with Erlang/OTP 27 62 - PostgreSQL 16+ 63 - Redis 7+ 64 - Ollama (for local AI models) 65 - Claude Desktop (for MCP client) 66 67 ### Setup in 3 Steps 68 69 **1. Start infrastructure:** 70 ```bash 71 # macOS with Homebrew 72 brew services start postgresql 73 brew services start redis 74 75 # Or use Nix shell (includes all dependencies) 76 nix-shell 77 ``` 78 79 **2. Setup database, LLMs, and agents:** 80 ```bash 81 # Create database and run migrations 82 cd shared 83 mix ecto.create 84 mix ecto.migrate 85 cd .. 86 87 # Install Ollama and download AI models (~48GB) 88 ./setup_llms.sh 89 90 # Build all agents 91 ./setup.sh 92 ``` 93 94 **3. Configure Claude Desktop:** 95 96 The setup script automatically creates the configuration. Just restart Claude Desktop! 97 98 **Manual configuration:** See `CLAUDE_DESKTOP_SETUP.md` 99 100 ### Verify Installation 101 102 ```bash 103 # Check system health 104 ./echo.sh summary 105 106 # Expected output: 107 # ● System Status: OPERATIONAL 108 # Infrastructure: ✓ PostgreSQL, ✓ Redis 109 # Agents: ✓ 3 / 9 agents healthy 110 111 # Test LLM integration for specific agent 112 ./scripts/agents/test_agent_llm.sh ceo 113 114 # Test all agents' LLM integration 115 ./scripts/agents/test_all_agents_llm.sh 116 ``` 117 118 ### First Demo 119 120 Open Claude Desktop and try: 121 122 ``` 123 Use the CEO agent to approve a strategic initiative: 124 - Name: "AI Research Lab" 125 - Budget: $750,000 126 - Expected outcome: "Advanced AI capabilities" 127 ``` 128 129 See `DEMO_GUIDE.md` for 10 comprehensive demo scenarios. 130 131 ## 📚 Documentation 132 133 | Document | Description | 134 |----------|-------------| 135 | [CLAUDE_DESKTOP_SETUP.md](./CLAUDE_DESKTOP_SETUP.md) | Connect agents to Claude Desktop | 136 | [DEMO_GUIDE.md](./DEMO_GUIDE.md) | 10 demo scenarios with examples | 137 | [ECHO_ARCHITECTURE.md](./ECHO_ARCHITECTURE.md) | Complete system architecture | 138 | [AGENT_INTEGRATION_GUIDE.md](./AGENT_INTEGRATION_GUIDE.md) | Agent implementation details | 139 | [LLM_TESTING_SUCCESS.md](./LLM_TESTING_SUCCESS.md) | LLM integration testing guide | 140 | [OLLAMA_SETUP_COMPLETE.md](./OLLAMA_SETUP_COMPLETE.md) | Ollama and model setup | 141 | [DISTRIBUTED_SYSTEMS_IMPROVEMENTS.md](./DISTRIBUTED_SYSTEMS_IMPROVEMENTS.md) | Reliability & observability | 142 | [ECHO_SH_README.md](./ECHO_SH_README.md) | Monitoring script documentation | 143 144 ## 🤖 Available Agents 145 146 Each agent has AI assistance via specialized local LLM models: 147 148 | Agent | Role | AI Model | Status | 149 |-------|------|----------|--------| 150 | CEO | Strategic leadership, budget allocation | qwen2.5:14b | ✅ Built + AI | 151 | CTO | Technology strategy, architecture | deepseek-coder:33b | ✅ Built + AI | 152 | CHRO | Human resources, talent management | llama3.1:8b | ✅ Built + AI | 153 | Operations Head | Infrastructure and operations | mistral:7b | ✅ Built + AI | 154 | Product Manager | Product strategy, prioritization | llama3.1:8b | ✅ Built + AI | 155 | Senior Architect | System design, technical specs | deepseek-coder:33b | ✅ Built + AI | 156 | UI/UX Engineer | Interface design, user experience | llama3.2-vision:11b | ✅ Built + AI | 157 | Senior Developer | Feature implementation, coding | deepseek-coder:6.7b | ✅ Built + AI | 158 | Test Lead | Quality assurance, testing | codellama:13b | ✅ Built + AI | 159 160 All agents use **local AI models via Ollama** - zero API costs, complete privacy, works offline. 161 162 ## 🎯 Key Features 163 164 ### AI-Powered Decision Making 165 166 Every agent has an `ai_consult` tool for AI-assisted analysis: 167 168 ```elixir 169 # CEO consulting AI for strategic decision 170 ai_consult( 171 query_type: "decision_analysis", 172 question: "Should we expand to European market?", 173 context: %{ 174 options: ["Immediate expansion", "Pilot program", "Defer"], 175 budget: "$5M", 176 timeline: "12 months" 177 } 178 ) 179 ``` 180 181 **Benefits:** 182 - 🔒 **Private** - All AI runs locally, no cloud APIs 183 - 💰 **Free** - Zero API costs after setup 184 - 🎯 **Specialized** - Each role has domain-specific model 185 - ⚡ **Fast** - Low latency for real-time decisions 186 - 🌐 **Offline** - Works without internet 187 188 ### Decision Modes 189 190 **Autonomous** - Agent makes decision within authority: 191 ```elixir 192 # CEO can approve budgets under $1M autonomously 193 approve_budget(amount: 750_000) # ✅ Autonomous 194 approve_budget(amount: 5_000_000) # ⬆️ Escalates to human 195 ``` 196 197 **Collaborative** - Multiple agents vote/consensus: 198 ```elixir 199 # CTO proposes architecture, team votes 200 propose_architecture(design: "Microservices") 201 # → Senior Architect, Operations, Product Manager vote 202 ``` 203 204 **Hierarchical** - Escalates up reporting chain: 205 ```elixir 206 # Developer uncertain → Architect → CTO → CEO 207 escalate_technical_decision(issue: "Database choice") 208 ``` 209 210 **Human-in-the-Loop** - Critical decisions require human: 211 ```elixir 212 # Legal, financial, or strategic risks 213 escalate_to_human(reason: "Regulatory compliance") 214 ``` 215 216 ### Inter-Agent Communication 217 218 Agents communicate via Redis pub/sub + PostgreSQL persistence: 219 220 ```elixir 221 # Product Manager → CTO 222 publish_message( 223 from: :product_manager, 224 to: :cto, 225 type: :request, 226 subject: "Technical feasibility review" 227 ) 228 ``` 229 230 ### Workflow Engine 231 232 Define multi-agent workflows: 233 234 ```elixir 235 workflow "Feature Development" do 236 step :product_manager, "define_requirements" 237 step :senior_architect, "design_system" 238 step :cto, "approve_architecture" 239 240 parallel do 241 step :senior_developer, "implement_backend" 242 step :ui_ux_engineer, "design_ui" 243 end 244 245 step :test_lead, "create_test_plan" 246 step :ceo, "approve_budget" 247 end 248 ``` 249 250 ### Health Monitoring 251 252 Real-time system observability: 253 254 ```bash 255 ./echo.sh # Full system status 256 ./echo.sh agents # Agent health with heartbeats 257 ./echo.sh workflows # Running workflows 258 ./echo.sh messages # Message queue status 259 ./echo.sh decisions # Pending decisions 260 ``` 261 262 ## 🚧 Development Status 263 264 **Current Phase:** Phase 4 - Workflows & Integration 265 266 **Completed:** 267 - ✅ Phase 1: Foundation (shared library, MCP protocol, database schemas) 268 - ✅ Phase 2: CEO agent (reference implementation) 269 - ✅ Phase 3: All 9 agents implemented 270 - ✅ Phase 4.1: Distributed systems improvements (reliability, observability) 271 272 **In Progress:** 273 - 🔄 Workflow engine testing 274 - 🔄 Integration with external systems 275 - 🔄 Production deployment guides 276 277 See [ECHO_ARCHITECTURE.md](./ECHO_ARCHITECTURE.md) for complete architecture design. 278 279 ## 📄 License 280 281 MIT License 282 283 --- 284 285 **ECHO** - Building the future of AI-powered organizations, one agent at a time. 🚀