Metadata-Version: 2.4
Name: aerrik
Version: 5.4.0
Summary: AI Task Complexity Routing Engine - Helps AI coding agents choose the right execution strategy
Project-URL: Homepage, https://github.com/aerrik-studio/aerrik
Project-URL: Documentation, https://github.com/aerrik-studio/aerrik#readme
Project-URL: Repository, https://github.com/aerrik-studio/aerrik
Project-URL: Issues, https://github.com/aerrik-studio/aerrik/issues
Project-URL: Changelog, https://github.com/aerrik-studio/aerrik/blob/main/CHANGELOG.md
Author-email: Anmol Singh <anmol@aerrik.studio>
Maintainer-email: AERRIK Studio <studio@aerrik.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,cli,complexity,developer-tools,routing,software-engineering,task-classification
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: rich<14.0.0,>=13.7.0
Requires-Dist: typer<1.0.0,>=0.9.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Provides-Extra: llm
Requires-Dist: anthropic<1.0.0,>=0.25.0; extra == 'llm'
Requires-Dist: openai<2.0.0,>=1.30.0; extra == 'llm'
Requires-Dist: pydantic-settings<2.0.0,>=2.1.0; extra == 'llm'
Requires-Dist: pydantic<3.0.0,>=2.5.0; extra == 'llm'
Requires-Dist: python-dotenv<2.0.0,>=1.0.0; extra == 'llm'
Description-Content-Type: text/markdown

# 🧠 AERRIK

**AI Task Complexity Routing Engine**

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

[![PyPI version](https://img.shields.io/pypi/v/aerrik.svg)](https://pypi.org/project/aerrik/)
[![Python](https://img.shields.io/pypi/pyversions/aerrik.svg)](https://pypi.org/project/aerrik/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-473%20passed-brightgreen.svg)](#validation-results)

---

## 🚀 Quick Start

### Installation

```bash
pip install aerrik
```

### Classify a Task

```bash
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

| Task | Classification |
|------|----------------|
| `"Create a simple button component"` | **SIMPLE** |
| `"Build a user profile system with database"` | **MEDIUM** |
| `"Design a distributed event-driven system"` | **COMPLEX** |

---

## 💡 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:

| Complexity | Agent Strategy |
|---|---|
| **SIMPLE** | Minimal planning, direct implementation, fewer tools, fast execution |
| **MEDIUM** | Structured planning, feature decomposition, database/API awareness, validation |
| **COMPLEX** | Architecture planning, risk analysis, system decomposition, security review, testing strategy |

---

## 📦 Installation

### From PyPI (Recommended)

```bash
pip install aerrik
```

### Upgrade

```bash
pip install --upgrade aerrik
```

### Verify Installation

```bash
aerrik --version
# Output: aerrik 5.4.0
```

### Development Installation

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

---

## 🎯 CLI Usage

### Classify a Task

```bash
aerrik classify "Create a REST API for tasks"
```

### JSON Output

```bash
aerrik classify "Build a payment system" --json
```

**Output:**
```json
{
  "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

```bash
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

```bash
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

```python
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

```python
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

```python
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

```python
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**:

| Dimension | What It Detects | Examples |
|---|---|---|
| **Scope** | Size of the task | button, form, dashboard, platform |
| **Architecture** | System design patterns | distributed, microservices, event-driven, CQRS |
| **Integration** | External service dependencies | Stripe, AWS, Kafka, Twilio |
| **Data** | Data persistence and sensitivity | database, PII, financial, health |
| **Security** | Authentication, encryption, compliance | OAuth2, JWT, encryption, GDPR |
| **Realtime** | Real-time communication needs | WebSocket, live, streaming |
| **Workflow** | Multi-step or multi-role processes | saga, compensation, versioning |
| **Concerns** | Number of independent implementation areas | Multiple dimensions active |

### 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:

| Test Suite | Tasks | Result | Status |
|---|---|---|---|
| **Existing Benchmark** | 180 | 100.0% | ✅ |
| **Regression Tests** | 100 | 100.0% | ✅ |
| **Security Tests** | 18 | 100.0% | ✅ |
| **300-Task Unseen Validation** | 300 | **95.3%** | ✅ |

### Unseen Validation — Per-Class Metrics

| Class | Precision | Recall | F1 Score |
|---|---|---|---|
| Simple | 0.969 | 0.940 | 0.954 |
| Medium | 0.907 | 0.970 | 0.937 |
| Complex | 0.990 | 0.950 | 0.969 |

### Generalization Proof

| Version | Benchmark | Unseen Validation | Gap |
|---|---|---|---|
| v5.3 | 100.0% | 66.7% | 33.3pp |
| **v5.4** | **100.0%** | **95.3%** | **4.7pp** |

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:

```bash
# 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)
- [x] Task complexity routing engine
- [x] 8-dimensional signal detection
- [x] Strong architecture singletons
- [x] False-positive suppression
- [x] Context-aware classification
- [x] 95.3% unseen validation accuracy
- [x] 100% benchmark accuracy
- [x] 18/18 security tests passing
- [x] PyPI package
- [x] CLI with Rich formatting
- [x] 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](CONTRIBUTING.md) for detailed guidelines.

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

### Quick Start for Contributors

```bash
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](SECURITY.md) for details

---

## 📄 License

MIT License — see [LICENSE](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](docs/installation.md) — Detailed installation instructions
- [Agent Integration Guide](docs/agent-integration.md) — How to integrate with AI agents
- [Architecture Deep Dive](docs/architecture.md) — Technical architecture details
- [API Reference](docs/api.md) — Complete API documentation

---

<div align="center">

**AERRIK** — *Complexity-aware routing for AI coding agents*

[⬆ Back to Top](#-aerrik)

</div>
