# AGENT.md — Istruzioni per agenti di sviluppo su ApiPilot

Questo documento definisce le regole e i confini per sviluppare e modificare ApiPilot, mantenendo la libreria generica, riutilizzabile e priva di riferimenti a domini specifici.

## 1. Architettura e confini dei moduli

ApiPilot ha un nucleo stabile e adattatori isolati per provider LLM:

| Modulo                                           | Responsabilità                                                                     | Non deve contenere                                                                 |
|--------------------------------------------------|-------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| [apipilot/core.py](apipilot/core.py)             | `ApiPilot` + configurazione + autorizzazione + esecuzione + size/timeout/errori.    | Logiche di dominio applicativo (nomi di tabelle, entità, ruoli hardcoded).         |
| [apipilot/fastapi.py](apipilot/fastapi.py)       | `install_apipilot`, wiring FastAPI, endpoints HTTP opzionali.                       | Formati tool-calling specifici di provider LLM.                                    |
| [apipilot/openapi_parser.py](apipilot/openapi_parser.py) | Parsing OpenAPI + generazione schema + validazione nomi duplicati.                  | Esecuzione runtime di endpoint.                                                    |
| [apipilot/validation.py](apipilot/validation.py) | Validazione argomenti via `jsonschema`.                                             | Regole di business non standard.                                                   |
| [apipilot/tool.py](apipilot/tool.py)             | `CompositeTool` + protocollo `PilotTool`.                                           | Implementazioni specifiche di tool di dominio.                                     |
| [apipilot/adapters/openai.py](apipilot/adapters/openai.py) | Adapter function calling OpenAI. | Qualsiasi dipendenza dal core oltre ToolDefinition/ExecuteResponse. |

Regola aurea: **Il nucleo non deve sapere di specifici provider LLM. Gli adapter non devono sapere di FastAPI.**

## 2. Installazione e test

```bash
# Setup
python -m venv .venv && source .venv/bin/activate
pip install -e ".[test,dev]"

# Test
pytest -q
pytest --cov=apipilot --cov-report=term-missing

# Controlli statici
ruff check apipilot tests examples
mypy apipilot
```

Tutti i nuovi moduli o funzionalità richiedono **test di regressione corrispondenti** in `tests/`.

## 3. Convenzioni di codice

- **Python 3.10+** come minimo. Usa `from __future__ import annotations` in ogni modulo.
- **Tipizza esplicitamente** parametri e ritorni pubblici; per interni usa la miglior stima.
- **Nessun riferimento a entità di dominio** nel core (es. `order`, `user`, `product` come nomi di parametri speciali o hardcoded, al di fuori di esempi e test).
- **Errori chiari**: usa la gerarchia in [apipilot/errors.py](apipilot/errors.py) e aggiungi sottotipi nuovi, non eccezioni grezze.
- **Messaggi di errore non vernacolari**: nomi tool duplicati devono indicare le due rotte coinvolte.
- **Dati non strutturati?** Sanifica sempre dimensione (`max_response_size`) e tempo (`timeout`).
- **Log granulari con tag**: introdurre logging se necessario, con tag `[apipilot:<modulo>]`. Non loggare credenziali, token, interi payload utente.

## 4. Convenzioni di sicurezza

- Non inoltrare mai header tecnologici (Authorization, X-*, Cookie) nello schema dei parametri dei tool. `openapi_parser` già salta i parametri `in: header`.
- L'utente AI non può scegliere URL/metodo HTTP/credenziali: tutto è fissato nella registrazione.
- Qualsiasi nuovo punto di ingresso (es. endpoints HTTP, WebSocket) deve rispettare `require_auth_for_http` e usare la `get_current_user` dell'app ospite.
- Prima di eseguire un tool controlla sempre `allow_tool(user, record)`: un tool negato è "non esistente" per quell'utente.
- Non serializzare direttamente eccezioni con traceback completo nella risposta `ExecuteResponse.error`.
- Non usare `exec`, `eval` o import dinamici basati su input agente.

## 5. Aggiungere un adapter per provider LLM

1. Crea `apipilot/adapters/<provider>.py`.
2. Implementa tre metodi statici:
   - `to_tools(tool_definitions: list[ToolDefinition]) -> list[<ProviderTool>]`
   - `parse_tool_call(tc_dict) -> tuple[tool_call_id, name, args_dict]`
   - `make_tool_result(tool_call_id, name, execute_response) -> <ProviderToolMessage>`
3. Esporta il modulo da [apipilot/adapters/__init__.py](apipilot/adapters/__init__.py).
4. Aggiungi test in `tests/test_adapters_<provider>.py`.
5. Non aggiungere dipendenze opzionali dal provider nel core.

## 6. Aggiungere un nuovo tipo di tool oltre a endpoint e CompositeTool

1. Estendi la classe [apipilot/tool.py](apipilot/tool.py) (protocollo `PilotTool`).
2. Il tipo deve avere `name`, `description`, un `run(args, user)` asincrono.
3. Estendi `ApiPilot.add_tool(...)` e `_run_*` in [apipilot/core.py](apipilot/core.py) in modo minimale.
4. Aggiungi test per autorizzazione, timeout, troncamento, argomenti non validi.

## 7. Endpoints HTTP — regole

- Default **disabilitati**. L'utente passa `expose_http_endpoints=True` per attivarli.
- Ogni nuovo endpoint HTTP deve:
  - usare `http_prefix` configurabile.
  - rispettare `require_auth_for_http` e la `get_current_user` dell'ospite.
  - restituire sempre JSON strutturato coerente con `ExecuteResponse` per le vie di errore.
  - NON introdurre route che eseguano codice arbitrario, script SQL, comandi shell.

## 8. Aggiornare documentazione e test

- Ogni modifica pubblica va tracciata in [CHANGELOG.md](CHANGELOG.md) in formato:
  ```
  ## YYYY-MM-DD — versione X.Y.Z
  - [file.py#L1-L99] descrizione modifica / nuova feature / bug fix.
  ```
- Ogni nuova feature pubblica va documentata in [README.md](README.md) con un esempio minimo.
- `CLAUDE.md` rimanda a questo documento per le regole comuni; aggiungi in `CLAUDE.md` solo note specifiche per Claude se diverse dalle regole generali.
- I test devono coprire: percorsi happy, autorizzazione negata, tool sconosciuti, argomenti non validi, errori dell'endpoint, timeout, troncamento, tool composti, adapter.

## 9. Processo di modifica suggerito per l'agente

1. Leggi [CHANGELOG.md](CHANGELOG.md) e i test per capire l'impatto.
2. Modifica il modulo target.
3. Aggiungi/aggiorna test case.
4. Esegui `pytest -q && ruff check apipilot tests examples`.
5. Aggiorna CHANGELOG.md e README.md.
6. Non fare commit di token, chiavi, o payload di clienti.
7. always update documents