Trasforma qualsiasi raccolta di documenti in un grafo di conoscenza. Estrai entità e relazioni tramite LLM, deduplica con la tua approvazione. Mappa i domini, trova connessioni nascoste, individua modelli tra i documenti — conoscenza che persiste e si accumula, per te e i tuoi agenti AI. Tutto dalla CLI.
Trasforma qualsiasi raccolta di documenti in un grafo di conoscenza.
Nessun codice, nessun database, nessuna infrastruttura — solo una CLI e i tuoi documenti. Inserisci PDF, articoli, paper o record — ottieni in pochi minuti un grafo di conoscenza navigabile che mostra come tutto è connesso. sift-kg estrae entità e relazioni tramite LLM, deduplica con la tua approvazione e genera un visualizzatore interattivo che puoi esplorare nel tuo browser. Mappe concettuali per qualsiasi cosa, a portata di mano.
Lo stesso grafo che alimenta le tue visualizzazioni funge anche da secondo cervello AI. Tutti passano mesi a costruire basi di conoscenza in Notion e Obsidian. Chi ha tempo per questo? sift-kg è la memoria strutturata che costruisci in 2 minuti invece che in 2 anni. Basta puntare ai tuoi documenti e la tua AI ha una comprensione strutturata di come tutto è connesso.
Demo live → grafi generati interamente da sift-kg```bash pip install sift-kg
sift init # create sift.yaml + .env.example sift extract ./documents/ # extract entities & relations sift build # build knowledge graph sift resolve # find duplicate entities sift review # approve/reject merges interactively sift apply-merges # apply your decisions sift narrate # generate narrative summary sift view # interactive graph in your browser sift export graphml # export to Gephi, yEd, Cytoscape, SQLite, etc.
## Come Funziona```
Documents (PDF, DOCX, text, HTML, and 75+ formats)
↓
Text Extraction (Kreuzberg, local) — with optional OCR (Tesseract, EasyOCR, PaddleOCR, or Google Cloud Vision)
↓
Schema Discovery (LLM designs entity/relation types from your data — or use a predefined domain)
↓
Entity & Relation Extraction (LLM, using discovered or predefined schema)
↓
Knowledge Graph (NetworkX, JSON)
↓
Entity Resolution (LLM proposes → you review)
↓
Narrative Generation (LLM)
↓
Interactive Viewer (browser) / Export (GraphML, GEXF, CSV, SQLite)
Ogni entità e relazione si collega al documento e al passo di origine. Controlli tu cosa viene unito. Il grafo è tuo.
sift.yaml nel tuo progetto per impostazioni persistentidiscovered_domain.yaml per riutilizzo e modifica. Oppure usa un dominio strutturato (general, osint, academic) per schemi fissi, o definisci il tuo in YAMLsift search "SBF" trova entità per nome o alias, con output opzionale di relazioni e descrizioni--neighborhood, --top, , , sift-kg genera conoscenza strutturata che gli agenti AI possono utilizzare direttamente.
Punta sift verso i tuoi documenti, appunti o file di progetto. L'output — un grafo della conoscenza JSON — fornisce a qualsiasi agente AI una comprensione strutturata e persistente di come tutto nel tuo mondo si connette. Nessuna organizzazione manuale, nessun tagging, nessun collegamento wiki. La struttura emerge dal contenuto.```bash sift extract ./my-stuff/ sift build sift topology # structural overview (JSON, for agents) sift query "topic" # entity neighborhood subgraph (JSON, for agents) sift search "X" --json # entity lookup (JSON, for agents) sift info --json # project stats (JSON, for agents)
Il grafico persiste tra le sessioni e cresce in modo incrementale — estrai nuovi documenti nella stessa directory di output e ricostruisci. La deduplicazione delle entità garantisce che il grafico rimanga coerente mentre cresce.
**Cosa dà questo al tuo agente:**
- **Struttura** — non solo blocchi di testo, ma entità, relazioni, comunità e come si connettono
- **Topologia** — quali cluster di conoscenza esistono, cosa li collega, cosa è isolato
- **Durabilità** — il grafico sopravvive ai reset della finestra di contesto. Il tuo agente smette di ricominciare da zero ogni sessione
**Abilità agente inclusa:** sift-kg è fornito con un'abilità in `.agents/skills/sift-kg/SKILL.md` che insegna agli agenti come utilizzare il grafico della conoscenza come memoria persistente — orientamento della sessione, esplorazione delle entità, ragionamento sui collegamenti tra isole di conoscenza e generazione di suggerimenti fondati.
## Domini Inclusi
sift-kg include domini specializzati che puoi utilizzare immediatamente:```bash
sift domains # list available domains
sift extract ./docs/ --domain-name osint # use a bundled domain
Imposta un dominio in sift.yaml così non ti serve il flag ogni volta:```yaml
domain: academic
Funziona con nomi integrati (`schema-free`, `general`, `osint`, `academic`) o con un percorso verso un file YAML personalizzato.
| Dominio | Focus | Tipi di Entità Chiave | Tipi di Relazione Chiave |
|--------|-------|------------------|--------------------|
| `schema-free` | Rilevato automaticamente dai tuoi dati (predefinito) | *(Progettati dall'LLM per corpus)* | *(Progettati dall'LLM per corpus)* |
| `general` | Analisi documentale generale | PERSON, ORGANIZATION, LOCATION, EVENT, DOCUMENT | ASSOCIATED_WITH, MEMBER_OF, LOCATED_IN |
| `osint` | Indagini & FOIA | SHELL_COMPANY, FINANCIAL_ACCOUNT | BENEFICIAL_OWNER_OF, TRANSACTED_WITH, SIGNATORY_OF |
| `academic` | Revisione della letteratura e mappatura degli argomenti | CONCEPT, THEORY, METHOD, SYSTEM, FINDING, PHENOMENON, RESEARCHER, PUBLICATION, FIELD, DATASET | SUPPORTS, CONTRADICTS, EXTENDS, IMPLEMENTS, EXPLAINS, PROPOSED_BY, USES_METHOD, APPLIED_TO, INVESTIGATES |
Il dominio **academic** mappa il panorama intellettuale di un'area di ricerca: inserisci articoli e ottieni un grafo di come teorie, metodi, sistemi, risultati e concetti si collegano. Distingue idee astratte (THEORY, METHOD) da artefatti concreti (SYSTEM — es. GPT-2, BERT, GLUE). Progettato per revisioni della letteratura, mappatura di argomenti e comprensione di dove le idee concordano, si contraddicono o si basano le une sulle altre.
Il dominio **schema-free** (predefinito) esegue un passo di **scoperta dello schema** prima dell'estrazione: una chiamata LLM campiona i tuoi documenti e progetta tipi di entità e relazione su misura per il corpus. Lo schema scoperto viene salvato in `output/discovered_domain.yaml` e riutilizzato nelle esecuzioni successive, così i tipi rimangono coerenti tra tutti i chunk e documenti. Puoi ispezionare, modificare manualmente o copiare il file come punto di partenza per un dominio personalizzato. Usa `--force` per riscoprire. Invece di forzare le relazioni in categorie predefinite come ASSOCIATED_WITH, produce tipi specifici come FUNDED, TESTIFIED_AGAINST, o ENROLLED_AT. Usa un dominio strutturato come `general` o `osint` quando vuoi uno schema fisso definito a priori.
Il dominio **general** fornisce uno schema fisso con tipi di entità PERSON, ORGANIZATION, LOCATION, EVENT e DOCUMENT più tipi di relazione comuni. Utile quando desideri tipi prevedibili e coerenti tra i documenti.
Il dominio **osint** aggiunge tipi di entità per società fittizie, conti finanziari e giurisdizioni offshore, più tipi di relazione per tracciare la proprietà effettiva e i flussi finanziari.
Niente viene unito senza la tua approvazione — l'LLM propone, tu verifichi. Ogni estrazione rimanda al documento e al passaggio sorgente.
Vedi [`examples/transformers/`](https://github.com/juanceresa/sift-kg/blob/HEAD/examples/transformers/) per 12 articoli fondamentali sull'AI mappati come grafo concettuale (425 entità, ~$0.72), e [`examples/ftx/`](https://github.com/juanceresa/sift-kg/blob/HEAD/examples/ftx/) per il crollo di FTX (431 entità da 9 articoli). [**Esplora le demo live**](https://juanceresa.github.io/sift-kg/) — nessuna installazione, nessuna chiave API.
## Civic Table
Cerchi una piattaforma hosted con analisi legale forense e verifica da parte di analisti?
[**Civic Table**](https://github.com/juanceresa/forensic_analysis_platform) è una piattaforma di intelligence forense costruita sulla pipeline sift-kg. Aggiunge un sistema di verifica a 4 livelli in cui analisti e laureati in giurisprudenza (JD) convalidano i fatti estratti dall'AI prima che vengano trattati come prove, generazione di dossier LaTeX per sottomissioni legali e un'interfaccia web per condividere i risultati con clienti e famiglie. Realizzato per la restituzione di proprietà, il giornalismo investigativo e qualsiasi contesto in cui la provenienza documentale conta.
sift-kg è la CLI open-source. Civic Table è la piattaforma completa — e il luogo in cui l'output viene esaminato da analisti e JD prima di avere peso probatorio.
## Installazione
Richiede Python 3.11+.```bash
pip install sift-kg
Per il supporto OCR (PDF scansionati, immagini):```bash
brew install tesseract # macOS sudo apt install tesseract-ocr # Ubuntu/Debian
Per Google Cloud Vision OCR come backend alternativo (opzionale):```bash
pip install sift-kg[ocr]
# Then use: sift extract ./docs/ --ocr --ocr-backend gcv
Per il clustering semantico durante la risoluzione delle entità (opzionale, ~2GB per PyTorch):```bash pip install sift-kg[embeddings]
Per lo sviluppo:```bash
git clone https://github.com/juanceresa/sift-kg.git
cd sift-kg
pip install -e ".[dev]"
sift init # creates sift.yaml + .env.example cp .env.example .env # copy and add your API key
`sift init` genera un file di configurazione del progetto `sift.yaml` in modo da non aver bisogno di flag su ogni comando:```yaml
# sift.yaml
domain: domain.yaml # or a bundled name like "osint"
model: openai/gpt-4o-mini
ocr: true # enable OCR for scanned PDFs
# extraction:
# backend: kreuzberg # kreuzberg (default, 75+ formats) | pdfplumber
# ocr_backend: tesseract # tesseract | easyocr | paddleocr | gcv
# ocr_language: eng
Imposta la tua chiave API in .env:```
SIFT_OPENAI_API_KEY=sk-...
Oppure usa Anthropic, Mistral, Ollama o qualsiasi provider LiteLLM:```
SIFT_ANTHROPIC_API_KEY=sk-ant-...
SIFT_MISTRAL_API_KEY=...
Priorità delle impostazioni: CLI flags > env vars > .env > sift.yaml > valori predefiniti. Puoi sovrascrivere qualsiasi cosa da sift.yaml con un flag su qualsiasi comando.
sift extract ./my-documents/ sift extract ./my-documents/ --ocr # local OCR via Tesseract sift extract ./my-documents/ --ocr --ocr-backend gcv # Google Cloud Vision OCR sift extract ./my-documents/ --extractor pdfplumber # legacy pdfplumber backend
Legge oltre 75 formati di documenti — PDF, DOCX, XLSX, PPTX, HTML, EPUB, immagini e altri. Estrae entità e relazioni utilizzando il tuo LLM configurato. I risultati vengono salvati come JSON in `output/extractions/`.
Il flag `--ocr` abilita l'OCR locale tramite Tesseract per PDF scansionati — nessuna chiave API o servizio cloud necessario. Puoi cambiare motore OCR con `--ocr-backend`:```bash
sift extract ./docs/ --ocr # Tesseract (default, local)
sift extract ./docs/ --ocr --ocr-backend easyocr # EasyOCR (local)
sift extract ./docs/ --ocr --ocr-backend paddleocr # PaddleOCR (local)
sift extract ./docs/ --ocr --ocr-backend gcv # Google Cloud Vision (requires credentials)
Rileva automaticamente quali PDF necessitano di OCR — i PDF ricchi di testo utilizzano l'estrazione standard, solo le pagine quasi vuote ripiegano sull'OCR. Sicuro per cartelle miste. Senza --ocr, sift avviserà se un PDF sembra essere scansionato.
Puoi anche cambiare completamente il backend di estrazione con --extractor pdfplumber per il backend legacy pdfplumber (solo PDF/DOCX/TXT/HTML).
sift build
Costruisce un grafo NetworkX da tutte le estrazioni. Deduplica automaticamente i nomi di entità quasi identici (plurali, varianti Unicode, differenze di maiuscole/minuscole) prima che diventino nodi del grafo. Corregge le direzioni degli archi invertite quando il LLM scambia i tipi sorgente/destinazione rispetto allo schema del dominio. Segnala le relazioni a bassa confidenza per la revisione. Salva in `output/graph_data.json`.
### 4. Risolvi le entità duplicate
Vedi il [Flusso di lavoro per la risoluzione delle entità](#entity-resolution-workflow) qui sotto per la guida completa — particolarmente importante per casi d'uso genealogici, legali e investigativi dove l'accuratezza è fondamentale.
### 5. Esplora ed esporta
**Visualizzatore interattivo** — esplora la tua mappa concettuale nel browser:```bash
sift view # full graph
sift view --neighborhood "Palantir Technologies" # 1-hop ego graph around an entity
sift view --neighborhood "Palantir" --depth 3 # 3-hop neighborhood
sift view --top 10 # top 10 hubs + their neighbors
sift view --community "Community 1" # focus on a specific community
sift view --source-doc palantir_nsa_surveillance # entities from one document
sift view --min-confidence 0.8 # hide low-confidence nodes/edges
Apre un grafo force-directed nel tuo browser. La panoramica mostra regioni di community — involucri convessi colorati che raggruppano entità correlate — così puoi vedere la struttura del grafo a colpo d'occhio senza ingombro di etichette. Passa il mouse su qualsiasi nodo per visualizzare in anteprima il suo nome e le connessioni. Include ricerca, attivazione/disattivazione di tipo/community/relazione, filtro per documento sorgente, filtro per grado e una barra laterale dei dettagli.
I flag di pre-filtro (--top, --neighborhood, --source-doc, --min-confidence) riducono il grafo prima del rendering. --community preseleziona una community nella barra laterale. --neighborhood accetta ID di entità (person:alice) o nomi visualizzati (senza distinzione tra maiuscole e minuscole).
Modalità Focus: Fai doppio clic su qualsiasi entità per isolare il suo vicinato. Usa i tasti freccia per scorrere le connessioni una per una — ogni coppia viene mostrata in isolamento con archi etichettati. Premi Invio/Freccia destra per spostare il focus su un vicino, Backspace/Freccia sinistra per tornare indietro lungo il tuo percorso, Esc per uscire. La tua esplorazione viene tracciata come un percorso breadcrumb nella barra laterale — un percorso persistente che mostra ogni nodo visitato e le relazioni tra di essi. Gli archi del percorso rimangono evidenziati sulla tela in modo da poter vedere il tuo percorso attraverso il grafo. Questo è il modo previsto per esplorare grafi densi — ingrandisci su ciò che conta, traccia le connessioni, leggi le prove.
Ricerca CLI — interroga le entità direttamente dal terminale:```bash sift search "Sam Bankman" # search by name sift search "SBF" # search by alias sift search "Caroline" -r # show relations sift search "FTX" -d -t ORGANIZATION # descriptions + type filter
**Esportazioni statiche** — per strumenti di analisi in cui si desidera layout, filtraggio o stili personalizzati:```bash
sift export graphml # → output/graph.graphml (Gephi, yEd, Cytoscape)
sift export gexf # → output/graph.gexf (Gephi native)
sift export sqlite # → output/graph.sqlite (SQL queries, DuckDB, Datasette)
sift export csv # → output/csv/entities.csv + relations.csv
sift export json # → output/graph.json
Utilizza GraphML/GEXF quando desideri controllare le dimensioni dei nodi, il peso degli archi, schemi di colore personalizzati, o applicare algoritmi sui grafi (centralità, rilevamento di comunità) in strumenti dedicati. SQLite è utile per query SQL ad-hoc, pubblicazione con Datasette, o caricamento in DuckDB.
sift narrate sift narrate --communities-only # regenerate community labels only (~$0.01)
Produces `output/narrative.md` — un report in prosa con una panoramica, catene di relazioni chiave tra le entità principali, una cronologia (quando nel dataset sono presenti date) e profili di entità raggruppati per comunità tematica (scoperta tramite rilevamento di comunità Louvain). Le descrizioni delle entità sono scritte in forma attiva con azioni specifiche, non riassunti di ruoli.
## Configurazione del Dominio
sift-kg è fornito con quattro domini preconfigurati (vedi [Domini Preconfigurati](#bundled-domains) sopra per i dettagli). Il default è `schema-free`.
Usa un dominio preconfigurato:```bash
sift extract ./docs/ --domain-name osint
Oppure crea il tuo domain.yaml:```yaml
name: My Domain
fallback_relation: RELATED_TO # optional — catch-all for relations that don't fit defined types
entity_types:
PERSON:
description: People and individuals
extraction_hints:
- Look for full names with titles
COMPANY:
description: Business entities
DEPARTMENT:
description: Named departments within a company
canonical_names: # closed vocabulary — only these values allowed
- Engineering
- Sales
- Legal
- Marketing
canonical_fallback_type: ORGANIZATION # non-canonical names get retyped
relation_types:
EMPLOYED_BY:
description: Employment relationship
source_types: [PERSON]
target_types: [COMPANY]
OWNS:
description: Ownership relationship
symmetric: false
review_required: true
RELATED_TO: # define the fallback type if you use one
description: General relationship
**Applicazione dello schema:** I tipi di entità e i tipi di relazione definiti nel tuo dominio vengono trattati come un insieme chiuso — all'LLM viene istruito di utilizzare solo questi tipi e non ne inventerà di nuovi. Se `fallback_relation` è impostato, le relazioni che non rientrano in alcun tipo definito vengono mappate al fallback. Se omesso, l'LLM utilizza il tipo definito più vicino con una confidenza inferiore. Se vedi molte relazioni finire sul tuo tipo di fallback, è probabile che il tuo schema manchi di un tipo di relazione di cui i dati hanno bisogno — aggiungilo e ri-estrai.
I tipi di entità con `canonical_names` impongono un vocabolario chiuso. I nomi consentiti vengono iniettati nel prompt di estrazione dell'LLM in modo che produca corrispondenze esatte. Come rete di sicurezza, qualsiasi nome estratto non presente nell'elenco viene riclassificato in `canonical_fallback_type` durante la creazione del grafo (o mantenuto così com'è se nessun fallback è impostato). Utile per tassonomie controllate — dipartimenti, giurisdizioni, classificazioni predefinite.```bash
sift extract ./docs/ --domain path/to/domain.yaml
Usa sift-kg da Python — notebook Jupyter, script, applicazioni web:```python from sift_kg import load_domain, run_extract, run_build, run_narrate, run_resolve, run_export, run_view from sift_kg import KnowledgeGraph from pathlib import Path
domain = load_domain() # or load_domain(bundled_name="osint")
results = run_extract( Path("./docs"), "openai/gpt-4o-mini", domain, Path("./output"), ocr=True, ocr_backend="tesseract", # enable OCR for scanned PDFs extractor="kreuzberg", # or "pdfplumber" concurrency=4, chunk_size=10000, )
kg = run_build(Path("./output"), domain) print(f"{kg.entity_count} entities, {kg.relation_count} relations")
merges = run_resolve(Path("./output"), "openai/gpt-4o-mini", domain=domain, use_embeddings=True)
run_export(Path("./output"), "sqlite")
run_narrate(Path("./output"), "openai/gpt-4o-mini", communities_only=True)
run_view(Path("./output")) # full graph run_view(Path("./output"), neighborhood="person:alice", depth=2) # ego graph run_view(Path("./output"), top_n=10) # top hubs
from sift_kg import run_pipeline run_pipeline(Path("./docs"), "openai/gpt-4o-mini", domain, Path("./output"))
## Struttura del Progetto
Dopo aver eseguito la pipeline, la tua directory di output contiene:```
output/
├── extractions/ # Per-document extraction JSON
│ ├── document1.json
│ └── document2.json
├── discovered_domain.yaml # Auto-discovered schema (schema-free mode)
├── graph_data.json # Knowledge graph (native format)
├── merge_proposals.yaml # Entity merge proposals (DRAFT/CONFIRMED/REJECTED)
├── relation_review.yaml # Flagged relations for review
├── narrative.md # Generated narrative summary
├── entity_descriptions.json # Entity descriptions (loaded by viewer)
├── communities.json # Community assignments (shared by narrate + viewer)
├── graph.html # Interactive graph visualization
├── graph.graphml # GraphML export (if exported)
├── graph.gexf # GEXF export (if exported)
├── graph.sqlite # SQLite export (if exported)
└── csv/ # CSV export (if exported)
├── entities.csv
└── relations.csv
Quando costruisci un grafo della conoscenza da registri familiari, documenti legali o qualsiasi documento in cui l'accuratezza è importante, vuoi il pieno controllo su quali entità vengono unite. sift-kg non unisce mai nulla senza la tua approvazione.
Il flusso di lavoro ha tre livelli, ognuno dei quali cattura diversi tipi di duplicati:
sift build)Prima che le entità diventino nodi del grafo, sift collassa deterministicamente i nomi che sono ovviamente gli stessi. Nessun LLM coinvolto, nessun costo, nessuna revisione necessaria:
Questo avviene automaticamente ogni volta che esegui sift build. Questi sono i casi banali — varianti ortografiche che ingombrerebbero il grafo senza aggiungere informazioni.
sift resolve)L'LLM vede lotti di entità (tutti i tipi tranne DOCUMENT) e identifica quelle che probabilmente si riferiscono alla stessa cosa del mondo reale. Rileva anche duplicati tra tipi diversi (stesso nome, tipo di entità diverso) e propone relazioni di variante (EXTENDS) quando trova pattern genitore/figlio. I risultati vanno in merge_proposals.yaml (unioni di entità) e relation_review.yaml (relazioni varianti), tutti inizialmente in stato DRAFT:```bash
sift resolve # uses domain from sift.yaml
sift resolve --domain osint # or specify explicitly
Se hai configurato un dominio, il LLM utilizza quel contesto per formulare giudizi migliori sui nomi delle entità specifiche del tuo settore.
Questo genera proposte come:```yaml
proposals:
- canonical_id: person:samuel_benjamin_bankman_fried
canonical_name: Samuel Benjamin Bankman-Fried
entity_type: PERSON
status: DRAFT # ← you decide
members:
- id: person:bankman_fried
name: Bankman-Fried
confidence: 0.99
reason: Same person referenced with full name vs. surname only.
- canonical_id: person:stephen_curry
canonical_name: Stephen Curry
entity_type: PERSON
status: DRAFT # ← you decide
members:
- id: person:steph_curry
name: Steph Curry
confidence: 0.99
reason: Same basketball player referenced with nickname 'Steph' and full name 'Stephen'.
Niente è ancora stato unito. Il LLM sta proponendo, non decidendo.
Hai due opzioni per rivedere le proposte:
Opzione A: Revisione interattiva tramite terminale```bash sift review
Scorre ogni proposta `DRAFT` una per una. Per ciascuna, vedi l'entità canonica, i membri proposti per l'unione, la confidenza e il ragionamento del LLM. Approvi, rifiuti o salti.
Le proposte ad alta confidenza (>0.85 per impostazione predefinita) vengono approvate automaticamente, e le relazioni a bassa confidenza (<=0.5 per impostazione predefinita) vengono rifiutate automaticamente:```bash
sift review # uses defaults: --auto-approve 0.85, --auto-reject 0.5
sift review --auto-approve 0.90 # raise the auto-approve threshold
sift review --auto-reject 0.3 # lower the auto-reject threshold
sift review --auto-approve 1.0 # disable auto-approve, review everything manually
Opzione B: modifica direttamente il file YAML
Apri output/merge_proposals.yaml in un qualsiasi editor di testo. Cambia status: DRAFT in CONFIRMED o REJECTED:```yaml
canonical_id: person:stephen_curry canonical_name: Stephen Curry entity_type: PERSON status: CONFIRMED # ← approve this merge members:
canonical_id: person:winklevoss_twins canonical_name: Winklevoss twins entity_type: PERSON status: REJECTED # ← these are distinct people, don't merge members:
**Per casi d'uso ad alta precisione** (genealogia, revisione legale), si consiglia di modificare direttamente il file YAML in modo da poter studiare attentamente ogni proposta. Il file è progettato per essere leggibile dall'uomo.
### Layer 3b: Revisione delle Relazioni
Durante `sift build`, le relazioni al di sotto della soglia di confidenza (predefinita 0.7) o di tipi contrassegnati come `review_required` nella configurazione del tuo dominio vengono segnalate in `output/relation_review.yaml`:```yaml
review_threshold: 0.7
relations:
- source_name: Alice Smith
target_name: Acme Corp
relation_type: WORKS_FOR
confidence: 0.45
evidence: "Alice mentioned she used to work near the Acme building."
status: DRAFT # ← you decide: CONFIRMED or REJECTED
flag_reason: Low confidence (0.45 < 0.7)
Stesso flusso di lavoro: rivedi con sift review o modifica il YAML, poi applica.
Una volta che hai rivisto tutto:```bash sift apply-merges
Questo fa tre cose:
1. **Unioni di entità confermate** — le entità membro vengono assorbite nell'entità canonica. Tutte le loro relazioni vengono ricollegate. I documenti sorgente vengono combinati. I nodi membro vengono rimossi.
2. **Relazioni rifiutate** — rimosse completamente dal grafo.
3. **Proposte DRAFT** — lasciate intatte. Puoi tornarci in seguito.
Il grafo viene salvato in `output/graph_data.json`. Puoi riesportare, narrare o visualizzare il grafo ripulito.
### Iterazione
La risoluzione delle entità non è sempre un'operazione in un unico passaggio. Dopo l'unione, possono emergere nuovi duplicati. Puoi rieseguire:```bash
sift resolve # find new duplicates in the cleaned graph
sift review # review the new proposals
sift apply-merges # apply again
Ogni esecuzione è additiva — le decisioni precedenti CONFERMATO/RIFIUTATO in merge_proposals.yaml sono preservate.
Le tecniche di pre-dedup e raggruppamento LLM sono ispirate a KGGen (NeurIPS 2025) di @stochastic-sisyphus. KGGen utilizza SemHash per la deduplicazione deterministica delle entità e il clustering basato su embedding per raggruppare le entità prima del confronto LLM. sift-kg adatta queste tecniche nel suo flusso di lavoro di revisione con intervento umano.
Per impostazione predefinita, sift resolve ordina le entità alfabeticamente e le suddivide in batch sovrapposti per il confronto LLM. Questo funziona bene quando i duplicati hanno ortografia simile — ma "Robert Smith" (R) e "Bob Smith" (B) finiscono in batch diversi e non vengono mai confrontati.```bash
pip install sift-kg[embeddings] # sentence-transformers + scikit-learn (~2GB, pulls PyTorch)
sift resolve --embeddings
Questo sostituisce il raggruppamento alfabetico con il clustering KMeans sugli embeddings delle frasi (all-MiniLM-L6-v2). Nomi semanticamente simili si raggruppano insieme indipendentemente dall'ortografia.
| | Predefinito (alfabetico) | `--embeddings` |
|---|---|---|
| Dimensioni installazione | Incluso | ~2GB (PyTorch) |
| Overhead primo avvio | Nessuno | ~90MB download modello |
| Overhead per esecuzione | Solo ordinamento | Codifica (<1s per centinaia di entità) |
| Duplicati tra alfabeti | Persi se in lotti diversi | Rilevati |
| Grafici piccoli (<100/tipo) | Stesso risultato | Stesso risultato |
Ricade al raggruppamento alfabetico se le dipendenze non sono installate o il clustering fallisce.
## Licenza
MIT
--community--source-doc--min-confidence--ocr), con fallback opzionale su Google Cloud Vision (--ocr-backend gcv)--max-cost per limitare la spesa LLM| Caso d'Uso | Approccio Suggerito |
|---|
| Esplorazione rapida | sift review --auto-approve 0.85 — approva alte certezze, revisiona il resto |
| Genealogia / documenti familiari | Modifica YAML manualmente, --auto-approve 1.0 — revisiona ogni singola unione |
| Legale / investigativo | sift resolve --embeddings, modifica YAML manualmente, usa sift view per ispezionare tra i round |
| Corpus ampio (1000+ entità) | sift resolve --embeddings per un migliore raggruppamento, quindi revisione interattiva |