Metadata-Version: 2.4
Name: clean-agents
Version: 0.1.0
Summary: Design, plan, and harden production-grade agentic AI systems
Project-URL: Homepage, https://github.com/leansroasas/clean-agents
Project-URL: Documentation, https://github.com/leansroasas/clean-agents#readme
Project-URL: Repository, https://github.com/leansroasas/clean-agents
Project-URL: Issues, https://github.com/leansroasas/clean-agents/issues
Project-URL: Changelog, https://github.com/leansroasas/clean-agents/blob/main/CHANGELOG.md
Author-email: Leandro <leansroasas@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,architecture,blueprint,claude,crewai,guardrails,langgraph,llm,multi-agent,openai,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer[all]>=0.12.0
Provides-Extra: ai
Requires-Dist: anthropic>=0.40.0; extra == 'ai'
Provides-Extra: all
Requires-Dist: anthropic>=0.40.0; extra == 'all'
Requires-Dist: fastapi>=0.115; extra == 'all'
Requires-Dist: garak>=0.9; extra == 'all'
Requires-Dist: locust>=2.24; extra == 'all'
Requires-Dist: openai>=1.50; extra == 'all'
Requires-Dist: opentelemetry-api>=1.25; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.25; extra == 'all'
Requires-Dist: ragas>=0.2; extra == 'all'
Requires-Dist: uvicorn>=0.30; extra == 'all'
Provides-Extra: api
Requires-Dist: fastapi>=0.115; extra == 'api'
Requires-Dist: uvicorn>=0.30; extra == 'api'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: eval
Requires-Dist: ragas>=0.2; extra == 'eval'
Provides-Extra: load
Requires-Dist: locust>=2.24; extra == 'load'
Provides-Extra: observe
Requires-Dist: opentelemetry-api>=1.25; extra == 'observe'
Requires-Dist: opentelemetry-sdk>=1.25; extra == 'observe'
Provides-Extra: openai
Requires-Dist: openai>=1.50; extra == 'openai'
Provides-Extra: security
Requires-Dist: garak>=0.9; extra == 'security'
Description-Content-Type: text/markdown

# 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

```bash
pip install clean-agents
```

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

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

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

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

```bash
# 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%)

## License

MIT — see [LICENSE](LICENSE).

---

Built by [@leansroasas](https://github.com/leansroasas)
