first

2026-09-24 05:19:06 -04:00
commit 2cec225860
27 changed files with 2640 additions and 0 deletions
@@ -0,0 +1,75 @@
+Sviluppa **ApiPilot**, una libreria Python riutilizzabile che trasforma operazioni di un’applicazione FastAPI in tool eseguibili da agenti AI. La libreria non deve contenere riferimenti a progetti, API o domini applicativi specifici.
+
+## Obiettivo
+
+Lo sviluppatore abilita un endpoint esistente tramite `x-apipilot` nel decorator FastAPI. ApiPilot genera le definizioni dei tool, valida ed esegue le chiamate e restituisce risultati strutturati. L’agente decide quando usare un tool; ApiPilot ne gestisce l’esecuzione.
+
+## Prima di implementare
+
+Esamina struttura del repository, versioni Python e FastAPI, convenzioni di autenticazione e test. Definisci un piano breve e segui le convenzioni del progetto.
+
+## Interfaccia desiderata
+
+```python
+from apipilot.fastapi import install_apipilot
+
+pilot = install_apipilot(
+    app,
+    get_current_user=get_current_user,
+)
+
+tools = pilot.tools_for(user)
+result = await pilot.execute(
+    user=user,
+    name="list_items",
+    arguments={"category": "active"},
+)
+```
+
+Un endpoint deve poter essere abilitato così:
+
+```python
+@router.get(
+    "/items",
+    summary="Elenca gli elementi",
+    openapi_extra={
+        "x-apipilot": {
+            "enabled": True,
+            "name": "list_items",
+            "description": (
+                "Cerca gli elementi disponibili. Usalo quando "
+                "l'utente chiede un elenco o cerca elementi "
+                "di una categoria."
+            ),
+        }
+    },
+)
+async def list_items(category: str | None = None):
+    ...
+```
+
+Puoi migliorare l’interfaccia proposta se trovi una soluzione più semplice, mantenendo documentate le scelte.
+
+## Requisiti
+
+1. Leggi l’OpenAPI generato dall’app FastAPI e registra solo le operazioni con `x-apipilot.enabled: true`.
+2. Genera nome, descrizione e schema JSON dei parametri nel formato function calling compatibile OpenAI. Supporta parametri di path, query e body. Non esporre al modello credenziali o header tecnici.
+3. Rileva nomi duplicati, configurazioni incomplete e schemi non supportati con errori chiari.
+4. Implementa `tools_for(user)` e `execute(user, name, arguments)`.
+5. Esegui solo tool registrati. Valida gli argomenti e applica l’autenticazione e i permessi dell’app ospite. Il modello non deve poter scegliere liberamente URL, metodo HTTP o credenziali.
+6. Gestisci timeout, errori degli endpoint, risultati vuoti e risposte troppo grandi. Restituisci errori strutturati.
+7. Permetti di registrare tool Python composti che eseguono più passaggi e non corrispondono a un singolo endpoint OpenAPI.
+8. Mantieni separati il nucleo di ApiPilot e gli adapter per specifici provider LLM. Implementa un adapter iniziale per il formato tool calling compatibile OpenAI, incluso il collegamento tra risultato e `tool_call_id`.
+9. Se esponi catalogo ed esecuzione via HTTP, rendili opzionali e documenta autenticazione e contratto delle richieste.
+
+## Documentazione per gli agenti di sviluppo
+
+Genera nella radice del repository **`AGENT.md` e `CLAUDE.md`**. Devono contenere istruzioni pratiche e coerenti per chi sviluppa ApiPilot con agenti di coding: architettura e confini dei moduli, comandi di installazione e test, convenzioni del codice, requisiti di sicurezza, criteri per aggiungere adapter e regole per aggiornare documentazione e test. Evita duplicazioni divergenti: `CLAUDE.md` può rimandare ad `AGENT.md` e aggiungere solo istruzioni specifiche, se necessarie.
+
+## Verifica e consegna
+
+Aggiungi test per selezione delle operazioni, conversione dei parametri, autorizzazione, rifiuto di tool sconosciuti, argomenti invalidi, gestione degli errori e tool composti. Usa una piccola app FastAPI di esempio, senza dipendenze da sistemi esterni.
+
+Consegna codice installabile, README con esempi di integrazione, formato documentato di `x-apipilot`, `AGENT.md`, `CLAUDE.md` e comandi per eseguire i test. Evita comportamenti o nomi legati a una singola applicazione.
+
+Includi anche un esempio demo di un FastAPI backend che usa apipilot