apipilot/AGENT.md

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 + configurazione + autorizzazione + esecuzione + size/timeout/errori.	Logiche di dominio applicativo (nomi di tabelle, entità, ruoli hardcoded).
apipilot/fastapi.py	install_apipilot, wiring FastAPI, endpoints HTTP opzionali.	Formati tool-calling specifici di provider LLM.
apipilot/openapi_parser.py	Parsing OpenAPI + generazione schema + validazione nomi duplicati.	Esecuzione runtime di endpoint.
apipilot/validation.py	Validazione argomenti via jsonschema.	Regole di business non standard.
apipilot/tool.py	CompositeTool + protocollo PilotTool.	Implementazioni specifiche di tool di dominio.
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

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