Metadata-Version: 2.4
Name: agentic-software-engineer
Version: 0.1.4
Summary: Agent-driven software engineering framework — transforms work tickets into code, tests, docs, and deployments through specialized LLM agents.
Project-URL: Homepage, https://github.com/AG4MA/agentic_software_engineer
Project-URL: Repository, https://github.com/AG4MA/agentic_software_engineer
Project-URL: Issues, https://github.com/AG4MA/agentic_software_engineer/issues
Author: AG4MA
License: MIT License
        
        Copyright (c) 2026 AG4MA
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,ai,automation,llm,mcp,software-engineering
Classifier: Development Status :: 3 - Alpha
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
Classifier: Topic :: Software Development :: Code Generators
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: aiosqlite<1,>=0.20
Requires-Dist: anyio<5,>=4.0
Requires-Dist: litellm<2,>=1.40
Requires-Dist: mcp<2,>=1.0
Requires-Dist: pydantic<3,>=2.5
Requires-Dist: python-dotenv<2,>=1.0
Requires-Dist: rich<14,>=13.0
Requires-Dist: tiktoken<1,>=0.7
Requires-Dist: typer<1,>=0.12
Provides-Extra: dev
Requires-Dist: mypy<2,>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio<1,>=0.23; extra == 'dev'
Requires-Dist: pytest-cov<6,>=5.0; extra == 'dev'
Requires-Dist: pytest<9,>=8.0; extra == 'dev'
Requires-Dist: ruff<1,>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# ASE — Agentic Software Engineer

[![PyPI](https://img.shields.io/pypi/v/agentic-software-engineer.svg)](https://pypi.org/project/agentic-software-engineer/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

**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

```bash
pip install agentic-software-engineer
```

## Uso

### 1. Vai nella root del tuo progetto

```bash
cd /path/to/mio-progetto
```

### 2. Configura la chiave API

Crea un file `.env` nella root del progetto:

```bash
ANTHROPIC_API_KEY=sk-ant-la-tua-chiave
```

### 3. Inizializza ASE

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

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

```bash
ase onboard --auto-only
```

### 5. Dai lavoro agli agenti

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

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

```bash
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 resume` | Riprende ticket interrotti dalla sessione precedente |
| `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

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

### Session Resume

Se il processo muore, niente si perde. Tutto lo stato è in SQLite (`.ase/ase.db`):
ticket, assignment, plan, retry count, escalation level.

Al prossimo `ase start` o `ase resume`, ASE:
1. Cerca ticket in `in_progress` o `triaged`
2. Legge gli assignment dal DB — chi ha finito, chi era in corso
3. Riprende il plan da dove si era fermato (step completati = skip, falliti = retry)

```bash
# Resume esplicito (boot, resume, wait, shutdown)
ase resume

# Oppure: ase start fa resume automatico all'avvio
ase start
```

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

```bash
# 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](LICENSE)
