trustgraph/docs/tech-specs/extraction-time-provenance.pt.md

layout	title	parent
default	Proveniência no Momento da Extração: Camada de Origem	Portuguese (Beta)

Proveniência no Momento da Extração: Camada de Origem

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

Visão Geral

Este documento registra notas sobre a proveniência no momento da extração para trabalhos de especificação futuros. A proveniência no momento da extração registra a "camada de origem" - de onde os dados vieram originalmente, como foram extraídos e transformados.

Isso é diferente da proveniência no momento da consulta (veja query-time-provenance.md), que registra o raciocínio do agente.

Declaração do Problema

Implementação Atual

Atualmente, a proveniência funciona da seguinte forma: Metadados do documento são armazenados como triplas RDF no grafo de conhecimento. Um ID de documento associa metadados ao documento, de modo que o documento aparece como um nó no grafo. Quando arestas (relacionamentos/fatos) são extraídas de documentos, um relacionamento subjectOf vincula a aresta extraída ao documento de origem.

Problemas com a Abordagem Atual

<<<<<<< HEAD

1. Carregamento repetitivo de metadados: Os metadados do documento são agrupados e carregados repetidamente com cada lote de triplas extraídas daquele documento. Isso é um desperdício e redundante - os mesmos metadados viajam como carga com cada saída de extração. =======
2. Carregamento repetitivo de metadados: Os metadados do documento são agrupados e carregados repetidamente com cada lote de triplas extraídas daquele documento. Isso é um desperdício e redundante - os mesmos metadados viajam como carga útil com cada saída de extração.

82edf2d (New md files from RunPod)

2. Proveniência superficial: O relacionamento subjectOf atual vincula apenas os fatos diretamente ao documento de nível superior. Não há visibilidade da cadeia de transformação - qual página o fato veio, qual trecho, qual método de extração foi usado.

Estado Desejado

1. Carregar metadados uma vez: Os metadados do documento devem ser carregados uma vez e anexados ao nó do documento de nível superior, não repetidos com cada lote de triplas.

2. DAG de proveniência rica: Capture toda a cadeia de transformação desde o documento de origem, passando por todos os artefatos intermediários, até os fatos extraídos. Por exemplo, uma transformação de documento PDF:

   PDF file (source document with metadata)
     → Page 1 (decoded text)
       → Chunk 1
         → Extracted edge/fact (via subjectOf)
         → Extracted edge/fact
       → Chunk 2
         → Extracted edge/fact
     → Page 2
       → Chunk 3
         → ...
   

<<<<<<< HEAD 3. Armazenamento unificado: O grafo de proveniência é armazenado no mesmo grafo de conhecimento que o conhecimento extraído. Isso permite que a proveniência seja consultada da mesma forma que o conhecimento - seguindo as arestas de volta à cadeia de qualquer fato para sua localização de origem exata.

3. Armazenamento unificado: O grafo de proveniência é armazenado no mesmo grafo de conhecimento que o conhecimento extraído. Isso permite que a proveniência seja consultada da mesma forma que o conhecimento - seguindo as arestas de volta à cadeia de qualquer fato até sua localização de origem exata.

82edf2d (New md files from RunPod)

4. IDs estáveis: Cada artefato intermediário (página, trecho) possui um ID estável como um nó no grafo.

5. Vinculação pai-filho: Documentos derivados são vinculados aos seus pais até o documento de origem de nível superior, usando tipos de relacionamento consistentes.

<<<<<<< HEAD 6. Atribuição precisa de fatos: O relacionamento subjectOf nas arestas extraídas aponta para o pai imediato (trecho), não para o documento de nível superior. A proveniência completa é recuperada percorrendo o DAG.

6. Atribuição precisa de fatos: O relacionamento subjectOf nas arestas extraídas aponta para o pai imediato (trecho), e não para o documento de nível superior. A proveniência completa é recuperada percorrendo o DAG.

82edf2d (New md files from RunPod)

Casos de Uso

UC1: Atribuição de Fonte em Respostas GraphRAG

Cenário: Um usuário executa uma consulta GraphRAG e recebe uma resposta do agente.

Fluxo:

1. O usuário envia uma consulta para o agente GraphRAG.
2. O agente recupera fatos relevantes do grafo de conhecimento para formular uma resposta.
3. De acordo com a especificação de proveniência em tempo de consulta, o agente informa quais fatos contribuíram para a resposta.
4. Cada fato vincula-se ao seu trecho de origem através do grafo de proveniência.
5. Trechos vinculam-se a páginas, páginas vinculam-se a documentos de origem.

Resultado da Experiência do Usuário: A interface exibe a resposta do LLM juntamente com a atribuição da fonte. O usuário pode: <<<<<<< HEAD Ver quais fatos apoiaram a resposta.

Ver quais fatos suportaram a resposta.

82edf2d (New md files from RunPod) Acessar informações detalhadas de fatos → trechos → páginas → documentos. Examinar os documentos de origem para verificar as alegações. Entender exatamente onde em um documento (qual página, qual seção) um fato se originou.

Valor: Os usuários podem verificar as respostas geradas por IA em relação às fontes primárias, construindo confiança e permitindo a verificação de fatos.

UC2: Depuração da Qualidade da Extração

Um fato parece incorreto. Rastreie de volta através do trecho → página → documento para ver o texto original. Foi uma extração ruim ou a fonte em si estava incorreta?

<<<<<<< HEAD

UC3: Reextração Incremental

=======

UC3: Re-extração Incremental

82edf2d (New md files from RunPod)

O documento de origem é atualizado. Quais trechos/fatos foram derivados dele? Invalide e regenere apenas esses, em vez de reprocessar tudo.

UC4: Exclusão de Dados / Direito ao Esquecimento

Um documento de origem deve ser removido (GDPR, legal, etc.). Percorra o DAG para encontrar e remover todos os fatos derivados.

UC5: Resolução de Conflitos

<<<<<<< HEAD Dois fatos se contradizem. Rastreie ambos de volta às suas fontes para entender por que e decidir qual confiar (fonte mais autoritária, mais recente, etc.).

Dois fatos se contradizem. Rastreie ambos de volta às suas fontes para entender o porquê e decidir qual confiar (fonte mais autoritária, mais recente, etc.).

82edf2d (New md files from RunPod)

UC6: Ponderação da Autoridade da Fonte

Algumas fontes são mais autoritárias do que outras. Os fatos podem ser ponderados ou filtrados com base na autoridade/qualidade de seus documentos de origem.

UC7: Comparação de Pipelines de Extração

Compare os resultados de diferentes métodos/versões de extração. Qual extrator produziu melhores fatos da mesma fonte?

Pontos de Integração

Bibliotecário

<<<<<<< HEAD O componente bibliotecário já fornece armazenamento de documentos com IDs de documento exclusivos. O sistema de rastreabilidade se integra com essa infraestrutura existente.

O componente bibliotecário já fornece armazenamento de documentos com IDs de documentos exclusivos. O sistema de rastreabilidade se integra a essa infraestrutura existente.

82edf2d (New md files from RunPod)

Capacidades Existentes (já implementadas)

Vinculação de Documentos Pai-Filho: Campo parent_id em DocumentMetadata - vincula o documento filho ao documento pai Campo document_type - valores: "source" (original) ou "extracted" (derivado) API add-child-document - cria um documento filho com document_type = "extracted" automático API list-children - recupera todos os filhos de um documento pai Exclusão em cascata - a remoção de um pai exclui automaticamente todos os documentos filhos

Identificação de Documentos: <<<<<<< HEAD Os IDs de documento são especificados pelo cliente (não gerados automaticamente) Documentos indexados por (user, document_id) composto no Cassandra IDs de objeto (UUIDs) gerados internamente para armazenamento de blobs

Os IDs dos documentos são especificados pelo cliente (não gerados automaticamente) Documentos indexados por (user, document_id) composto no Cassandra IDs de objetos (UUIDs) gerados internamente para armazenamento de blobs

82edf2d (New md files from RunPod)

Suporte a Metadados: Campo metadata: list[Triple] - triplas RDF para metadados estruturados title, comments, tags - metadados básicos do documento time - carimbo de data/hora, kind - tipo MIME

Arquitetura de Armazenamento: Metadados armazenados no Cassandra (espaço de chaves librarian, tabela document) Conteúdo armazenado no armazenamento de blobs MinIO/S3 (bucket library) Entrega inteligente de conteúdo: documentos < 2MB incorporados, documentos maiores transmitidos

Arquivos Chave

trustgraph-flow/trustgraph/librarian/librarian.py - Operações principais do bibliotecário <<<<<<< HEAD trustgraph-flow/trustgraph/librarian/service.py - Processador de serviço, carregamento de documento

trustgraph-flow/trustgraph/librarian/service.py - Processador de serviço, carregamento de documentos

82edf2d (New md files from RunPod) trustgraph-flow/trustgraph/tables/library.py - Armazenamento de tabela Cassandra trustgraph-base/trustgraph/schema/services/library.py - Definições de esquema

Lacunas a Serem Abordadas

O bibliotecário tem os blocos de construção, mas atualmente:

1. A vinculação pai-filho é de um único nível - não há auxiliares de travessia de DAG de vários níveis
2. Não há vocabulário padrão de tipo de relacionamento (por exemplo, derivedFrom, extractedFrom)
3. Metadados de rastreabilidade (método de extração, confiança, posição do fragmento) não estão padronizados <<<<<<< HEAD
4. Não há API de consulta para percorrer toda a cadeia de rastreabilidade de um fato até a fonte =======
5. Não há API de consulta para percorrer toda a cadeia de rastreabilidade de um fato até a origem

82edf2d (New md files from RunPod)

Design de Fluxo de Extremo a Extremo

Cada processador no pipeline segue um padrão consistente: Recebe o ID do documento do upstream Recupera o conteúdo do bibliotecário Produz artefatos filhos Para cada filho: salva no bibliotecário, emite uma aresta para o grafo, encaminha o ID para o downstream

Fluxos de Processamento

Existem dois fluxos dependendo do tipo de documento:

Fluxo de Documento PDF

┌─────────────────────────────────────────────────────────────────────────┐
│ Librarian (initiate processing)                                         │
│   1. Emit root document metadata to knowledge graph (once)              │
│   2. Send root document ID to PDF extractor                             │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ PDF Extractor (per page)                                                │
│   1. Fetch PDF content from librarian using document ID                 │
│   2. Extract pages as text                                              │
│   3. For each page:                                                     │
│      a. Save page as child document in librarian (parent = root doc)   │
│      b. Emit parent-child edge to knowledge graph                       │
│      c. Send page document ID to chunker                                │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Chunker (per chunk)                                                     │
│   1. Fetch page content from librarian using document ID                │
│   2. Split text into chunks                                             │
│   3. For each chunk:                                                    │
│      a. Save chunk as child document in librarian (parent = page)      │
│      b. Emit parent-child edge to knowledge graph                       │
│      c. Send chunk document ID + chunk content to next processor        │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
          ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
          Post-chunker optimization: messages carry both
          chunk ID (for provenance) and content (to avoid
          librarian round-trip). Chunks are small (2-4KB).
          ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Knowledge Extractor (per chunk)                                         │
│   1. Receive chunk ID + content directly (no librarian fetch needed)   │
│   2. Extract facts/triples and embeddings from chunk content            │
│   3. For each triple:                                                   │
│      a. Emit triple to knowledge graph                                  │
│      b. Emit reified edge linking triple → chunk ID (edge pointing     │
│         to edge - first use of reification support)                     │
│   4. For each embedding:                                                │
│      a. Emit embedding with its entity ID                               │
│      b. Link entity ID → chunk ID in knowledge graph                   │
└─────────────────────────────────────────────────────────────────────────┘

Fluxo de Documentos de Texto

Documentos de texto ignoram o extrator de PDF e vão diretamente para o processador de fragmentos:

┌─────────────────────────────────────────────────────────────────────────┐
│ Librarian (initiate processing)                                         │
│   1. Emit root document metadata to knowledge graph (once)              │
│   2. Send root document ID directly to chunker (skip PDF extractor)    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Chunker (per chunk)                                                     │
│   1. Fetch text content from librarian using document ID                │
│   2. Split text into chunks                                             │
│   3. For each chunk:                                                    │
│      a. Save chunk as child document in librarian (parent = root doc) │
│      b. Emit parent-child edge to knowledge graph                       │
│      c. Send chunk document ID + chunk content to next processor        │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Knowledge Extractor                                                     │
│   (same as PDF flow)                                                    │
└─────────────────────────────────────────────────────────────────────────┘

<<<<<<< HEAD O grafo acíclico dirigido (DAG) resultante é um nível mais curto:

O grafo acíclico direcionado (DAG) resultante é um nível mais curto:

82edf2d (New md files from RunPod)

PDF:  Document → Pages → Chunks → Triples/Embeddings
Text: Document → Chunks → Triples/Embeddings

O design acomoda ambos porque o processador divide o conteúdo de forma genérica - ele usa qualquer ID de documento que recebe como pai, independentemente de ser um documento de origem ou uma página.

Esquema de Metadados (PROV-O)

Os metadados de procedência utilizam a ontologia W3C PROV-O. Isso fornece um vocabulário padrão e permite a futura assinatura/autenticação dos resultados da extração.

Conceitos Principais do PROV-O

Tipo PROV-O	Uso no TrustGraph
prov:Entity	Documento, Página, Trecho, Tripla, Incorporação
prov:Activity	Instâncias de operações de extração
prov:Agent	Componentes do TG (extrator de PDF, processador, etc.) com versões

Relacionamentos do PROV-O

Predicado	Significado	Exemplo
<<<<<<< HEAD
prov:wasDerivedFrom	Entidade derivada de outra entidade	Página foiDerivadaDe Documento
prov:wasGeneratedBy	Entidade gerada por uma atividade	Página foiGeradaPor AtividadeDeExtraçãoDePDF
prov:used	Atividade que usou uma entidade como entrada	AtividadeDeExtraçãoDePDF usou Documento
prov:wasAssociatedWith	Atividade realizada por um agente	AtividadeDeExtraçãoDePDF foiAssociadaA tg:ExtratorDePDF

======= | prov:wasDerivedFrom | Entidade derivada de outra entidade | Página derivadaDocumento | | prov:wasGeneratedBy | Entidade gerada por uma atividade | Página geradaPor AtividadeDeExtraçãoDePDF | | prov:used | Atividade que usou uma entidade como entrada | AtividadeDeExtraçãoDePDF usou Documento | | prov:wasAssociatedWith | Atividade realizada por um agente | AtividadeDeExtraçãoDePDF associadaA tg:ExtratorDePDF |

82edf2d (New md files from RunPod)

Metadados em Cada Nível

Documento de Origem (emitido pelo Librarian):

doc:123 a prov:Entity .
doc:123 dc:title "Research Paper" .
doc:123 dc:source <https://example.com/paper.pdf> .
doc:123 dc:date "2024-01-15" .
doc:123 dc:creator "Author Name" .
doc:123 tg:pageCount 42 .
doc:123 tg:mimeType "application/pdf" .

Página (emitida pelo Extrator de PDF):

page:123-1 a prov:Entity .
page:123-1 prov:wasDerivedFrom doc:123 .
page:123-1 prov:wasGeneratedBy activity:pdf-extract-456 .
page:123-1 tg:pageNumber 1 .

activity:pdf-extract-456 a prov:Activity .
activity:pdf-extract-456 prov:used doc:123 .
activity:pdf-extract-456 prov:wasAssociatedWith tg:PDFExtractor .
activity:pdf-extract-456 tg:componentVersion "1.2.3" .
activity:pdf-extract-456 prov:startedAtTime "2024-01-15T10:30:00Z" .

Bloco (emitido pelo Chunker):

chunk:123-1-1 a prov:Entity .
chunk:123-1-1 prov:wasDerivedFrom page:123-1 .
chunk:123-1-1 prov:wasGeneratedBy activity:chunk-789 .
chunk:123-1-1 tg:chunkIndex 1 .
chunk:123-1-1 tg:charOffset 0 .
chunk:123-1-1 tg:charLength 2048 .

activity:chunk-789 a prov:Activity .
activity:chunk-789 prov:used page:123-1 .
activity:chunk-789 prov:wasAssociatedWith tg:Chunker .
activity:chunk-789 tg:componentVersion "1.0.0" .
activity:chunk-789 tg:chunkSize 2048 .
activity:chunk-789 tg:chunkOverlap 200 .

Tripla (emitida pelo Extrator de Conhecimento):

# The extracted triple (edge)
entity:JohnSmith rel:worksAt entity:AcmeCorp .

# Subgraph containing the extracted triples
subgraph:001 tg:contains <<entity:JohnSmith rel:worksAt entity:AcmeCorp>> .
subgraph:001 prov:wasDerivedFrom chunk:123-1-1 .
subgraph:001 prov:wasGeneratedBy activity:extract-999 .

activity:extract-999 a prov:Activity .
activity:extract-999 prov:used chunk:123-1-1 .
activity:extract-999 prov:wasAssociatedWith tg:KnowledgeExtractor .
activity:extract-999 tg:componentVersion "2.1.0" .
activity:extract-999 tg:llmModel "claude-3" .
activity:extract-999 tg:ontology <http://example.org/ontologies/business-v1> .

Incorporação (armazenada em um armazenamento vetorial, não em um armazenamento triplo):

As incorporações são armazenadas no armazenamento vetorial com metadados, e não como triplos RDF. Cada registro de incorporação contém:

Campo	Descrição	Exemplo
vetor	O vetor de incorporação	[0.123, -0.456, ...]
entidade	URI do nó que a incorporação representa	entity:JohnSmith
chunk_id	Fragmento de origem (proveniência)	chunk:123-1-1
modelo	Modelo de incorporação usado	text-embedding-ada-002
component_version	Versão do incorporador TG	1.0.0

<<<<<<< HEAD O campo entity vincula a incorporação ao grafo de conhecimento (URI do nó). O campo chunk_id fornece a proveniência de volta ao fragmento de origem, permitindo a navegação ascendente no DAG até o documento original.

O campo entity vincula a incorporação ao grafo de conhecimento (URI do nó). O campo chunk_id fornece a proveniência de volta ao fragmento de origem, permitindo a travessia ascendente do DAG até o documento original.

82edf2d (New md files from RunPod)

Extensões do Namespace TrustGraph

Predicados personalizados sob o namespace tg: para metadados específicos de extração:

Predicado	Domínio	Descrição
tg:contains	Subgrafo	Aponta para um triplo contido neste subgrafo de extração
tg:pageCount	Documento	Número total de páginas no documento de origem
tg:mimeType	Documento	Tipo MIME do documento de origem
tg:pageNumber	Página	Número da página no documento de origem
tg:chunkIndex	Fragmento	Índice do fragmento dentro do fragmento pai
tg:charOffset	Fragmento	Deslocamento de caractere no texto pai
tg:charLength	Fragmento	Comprimento do fragmento em caracteres
tg:chunkSize	Atividade	Tamanho do fragmento configurado
tg:chunkOverlap	Atividade	Sobreposição configurada entre fragmentos
tg:componentVersion	Atividade	Versão do componente TG
tg:llmModel	Atividade	LLM usado para extração
tg:ontology	Atividade	URI da ontologia usada para guiar a extração
tg:embeddingModel	Atividade	Modelo usado para incorporações
tg:sourceText	Declaração	Texto exato do qual um triplo foi extraído
tg:sourceCharOffset	Declaração	Deslocamento de caractere dentro do fragmento onde o texto de origem começa
tg:sourceCharLength	Declaração	Comprimento do texto de origem em caracteres

Inicialização do Vocabulário (Por Coleção)

O grafo de conhecimento é neutro em relação à ontologia e é inicializado como vazio. Ao gravar dados de proveniência PROV-O em uma coleção pela primeira vez, o vocabulário deve ser inicializado com rótulos RDF para todas as classes e predicados. Isso garante a exibição legível por humanos em consultas e na interface do usuário.

Classes PROV-O:

prov:Entity rdfs:label "Entity" .
prov:Activity rdfs:label "Activity" .
prov:Agent rdfs:label "Agent" .

Predicados PROV-O:

prov:wasDerivedFrom rdfs:label "was derived from" .
prov:wasGeneratedBy rdfs:label "was generated by" .
prov:used rdfs:label "used" .
prov:wasAssociatedWith rdfs:label "was associated with" .
prov:startedAtTime rdfs:label "started at" .

<<<<<<< HEAD Predicados TrustGraph:

Predicados do TrustGraph:

82edf2d (New md files from RunPod)

tg:contains rdfs:label "contains" .
tg:pageCount rdfs:label "page count" .
tg:mimeType rdfs:label "MIME type" .
tg:pageNumber rdfs:label "page number" .
tg:chunkIndex rdfs:label "chunk index" .
tg:charOffset rdfs:label "character offset" .
tg:charLength rdfs:label "character length" .
tg:chunkSize rdfs:label "chunk size" .
tg:chunkOverlap rdfs:label "chunk overlap" .
tg:componentVersion rdfs:label "component version" .
tg:llmModel rdfs:label "LLM model" .
tg:ontology rdfs:label "ontology" .
tg:embeddingModel rdfs:label "embedding model" .
tg:sourceText rdfs:label "source text" .
tg:sourceCharOffset rdfs:label "source character offset" .
tg:sourceCharLength rdfs:label "source character length" .

<<<<<<< HEAD Observação sobre a implementação: Este processo de inicialização do vocabulário deve ser idempotente - seguro para executar várias vezes sem criar duplicatas. Pode ser acionado no processamento do primeiro documento em uma coleção, ou como uma etapa separada de inicialização da coleção.

Observação sobre a implementação: Este vocabulário de inicialização deve ser idempotente - seguro para executar várias vezes sem criar duplicatas. Pode ser acionado no processamento do primeiro documento em uma coleção, ou como uma etapa separada de inicialização da coleção.

82edf2d (New md files from RunPod)

Proveniência de Sub-Fragmentos (Alvo)

Para uma rastreabilidade mais detalhada, seria valioso registrar exatamente onde, dentro de um fragmento, uma tripla foi extraída. Isso permite:

Destacar o texto de origem exato na interface do usuário <<<<<<< HEAD Verificar a precisão da extração em relação à fonte

Verificar a precisão da extração em relação à origem

82edf2d (New md files from RunPod) Depurar a qualidade da extração no nível da frase

Exemplo com rastreamento de posição:

# The extracted triple
entity:JohnSmith rel:worksAt entity:AcmeCorp .

# Subgraph with sub-chunk provenance
subgraph:001 tg:contains <<entity:JohnSmith rel:worksAt entity:AcmeCorp>> .
subgraph:001 prov:wasDerivedFrom chunk:123-1-1 .
subgraph:001 tg:sourceText "John Smith has worked at Acme Corp since 2019" .
subgraph:001 tg:sourceCharOffset 1547 .
subgraph:001 tg:sourceCharLength 46 .

Exemplo com intervalo de texto (alternativa):

subgraph:001 tg:contains <<entity:JohnSmith rel:worksAt entity:AcmeCorp>> .
subgraph:001 prov:wasDerivedFrom chunk:123-1-1 .
subgraph:001 tg:sourceRange "1547-1593" .
subgraph:001 tg:sourceText "John Smith has worked at Acme Corp since 2019" .

Considerações de implementação:

A extração baseada em LLM pode não fornecer naturalmente as posições dos caracteres. Poderia solicitar ao LLM que retornasse a frase/frase de origem junto com as triplas extraídas. <<<<<<< HEAD Alternativamente, pós-processe para fazer uma correspondência aproximada das entidades extraídas com o texto de origem.

Alternativamente, pós-processar para fazer uma correspondência aproximada das entidades extraídas com o texto de origem.

82edf2d (New md files from RunPod) Compromisso entre a complexidade da extração e a granularidade da procedência. Pode ser mais fácil de alcançar com métodos de extração estruturados do que com a extração de LLM de formato livre.

Isso está marcado como uma meta a longo prazo - a procedência no nível do bloco deve ser implementada primeiro, com o rastreamento de subblocos como um aprimoramento futuro, se viável.

Modelo de Armazenamento Duplo

O grafo de procedência é construído progressivamente à medida que os documentos fluem pelo pipeline:

Armazenamento	O que é armazenado	Propósito
<<<<<<< HEAD
Bibliotecário	Conteúdo do documento + links pai-filho	Recuperação de conteúdo, exclusão em cascata
Grafo de Conhecimento	Arestas pai-filho + metadados	Consultas de procedência, atribuição de fatos

Ambos os armazenamentos mantêm a mesma estrutura de grafo. O bibliotecário armazena o conteúdo; o grafo armazena os relacionamentos e permite consultas de travessia.

Princípios de Design Chave

1. ID do documento como a unidade de fluxo - Os processadores passam IDs, não o conteúdo. O conteúdo é buscado do bibliotecário quando necessário. ======= | Librarian | Conteúdo do documento + links pai-filho | Recuperação de conteúdo, exclusão em cascata | | Knowledge Graph | Arestas pai-filho + metadados | Consultas de procedência, atribuição de fatos |

Ambos os armazenamentos mantêm a mesma estrutura de grafo. O librarian armazena o conteúdo; o grafo armazena os relacionamentos e permite consultas de travessia.

Princípios de Design Chave

1. ID do documento como a unidade de fluxo - Os processadores passam IDs, não o conteúdo. O conteúdo é buscado do librarian quando necessário.

82edf2d (New md files from RunPod)

2. Emitir uma vez na origem - Os metadados são gravados no grafo uma vez quando o processamento começa, e não repetidos downstream.

3. Padrão de processador consistente - Cada processador segue o mesmo padrão de receber/buscar/produzir/salvar/emitir/transmitir.

4. Construção progressiva do grafo - Cada processador adiciona seu nível ao grafo. A cadeia completa de procedência é construída incrementalmente.

<<<<<<< HEAD 5. Otimização pós-fragmentação - Após a fragmentação, as mensagens carregam tanto o ID quanto o conteúdo. Os fragmentos são pequenos (2-4 KB), portanto, incluir o conteúdo evita viagens de ida e volta desnecessárias ao bibliotecário, preservando a procedência por meio do ID.

Tarefas de Implementação

Alterações no Bibliotecário

======= 5. Otimização pós-fragmentação - Após a fragmentação, as mensagens carregam tanto o ID quanto o conteúdo. Os fragmentos são pequenos (2-4 KB), portanto, incluir o conteúdo evita viagens de ida e volta desnecessárias ao librarian, preservando a procedência por meio do ID.

Tarefas de Implementação

Alterações no Librarian

82edf2d (New md files from RunPod)

Estado Atual

Inicia o processamento do documento enviando o ID do documento para o primeiro processador. <<<<<<< HEAD Não possui conexão com o armazenamento de triplas - os metadados são agrupados com as saídas de extração.

Não possui conexão com o triple store - os metadados são agrupados com as saídas de extração.

82edf2d (New md files from RunPod) add-child-document cria links pai-filho de um nível. list-children retorna apenas os filhos imediatos.

Alterações Necessárias

<<<<<<< HEAD 1. Nova interface: Conexão com o armazenamento de triplas

O bibliotecário precisa emitir as bordas de metadados do documento diretamente para o grafo de conhecimento ao iniciar o processamento. Adicione um cliente/publicador de armazenamento de triplas ao serviço do bibliotecário. Na inicialização do processamento: emita os metadados do documento raiz como bordas do grafo (uma vez).

2. Vocabulário de tipo de documento

Padronize os valores de document_type para documentos filhos:

1. Nova interface: Conexão com o triple store

O librarian precisa emitir as bordas de metadados do documento diretamente para o knowledge graph ao iniciar o processamento. Adicionar cliente/publicador do triple store ao serviço do librarian. Na inicialização do processamento: emitir os metadados do documento raiz como bordas do grafo (uma vez).

2. Vocabulário de tipo de documento

Padronizar os valores de document_type para documentos filhos:

82edf2d (New md files from RunPod) source - documento original carregado. page - página extraída da fonte (PDF, etc.). chunk - fragmento de texto derivado da página ou da fonte.

Resumo das Alterações na Interface

Interface	Alteração
<<<<<<< HEAD
Armazenamento de triplas	Nova conexão de saída - emita bordas de metadados do documento
Início do processamento	Emita metadados para o grafo antes de encaminhar o ID do documento

======= | Triple store | Nova conexão de saída - emitir bordas de metadados do documento | | Início do processamento | Emitir metadados para o grafo antes de encaminhar o ID do documento |

82edf2d (New md files from RunPod)

Alterações no Extrator de PDF

Estado Atual

Recebe o conteúdo do documento (ou transmite documentos grandes). Extrai texto das páginas PDF. Transmite o conteúdo da página para o fragmentador. <<<<<<< HEAD Não interage com o bibliotecário ou o armazenamento de triplas.

Alterações Necessárias

1. Nova interface: Cliente do bibliotecário

O extrator de PDF precisa salvar cada página como um documento filho no bibliotecário. Adicione um cliente do bibliotecário ao serviço do extrator de PDF. Para cada página: chame add-child-document com pai = ID do documento raiz.

2. Nova interface: Conexão com o armazenamento de triplas

O extrator de PDF precisa emitir bordas pai-filho para o grafo de conhecimento. Adicione um cliente/publicador de armazenamento de triplas. Para cada página: emita uma borda que vincule o documento da página ao documento pai.

Não interage com o librarian ou o triple store.

Alterações Necessárias

1. Nova interface: Cliente do librarian

O extrator de PDF precisa salvar cada página como um documento filho no librarian. Adicionar cliente do librarian ao serviço do extrator de PDF. Para cada página: chamar add-child-document com pai = ID do documento raiz.

2. Nova interface: Conexão com o triple store

O extrator de PDF precisa emitir bordas pai-filho para o knowledge graph. Adicionar cliente/publicador do triple store. Para cada página: emitir uma borda que vincule o documento da página ao documento pai.

82edf2d (New md files from RunPod)

3. Alterar o formato de saída

Em vez de encaminhar o conteúdo da página diretamente, encaminhe o ID do documento da página. O Chunker buscará o conteúdo do "librarian" usando o ID.

Resumo das Alterações na Interface

Interface	Mudança
Librarian	Nova saída - salvar documentos filhos
Triple store	Nova saída - emitir arestas pai-filho
Mensagem de saída	Mudança de conteúdo para ID do documento

Mudanças no Chunker

Estado Atual

Recebe conteúdo da página/texto Divide em partes (chunks) Encaminha o conteúdo da parte para processadores subsequentes Sem interação com o "librarian" ou o "triple store"

Mudanças Necessárias

1. Alterar o tratamento da entrada

Receber o ID do documento em vez do conteúdo, buscar do "librarian". Adicionar cliente do "librarian" ao serviço do Chunker Buscar o conteúdo da página usando o ID do documento

2. Nova interface: Cliente do "Librarian" (escrita)

Salvar cada parte como um documento filho no "librarian". Para cada parte: chamar add-child-document com parent = ID do documento da página

3. Nova interface: Conexão com o "Triple store"

Emitir arestas pai-filho para o grafo de conhecimento. Adicionar cliente/publicador do "triple store" Para cada parte: emitir aresta ligando o documento da parte ao documento da página

4. Alterar o formato de saída

Encaminhar tanto o ID do documento da parte quanto o conteúdo da parte (otimização pós-chunker). Os processadores subsequentes recebem o ID para rastreabilidade + o conteúdo para trabalhar

Resumo das Alterações na Interface

Interface	Mudança
Mensagem de entrada	Mudança de conteúdo para ID do documento
Librarian	Nova saída (leitura + escrita) - buscar conteúdo, salvar documentos filhos
Triple store	Nova saída - emitir arestas pai-filho
Mensagem de saída	Mudança de conteúdo-apenas para ID + conteúdo

Mudanças no Extrator de Conhecimento

Estado Atual

Recebe conteúdo da parte Extrai triplas e embeddings Emite para o "triple store" e o "embedding store" A relação subjectOf aponta para o documento de nível superior (não para a parte)

Mudanças Necessárias

1. Alterar o tratamento da entrada

Receber o ID do documento da parte junto com o conteúdo. Usar o ID da parte para rastreabilidade (o conteúdo já está incluído por otimização)

2. Atualizar a rastreabilidade das triplas

Ligar as triplas extraídas à parte (não ao documento de nível superior). Usar a reificação para criar uma aresta apontando para a aresta Relação subjectOf: tripla → ID do documento da parte Primeiro uso do suporte de reificação existente

3. Atualizar a rastreabilidade dos embeddings

Ligar os IDs das entidades de embedding à parte. Emitir aresta: ID da entidade de embedding → ID do documento da parte

Resumo das Alterações na Interface

Interface	Mudança
Mensagem de entrada	Esperar ID da parte + conteúdo (não apenas conteúdo)
Triple store	Usar reificação para rastreabilidade de tripla → parte
Rastreabilidade de embedding	Ligar ID da entidade → ID da parte

Referências

Rastreabilidade em tempo de consulta: docs/tech-specs/query-time-provenance.md Padrão PROV-O para modelagem de rastreabilidade Metadados de origem existentes no grafo de conhecimento (precisa de auditoria)