EMAS - Evolutionary Multi-Agent System

Deterministic Orchestration of Non-Deterministic Agents.

EMAS treats AI agents like biological organisms. Instead of one prompt -> one answer, it spins up teams of agents with different reasoning strategies and evolves the best approach through natural selection.

Built in Rust for zero-cost concurrency, high-speed evaluation, and memory-safe agent lifecycle management.

Showcase

Components

| Module | Role | |----------------|------| | Genotype | Agent DNA: system prompt, reasoning strategy, temperature | | Agent | A single AI worker. Calls the LLM with its genotype's config | | Team | A group of agents (standard + 1 Red-Team) tackling a problem | | Orchestrator | The Judge. Scores teams on Quality, Consistency, Efficiency | | Knowledge | Global Knowledge Base: persists insights & conflicts across generations | | Evolution | Selection, crossover, and mutation operators | | Arena | The environment. Runs the full evolutionary loop | | TUI | Terminal User Interface for interactive queries and monitoring | | LLM Client | Async HTTP client - supports OpenAI-compatible & Google Gemini natively |

Reasoning Strategies

Each team member is assigned one of nine reasoning strategies:

Chain-of-Thought - Step-by-step decomposition
Critical Analysis - Scrutinise flaws and assumptions
Creative / Lateral - Unconventional, cross-domain thinking
Strict Logic - Formal deductive / inductive reasoning
Edge-Case Analysis - Boundary conditions and failure modes
Performance Focus - Optimisation and benchmarking
Devil's Advocate - Argue against the obvious solution
First Principles - Rebuild from fundamental truths
Red-Team Analyst - Active contrarian; searches for alternative solutions

Note: Every team of size > 1 automatically includes exactly one Red-Team Analyst to ensure healthy divergence and prevent groupthink.

Fitness Function

| Metric | Description | Default Weight | |---------------|-------------|:--------------:| | Quality | Dual-Judge evaluation (Correctness, Skeptical, or Exhaustive) | 0.50 | | Consistency | Pairwise Jaccard similarity (with bonus for Red-Team divergence) | 0.30 | | Efficiency | Inverse token usage (decays quadratically over generations) | 0.20 |

Advanced Scoring Dynamics

Dual-Judge Rotation: The Orchestrator rotates between three judge personas (Correctness, Skeptical, Exhaustiveness) to prevent agents from "gaming" a single evaluator.
Efficiency Decay: In early generations, efficiency is weighted heavily to find cheap, fast solutions. As evolution progresses, the weight decays, allowing the system to prioritise raw depth and quality over cost.
Red-Team Divergence Bonus: While standard agents are rewarded for agreement, the Red-Team worker is rewarded for diverging from the consensus, earning the team bonus points for surfacing novel alternatives.
Diversity Penalty: Teams that repeat a conclusion that previously scored poorly receive a fitness penalty, pushing the population toward unexplored areas of the solution space.
Global Knowledge Base: Insights and conflicts discovered in prior generations are injected into the system prompts of subsequent agents, allowing the system to "remember" and resolve past disagreements.

Evolutionary Operators

Selection: Top 40% of teams survive as elites.
Crossover: Two elite parents produce a child; for each agent slot, a genotype is randomly picked from either parent, temperatures are blended.
Mutation (per-agent, probability = mutation_rate):
- Temperature perturbation +/-0.15
- 25% chance: strategy swap
- 20% chance: instruction modifier appended

Quick Start

Prerequisites

Rust toolchain (1.75+): https://rustup.rs
An OpenAI-compatible API key (OpenAI, Ollama, vLLM, etc.)

Setup

# Clone & enter the project
cd EMAS

# Copy the env template and fill in your API key
cp .env.example .env
# Edit .env with your API key

# Build (release mode recommended)
cargo build --release

Run

# Launch the interactive TUI (Recommended for development)
cargo run --release -- --tui

# Basic CLI usage
cargo run --release -- "What is the most efficient sorting algorithm for nearly-sorted data?"

# With custom parameters
cargo run --release -- \
  --population 8 \
  --team-size 4 \
  --generations 15 \
  --threshold 9.0 \
  --mutation-rate 0.4 \
  --model gpt-4o \
  "Design a rate limiter for a distributed API gateway"

Persistent Settings

EMAS automatically saves your parameters (model, weights, provider, etc.) after every successful run. Subsequent runs will use these as defaults unless overridden.

Storage Location: ~/.config/emas/last_params.json (Linux)
Reset: Pass --reset-defaults to clear saved settings and restore built-in defaults.

Using with Google Gemini

# Option A: Set GOOGLE_API_KEY (auto-detects provider)
export GOOGLE_API_KEY="AIza..."
cargo run --release -- "What is the most efficient sorting algorithm for nearly-sorted data?"

# Option B: Explicit provider flag
cargo run --release -- \
  --provider google \
  --model gemini-2.0-flash-lite \
  "Design a rate limiter for a distributed API gateway"

# Option C: Other Gemini models
cargo run --release -- \
  --provider google \
  --model gemini-2.5-flash-preview-05-20 \
  "Explain the CAP theorem with practical examples"

Using with Ollama (local models)

# Start Ollama
ollama serve

# Run EMAS against a local model
cargo run --release -- \
  --api-url http://localhost:11434/v1 \
  --model llama3.1 \
  "Explain the CAP theorem with practical examples"

CLI Options

Usage: emas [OPTIONS] [PROBLEM]

Arguments:
  [PROBLEM]  The problem or question to solve (required unless --tui is used)

Options:
      --tui                                    Launch interactive TUI mode
      --population <POPULATION>                Number of teams [default: 5]
      --team-size <TEAM_SIZE>                  Agents per team [default: 3]
      --generations <GENERATIONS>              Max generations [default: 10]
      --threshold <THRESHOLD>                  Convergence threshold 1-10 [default: 8.5]
      --mutation-rate <MUTATION_RATE>          Mutation rate 0-1 [default: 0.3]
      --provider <PROVIDER>                    LLM provider: "openai" or "google"
      --model <MODEL>                          LLM model name
      --api-url <API_URL>                      API base URL
      --api-key <API_KEY>                      Directly provide API key
      --max-tokens <MAX_TOKENS>                Max tokens per response [default: 1024]
      --quality-weight <QUALITY_WEIGHT>        Quality fitness weight [default: 0.50]
      --consistency-weight <CONSISTENCY_WEIGHT> Consistency fitness weight [default: 0.30]
      --efficiency-weight <EFFICIENCY_WEIGHT>  Efficiency fitness weight [default: 0.20]
      --judge-model <JUDGE_MODEL>              Separate model for the Orchestrator
      --judge-provider <JUDGE_PROVIDER>        Provider for the judge ("openai" or "google")
      --judge-api-url <JUDGE_API_URL>          API base URL for the judge
      --judge-api-key <JUDGE_API_KEY>          API key for the judge
      --reset-defaults                         Clear saved parameters
      --no-save                                Don't save parameters after this run
  -h, --help                                   Print help
  -V, --version                                Print version

Environment Variables

| Variable | Fallback | Description | |----------|----------|-------------| | EMAS_API_KEY | GOOGLE_API_KEY / OPENAI_API_KEY | API key for the LLM provider | | EMAS_PROVIDER | - | Force provider: openai or google (auto-detected if omitted) | | EMAS_API_BASE_URL | OPENAI_API_BASE | Base URL for the API endpoint | | EMAS_MODEL | GOOGLE_MODEL / OPENAI_MODEL | Default model name | | GOOGLE_API_KEY | - | Google Gemini API key (triggers auto-detection) | | GOOGLE_MODEL | - | Google model override (default: gemini-2.0-flash-lite) | | EMAS_JUDGE_MODEL | agent model | Separate model for the judge / Orchestrator | | EMAS_JUDGE_API_KEY | agent key | API key for the judge (if different provider) | | EMAS_JUDGE_API_BASE_URL | agent URL | API endpoint for the judge | | RUST_LOG | info | Logging verbosity (trace, debug, info, warn, error) |

Why Rust?

| Advantage | Explanation | |-----------|-------------| | Zero-Cost Concurrency | tokio async runtime manages all agent/team API calls concurrently with minimal overhead | | High-Speed Evaluation | The Orchestrator's fitness scoring (Jaccard similarity, normalisation) runs at native speed | | Memory Safety | Ownership model guarantees no leaks when teams are "killed" and agents are spawned/cloned across generations | | Predictable Performance | No GC pauses; consistent latency even under heavy concurrent load |

Project Structure

src/
|-- main.rs          # CLI entry point
|-- lib.rs           # Module declarations
|-- config.rs        # CLI args + environment -> Config
|-- genotype.rs      # ReasoningStrategy, Genotype, mutation modifiers
|-- agent.rs         # Agent execution (LLM call)
|-- team.rs          # Team of agents, concurrent execution
|-- llm.rs           # OpenAI-compatible HTTP client
|-- orchestrator.rs  # Fitness evaluation (Quality, Consistency, Efficiency)
|-- evolution.rs     # Sel

EMAS

Install / Use

README