105 lines
6.5 KiB
Markdown
105 lines
6.5 KiB
Markdown
# 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
|
|
|