Perché i Database Vettoriali non Salveranno gli Agenti dagli Auditor e Come Semantica Risolve Questo

Immagina uno scenario reale. Un agente IA presso una società finanziaria ha automaticamente rifiutato una richiesta di prestito o ha fissato un tasso di interesse. Sei mesi dopo, un regolatore si presenta e fa una semplice domanda: "Su quale base il sistema ha preso questa decisione?"

Se il tuo agente si affida esclusivamente a un database vettoriale e al RAG standard, non avrai una risposta adeguata. Gli embedding vettoriali possono trovare frammenti di testo simili basandosi sulla somiglianza semantica. Ma non hanno alcuna idea su quali fatti si contraddicano, quali precedenti passati il modello ha utilizzato e quali conseguenze questa catena di ragionamento ha prodotto.

È qui che entra in gioco il framework Semantica. Gli sviluppatori lo posizionano come un'alternativa open-source a Palantir per agenti autonomi. Lo strumento si integra direttamente sotto il tuo framework di agenti, modello e vector store, aggiungendo un livello deterministico di grafi, regole e audit.

Panoramica del Progetto e Concetto

Semantica è una libreria Python (pip install semantica) costruita attorno al concetto di Context Graphs. Invece di affidarsi a un modello linguistico per costruire connessioni logiche, la libreria si assume il lavoro deterministico da sola. Costruire un knowledge graph, eseguire regole o tracciare l'audit LLM non richiede affatto un LLM.

L'architettura della libreria copre l'intero ciclo di elaborazione dei dati. I dati provengono da file, pagine web, database tradizionali e piattaforme enterprise come Databricks e Snowflake. Il testo grezzo viene estratto, pulito e suddiviso in chunk basati sulle entità. Da questi chunk si forma un knowledge graph che si connette a motori di inferenza deterministici (Rete, Datalog, SPARQL), standard W3C PROV-O e moduli di logging delle decisioni.

Funzionalità Principali del Framework

• Le decisioni come oggetti di prima classe. Nei sistemi convenzionali, le decisioni dell'agente finiscono nei log o nella memoria della chat. In Semantica, chiamare record_decision() crea un nodo del grafo con scenario, argomenti, confidenza e metadati. Le decisioni sono collegate tra loro attraverso relazioni causali.
• Motori di ragionamento deterministici. I modelli linguistici sono inclini ad allucinazioni quando calcolano regole di business complesse. Il framework include motori Rete, Datalog e forward chaining. Definisci le regole nel codice e il sistema verifica i fatti senza coinvolgimento del LLM, producendo risultati trasparenti.
• Rilevamento dei conflitti e deduplicazione. Quando un indice vettoriale riceve due fatti contraddittori, in genere memorizza entrambi o sovrascrive quello vecchio. Semantica traccia queste discrepanze, segnala i conflitti e propone strategie di risoluzione: dalla ponderazione dell'affidabilità della fonte alla selezione del fatto più recente.
• Flessibilità di archiviazione senza lock-in del vendor. Il livello di archiviazione è completamente polyglot. Puoi lavorare con archivi RDF (Oxigraph, Blazegraph, Jena, RDF4J) tramite SPARQL o grafi a proprietà (Neo4j, FalkorDB, Apache AGE, AWS Neptune) tramite Cypher. I database vettoriali come Qdrant, Pinecone, Weaviate o pgvector si connettono senza modificare il codice core.

Come Appare nel Codice

Guardiamo uno scenario base per registrare una decisione e tracciarne le cause.

from semantica.context import ContextGraph

graph = ContextGraph(advanced_analytics=True)

# Регистрируем решение о согласовании заявки
app_id = graph.record_decision(
    category="credit_application",
    scenario="Персональный кредит, доход 150k, DTI 31%",
    reasoning="Доход соответствует порогу, стабильный стаж работы",
    outcome="proceed_to_underwriting",
    confidence=0.88,
    metadata={"applicant_id": "A-7291"}
)

# Следующий шаг андеррайтинга
uw_id = graph.record_decision(
    category="loan_underwriting",
    scenario="Проверка андеррайтером для A-7291",
    reasoning="DTI в пределах нормы, чистая кредитная история",
    outcome="approved",
    confidence=0.94
)

# Связываем решения причиной и следствием
graph.add_causal_relationship(app_id, uw_id, relationship_type="CAUSED")

# Получаем всю цепочку для проверки или аудита
chain = graph.trace_decision_chain(uw_id)
similar = graph.find_similar_decisions("кредит с низким DTI", max_results=5)

Ogni decisione presa viene esportata in formato W3C PROV-O, che i regolatori nei settori finanziario e medico accettano.

Integrazioni ed Ecosistema

La libreria fornisce strumenti di deployment pronti all'uso:

• Un server MCP pronto all'uso che connette Semantica a Claude Desktop, Windsurf, Cursor o VS Code in un paio di minuti.
• Integrazione nativa con il framework multi-agente Agno, che permette a più agenti di condividere un grafo di contesto comune.
• REST API su FastAPI e l'utility CLI semantica per la riga di comando.
• Un'interfaccia Knowledge Explorer basata su browser costruita su React e Sigma.js per la visualizzazione dei grafi, il tracciamento delle timeline e l'annotazione manuale delle entità.

Chi Beneficerà da Questo Progetto

Se stai costruendo un semplice progetto personale o un chatbot base per query su una knowledge base, Semantica sarebbe eccessivo. Il RAG base su LangChain o LlamaIndex sarebbe sufficiente qui.

Ma il progetto vale sicuramente la pena di essere esplorato se stai costruendo agenti per il settore finanziario, il diritto, la medicina o la cybersecurity. In questi domini, la capacità di mostrare una cronologia completa delle decisioni e garantire la conformità alle regole di business diventa un requisito critico del prodotto.