agentic-software-engineer 0.1.3

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

ASE — Agentic Software Engineer

Tu gli dici cosa fare, gli agenti lo fanno.

ASE è un framework che trasforma richieste in linguaggio naturale in codice, test, documentazione e deployment — tramite 11 agenti LLM specializzati che lavorano in autonomia sul tuo progetto. Tu supervisioni, loro eseguono.

Come Funziona

Tu: "Implementa API REST per utenti con JWT"
 │
 ▼
ASE: intake → analyzer → triage → orchestrator
 │
 ├─→ Backend Agent  → scrive codice
 ├─→ Testing Agent  → scrive test
 ├─→ Security Agent → audit JWT
 ├─→ Docs Agent     → documentazione
 │
 ▼
Output: codice, test, docs — tutto tracciato con costi e decision log

Non cloni niente. Installi ASE, lo punti al progetto del cliente, e gli dai istruzioni. Gli agenti fanno il resto.

Installa

pip install agentic-software-engineer

Uso

1. Vai nella root del tuo progetto

cd /path/to/mio-progetto

2. Configura la chiave API

Crea un file .env nella root del progetto:

ANTHROPIC_API_KEY=sk-ant-la-tua-chiave

3. Inizializza ASE

ase init

ASE crea una cartella .ase/ (nascosta e gitignored automaticamente):

• .ase/config.toml — configurazione agenti, modello, limiti
• .ase/ase.db — database SQLite per stato e tracking

4. Onboarding — insegna ad ASE il tuo progetto

ase onboard

ASE scansiona i file del progetto (README, package.json, Dockerfile, CI config…) e impara automaticamente tech stack, architettura, convenzioni. Per quello che non riesce a inferire, ti fa domande mirate.

Puoi anche fare solo auto-discovery senza domande:

ase onboard --auto-only

5. Dai lavoro agli agenti

ase submit "Aggiungi endpoint CRUD per i prodotti con validazione"

Il pipeline parte in automatico:

1. Intake — normalizza la richiesta, crea il ticket
2. Analyzer — capisce intent, complessità, scope
3. Triage — decide quali agenti servono, crea il plan
4. Orchestrator — esegue il plan rispettando le dipendenze
5. Agenti — Backend, Testing, Security, Docs… ognuno fa il suo
6. Review — gate configurabile (PR, manuale, auto-approve)

Tutto tracciato: ogni decisione, ogni tool call, ogni centesimo speso.

6. Monitora

# Stato dei ticket e degli agenti
ase status

# Costi e metriche
ase metrics

# Decision log completo
ase audit

# Audit filtrato per agente o ticket
ase audit --agent backend --last 20
ase audit --ticket T-001

# Segui gli eventi in tempo reale
ase audit --follow

7. Runtime persistente (opzionale)

Se vuoi tenere ASE in ascolto continuo per ricevere ticket:

ase start

Lancia i server MCP, connette il bridge, e resta in attesa. Utile quando integri ASE con altri sistemi di intake (webhook, bot, etc.).

CLI — Comandi Disponibili

Tutti i comandi lavorano dalla directory corrente. Basta essere nella root del progetto.

Comando	Cosa fa
ase init	Inizializza ASE nella directory corrente (crea .ase/)
ase onboard	Scopre e popola il contesto del progetto
ase submit "richiesta"	Invia lavoro agli agenti
ase start	Avvia il runtime in ascolto continuo
ase status	Mostra stato ticket e agenti
ase metrics	Costi, throughput, statistiche
ase audit	Decision log con filtri e follow mode
ase guide	Guida interattiva al framework
ase version	Versione installata

Agenti

Agente	Cosa fa
Analyzer	Analizza la richiesta: intent, complessità, scope
Triage	Decide quali agenti attivare e crea il plan di esecuzione
Backend	Implementa business logic, API, servizi
Frontend	Implementa UI e componenti
Testing	Scrive test unitari, integrazione, e2e
Security	Audit sicurezza, hardening, vulnerabilità
Database	Schema, migrazioni, query optimization
DevOps	CI/CD, container, deploy
Docs	Documentazione tecnica e API
Platform	Infrastruttura e piattaforma
Cloud	Servizi cloud e configurazione

Ogni agente ha il suo system prompt specializzato e un set di tool MCP dedicato. Gli agenti comunicano tramite il Bridge che traduce automaticamente le tool call verso il server MCP corretto (Operativo per lo stato runtime, Statico per il contesto progetto).

Configurazione — .ase/config.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

Fault Tolerance

3 livelli di recovery automatico:

1. L1 — Self-retry: l'agente ritenta con exponential backoff
2. L2 — Peer escalation: se l'agente fallisce, un altro prende il task
3. L3 — Human notification: se tutto fallisce, notifica l'umano

Memory & Knowledge Base

ASE impara lavorando. Dopo ogni ticket completato, il Memory Consolidator estrae automaticamente:

• Decisioni architetturali prese
• Gotcha e workaround scoperti
• Pattern e convenzioni osservate
• Quirk delle dipendenze

Queste osservazioni vengono deduplicate e salvate nella knowledge base del progetto. Gli agenti le usano nei ticket successivi per non ripetere errori e rispettare le convenzioni.

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)   │
            └──────────┘

Struttura Progetto

src/ase/
├── runtime.py              # Connettore centrale — wiring di tutti i componenti
├── cli/main.py             # CLI: init, start, submit, status, metrics, audit, guide, onboard
├── config/                 # TOML loader + Pydantic schema
├── db/                     # SQLite schema + connection factory
├── mcp/
│   ├── process.py          # MCP subprocess launcher (env sandboxing)
│   ├── operativo/          # Server MCP operativo (ticket, eventi, assignment, costi)
│   └── statico/            # Server MCP statico (tech stack, arch, convenzioni, KB)
├── agents/
│   ├── base.py             # Think-loop engine (LLM → tool calls → iterate)
│   ├── bridge.py           # LLM↔MCP bridge (tool routing per prefix)
│   ├── lifecycle.py        # Agent spawning, timeout, cancellazione
│   ├── prompts/            # System prompt per agente
│   └── specialized/        # Implementazioni agenti (11)
├── orchestrator/           # Engine + scheduler + fault tolerance (3 livelli)
├── onboarding/             # Context discovery + completeness check + memory consolidator
├── 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

Per chi contribuisce

# Clona e installa in dev mode
git clone https://github.com/AG4MA/agentic_software_engineer.git
cd agentic_software_engineer
pip install -e ".[dev]"

# Test
pytest

# Lint
ruff check src/ tests/

# Type check
mypy src/ase/

License

MIT