agentic-software-engineer 0.1.2

Agent-driven software engineering framework — transforms work tickets into code, tests, docs, and deployments through specialized LLM agents.

ASE — Agentic Software Engineer

Framework agent-driven che trasforma richieste di lavoro in codice, test, documentazione e deployment tramite agenti LLM specializzati — tutto supervisionato, tutto tracciato.

Features

• 11 Agenti Specializzati — Analyzer, Triage, Backend, Frontend, Testing, Security, Database, DevOps, Docs, Platform, Cloud — ognuno con il suo system prompt e set di tool dedicato.
• MCP Servers — Operativo (stato runtime, ticket, eventi, assignment) + Statico (profilo azienda, tech stack, architettura, convenzioni, blueprint, knowledge base). Entrambi come subprocessi stdio.
• Bridge LLM↔MCP — Converte automaticamente i tool MCP in formato OpenAI function-calling per litellm e ruota le risposte verso il server giusto.
• Orchestrator — Task graph execution con dependency resolution e parallelismo. Spawna agenti in base alle dipendenze soddisfatte.
• Fault Tolerance 3 Livelli — L1: self-retry con exponential backoff, L2: peer escalation verso agente alternativo, L3: notifica umana.
• Event Bus — Pub/sub persistence-first (eventi salvati in SQLite via MCP, polling con cursore). Zero dipendenze esterne.
• Decision Log — Ogni azione agente è registrata: reasoning, tool usato, modello, token, costo, durata.
• Cost Tracking — Limite per-ticket e giornaliero. Ogni chiamata LLM è tracciata con costo USD.
• Human-in-the-Loop — Review gates configurabili (PR, manuale, auto-approve).
• ASE Runtime — Connettore centrale che chiude il cerchio: config → MCP → bridge → LLM → agenti → orchestrator → output.

Quick Start

1. Installa

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

2. Configura la chiave API

cp .env.example .env
# Edita .env e aggiungi la tua chiave:
# ANTHROPIC_API_KEY=sk-ant-...

3. Inizializza un progetto cliente

ase init nome-cliente

Questo crea:

• projects/nome-cliente/ase.toml — configurazione
• projects/nome-cliente/.ase/ase.db — database SQLite
• projects/nome-cliente/.env.example — template variabili ambiente

4. Personalizza la configurazione

Edita projects/nome-cliente/ase.toml per il cliente specifico: modello LLM, agenti abilitati, limiti di costo, metodo di review.

5. Avvia il runtime

ase start nome-cliente

Questo lancia i server MCP come subprocessi, connette il bridge, avvia l'event bus e mette il sistema in ascolto.

6. Invia lavoro

ase submit nome-cliente "Implementa API REST per gestione utenti con JWT"

Il pipeline completo parte automaticamente: intake → normalize → analyzer → triage → orchestrator → agenti → review

7. Controlla lo stato

# Stato ticket
ase status nome-cliente

# Metriche e costi
ase metrics nome-cliente

# Versione
ase version

Configurazione — ase.toml

[project]
name = "my-api"
description = "REST API per gestione utenti"

[llm]
default_model = "anthropic/claude-sonnet-4-20250514"
cost_limit_per_ticket_usd = 5.00
cost_limit_daily_usd = 100.00

[agents]
enabled = ["analyzer", "triage", "backend", "testing"]

[agents.model_overrides]
triage = "anthropic/claude-sonnet-4-20250514"

[fault_tolerance]
max_self_retries = 3
max_peer_escalations = 2

[hil]
review_method = "pr"   # pr | manual | auto-approve

Architettura

ase submit "Implementa feature X"
        │
        ▼
  ┌─────────────┐
  │   Intake     │  normalize + create ticket via MCP
  │  Normalizer  │
  └──────┬──────┘
         ▼
  ┌─────────────┐
  │  Analyzer   │  capisce intent, complessità, scope
  │   Agent     │
  └──────┬──────┘
         ▼
  ┌─────────────┐     ┌──────────────┐
  │   Triage    │────▶│ Orchestrator │
  │   Agent     │     │ (task graph) │
  └─────────────┘     └──────┬───────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        ┌──────────┐   ┌──────────┐   ┌──────────┐
        │ Backend  │   │ Testing  │   │  Docs    │
        │  Agent   │   │  Agent   │   │  Agent   │
        └────┬─────┘   └────┬─────┘   └────┬─────┘
             │              │              │
             ▼              ▼              ▼
     ┌─────────────────────────────────────────┐
     │    MCPBridge (tool routing by prefix)    │
     └─────────────┬───────────────────────────┘
                   │
       ┌───────────┼───────────┐
       ▼                       ▼
 ┌───────────┐          ┌───────────┐
 │ Operativo │          │  Statico  │
 │  (runtime │          │ (project  │
 │   state)  │          │  context) │
 └─────┬─────┘          └─────┬─────┘
       │                      │
       └──────────┬───────────┘
                  ▼
            ┌──────────┐
            │  SQLite  │
            │  (WAL)   │
            └──────────┘

Componenti chiave

Componente	File	Ruolo
Runtime	ase/runtime.py	Connettore centrale, wiring di tutti i componenti
MCPBridge	ase/agents/bridge.py	Routing tool call verso il server MCP corretto
MCP Process Manager	ase/mcp/process.py	Lancia MCP servers come subprocessi stdio
Operativo Server	ase/mcp/operativo/server.py	Ticket, assignment, eventi, decision log, costi
Statico Server	ase/mcp/statico/server.py	Profilo azienda, tech stack, architettura, convenzioni
BaseAgent	ase/agents/base.py	Think-loop engine (LLM → tool calls → iterate)
Lifecycle Manager	ase/agents/lifecycle.py	Spawn, timeout, cancellazione agenti
Orchestrator	ase/orchestrator/engine.py	Esecuzione plan con dependency graph
FaultHandler	ase/orchestrator/fault.py	Recovery 3 livelli (retry → peer → human)
EventBus	ase/events/bus.py	Pub/sub persistence-first via MCP polling
LLM Client	ase/llm/client.py	litellm wrapper con retry e cost tracking

Agenti disponibili

Agente	Tipo	Ruolo
Analyzer	analyzer	Analisi intent e complessità del ticket
Triage	triage	Routing e creazione execution plan
Backend	backend	Implementazione business logic e API
Frontend	frontend	Implementazione UI
Testing	testing	Test unitari, integrazione, e2e
Security	security	Audit sicurezza e hardening
Database	database	Schema, migrazioni, query
DevOps	devops	CI/CD, containerizzazione, deploy
Docs	docs	Documentazione tecnica
Platform	platform	Infrastruttura e piattaforma
Cloud	cloud	Servizi cloud e configurazione

Struttura Progetto

src/ase/
├── runtime.py              # Connettore centrale
├── cli/main.py             # CLI: init, start, submit, status, metrics
├── config/                 # TOML loader + Pydantic schema
├── db/                     # SQLite schema + connection factory
├── mcp/
│   ├── process.py          # MCP subprocess launcher
│   ├── operativo/          # Server MCP operativo (ticket, eventi, ...)
│   └── statico/            # Server MCP statico (tech stack, arch, ...)
├── agents/
│   ├── base.py             # Think-loop engine
│   ├── bridge.py           # LLM↔MCP bridge
│   ├── lifecycle.py        # Agent spawning/monitoring
│   ├── prompts/            # System prompt per agente
│   └── specialized/        # Implementazioni agenti
├── orchestrator/           # Engine + scheduler + fault tolerance
├── events/                 # Event bus + handler registry
├── intake/                 # Normalizzazione input + ticket factory
├── llm/                    # litellm client + cost tracking
├── audit/                  # Decision log
├── hil/                    # Human-in-the-loop (review, staging, notifiche)
└── scaffold/               # Scaffolding nuovi progetti

Development

# Installa dipendenze dev
pip install -e ".[dev]"

# Test
pytest

# Lint
ruff check src/ tests/

# Type check
mypy src/ase/

License

MIT