Panoramica

Il motore di RAGSpine è Python ordinario: interfacce tipizzate, dataclass, store espliciti e un flusso di controllo leggibile. answer_question(...) è il punto di ingresso per la composizione delle Q&A. Un dominio separato dedicato ai flussi di lavoro esegue il parsing, lo scaffolding, l'anteprima, la conversione e la compilazione di configurazioni compatibili con Dify; un servizio FastAPI opzionale espone tali operazioni e un executor deliberatamente disattivato per impostazione predefinita.

Questa distinzione è importante. RAGSpine dispone di superfici di interscambio con Dify e n8n, ma non incorpora il runtime di nessuna delle due piattaforme, non scarica i loro marketplace a runtime e non richiede un framework a grafo per rispondere a una domanda.

Impegni architetturali

Ciclo di vita di una richiesta Q&A

question
  → deterministic security/intent screening
  → clarification gateway
  → optional service-edge FAQ short-circuit
  → structured | narrative | composite route
       structured: normalize → query fact store → found/not_found/unrecognized
       narrative: filter → retrieve/fuse → rerank/postprocess → cited generation
       composite: execute both evidence paths and merge
  → anti-fabrication/provenance checks
  → answer + sources

L'eventuale history viene inserito solo nella sequenza finale dei messaggi di generazione. Non modifica mai la decisione deterministica di intento/sicurezza, la query di recupero o ciò che conta come evidenza.

Il percorso narrativo può utilizzare filtri sui metadati, instradamento per libreria con fusione RRF ed espansione parent/window a livello di store. I campi di citazione restano quelli dell'hit figlio; il testo espanso è contesto di generazione separato. Un figlio con restrizioni viene rimosso prima dell'espansione.

Ciclo di vita del flusso di lavoro

description or JSON/YAML/TOML
  → normalize to JSON-compatible mapping
  → explicit template or catalog match
  → reuse safe Dify workflow | generate fixed start→llm→end graph
  → deterministic YAML/JSON + preview schema v1
  → optional analyze / convert / compile
  → explicit server-controlled execution gate (off by default)

Il catalogo è costituito da dati di pacchetto: 7 template curati più 993 descrittori generati. Gli URL upstream di Dify/n8n sono soltanto metadati di ricerca; nessun testo di flussi di lavoro upstream né alcuna credenziale viene ridistribuito.

Confini di fiducia

• La libreria di base e il catalogo non richiedono alcuna chiave API.
• Le route ordinarie del servizio per motore/catalogo/compilatore non hanno autenticazione applicativa integrata e devono essere protette dall'infrastruttura di deployment.
• Gli endpoint pubblici compatibili con Dify richiedono una app key Bearer; le operazioni CRUD pubbliche compatibili con n8n richiedono X-N8N-API-KEY.
• I webhook sono intenzionalmente privi di autenticazione e necessitano di controlli in ingresso.
• L'esecuzione dei flussi di lavoro è inoltre vincolata da RAGSPINE_DIFY_RUN_ENABLED=false per impostazione predefinita.
• Il livello di restrizione in-process non è una sandbox a livello di sistema operativo; i limiti di risorse dei sottoprocessi sono disponibili solo su Linux.

Come proseguire