AI Code Framework

A framework for building, deploying, and maintaining code components that are ideal for AI agents to create and maintain.

Core Philosophy

This framework is built on the principle that AI agents work best with:

1. Small, focused components - Each component fits comfortably within an LLM context window
2. Strict interface contracts - Rust's trait system enforces type-safe communication
3. Comprehensive context - Every component has context files documenting decisions, constraints, and requirements
4. Autonomous operation - Components can be updated, tested, and deployed by AI agents
5. Event-driven coordination - NATS pub/sub enables loosely-coupled component interaction

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Architect AI                           │
│  (Defines interfaces, creates component specifications)     │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                  Shared Interfaces                          │
│  (Trait definitions visible to all components)              │
└─────────────────────┬───────────────────────────────────────┘
                      │
         ┌────────────┼────────────┐
         ▼            ▼            ▼
    ┌────────┐  ┌────────┐  ┌────────┐
    │Component│  │Component│  │Component│
    │   A    │  │   B    │  │   C    │
    │        │  │        │  │        │
    │ Agent  │  │ Agent  │  │ Agent  │
    │ Context│  │ Context│  │ Context│
    └────┬───┘  └────┬───┘  └────┬───┘
         │           │           │
         └───────────┼───────────┘
                     ▼
         ┌───────────────────────┐
         │   NATS Message Bus    │
         │  (Event Coordination) │
         └───────────────────────┘

Project Structure

main-stack/
├── crates/
│   ├── interfaces/          # Shared trait definitions
│   │   ├── component.rs     # Core Component trait
│   │   ├── messaging.rs     # Message passing interfaces
│   │   ├── versioning.rs    # Version management
│   │   └── health.rs        # Health check interfaces
│   │
│   └── framework/           # Core framework runtime
│       ├── messaging.rs     # NATS integration
│       ├── runtime.rs       # Component lifecycle
│       └── agent.rs         # AI agent coordination
│
├── components/
│   ├── user-service/
│   │   ├── src/
│   │   │   ├── lib.rs       # Implementation
│   │   │   └── interface.rs # Public interface
│   │   └── context/         # AI agent context
│   │       ├── context.json
│   │       └── agent-config.json
│   │
│   └── notification-service/
│       ├── src/
│       └── context/
│
└── Cargo.toml              # Workspace configuration

Key Concepts

1. Components

Every component must implement the Component trait:

#[async_trait]
pub trait Component: Send + Sync {
    fn metadata(&self) -> &ComponentMetadata;
    async fn initialize(&mut self) -> anyhow::Result<()>;
    async fn shutdown(&mut self) -> anyhow::Result<()>;
    async fn handle_config_change(&mut self, config: serde_json::Value) -> anyhow::Result<()>;
}

Components are:

• Self-contained - All logic and data for one concern
• Interface-first - Define traits before implementation
• Testable - Implement Testable trait for validation
• Observable - Implement HealthCheckable for monitoring

2. Interfaces

Interface definitions live in crates/interfaces/ and individual component interface files. These are:

• Versioned - Changes trigger notifications to dependent components
• Strongly typed - Rust's type system prevents misuse
• Documented - Each interface includes purpose and usage
• Minimal - Only expose what other components need

3. Agent Context

Each component has a context/ directory containing:

context.json

Documents all information needed to maintain the component:

• Design decisions and rationale
• Dependencies and their purposes
• Known issues and workarounds
• Performance characteristics
• Security considerations

agent-config.json

Configures the AI agent responsible for the component:

• Monitored topics
• Autonomy level (can it self-deploy?)
• Escalation rules
• Responsibilities and constraints

4. Messaging

Components communicate via NATS pub/sub:

// Publishing a message
let message = MessageBuilder::new(
    ComponentId("user-service"),
    MessageType::ChangeNotification {
        change_summary: "New user created"
    }
)
.payload(user_data)
.build();

publisher.publish(message).await?;

// Handling messages
impl MessageHandler for MyComponent {
    async fn handle_message(&mut self, message: Message) -> anyhow::Result<Option<Message>> {
        // Process message
        // Return Some(response) to reply, None otherwise
    }

    fn subscribed_topics(&self) -> Vec<String> {
        vec!["component.my-service.messages"]
    }
}

5. Versioning and Deployment

Components implement VersionManager for controlled deployments:

1. AI agent detects need for change (message from another component, dependency update, etc.)
2. Agent evaluates whether to act autonomously or escalate
3. If autonomous: Make changes, create new version, run tests
4. Test both versions - old and new
5. Compare results - ensure new version passes all tests
6. Promote to production - if tests pass
7. Rollback capability - if issues detected

Getting Started

Prerequisites

• Rust 1.70+
• NATS server (for messaging)

Building

cargo build --workspace

Running Tests

cargo test --workspace

Running a Component

# Start NATS server
docker run -p 4222:4222 nats:latest

# Run user service
cargo run -p user-service

AI Agent Integration

MCP Server Pattern

Each component can have an MCP (Model Context Protocol) server that:

1. Monitors NATS topics for relevant messages
2. Loads component context from context.json
3. Evaluates messages using framework::agent::evaluate_message()
4. Takes action based on agent configuration:
   • Autonomous: Make changes and test
   • Escalate: Notify managing AI
   • Ignore: No action needed

Agent Decision Flow

Message arrives → Load context → Evaluate relevance
                                       ↓
                         ┌─────────────┼─────────────┐
                         ▼             ▼             ▼
                      Ignore        Act         Escalate
                                     ↓
                    Make changes → Test → Deploy

Example Agent Workflow

1. Interface Change Notification

   user-service changes UserManagement trait
   → NATS message: InterfaceChanged { interface_name: "UserManagement" }
   → notification-service agent receives message
   → Agent evaluates: depends on UserManagement
   → Decision: Escalate (interface changes need review)
   → Managing AI reviews change
   → If compatible: Agent updates code to match new interface
   → Agent runs tests
   → If tests pass: Deploy new version
   

2. Dependency Update

   New version of uuid crate released
   → Agent evaluates: is this a breaking change?
   → If patch/minor: Update autonomously
   → Run tests with new version
   → If pass: Deploy
   → If fail: Escalate to managing AI
   

Parallel Agent Execution

Yes! Multiple agents can run in parallel - this is a core design principle of the framework.

How It Works

1. Independent Agents: Each component has its own AI agent that operates autonomously
2. NATS Pub/Sub: Enables non-blocking, parallel message delivery
3. No Coordination Required: Agents make decisions independently
4. Scalable: Can scale horizontally with Docker

Example: Interface Change Broadcast

Architect AI broadcasts: InterfaceChanged("UserManagement")
                    ↓
            NATS Message Bus
                    ↓
    ┌───────────────┼───────────────┐
    ▼               ▼               ▼
Agent A         Agent B         Agent C
(2 min)         (30 sec)        (1 min)

All process simultaneously!
Total time: max(2, 0.5, 1) = 2 minutes
NOT 2 + 0.5 + 1 = 3.5 minutes

Performance Benefits

Traditional Sequential:

50 components × 2 min each = 100 minutes

Framework Parallel:

50 agents work simultaneously = 2 minutes

50x speedup!

Scaling with Docker

# Run multiple instances of each service
docker-compose up -d --scale user-service=3 \
                      --scale notification-service=3

# NATS queue groups automatically load-balance

Try It Yourself

See examples/parallel-agents/ for a complete demonstration:

# Start infrastructure
docker-compose up -d nats

# Terminal 1: Start Agent A
cargo run --example agent-simulator user-service true

# Terminal 2: Start Agent B
cargo run --example agent-simulator notification-service true

# Terminal 3: Broadcast event
cargo run --example broadcast-event interface-change UserManagement

Watch all agents process the message in parallel!

Docker Deployment

The framework is fully containerized for production deployment.

Quick Start

# Build and start all services
make up
# or
docker-compose up -d

# View logs
make logs

# Stop services
make down

What's Included

• NATS Message Broker - localhost:4222
• NATS Monitoring - http://localhost:8222
• User Service - Containerized with context files
• Notification Service - Subscribes to NATS topics
• Health Checks - Automatic monitoring and restart

See docs/DOCKER.md for complete deployment guide.

Why Rust?

Rust was chosen for this framework because:

1. Type Safety - Trait system provides compile-time interface verification
2. Explicit Interfaces - Traits are first-class, making contracts clear
3. Error Handling - Result<T, E> forces explicit error cases
4. Zero Runtime Overhead - Performance-critical components have no abstraction cost
5. Growing AI Proficiency - LLMs are increasingly good at Rust
6. Fearless Concurrency - Safe async/await for message handling

Comparison with Alternatives

Feature	Rust	Go	Python + Pydantic
Type Safety	Compile-time	Compile-time	Runtime
AI Fluency	Good	Excellent	Excellent
Context Efficiency	High	High	Very High
Error Detection	Compile-time	Compile-time	Runtime
Performance	Excellent	Very Good	Good
Learning Curve	Steep	Gentle	Gentle

Future Enhancements

• GraphQL or gRPC code generation from trait definitions
• Automatic documentation generation from interfaces
• Visual dependency graph of components
• Automated compatibility testing across versions
• Production-ready persistent storage implementations
• Distributed tracing integration
• Metrics and observability framework

Contributing

This is a proof-of-concept framework. Contributions welcome to:

• Add more example components
• Improve agent decision logic
• Enhance context file schemas
• Build MCP server implementations
• Add production-ready features

License

MIT