unified-intelligence-cli 1.0.0

Production-ready multi-agent task orchestration framework with Clean Architecture

Unified Intelligence CLI

Production-ready multi-agent task orchestration framework following Clean Architecture principles.

A CLI tool that intelligently distributes tasks to specialized agents (coder, tester, reviewer, researcher, coordinator) using LLM-powered execution with tool support. Inspired by AI Agents in Action and Robert C. Martin's Clean Code principles.

Features

✅ Multi-Task CLI: Accept multiple tasks in a single command ✅ Intelligent Agent Selection: Fuzzy matching assigns tasks to best-fit agents ✅ Tool Support: Agents can execute shell commands, read/write files, run tests ✅ LLM Providers: Mock (testing) and Grok (production) with extensible architecture ✅ Parallel Execution: Concurrent task processing with dependency handling ✅ Clean Architecture: Entities → Use Cases → Interfaces → Adapters ✅ 85% Test Coverage: 104 tests (73 unit + 31 integration)

Quick Start

# Setup
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Configure API key (for Grok provider)
echo "XAI_API_KEY=your_api_key_here" > .env

# Run with mock provider (no API needed)
python3 src/main.py \
  --task "Write a Python function for factorial" \
  --task "Write tests for factorial function" \
  --provider mock

# Run with live Grok (requires API key)
python3 src/main.py \
  --task "Implement FizzBuzz in Python" \
  --task "Create comprehensive tests" \
  --task "Run the tests and report results" \
  --provider grok \
  --verbose

Usage Examples

Single Task

python3 src/main.py --task "Review the codebase for security issues" --provider mock

Multi-Task Workflow

python3 src/main.py \
  --task "Implement binary search function" \
  --task "Write unit tests with edge cases" \
  --task "Review code for optimization opportunities" \
  --provider grok \
  --verbose

With Timeout and Parallel Execution

python3 src/main.py \
  --task "Analyze performance bottlenecks" \
  --task "Generate optimization report" \
  --provider grok \
  --timeout 120 \
  --parallel

With Configuration File

# Create config file (see config.example.json)
python3 src/main.py \
  --task "Implement feature X" \
  --task "Write tests for feature X" \
  --config config.example.json \
  --verbose  # CLI args override config file

End-to-End Demo

# Run complete dev workflow demo (requires API key)
python3 demo_full_workflow.py

Architecture

src/
├── entities/          # Core business objects (Agent, Task, ExecutionResult)
├── use_cases/         # Business logic (TaskCoordinator, TaskPlanner)
├── interfaces/        # Abstractions (ITextGenerator, IAgentExecutor)
├── adapters/          # External integrations
│   ├── llm/          # LLM providers (GrokAdapter, MockProvider)
│   ├── agent/        # Agent implementations (LLMAgentExecutor)
│   └── cli/          # CLI adapters (ResultFormatter)
├── factories/         # Dependency Injection (AgentFactory, ProviderFactory)
├── composition.py     # Composition root
├── tools.py           # Dev tools (run_command, read_file, write_file, list_files)
└── main.py            # CLI entry point

Clean Architecture Layers

1. Entities (innermost): Core business objects with no external dependencies
2. Use Cases: Business logic orchestrating entities
3. Interfaces: Abstractions following Dependency Inversion Principle
4. Adapters (outermost): External integrations (LLMs, CLI, tools)

Dependency Rule: Dependencies point inward only. Inner layers never depend on outer layers.

Security

This CLI enables LLM agents to execute shell commands and file operations. See SECURITY.md for:

• Command execution security model
• File operation safety
• API key protection
• Best practices and threat model

TL;DR: The CLI is a power tool for trusted local development. Run in isolated workspaces, review agent actions, use version control, and see SECURITY.md for full details.

Development

Run Tests

source venv/bin/activate
PYTHONPATH=. pytest tests/ -v

Check Coverage

PYTHONPATH=. pytest tests/ --cov=src --cov-report=term-missing

Add New Agent Type

# src/factories/agent_factory.py
Agent(
    role="your_role",
    capabilities=["capability1", "capability2"]
)

Add New LLM Provider

1. Implement ITextGenerator interface in src/adapters/llm/
2. Register in ProviderFactory.create_provider()
3. Add tests in tests/integration/test_provider_integration.py

Add New Tool

Use the extensible tool registry for easy registration:

# In your module
from src.tool_registry import default_registry

@default_registry.register(
    name="your_tool",
    description="What your tool does",
    parameters={
        "param": {"type": "string", "description": "Parameter description"}
    },
    required=["param"]
)
def your_tool(param: str) -> str:
    """Tool implementation."""
    return result

Tools are automatically available to LLM providers via DEV_TOOLS and TOOL_FUNCTIONS.

CI/CD

GitHub Actions workflows automatically run on push/PR:

• Tests: Run full test suite on Python 3.10, 3.11, 3.12
• Coverage: Generate and upload coverage reports
• Linting: Check code style with flake8
• Security: Scan with bandit and safety

See .github/workflows/tests.yml for configuration.

Project Structure

• src/: Production code (Clean Architecture layers)
• tests/: Unit and integration tests (TDD approach)
• scripts/: Utilities (GrokSession, API clients)
• demo_full_workflow.py: End-to-end workflow demonstration
• REFACTORING_ASSESSMENT.md: Code quality analysis

Testing Strategy

• Unit Tests (73): Test entities, use cases, tools, and CLI logic in isolation
• Integration Tests (31): Test component interactions, end-to-end workflows, and real file operations
• Coverage: 85% (tools: 96%, composition: 100%, use cases: 87-89%)

Configuration

Environment Variables (.env file)

XAI_API_KEY=your_grok_api_key_here

Configuration File (Optional)

Use --config flag to load settings from JSON file. CLI arguments override config file values.

Example config.json:

{
  "provider": "grok",
  "provider_config": {
    "model": "grok-code-fast-1",
    "temperature": 0.7
  },
  "parallel": true,
  "timeout": 120,
  "verbose": true,
  "custom_agents": [
    {
      "role": "security_analyst",
      "capabilities": ["security", "audit", "vulnerability"]
    }
  ]
}

See config.example.json for complete example.

Roadmap

Completed (100% Core Functionality):

• ✅ Multi-task CLI input
• ✅ Intelligent agent selection with fuzzy matching
• ✅ Tool-supported LLM execution
• ✅ Clean Architecture foundation
• ✅ End-to-end dev workflow demo

Future Enhancements:

• 🔄 Runtime provider switching via --config flag
• 🔄 Additional LLM providers (OpenAI, Anthropic)
• 🔄 Persistent task history and context
• 🔄 Web UI for task management
• 🔄 Plugin system for custom agents and tools

Principles

This project follows:

• Clean Code (Robert C. Martin): Small functions, meaningful names, explicit error handling
• Clean Architecture: Dependency inversion, use case-driven design
• SOLID Principles: SRP, OCP, LSP, ISP, DIP
• TDD: Tests first, refactor later
• Pragmatic: Fact-based decisions, avoid premature optimization

See CLAUDE.md for development guidelines.