System Architecture

MIU follows a layered, modular architecture with clear separation of concerns.

Overview

Core Components

Framework Layer (miu-core)

Agents
Tools
Providers

Location: packages/miu_core/miu_core/agents/

BaseAgent: Abstract base class defining agent interface
ReActAgent: Implements ReAct (Reasoning + Acting) pattern

class BaseAgent:
    async def run(self, query: str) -> str:
        """Run agent with given query."""

    async def _execute_step(self, context: AgentContext) -> bool:
        """Execute single step, return True if done."""

Location: packages/miu_core/miu_core/tools/

BaseTool: Abstract tool interface
ToolRegistry: Central tool management

class BaseTool(ABC):
    name: str
    description: str
    parameters: dict[str, Any]

    async def execute(self, **kwargs) -> ToolResult:
        """Execute tool with validated parameters."""

Location: packages/miu_core/miu_core/providers/

BaseProvider: Unified LLM interface
AnthropicProvider: Claude implementation
OpenAIProvider: GPT implementation
GoogleProvider: Gemini implementation

class BaseProvider(ABC):
    async def generate(
        self,
        messages: list[Message],
        tools: Optional[list[Tool]] = None,
    ) -> GenerateResponse:
        """Generate response from LLM."""

Coding Agent Layer (miu-code)

The CodingAgent specializes ReActAgent for code operations:

Tool	Purpose	Parameters
`read`	Read file contents	path: str
`write`	Write new file	path: str, content: str
`edit`	Modify existing file	path: str, old: str, new: str
`bash`	Execute shell command	command: str
`glob`	Find files by pattern	pattern: str
`grep`	Search file contents	pattern: str, path: str

TUI Application (miu-code)

Location: packages/miu_code/miu_code/tui/ Built with Textual framework:

StatusBar: Shows mode, path, token usage
Mode Management: NORMAL → PLAN → ASK cycling
Session Control: New session, clear, quit
Real-time Streaming: Text deltas, tool execution

Data Flow Patterns

Agent Execution Flow

Provider Abstraction

The provider interface allows swapping LLM backends without changing agent code:

# Agent code is provider-agnostic
response = await self.provider.generate(messages, tools)

# Different implementations
class AnthropicProvider(BaseProvider):
    async def generate(...):
        return anthropic_client.messages.create(...)

class OpenAIProvider(BaseProvider):
    async def generate(...):
        return openai_client.chat.completions.create(...)

Multi-Agent Patterns

Three coordination patterns in packages/miu_core/miu_core/patterns/:

Orchestrator

Coordinate agents with task dependencies using DAG

Pipeline

Sequential processing chain with stage transforms

Router

Route requests to specialist agents by keywords

Security Architecture

Input Validation

User input validated at entry point

Tool Security

Path validation, command escaping, result validation

Provider Layer

API key validation, request validation, rate limiting

External Services

Secure API communication

Extensibility

Adding a New Provider

class CustomProvider(BaseProvider):
    async def generate(self, messages, tools):
        # Your implementation
        pass

Adding a New Tool

class CustomTool(BaseTool):
    name = "custom"
    description = "Custom tool description"

    async def execute(self, **kwargs):
        # Your implementation
        pass

Async Architecture

Event Loop: Single asyncio event loop
Concurrency: asyncio.gather() for parallel operations
I/O: All blocking operations are async
Timeouts: All external calls have configurable timeouts

Getting Started

Core Concepts

Guides

Contributing

API Reference

System Architecture

System Architecture

Overview

Core Components

Framework Layer (miu-core)

Coding Agent Layer (miu-code)

TUI Application (miu-code)

Data Flow Patterns

Agent Execution Flow

Provider Abstraction

Multi-Agent Patterns

Orchestrator

Pipeline

Router

Security Architecture

Extensibility

Adding a New Provider

Adding a New Tool

Async Architecture

​System Architecture

​Overview

​Core Components

​Framework Layer (miu-core)

​Coding Agent Layer (miu-code)

​TUI Application (miu-code)

​Data Flow Patterns

​Agent Execution Flow

​Provider Abstraction

​Multi-Agent Patterns

Orchestrator

Pipeline

Router

​Security Architecture

​Extensibility

​Adding a New Provider

​Adding a New Tool

​Async Architecture

System Architecture

Overview

Core Components

Framework Layer (miu-core)

Coding Agent Layer (miu-code)

TUI Application (miu-code)

Data Flow Patterns

Agent Execution Flow

Provider Abstraction

Multi-Agent Patterns

Security Architecture

Extensibility

Adding a New Provider

Adding a New Tool

Async Architecture