How pirate-e/ai-workflow-task-agent works
Project Type & Purpose
• Type: Modular, enterprise-grade desktop AI assistant (CLI/console UI)
• Purpose: Hybrid AI integration (local Ollama + OpenAI/NVIDIA), multi-agent orchestration (LangGraph), dynamic Model Context Protocol (MCP) plugin system, rich error tracing, and professional workflows.
File Structure
Top-level directories:
– src/ : Core application code
– tools/ : 17-tool ecosystem (3 fundamental + 14 MCP filesystem tools)
– mcp/ : MCP server integration and dynamic registration
– ui/diagnostics/ : Rich Traceback & console UI
– config/ : Settings & logging configuration
– RAG/ : Retrieval-augmented graph (Neo4j)
– tests/ : Unit, integration, event-listener, serialization tests
– Dockerfile & docker-compose.yml: Containerization
Main Components & Their Relationships
A. Presentation Layer (Console UI)
• print_banner.py, print_message_style.py
• rich_error_print.py, rich_traceback_manager.py (diagnostics)
↕ (user input / output)
B. Orchestration Layer
• src/main_orchestrator.py (entry point)
• ChatInitializer → configures logging, loads .mcp.json, starts MCP servers
C. Routing & Classification
• classify_agent.py (detects “/agent” vs “/shell” vs normal chat)
• router.py (directs message to correct processor)
D. Processing Nodes
1. LLM Agent
– chat_llm.py (OpenAI/NVIDIA adapter with circuit breaker)
2. Tool Selector
– tool_selector.py
– tool_assign.py & tool_response_manager.py
3. Agent Orchestrator (Multi-step workflows)
– src/agents/agentic_orchestrator/AgentGraphCore.py
– hierarchical_agent_prompts.py
E. Tools Layer
1. Fundamental Tools (in-process)
– GoogleSearch, RAGSearch, Translate, RunShellCommand
2. MCP Filesystem Tools (plugin via JSON-RPC)
– dynamic registration (load_config.py + dynamically_tool_register.py)
– MCP manager subprocesses (manager.py)
F. Data & External Services
• Local Ollama host (HTTP on 11434)
• OpenAI/NVIDIA REST endpoints
• Neo4j graph database (for RAG)
• .mcp.json-driven Node.js MCP servers
G. Cross-Cutting Concerns
– config/settings.py (.env, MCP_CONFIG_PATH)
– configure_logging.py (structured, socket-based)
– event_listener.py & rich_status_listen.py (event bus, Rich.status)
– socket_manager.py (subprocess log routing)
Architectural Patterns & Design Principles
• Modular Monolith with clear separation of concerns
• Event-Driven (singleton EventManager, weak references)
• Strategy Pattern (ToolSelector + dynamic MCP mapping)
• Circuit Breaker Pattern (OpenAI/NVIDIA adapter)
• Plugin Architecture (MCP JSON-RPC, dynamic tool discovery)
• Singleton (StateAccessor in models/state.py)
Detailed Elements
– main_orchestrator.py (entry point)
– ChatInitializer (starts MCP, logging)
– Classifier & Router
– LLM Agent node & Circuit Breaker adapter
– Agentic orchestrator graph (planner → classifier → parameter generator → executor → synthesizer → validator → planner/finalizer)
– UI & Diagnostics (Rich Traceback, status listener)
– Config (.env, settings), Logging, Event Bus
– Comprehensive: showing all major modules and their interactions
– Accurate: aligned with the code structure and README architecture sections
– Actionable: illustrates dynamic plugin registration, multi-agent workflows, and fail-safe patterns