# Referencia de Tipos de Dados

Esta pagina documenta todas as dataclasses, enums e tipos de resultado usados nos pipelines de escrita, leitura e jobs de background que nao sao cobertos na [Referencia da API](../reference/index.md) principal.

---

## Tipos do Write Pipeline

### InputType

```python
class InputType(str, Enum)
```

Tipos de classificacao de texto de entrada, determinados por heuristicas em `classify_input()`.

| Valor | Descricao |
|-------|-----------|
| `SHORT` | Menos de 500 caracteres. |
| `MEDIUM` | 500-2000 caracteres, nao estruturado. |
| `LONG` | Mais de 2000 caracteres, nao estruturado. |
| `STRUCTURED` | Mais de 500 caracteres com headers, bullets ou tabelas. |

### ExtractionMode

```python
class ExtractionMode(str, Enum)
```

| Valor | Descricao |
|-------|-----------|
| `SINGLE_SHOT` | Chamada unica de LLM para extracao. |
| `CHUNKED` | Entrada e dividida em chunks, cada um processado separadamente. |

### InputClassification

```python
@dataclass
class InputClassification
```

Resultado de `classify_input()`. Veja [API do Write Pipeline](write-api.md#inputclassification) para referencia completa dos campos.

### ExtractionStrategy

```python
@dataclass
class ExtractionStrategy
```

Resultado de `select_strategy()`. Veja [API do Write Pipeline](write-api.md#extractionstrategy) para referencia completa dos campos.

### CorrectionResult

```python
@dataclass
class CorrectionResult
```

Resultado da deteccao de correcoes.

| Campo | Tipo | Padrao | Descricao |
|-------|------|--------|-----------|
| `corrections_detected` | `int` | `0` | Numero de correcoes encontradas. |
| `corrected_keys` | `list[str]` | `[]` | Chaves de atributo que foram corrigidas. |
| `facts_corrected_ids` | `list[str]` | `[]` | IDs dos fatos antigos que foram corrigidos. |

---

## Tipos do Read Pipeline

### ExpandedQuery

```python
@dataclass
class ExpandedQuery
```

Resultado da expansao de query (entity priming).

| Campo | Tipo | Descricao |
|-------|------|-----------|
| `primed_entities` | `list[str]` | Entity keys descobertas via alias + KG priming. |
| `temporal_range` | `tuple[datetime, datetime] | None` | Faixa de datas resolvida. |
| `expanded_terms` | `list[str]` | Termos de contexto adicionais dos fatos das entidades. |

### PatternQuery

```python
@dataclass
class PatternQuery
```

Uma query baseada em padrao para matching de sinal de keyword.

| Campo | Tipo | Padrao | Descricao |
|-------|------|--------|-----------|
| `entity_pattern` | `str` | -- | Padrao SQL LIKE para matching de entity_key. |
| `attribute_filter` | `str | None` | `None` | Filtro opcional de chave de atributo. |

### RetrievalPlan

```python
@dataclass
class RetrievalPlan
```

Saida do retrieval agent LLM planner. Veja [API do Read Pipeline](read-api.md#retrievalplan) para referencia completa dos campos.

### GraphRetrievalResult

```python
@dataclass
class GraphRetrievalResult
```

Resultado do retrieval baseado em grafo BFS de 2 saltos.

| Campo | Tipo | Padrao | Descricao |
|-------|------|--------|-----------|
| `facts` | `list[dict[str, Any]]` | `[]` | Dicts de fatos pontuados com `source="graph"`. |
| `neighbor_keys` | `list[str]` | `[]` | Entity keys descobertas via BFS. |
| `edges_traversed` | `int` | `0` | Total de arestas examinadas durante BFS. |
| `edges` | `list[dict[str, Any]]` | `[]` | Dicts de arestas deduplicadas com nomes de exibicao. |

### SpreadingActivationResult

```python
@dataclass
class SpreadingActivationResult
```

Resultado da expansao por spreading activation.

| Campo | Tipo | Padrao | Descricao |
|-------|------|--------|-----------|
| `candidates` | `list[RetrievalCandidate]` | `[]` | Candidatos expandidos dos saltos 1-2. |
| `meta_observations` | `list[Any]` | `[]` | Meta-observacoes relevantes referenciando fatos semente. |
| `entities_explored` | `list[str]` | `[]` | Entity keys exploradas durante spreading. |
| `clusters_explored` | `list[str]` | `[]` | Cluster IDs explorados durante spreading. |
| `hop1_count` | `int` | `0` | Numero de fatos encontrados no salto 1. |
| `hop2_count` | `int` | `0` | Numero de fatos encontrados no salto 2. |
| `kg_relationships_explored` | `int` | `0` | Numero de relacionamentos KG percorridos. |

### CompressedContext

```python
@dataclass
class CompressedContext
```

Resultado da compressao de contexto (camadas hot/warm/cold).

| Campo | Tipo | Padrao | Descricao |
|-------|------|--------|-----------|
| `context_text` | `str` | `""` | String de contexto final pronta para prompt. |
| `hot_count` | `int` | `0` | Numero de fatos na camada hot (Tier 1). |
| `warm_count` | `int` | `0` | Numero de fatos na camada warm (Tier 2). |
| `cold_count` | `int` | `0` | Numero de itens na camada cold (Tier 3). |
| `total_tokens` | `int` | `0` | Contagem estimada de tokens do context_text. |

### EmotionalTrendsResult

```python
@dataclass
class EmotionalTrendsResult
```

Resultado da materializacao de tendencias emocionais.

| Campo | Tipo | Padrao | Descricao |
|-------|------|--------|-----------|
| `emotion_counts` | `dict[str, int]` | `{}` | Mapeamento de emocao para contagem de ocorrencias. |
| `trend_direction` | `str` | `"stable"` | `"increasing"`, `"decreasing"` ou `"stable"`. |
| `dominant_emotion` | `str | None` | `None` | Emocao mais frequente. |
| `trigger_keywords` | `list[str]` | `[]` | Top keywords de eventos de alta intensidade. |
| `avg_intensity` | `float` | `0.0` | Intensidade emocional media. |
| `dominant_intensity` | `float` | `0.0` | Intensidade media da emocao dominante. |
| `dominant_energy` | `str` | `"medium"` | Nivel de energia predominante. |
| `events_analyzed` | `int` | `0` | Numero de eventos analisados. |
| `observation_created` | `bool` | `False` | Se uma meta-observacao foi criada/atualizada. |
| `observation_id` | `str | None` | `None` | ID da observacao criada/atualizada. |

### DirectiveBlock

```python
@dataclass
class DirectiveBlock
```

Resultado da geracao de diretivas (memoria procedimental).

| Campo | Tipo | Padrao | Descricao |
|-------|------|--------|-----------|
| `text` | `str` | `""` | Bloco de instrucoes comportamentais coeso. |
| `directive_count` | `int` | `0` | Numero de diretivas ativas usadas. |
| `cache_hit` | `bool` | `False` | Se foi servido do cache. |

### ContradictionResult

```python
@dataclass
class ContradictionResult
```

Resultado da verificacao de contradicao entre diretivas.

| Campo | Tipo | Padrao | Descricao |
|-------|------|--------|-----------|
| `has_contradiction` | `bool` | `False` | Se uma contradicao foi encontrada. |
| `conflicting_directive` | `str | None` | `None` | Titulo da diretiva conflitante. |
| `resolution` | `str | None` | `None` | Explicacao da resolucao. |

---

## Tipos de Resultado de Background Jobs

### ClusteringResult

```python
@dataclass
class ClusteringResult
```

Resultado do clustering de fatos.

| Campo | Tipo | Padrao | Descricao |
|-------|------|--------|-----------|
| `clusters_created` | `int` | `0` | Numero de novos clusters criados. |
| `clusters_reinforced` | `int` | `0` | Numero de clusters existentes atualizados. |
| `summaries_generated` | `int` | `0` | Numero de sumarios de cluster gerados via LLM. |
| `facts_assigned` | `int` | `0` | Numero de fatos atribuidos a clusters. |

### CommunityDetectionResult

```python
@dataclass
class CommunityDetectionResult
```

Resultado da deteccao de comunidades cross-entity.

| Campo | Tipo | Padrao | Descricao |
|-------|------|--------|-----------|
| `communities_created` | `int` | `0` | Novas observacoes de comunidade criadas. |
| `communities_reinforced` | `int` | `0` | Observacoes de comunidade existentes reforcadas. |
| `clusters_in_communities` | `int` | `0` | Total de clusters atribuidos a comunidades. |
| `skipped` | `bool` | `False` | Se a deteccao foi pulada. |
| `skip_reason` | `str | None` | `None` | Motivo de ter sido pulada. |

### ConsolidationResult

```python
@dataclass
class ConsolidationResult
```

Resultado da consolidacao L2/L3.

| Campo | Tipo | Padrao | Descricao |
|-------|------|--------|-----------|
| `events_processed` | `int` | `0` | Numero de eventos analisados. |
| `observations_created` | `int` | `0` | Novas meta-observacoes criadas. |
| `observations_reinforced` | `int` | `0` | Observacoes existentes reforcadas. |
| `skipped` | `bool` | `False` | Se a consolidacao foi pulada. |
| `skip_reason` | `str | None` | `None` | Motivo de ter sido pulada. |

### MemifyResult

```python
@dataclass
class MemifyResult
```

Resultado do pipeline memify (scoring de vitalidade, marcacao de obsolescencia, gerenciamento de arestas).

| Campo | Tipo | Padrao | Descricao |
|-------|------|--------|-----------|
| `facts_scored` | `int` | `0` | Numero de fatos pontuados por vitalidade. |
| `facts_marked_stale` | `int` | `0` | Numero de fatos marcados como obsoletos. |
| `edges_reinforced` | `int` | `0` | Numero de arestas KG reforcadas. |
| `merges_executed` | `int` | `0` | Numero de merges de entidade executados. |

### EntityImportanceResult

```python
@dataclass
class EntityImportanceResult
```

Resultado do scoring de importancia de entidades (sleep-time compute).

| Campo | Tipo | Padrao | Descricao |
|-------|------|--------|-----------|
| `entities_scored` | `int` | `0` | Numero de entidades pontuadas. |
| `top_entities` | `list[tuple[str, float]]` | `[]` | Top entidades por score (pares chave, score). |

### SummaryRefreshResult

```python
@dataclass
class SummaryRefreshResult
```

Resultado da atualizacao de sumarios de entidades (sleep-time compute).

| Campo | Tipo | Padrao | Descricao |
|-------|------|--------|-----------|
| `summaries_refreshed` | `int` | `0` | Numero de sumarios gerados. |
| `summaries_skipped` | `int` | `0` | Numero de entidades puladas. |

---

## Funcoes de Background

### tag_event_emotion

Infere emocao, intensidade e energia a partir de texto de evento via LLM.

```python
async def tag_event_emotion(
    event_text: str,
    llm: LLMProvider,
) -> dict[str, Any] | None
```

| Parametro | Tipo | Descricao |
|-----------|------|-----------|
| `event_text` | `str` | Texto para analisar. |
| `llm` | `LLMProvider` | Provider de LLM injetado. |

**Retorna:** Dict com chaves `emotion`, `intensity`, `energy`, ou `None` em caso de falha.

```python
from arandu.background import tag_event_emotion

result = await tag_event_emotion("Estou muito feliz hoje!", llm)
# {"emotion": "joy", "intensity": 0.85, "energy": "high"}
```

---

## Modelos de Banco de Dados

Os modelos SQLAlchemy abaixo definem a camada de persistencia. Eles vivem em `arandu.models` e sao uteis para queries avancadas executadas diretamente contra o banco de dados.

### MemoryFact

Ledger de fatos versionados — armazena fatos estruturados com janelas de validade.

| Coluna | Tipo | Descricao |
|--------|------|-----------|
| `id` | `UUID` | Chave primaria. |
| `user_id` | `Text` | ID do usuario proprietario (qualquer string: UUID, email, numerico, etc.). |
| `entity_type` | `String` | Tipo da entidade (ex: `"person"`). |
| `entity_key` | `String` | Chave canonica da entidade (ex: `"person:ana"`). |
| `entity_name` | `String?` | Nome legivel da entidade. |
| `attribute_key` | `String?` | Chave do atributo (ex: `"occupation"`). |
| `fact_text` | `Text` | Fato em linguagem natural. |
| `category` | `String(50)?` | Categoria do fato. |
| `confidence` | `Float` | Score de confianca (padrao 0.8). |
| `importance` | `Float` | Score de importancia (padrao 0.5). |
| `is_sensitive` | `Boolean` | Se o fato contem dados sensiveis. |
| `valid_from` | `DateTime` | Inicio da janela de validade. |
| `valid_to` | `DateTime?` | Fim da validade (`NULL` = ativo atualmente). |
| `ttl_days` | `Integer?` | Time-to-live opcional em dias. |
| `source_event_id` | `UUID?` | FK para `MemoryEvent`. |
| `supersedes_fact_id` | `UUID?` | ID do fato que este substitui. |
| `embedding_vec` | `Vector(1536)` | Embedding pgvector para busca semantica. |
| `vitality_score` | `Float?` | Score de vitalidade do sleep-time. |
| `is_stale` | `Boolean` | Se foi marcado como obsoleto pelo memify. |
| `cluster_id` | `UUID?` | FK para `MemoryCluster`. |
| `times_retrieved` | `Integer` | Quantas vezes este fato foi recuperado. |
| `search_vector` | `TSVECTOR` | Coluna de indice de busca full-text. |

### MemoryEntity

No de entidade de primeira classe no knowledge graph.

| Coluna | Tipo | Descricao |
|--------|------|-----------|
| `id` | `UUID` | Chave primaria. |
| `user_id` | `Text` | ID do usuario proprietario (qualquer string: UUID, email, numerico, etc.). |
| `canonical_key` | `String(128)` | Chave canonica unica (ex: `"person:ana"`). |
| `display_name` | `String(256)?` | Nome de exibicao legivel. |
| `entity_type` | `String(32)` | Tipo (`"person"`, `"organization"`, etc.). |
| `summary_text` | `Text?` | Sumario da entidade gerado por LLM. |
| `embedding_vec` | `Vector(1536)` | Embedding da entidade. |
| `fact_count` | `Integer` | Numero de fatos vinculados. |
| `importance_score` | `Float?` | Score de importancia do sleep-time. |
| `is_active` | `Boolean` | Se a entidade esta ativa. |

Constraint unica: `(user_id, canonical_key)`.

### MemoryEntityAlias

Mapeia nomes de alias para chaves canonicas de entidade para resolucao de entidades.

| Coluna | Tipo | Descricao |
|--------|------|-----------|
| `id` | `UUID` | Chave primaria. |
| `user_id` | `Text` | ID do usuario proprietario (qualquer string: UUID, email, numerico, etc.). |
| `alias` | `String` | Texto do alias (ex: `"Ana"`). |
| `canonical_entity_key` | `String` | Chave canonica de destino. |
| `canonical_entity_type` | `String` | Tipo da entidade de destino. |

Constraint unica: `(user_id, alias)`.

### MemoryEntityRelationship

Aresta direcionada entre duas entidades no knowledge graph.

| Coluna | Tipo | Descricao |
|--------|------|-----------|
| `id` | `UUID` | Chave primaria. |
| `user_id` | `Text` | ID do usuario proprietario (qualquer string: UUID, email, numerico, etc.). |
| `source_entity_key` | `String(128)` | Chave canonica da entidade de origem. |
| `target_entity_key` | `String(128)` | Chave canonica da entidade de destino. |
| `rel_type` | `String(64)` | Tipo de relacionamento (ex: `"works_at"`, `"mentored_by"`). |
| `strength` | `Float` | Forca da aresta (padrao 0.8). |
| `evidence_fact_id` | `UUID?` | FK para o fato que evidencia esta aresta. |
| `provenance` | `String(16)` | Como a aresta foi criada (`"rule"`, `"llm"`). |
| `valid_from` | `DateTime` | Inicio da validade. |
| `valid_to` | `DateTime?` | Fim da validade (`NULL` = ativa). |

Constraint unica: `(user_id, source_entity_key, target_entity_key, rel_type)`.

#### Tipos de Relacionamento Dinamicos

O campo `rel_type` aceita **qualquer** string curta e descritiva em `snake_case` — nao e restrito a um conjunto fixo. O pipeline de extracao instrui o LLM a escolher o tipo mais descritivo para cada relacionamento.

Tipos comuns (usados como exemplos no prompt de extracao, nao como restricoes):

`works_at`, `manages`, `reports_to`, `family_of`, `friend_of`, `partner_of`, `owns`, `lives_in`, `member_of`, `studies_at`, `works_with`

O LLM tambem pode produzir tipos como `mentored_by`, `inspired_by`, `competed_with`, ou qualquer outro tipo descritivo.

**Normalizacao**: Todos os tipos de relacionamento sao normalizados via `normalize_rel_type()` antes da persistencia:

- Lowercase + underscores (ex: `"Mentored By"` → `"mentored_by"`)
- Aliases conhecidos sao mapeados para tipos comuns (ex: `"boss"` → `"reports_to"`, `"spouse"` → `"partner_of"`)
- Tipos desconhecidos passam apos sanitizacao

O set `CANONICAL_REL_TYPES` em `arandu.constants` esta disponivel como **referencia** para consumers que queiram filtrar por tipos conhecidos, mas nao e usado como filtro de validacao.

Veja [Vinculação de Evidência e Cascata de Invalidação](../concepts/write-pipeline.md#vinculacao-de-evidencia-e-cascata-de-invalidacao) para como relacionamentos são vinculados a fatos e automaticamente limpos quando fatos mudam.

### MemoryEvent

Log imutavel de eventos — armazena todas as mensagens do usuario com embeddings.

| Coluna | Tipo | Descricao |
|--------|------|-----------|
| `id` | `UUID` | Chave primaria. |
| `user_id` | `Text` | ID do usuario proprietario (qualquer string: UUID, email, numerico, etc.). |
| `occurred_at` | `DateTime` | Quando o evento aconteceu. |
| `text` | `Text` | Conteudo textual do evento. |
| `source` | `String` | Origem (padrao `"api"`). |
| `importance` | `Float` | Score de importancia (padrao 0.5). |
| `embedding_vec` | `Vector(1536)` | Embedding do evento para retrieval. |
| `emotion_primary` | `String(32)?` | Label de emocao primaria. |
| `emotion_intensity` | `Float?` | Intensidade da emocao (0-1). |
| `energy_level` | `String(16)?` | Nivel de energia (`"low"`, `"medium"`, `"high"`). |

### MemoryCluster

Cluster semantico agrupando fatos relacionados para contexto mais rico.

| Coluna | Tipo | Descricao |
|--------|------|-----------|
| `id` | `UUID` | Chave primaria. |
| `user_id` | `Text` | ID do usuario proprietario (qualquer string: UUID, email, numerico, etc.). |
| `label` | `String(128)` | Label do cluster. |
| `summary_text` | `Text?` | Sumario do cluster gerado por LLM. |
| `cluster_type` | `String(32)` | Tipo do cluster (padrao `"auto"`). |
| `fact_count` | `Integer` | Numero de fatos no cluster. |
| `importance` | `Float` | Importancia do cluster (padrao 0.5). |
| `embedding_vec` | `Vector(1536)` | Embedding do cluster. |
| `is_active` | `Boolean` | Se o cluster esta ativo. |

### MemoryMetaObservation

Meta-observacoes derivadas da consolidacao — padroes, insights, tendencias.

| Coluna | Tipo | Descricao |
|--------|------|-----------|
| `id` | `UUID` | Chave primaria. |
| `user_id` | `Text` | ID do usuario proprietario (qualquer string: UUID, email, numerico, etc.). |
| `observation_type` | `String(32)` | Tipo (`"pattern"`, `"trend"`, `"community"`, etc.). |
| `title` | `String(256)` | Titulo curto. |
| `text` | `Text` | Texto completo da observacao. |
| `supporting_event_ids` | `JSONB` | Lista de UUIDs de eventos de suporte. |
| `supporting_fact_ids` | `JSONB` | Lista de UUIDs de fatos de suporte. |
| `confidence` | `Float` | Confianca (padrao 0.7). |
| `importance` | `Float` | Importancia (padrao 0.5). |
| `times_reinforced` | `Integer` | Quantas vezes esta observacao foi reforcada. |
| `is_active` | `Boolean` | Se a observacao esta ativa. |
| `embedding_vec` | `Vector(1536)` | Embedding da observacao. |

### MemoryAttributeRegistry

Registro para gerenciamento de chaves de atributo — rastreia chaves propostas vs ativas.

| Coluna | Tipo | Descricao |
|--------|------|-----------|
| `id` | `UUID` | Chave primaria. |
| `key` | `String(64)` | Chave de atributo unica. |
| `status` | `String(20)` | `"proposed"` ou `"active"`. |
| `value_type` | `String(20)` | Tipo de valor esperado (padrao `"string"`). |
| `conflict_policy` | `String(20)` | Como lidar com conflitos (padrao `"supersede"`). |
| `ttl_days` | `Integer?` | TTL padrao opcional para fatos com esta chave. |
| `seen_count` | `Integer` | Quantas vezes esta chave foi vista. |
| `proposed_by` | `String(20)` | Quem propos a chave (`"llm"`, `"user"`). |
| `reason` | `Text?` | Por que a chave foi proposta. |
