diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..6ea8c83 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,647 @@ +# Amico V2 Architecture Design + +## Introduction + +Amico V2 is a platform-agnostic **runtime** for AI agents built in Rust. It provides a framework for developers to build AI agent business logic similar to how web frameworks like Axum or Rocket enable web development. + +This document describes the system architecture using functional design principles, Haskell-style function definitions, and Rust trait examples. + +## Design Principles + +1. **Traits + Generics over Boxing**: Use traits and generics to describe abstract concepts at high abstraction levels, avoiding dynamic dispatch +2. **Compile-time Safety**: Prefer compile-time types and static evaluation over runtime polymorphism +3. **Zero-cost Abstractions**: Use references and lifetimes over `Box` and `Arc` +4. **Async Traits**: Abstract async tasks with `Future` traits, not `Pin>` +5. **Modular Architecture**: Organize crates properly, separating core utilities from high-level entry points + +## System Layers + +The Amico V2 architecture consists of four distinct layers: + +``` +┌─────────────────────────────────────────┐ +│ Application / Event Handlers │ ← Developer code +├─────────────────────────────────────────┤ +│ Workflows Layer (Presets) │ ← Tool loop agents, etc. +├─────────────────────────────────────────┤ +│ Runtime Layer │ ← Workflow execution +├─────────────────────────────────────────┤ +│ Models Layer │ ← Model abstractions +├─────────────────────────────────────────┤ +│ System Layer │ ← Tools, side-effects, I/O +└─────────────────────────────────────────┘ +``` + +## 1. Models Layer (`amico-models`) + +The models layer abstracts away specific AI model providers and parameters, categorizing models by their responsibility. + +### Functional Design + +```haskell +-- Model categories by capability +type LanguageModel context input output = context -> input -> Future +type ImageGenModel context input = context -> input -> Future +type VideoGenModel context input = context -> input -> Future