LLiaGraph
Connesso · memoria volatile

Tool disponibili

Mini reference e checklist update

Mini documentazione operativa dei tool registrati in backend/app/tools/.

Quando modifichi o aggiungi un tool, aggiorna questa pagina nello stesso commit.

Regole rapide per i tool

  • Mantieni docstring orientate all'uso: quando chiamare il tool, non solo cosa fa.
  • Evita eccezioni per errori attesi: ritorna messaggi utili all'agente.
  • Usa RunnableConfig per identita e contesto (user_id, thread_id`), non parametri inventabili dal modello.
  • Registra il tool con register_tool(...) e verifica che il modulo sia importato in app/tools/__init__.py.

Tool base (builtin.py)

calculator(expression: str) -> str

  • Scopo: calcolo aritmetico preciso senza affidarsi al ragionamento del modello.
  • Supporta: +, -, *, /, //, %, **, parentesi.
  • Note:
    • parser sicuro con AST (niente eval);
    • limite prudenziale sulla lunghezza dell'espressione.

current_datetime(timezone: str = "Europe/Rome") -> str

  • Scopo: ottenere data/ora corrente nel fuso richiesto.
  • Input: timezone IANA (es. Europe/Rome).
  • Fallback: se timezone non valida usa UTC.

Tool calendario Italia (calendar_it.py)

italian_working_hours(when: str = "") -> str

  • Scopo: verificare se una data/ora e` in finestra lavorativa italiana.
  • Regole:
    • weekend esclusi;
    • festivita` nazionali incluse Pasqua/Pasquetta;
    • orario ufficio 09:00-18:00 (Europe/Rome).
  • Uso tipico: prima di impostare send_at / reschedule_at.
  • Input:
    • stringa ISO-8601, oppure vuota per "adesso".
  • Output:
    • report testuale con decisione (PUOI INVIARE ORA / NON INVIARE ORA) e prossima finestra utile.

Tool memoria utente (memory_tools.py)

remember_fact(content: str, importance: int = 3) -> str

  • Scopo: salvare fatti duraturi (preferenze, vincoli, decisioni, anagrafiche).
  • Scope identita`:
    • user_id e thread_id letti da RunnableConfig.
  • Range importance: clamp automatico 1..5.
  • Output: conferma di salvataggio o messaggio se memoria persistente disattivata.

recall_facts(query: str) -> str

  • Scopo: recuperare fatti pertinenti dalla memoria a lungo termine.
  • Uso tipico: quando la risposta dipende da contesto storico cross-thread.
  • Output: elenco puntato di ricordi o messaggio "nessun ricordo".

Tool relationship (relationship_tools.py)

upsert_relationship_rule(rule: str, importance: int = 4) -> str

  • Scopo: salvare regole relazionali stabili (tono, tabù, frequenza, vincoli di contatto).
  • Kind memoria: rule.
  • Range importance: clamp automatico 1..5.

upsert_emotional_kpi(kpi_name: str, value: str, maneuver: str) -> str

  • Scopo: tracciare KPI emozionali e manovra consigliata per il prossimo messaggio.
  • Kind memoria: kpi.
  • Metadata: kpi, value, maneuver.

upsert_platform_description(platform: str, description: str) -> str

  • Scopo: memorizzare linee guida di stile/comportamento per canale (WhatsApp, email, LinkedIn...).
  • Kind memoria: platform.
  • Metadata: platform.

Tool onboarding (onboarding_tools.py)

recall_client_setup() -> str

  • Scopo: leggere la configurazione di comunicazione del creditore (tono, lingua, canali, cadenza solleciti, testi, piani di rientro).
  • Kind memoria: client_setup.
  • Quando: prima di scrivere un messaggio o pianificare un sollecito, se esiste un onboarding salvato.
  • Identità: user_id dalla RunnableConfig.

recall_team_policy() -> str

  • Scopo: leggere come devono comportarsi relationship, respond, negotiate, sollecito e orchestratore.
  • Kind memoria: team_policy.
  • Quando: per rispettare tetti di rate, sconti, messa in mora e finestra di invio.
  • register_tool(tool): registra/aggiorna tool nel registry in-memory.
  • get_tool(name), get_tools(names): risoluzione nomi -> oggetti tool.
  • list_tools(): elenco ordinato.
  • describe_tools(): payload serializzabile usato dalla UI/API.

Checklist quando aggiorni i tool

  1. Aggiorna codice tool e docstring.
  2. Aggiorna docs/TOOLS.md (sezione o scheda interessata).
  3. Verifica import in app/tools/__init__.py.
  4. Ricarica configurazione grafo (POST /api/graph/reload) se necessario.