Metadata-Version: 2.4
Name: agentic-software-engineer
Version: 0.1.2
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

[![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)

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

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

### 2. Configura la chiave API

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

### 3. Inizializza un progetto cliente

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

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

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

```bash
# Stato ticket
ase status nome-cliente

# Metriche e costi
ase metrics nome-cliente

# Versione
ase version
```

## Configurazione — ase.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
```

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

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

# Test
pytest

# Lint
ruff check src/ tests/

# Type check
mypy src/ase/
```

## License

[MIT](LICENSE)
