clean-agents 0.2.0

Design, plan, and harden production-grade agentic AI systems

CLean-agents

Design, plan, and harden production-grade agentic AI systems.

CLean-agents is a Python CLI + SDK for designing multi-agent architectures with evidence-backed recommendations, security analysis, cost optimization, and code scaffolding — from single agents to enterprise-scale swarms.

Clean (well-designed, no unnecessary complexity) + Lean (efficient, no over-engineering) = CLean-agents

Quick Start

pip install clean-agents

# Interactive architecture design session
clean-agents design

# With AI-enhanced mode (multi-turn with Claude)
export ANTHROPIC_API_KEY=sk-ant-...
clean-agents design --ai

# Non-interactive
clean-agents design --desc "Multi-agent customer support system with HIPAA compliance" --no-interactive

What It Does

Describe the system you want to build in plain language. CLean-agents will:

1. Classify your system (single agent → pipeline → multi-agent → complex)
2. Recommend an architecture pattern backed by benchmarks and research
3. Generate a full blueprint: agents, models, guardrails, infrastructure, compliance
4. Iterate via multi-turn AI conversations (with --ai flag)
5. Export as YAML, JSON, or interactive HTML report

CLI Commands

clean-agents init          Initialize project directory
clean-agents design        Interactive architecture session
clean-agents blueprint     View/export the current blueprint
clean-agents shield        Security hardening analysis (7 attack categories)
clean-agents cost          Cost simulator with monthly projections
clean-agents eval          Generate evaluation suite per agent
clean-agents observe       Observability blueprint (metrics, traces, alerts)
clean-agents models        Benchmark-based model selection
clean-agents prompts       Generate optimized prompt templates
clean-agents migrate       Migration advisor between frameworks
clean-agents comply        Regulation-to-component compliance mapping
clean-agents load          Load testing scenarios and configs
clean-agents scaffold      Generate starter code (LangGraph, CrewAI, Claude SDK, OpenAI SDK)
clean-agents plugin list   List installed plugins
clean-agents plugin run    Run a specific plugin
clean-agents plugin init   Scaffold a new plugin
clean-agents serve         Start API server (REST or MCP)

AI-Enhanced Mode

With ANTHROPIC_API_KEY set, commands gain AI superpowers:

• design --ai — Multi-turn design iteration with Claude. Refine your architecture conversationally.
• shield --ai — Deep security analysis: attack scenarios, vulnerability discovery, hardening checklists.
• prompts --ai — Production-quality system prompts generated by Claude instead of templates.

CLean-shield: Security Analysis

7 attack categories analyzed against your blueprint:

ID	Category	Checks
ATK-1	Prompt Injection	System prompt isolation, input sanitization, instruction hierarchy
ATK-2	Jailbreaking	Role boundaries, output monitoring, multi-turn tracking
ATK-3	Data Extraction	Output filtering, system prompt protection, RAG access control
ATK-4	Agent Manipulation	Inter-agent auth, message validation, privilege boundaries
ATK-5	Tool Abuse	Permission model, parameter validation, execution sandboxing
ATK-6	Denial of Service	Rate limiting, token budgets, recursion depth limits
ATK-7	Privacy Violation	PII detection, output sanitization, context isolation

Plugin System

Extend CLean-agents with custom analysis, transformations, or scaffolding:

from clean_agents.modules.base import AnalysisPlugin, PluginManifest, PluginResult, PluginType

class MyPlugin(AnalysisPlugin):
    def manifest(self):
        return PluginManifest(name="my-plugin", version="1.0", description="Custom analysis", plugin_type=PluginType.ANALYSIS)

    def analyze(self, blueprint, config=None):
        findings = []
        for agent in blueprint.agents:
            if agent.token_budget > 10000:
                findings.append({"agent": agent.name, "severity": "warning", "message": "High token budget"})
        return PluginResult("my-plugin", success=True, findings=findings, summary=f"{len(findings)} findings")

Three plugin types: AnalysisPlugin (read-only inspection), TransformPlugin (modify blueprints), ScaffoldPlugin (generate files).

Discovery sources: Python entry points (clean_agents.plugins), ~/.config/clean-agents/plugins/, .clean-agents/plugins/.

Python SDK

from clean_agents import Blueprint, Recommender, Config

# Generate a blueprint programmatically
recommender = Recommender()
blueprint = recommender.recommend("Multi-agent RAG system for legal document analysis with GDPR compliance")

# Inspect the result
print(blueprint.name)
print(blueprint.to_yaml())
print(f"Cost per request: ${blueprint.estimated_cost_per_request():.4f}")

# Access agents
for agent in blueprint.agents:
    print(f"{agent.name}: {agent.role} ({agent.model.primary})")

# Save and load
blueprint.save("my-blueprint.yaml")
loaded = Blueprint.load("my-blueprint.yaml")

API Server

# REST API
clean-agents serve --port 8000

# MCP server (for IDE integration)
clean-agents serve --mode mcp

REST endpoints: POST /api/design, GET /api/blueprint, POST /api/shield, POST /api/cost, POST /api/scaffold, GET /api/health.

Architecture Decision Engine

4-layer recommendation pipeline:

1. System Classification — Signals from description → single / pipeline / multi-agent / complex
2. Pattern Selection — Supervisor hierarchical / blackboard-swarm / hybrid / pipeline
3. Framework Selection — LangGraph / CrewAI / Claude Agent SDK / OpenAI Agents SDK / custom
4. Transversal Components — Memory, reasoning patterns, guardrails, observability, compliance

Every recommendation comes with design decisions explaining the rationale.

Installation Options

# Core (CLI + SDK)
pip install clean-agents

# With API server
pip install "clean-agents[api]"

# With all optional integrations
pip install "clean-agents[all]"

# Development
pip install "clean-agents[dev]"

Built-in Plugins

• Token Budget Auditor — flags agents with oversized or undersized token budgets
• Redundancy Detector — identifies potentially redundant agent pairs
• Cost Optimizer — auto-downgrades models where premium isn't needed (saves ~14%)

Crafters (Skills / MCPs / Tools / Plugins)

Design and ship production-quality Claude Code skills with the same opinionated-consultant flow.

# Non-interactive from a one-liner
clean-agents skill design "detect markdown tables in prompts" -o ./my-skill

# Validate (L1+L2+L3) — add --ai --eval for Claude-backed checks
clean-agents skill validate ./my-skill

# Bidirectional: design a skill for a specific agent in a blueprint
clean-agents skill design --for-agent risk_evaluator \
  --blueprint .clean-agents/blueprint.yaml -o ./risk-patterns

MCPs, Tools, and Plugins follow the same <noun> <verb> shape. See docs/crafters/README.md for the full flow.

License

MIT — see LICENSE.

---

Built by @Leandrozz