aerrik

🧠 AERRIK

AI Task Complexity Routing Engine

Helps AI coding agents choose the right execution strategy for every software task.

---

🚀 Quick Start

Installation

pip install aerrik

Classify a Task

aerrik classify "Build a distributed event-driven system"

Output:

╭──────────────────────────────────────────────────────────────╮
│ ⚡ AERRIK Task Classification                                 │
╰──────────────────────────────────────────────────────────────╯

Task
Build a distributed event-driven system

Classification
COMPLEX

Scope
PLATFORM

Confidence
100%

Reasons
  ✓ Architecture: distributed
  ✓ Architecture: event-driven
  ✓ Multi-concern scope: 2 independent concerns

Agent Strategy
  → Architecture planning, risk analysis, system decomposition

---

📋 What Is AERRIK?

AERRIK is a task complexity routing engine — an intelligence layer that analyzes software development tasks and classifies them into SIMPLE, MEDIUM, or COMPLEX.

AI coding agents use this classification to decide how much planning, reasoning, architecture, tooling, and execution a task requires.

The Flow

User describes a software task
        ↓
AERRIK analyzes the task description
        ↓
Detects complexity signals (architecture, security, integration, data, etc.)
        ↓
Classifies: SIMPLE | MEDIUM | COMPLEX
        ↓
AI agent uses the result to select an execution strategy

Example Classifications

---

💡 Why AERRIK Exists

AI coding agents often use the same reasoning process for every task — whether it's creating a button or designing a distributed system. This causes:

• ❌ Overthinking simple tasks (wasting tokens and time)
• ❌ Under-planning complex tasks (missing architecture, security, edge cases)
• ❌ Inefficient tool usage (same tools for every task)
• ❌ Bad execution strategies (one-size-fits-all approach)

AERRIK acts as a complexity-aware routing layer that helps agents calibrate their approach:

---

📦 Installation

From PyPI (Recommended)

pip install aerrik

Upgrade

pip install --upgrade aerrik

Verify Installation

aerrik --version
# Output: aerrik 5.4.0

Development Installation

git clone https://github.com/aerrik-studio/aerrik.git
cd aerrik
pip install -e .

---

🎯 CLI Usage

Classify a Task

aerrik classify "Create a REST API for tasks"

JSON Output

aerrik classify "Build a payment system" --json

Output:

{
  "policy": "medium",
  "scope_level": "feature",
  "score": 5.0,
  "confidence": 0.99,
  "reasons": [
    "Feature scope: 1 signals (score: 3.0)",
    "Security: 3/10",
    "Multi-concern scope: 2 independent concerns"
  ],
  "signals": {
    "architecture": 0.0,
    "scope": 2.64,
    "integration": 0.0,
    "data": 0.0,
    "security": 3.0,
    "realtime": 0.0,
    "workflow": 0.0,
    "concern_count": 2,
    "concern_types": []
  }
}

Detailed Explanation

aerrik explain "Build a multi-tenant SaaS platform"

Shows comprehensive breakdown including:

• Classification and scope
• Score and confidence
• All signal dimensions (architecture, integration, security, etc.)
• Concern count and types
• All detection reasons

Agent Strategy

aerrik strategy "Build a distributed payment system"

Output:

╭──────────────────────────────────────────────────────────────╮
│ 🤖 AERRIK Agent Strategy                                     │
╰──────────────────────────────────────────────────────────────╯

Classification: COMPLEX

Recommended Agent Strategy

  Planning Steps         5
  Maximum Tools          15
  Architecture Review    ENABLED
  Security Review        ENABLED
  Review Required        YES
  Testing                Full test suite

Architecture planning, risk analysis, system decomposition

---

🐍 Python API

Basic Usage

from aerrik import TaskComplexity

# Simple classification
result = TaskComplexity.classify("Build a distributed cache")
print(result.value)  # "complex"

# Detailed classification
breakdown = TaskComplexity.classify_detailed("Build a distributed cache")
print(f"Policy: {breakdown.policy.value}")      # "complex"
print(f"Scope: {breakdown.scope_level.value}")   # "platform"
print(f"Score: {breakdown.score}")               # 23.9
print(f"Confidence: {breakdown.confidence}")     # 1.0
print(f"Reasons: {breakdown.reasons}")           # ["Architecture: distributed", ...]

Advanced Usage

from aerrik import TaskComplexity, ActivationPolicy

breakdown = TaskComplexity.classify_detailed("Build SaaS with multi-tenancy")

# Check policy
if breakdown.policy == ActivationPolicy.COMPLEX:
    print("This is a complex task!")

# Access signal dimensions
print(f"Architecture: {breakdown.signals.architecture}")  # 8.5
print(f"Security: {breakdown.signals.security}")          # 0.0
print(f"Integration: {breakdown.signals.integration}")    # 0.0
print(f"Concern count: {breakdown.signals.concern_count}") # 2

# Check specific signals
if breakdown.signals.architecture > 5:
    print("Enable architecture review")

if breakdown.signals.security > 5:
    print("Enable security review")

---

🤖 For AI Agent Developers

AERRIK is designed to be integrated into AI coding agents as a pre-execution routing layer.

Integration Architecture

User Task
    ↓
AERRIK (classify)
    ↓
SIMPLE | MEDIUM | COMPLEX
    ↓
Agent Strategy Selection
    ↓
Planning → Tool Selection → Code Generation → Testing

Strategy Mapping Example

from aerrik import TaskComplexity

def get_agent_strategy(task_description: str) -> dict:
    """Map AERRIK classification to agent execution strategy."""
    breakdown = TaskComplexity.classify_detailed(task_description)
    
    strategies = {
        "simple": {
            "planning_steps": 1,
            "max_tools": 3,
            "review_required": False,
            "test_depth": "unit_only",
            "architecture_review": False,
        },
        "medium": {
            "planning_steps": 3,
            "max_tools": 8,
            "review_required": True,
            "test_depth": "unit_and_integration",
            "architecture_review": False,
        },
        "complex": {
            "planning_steps": 5,
            "max_tools": 15,
            "review_required": True,
            "test_depth": "full_suite",
            "architecture_review": True,
            "security_review": True,
        },
    }
    return strategies[breakdown.policy.value]

Using Signal Dimensions

breakdown = TaskComplexity.classify_detailed(task)

# Fine-grained decisions based on signals
if breakdown.signals.security > 5:
    enable_security_review()

if breakdown.signals.architecture > 5:
    enable_architecture_planning()

if breakdown.signals.realtime > 0:
    enable_realtime_considerations()

if breakdown.signals.concern_count >= 3:
    enable_task_decomposition()

Important: AERRIK classifies complexity. The agent decides the final execution strategy. AERRIK does not generate code, run tools, or execute tasks on its own.

---

🔬 How It Works

Signal Detection

AERRIK analyzes task descriptions across 8 independent signal dimensions:

Classification Pipeline

Task Description
    ↓
┌──────────────────────────────────────────┐
│  STEP 0: Simple Context Detection       │
│  (health check, status endpoint, etc.)   │
├──────────────────────────────────────────┤
│  STEP 1: Negative Signal Detection      │
│  (simple, basic, single, utility)        │
├──────────────────────────────────────────┤
│  STEP 2: Strong Signal Detection        │
│  Architecture, Domain, Workflow, Infra   │
├──────────────────────────────────────────┤
│  STEP 3: Feature Signal Scoring         │
│  With cross-signal deduplication         │
├──────────────────────────────────────────┤
│  STEP 4-7: Multi-Dimensional Scoring    │
│  Integration, Security, Data, Realtime   │
├──────────────────────────────────────────┤
│  STEP 8: Multi-Concern Analysis         │
│  Count independent implementation areas  │
├──────────────────────────────────────────┤
│  STEP 9: Scope Level Detection          │
│  LOCAL → FEATURE → SYSTEM → PLATFORM    │
├──────────────────────────────────────────┤
│  STEP 10-12: Overrides & Adjustments    │
│  Architecture singletons, context rules  │
├──────────────────────────────────────────┤
│  STEP 13: Policy Mapping                │
│  LOCAL→SIMPLE  FEATURE→MEDIUM           │
│  SYSTEM→COMPLEX  PLATFORM→COMPLEX       │
└──────────────────────────────────────────┘
    ↓
SIMPLE | MEDIUM | COMPLEX

Key Design Decisions

• Strong Architecture Singletons: A single "distributed" or "event-driven" signal is strong enough to prevent SIMPLE classification
• False-Positive Suppression: "form" inside "format" or "list" inside "wishlist" are detected and suppressed
• Context-Aware Detection: "health check" ≠ "health data"; "landing page" forces simple regardless of domain
• Component Context: "comparison table component" is recognized as a simple UI element

---

📊 Validation Results

AERRIK v5.4 has been validated against 480 tasks across multiple test suites:

Unseen Validation — Per-Class Metrics

Generalization Proof

The 28.6 percentage point improvement on unseen tasks demonstrates genuine generalization — not benchmark overfitting.

---

🏗️ Architecture

Engine Architecture

AERRIK has three core engines:

Task Description
    ↓
┌──────────────────────────────────────┐
│  Routing Engine (routing_engine.py)  │
│  Classifies: SIMPLE/MEDIUM/COMPLEX   │
│  Output: RoutingBreakdown            │
└──────────────┬───────────────────────┘
               ↓
┌──────────────────────────────────────┐
│  Risk Engine (risk_engine.py)        │
│  Scores: 0-10 risk level             │
│  Output: RiskBreakdown               │
└──────────────┬───────────────────────┘
               ↓
┌──────────────────────────────────────┐
│  Policy Engine (policy_engine.py)    │
│  Decides: execution policy           │
│  Output: PolicyDecision              │
└──────────────────────────────────────┘

Package Structure

aerrik/
├── pyproject.toml          # Package configuration
├── README.md               # This file
├── LICENSE                 # MIT License
├── CHANGELOG.md            # Version history
│
├── src/
│   └── aerrik/
│       ├── __init__.py     # Public API
│       ├── __main__.py     # python -m aerrik
│       ├── version.py      # Version: 5.4.0
│       │
│       ├── engines/        # Core intelligence engines
│       │   ├── routing_engine.py
│       │   ├── risk_engine.py
│       │   └── policy_engine.py
│       │
│       └── cli/            # Command-line interface
│           ├── main.py
│           └── formatting.py
│
├── tests/                  # Test suites
│   ├── test_launch_checklist.py
│   ├── security_audit.py
│   └── test_routing_engine_v51.py
│
└── benchmark/              # Benchmarking system
    ├── tasks_300.py
    └── benchmark_300.py

---

🧪 Testing

Run all tests:

# Core tests (155 tests)
python3 tests/test_launch_checklist.py

# Security tests (18 tests)
python3 tests/security_audit.py

# Regression tests (100 tests)
python3 tests/test_routing_engine_v51.py

# Benchmark (180 tasks)
python3 benchmark/benchmark_300.py

# Unseen validation (300 tasks)
python3 run_unseen_validation.py

---

📐 Design Principles

1. No Benchmark Hardcoding — The router never matches specific benchmark task descriptions. All classification is based on general signal detection.

2. Validation-First Development — Every change is validated against benchmark, regression, security, and unseen test suites before acceptance.

3. Generalization Over Perfection — A 95% score on unseen tasks is more valuable than 100% on known tasks.

4. Deterministic Classification — Same input always produces same output. No randomness, no LLM dependency in the routing engine.

5. Context-Aware Signals — "health check" ≠ "health data"; "landing page" ≠ "SaaS platform"; context matters.

6. Security Preservation — All 18 security tests must pass with every change. Security is non-negotiable.

7. Explainable Results — Every classification includes human-readable reasons explaining why the task was classified as it was.

---

⚠️ Limitations

AERRIK is a task complexity classifier, not a complete AI system. Here's what it does NOT do:

• ❌ Does not write code — It classifies tasks; agents write code
• ❌ Does not understand all software requirements — It detects patterns in task descriptions
• ❌ Is not an autonomous coding agent — It's a routing layer for agents
• ❌ May have edge cases — 14 out of 300 unseen tasks were misclassified (4.7%)
• ❌ English-only — Currently optimized for English task descriptions
• ❌ Text-based only — Cannot analyze images, diagrams, or code directly
• ❌ No LLM required — The routing engine is standalone and deterministic

Known Edge Cases (v5.4)

• Non-adjacent compound signals (e.g., "ping endpoint for monitoring")
• Novel vocabulary not yet in signal dictionaries
• Tasks that genuinely sit at complexity boundaries

---

🗺️ Roadmap

✅ Current (v5.4)

• Task complexity routing engine
• 8-dimensional signal detection
• Strong architecture singletons
• False-positive suppression
• Context-aware classification
• 95.3% unseen validation accuracy
• 100% benchmark accuracy
• 18/18 security tests passing
• PyPI package
• CLI with Rich formatting
• JSON output support

🔜 Next

• Stable public Python API with versioning (v1.0)
• Agent strategy adapter library
• More adversarial unseen validation datasets
• Multi-language task description support
• Batch classification API

🔮 Future

• Pluggable routing policies (customizable signal weights)
• LLM-assisted classification mode (hybrid deterministic + LLM)
• Code-aware routing (analyze actual code, not just descriptions)
• Real-time routing API endpoint
• Integration adapters for popular agent frameworks (LangChain, AutoGPT, etc.)
• Community-contributed signal packs
• Web UI for task visualization

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines.

Golden Rule: Do NOT improve benchmark accuracy by hardcoding benchmark task descriptions.

Quick Start for Contributors

git clone https://github.com/aerrik-studio/aerrik.git
cd aerrik
pip install -e ".[dev]"

# Make your changes, then run ALL tests:
python3 tests/test_launch_checklist.py
python3 tests/security_audit.py
python3 tests/test_routing_engine_v51.py
python3 benchmark/benchmark_300.py
python3 run_unseen_validation.py

---

🔒 Security

If you discover a security vulnerability, please report it responsibly.

• Use GitHub Security Advisories to report vulnerabilities privately
• Do NOT open public issues for security vulnerabilities
• See SECURITY.md for details

---

📄 License

MIT License — see LICENSE for details.

---

🙏 Credits

Created by: Anmol Singh / AERRIK Studio

Built with: Python, Rich, Typer, Hatch

Tested with: 480 tasks across 5 validation suites

---

📚 Documentation

• Installation Guide — Detailed installation instructions
• Agent Integration Guide — How to integrate with AI agents
• Architecture Deep Dive — Technical architecture details
• API Reference — Complete API documentation

---