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

---
layout: default
title: "Proveniência de Extração: Modelo de Subgrafo"
parent: "Portuguese (Beta)"
---

# Proveniência de Extração: Modelo de Subgrafo

> **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.

## Problema

A proveniência em tempo de extração atualmente gera uma reificação completa para cada
<<<<<<< HEAD
tripla extraída: um `stmt_uri`, `activity_uri` e metadados PROV-O associados para cada
fato de conhecimento. O processamento de um bloco que gera 20 relacionamentos produz aproximadamente 220 triplas de proveniência, além de
aproximadamente 20 triplas de conhecimento — uma sobrecarga de aproximadamente 10:1.


Isso é caro (armazenamento, indexação, transmissão) e semanticamente
impreciso. Cada bloco é processado por uma única chamada de LLM que produz
todas as suas triplas em uma única transação. O modelo atual, baseado em tripla,
=======
tripla extraída: um `stmt_uri`, `activity_uri` e metadados PROV-O associados para
cada fato de conhecimento. O processamento de um bloco que gera 20 relacionamentos produz
aproximadamente 220 triplas de proveniência, além das aproximadamente 20 triplas de
conhecimento — uma sobrecarga de aproximadamente 10:1.

Isso é caro (armazenamento, indexação, transmissão) e semanticamente
impreciso. Cada bloco é processado por uma única chamada de LLM que produz
todas as suas triplas em uma única transação. O modelo atual, por tripla,
>>>>>>> 82edf2d (New md files from RunPod)
obscure isso, criando a ilusão de 20 eventos de extração independentes.


Além disso, dois dos quatro processadores de extração (kg-extract-ontology,
<<<<<<< HEAD
kg-extract-agent) não possuem proveniência, deixando lacunas no registro de auditoria.


## Solução

Substituir a reificação por tripla por um **modelo de subgrafo**: um registro de proveniência
por extração de bloco, compartilhado entre todas as triplas produzidas a partir desse
bloco.
=======
kg-extract-agent) não possuem proveniência, deixando lacunas no registro de
auditoria.

## Solução

Substituir a reificação por tripla por um **modelo de subgrafo**: um registro de
proveniência por extração de bloco, compartilhado entre todas as triplas produzidas
a partir desse bloco.
>>>>>>> 82edf2d (New md files from RunPod)

### Mudança de Terminologia

| Antigo | Novo |
|-----|-----|
| `stmt_uri` (`https://trustgraph.ai/stmt/{uuid}`) | `subgraph_uri` (`https://trustgraph.ai/subgraph/{uuid}`) |
| `statement_uri()` | `subgraph_uri()` |
| `tg:reifies` (1:1, identidade) | `tg:contains` (1:muitos, contenção) |

### Estrutura Alvo

Todas as triplas de proveniência devem ser inseridas no grafo nomeado `urn:graph:source`.

```
# Subgraph contains each extracted triple (RDF-star quoted triples)
<subgraph> tg:contains <<s1 p1 o1>> .
<subgraph> tg:contains <<s2 p2 o2>> .
<subgraph> tg:contains <<s3 p3 o3>> .

# Derivation from source chunk
<subgraph> prov:wasDerivedFrom <chunk_uri> .
<subgraph> prov:wasGeneratedBy <activity> .

# Activity: one per chunk extraction
<activity> rdf:type          prov:Activity .
<activity> rdfs:label        "{component_name} extraction" .
<activity> prov:used         <chunk_uri> .
<activity> prov:wasAssociatedWith <agent> .
<activity> prov:startedAtTime "2026-03-13T10:00:00Z" .
<activity> tg:componentVersion "0.25.0" .
<activity> tg:llmModel       "gpt-4" .          # if available
<activity> tg:ontology        <ontology_uri> .   # if available

# Agent: stable per component
<agent> rdf:type   prov:Agent .
<agent> rdfs:label "{component_name}" .
```

### Comparação de Volume

Para um conjunto de dados que produz N triplas extraídas:

| | Antigo (por tripla) | Novo (subgrafo) |
|---|---|---|
| `tg:contains` / `tg:reifies` | N | N |
| Triplas de atividade | ~9 x N | ~9 |
| Triplas de agente | 2 x N | 2 |
| Metadados de declaração/subgrafo | 2 x N | 2 |
| **Total de triplas de rastreabilidade** | **~13N** | **N + 13** |
| **Exemplo (N=20)** | **~260** | **33** |

## Escopo

### Processadores a serem Atualizados (rastreabilidade existente, por tripla)

**kg-extract-definitions**
(`trustgraph-flow/trustgraph/extract/kg/definitions/extract.py`)

Atualmente, chama `statement_uri()` + `triple_provenance_triples()` dentro
do loop por definição.

Alterações:
Mover a criação de `subgraph_uri()` e `activity_uri()` antes do loop
Coletar triplas `tg:contains` dentro do loop
Emitir bloco compartilhado de atividade/agente/derivação uma vez após o loop

**kg-extract-relationships**
(`trustgraph-flow/trustgraph/extract/kg/relationships/extract.py`)

Mesmo padrão que definições. As mesmas alterações.

### Processadores a serem Adicionados para Rastreabilidade (atualmente ausente)

**kg-extract-ontology**
(`trustgraph-flow/trustgraph/extract/kg/ontology/extract.py`)

Atualmente, emite triplas sem rastreabilidade. Adicionar rastreabilidade de subgrafo
usando o mesmo padrão: um subgrafo por conjunto de dados, `tg:contains` para cada
tripla extraída.

**kg-extract-agent**
(`trustgraph-flow/trustgraph/extract/kg/agent/extract.py`)

Atualmente, emite triplas sem rastreabilidade. Adicionar rastreabilidade de subgrafo
usando o mesmo padrão.

### Alterações na Biblioteca Compartilhada de Rastreabilidade

**`trustgraph-base/trustgraph/provenance/triples.py`**

Substituir `triple_provenance_triples()` por `subgraph_provenance_triples()`
Nova função aceita uma lista de triplas extraídas em vez de uma única
Gera um `tg:contains` por tripla, bloco compartilhado de atividade/agente
Remover `triple_provenance_triples()` antigo

**`trustgraph-base/trustgraph/provenance/uris.py`**

Substituir `statement_uri()` por `subgraph_uri()`

**`trustgraph-base/trustgraph/provenance/namespaces.py`**

Substituir `TG_REIFIES` por `TG_CONTAINS`

<<<<<<< HEAD
### Não no Escopo
=======
### Não está no Escopo
>>>>>>> 82edf2d (New md files from RunPod)

**kg-extract-topics**: processador de estilo antigo, não usado atualmente em
  fluxos padrão
**kg-extract-rows**: produz linhas, não triplas, modelo de rastreabilidade
  diferente
**Rastreabilidade em tempo de consulta** (`urn:graph:retrieval`): questão separada,
  já usa um padrão diferente (pergunta/exploração/foco/síntese)
**Rastreabilidade de documento/página/conjunto de dados** (decodificador PDF, divisor): já usa
  `derived_entity_triples()` que é por entidade, não por tripla — não há
  problema de redundância

## Notas de Implementação

### Reestruturação do Loop do Processador

Antes (por tripla, em relacionamentos):
```python
for rel in rels:
    # ... build relationship_triple ...
    stmt_uri = statement_uri()
    prov_triples = triple_provenance_triples(
        stmt_uri=stmt_uri,
        extracted_triple=relationship_triple,
        ...
    )
    triples.extend(set_graph(prov_triples, GRAPH_SOURCE))
```

Após (subgrafo):
```python
sg_uri = subgraph_uri()

for rel in rels:
    # ... build relationship_triple ...
    extracted_triples.append(relationship_triple)

prov_triples = subgraph_provenance_triples(
    subgraph_uri=sg_uri,
    extracted_triples=extracted_triples,
    chunk_uri=chunk_uri,
    component_name=default_ident,
    component_version=COMPONENT_VERSION,
    llm_model=llm_model,
    ontology_uri=ontology_uri,
)
triples.extend(set_graph(prov_triples, GRAPH_SOURCE))
```

<<<<<<< HEAD
### Nova Assinatura de Auxílio
=======
### Nova Assinatura de Ajuda
>>>>>>> 82edf2d (New md files from RunPod)

```python
def subgraph_provenance_triples(
    subgraph_uri: str,
    extracted_triples: List[Triple],
    chunk_uri: str,
    component_name: str,
    component_version: str,
    llm_model: Optional[str] = None,
    ontology_uri: Optional[str] = None,
    timestamp: Optional[str] = None,
) -> List[Triple]:
    """
    Build provenance triples for a subgraph of extracted knowledge.

    Creates:
    - tg:contains link for each extracted triple (RDF-star quoted)
    - One prov:wasDerivedFrom link to source chunk
    - One activity with agent metadata
    """
```

### Mudança Significativa

<<<<<<< HEAD
Esta é uma mudança significativa no modelo de rastreabilidade. A rastreabilidade não
=======
Esta é uma mudança significativa no modelo de rastreabilidade. A rastreabilidade ainda não
>>>>>>> 82edf2d (New md files from RunPod)
foi lançada, portanto, nenhuma migração é necessária. O código antigo `tg:reifies` /
`statement_uri` pode ser removido completamente.