# Configuração

Todos os parâmetros do sistema de memória são configurados através de uma única dataclass `MemoryConfig`. Todo parâmetro tem um default sensato — sobrescreva apenas o que importa para o seu caso de uso.

```python
from arandu import MemoryClient, MemoryConfig

config = MemoryConfig(
    extraction_timeout_sec=15.0,
    topk_facts=30,
    enable_reranker=True,
)

memory = MemoryClient(
    database_url="postgresql+psycopg://...",
    llm=provider,
    embeddings=provider,
    config=config,
)
```

---

## Extraction

Parâmetros que controlam como fatos, entidades e relacionamentos são extraídos de mensagens.

| Parâmetro | Tipo | Default | Descrição |
|-----------|------|---------|-----------|
| `extraction_timeout_sec` | `float` | `30.0` | Timeout por chamada LLM durante extração. No timeout, a extração retorna resultado vazio (fail-safe) — sem exceção |

**Dicas:**

- O modelo de extração é determinado pelo `LLMProvider` injetado no `MemoryClient`. Para usar um modelo mais barato na extração, injete um provider configurado com esse modelo
- Reduza `extraction_timeout_sec` se precisa de respostas mais rápidas ao custo de extrações potencialmente perdidas

---

## Entity Resolution

Parâmetros que controlam como menções de entidades extraídas são resolvidas para registros canônicos.

| Parâmetro | Tipo | Default | Descrição |
|-----------|------|---------|-----------|
| `fuzzy_threshold` | `float` | `0.85` | Threshold de similaridade de cosseno para fuzzy match direto. Score ≥ esse valor resolve diretamente; score entre 0.50 e esse valor encaminha para LLM; score < 0.50 cria nova entidade. Reduzir esse valor expande a faixa de fuzzy-resolve e reduz chamadas LLM |
| `enable_llm_resolution` | `bool` | `True` | Se deve usar um LLM para fuzzy matches ambíguos (faixa 0.50–`fuzzy_threshold`). Quando `False`, candidatos ambíguos criam nova entidade |

**Dicas:**

- Reduza `fuzzy_threshold` (ex: 0.75) para ser mais agressivo no matching — isso encolhe a faixa "ambígua" que requer chamadas LLM
- Defina `enable_llm_resolution=False` para pular o fallback LLM em matches ambíguos (mais rápido, mas pode criar mais entidades duplicadas)
- O modelo LLM para entity resolution e reconciliação é determinado pelo `LLMProvider` injetado no `MemoryClient`

---

## Retrieval

Parâmetros que controlam como fatos são recuperados em resposta a queries.

| Parâmetro | Tipo | Default | Descrição |
|-----------|------|---------|-----------|
| `topk_facts` | `int` | `20` | Número máximo de fatos a retornar |
| `topk_events` | `int` | `8` | Número máximo de eventos a considerar para contexto |
| `event_max_scan` | `int` | `200` | Máximo de eventos a escanear durante retrieval |
| `min_similarity` | `float` | `0.20` | Similaridade de cosseno mínima para resultados de busca semântica |
| `min_confidence` | `float` | `0.55` | Confiança mínima do fato para incluir nos resultados de retrieval |

!!! warning "`min_confidence` é um **filtro apenas de read-time**"
    Todos os fatos são persistidos durante o write independente do score de confidence. A filtragem acontece durante `memory.read()` / `memory.retrieve()`. Isso é por design: a confidence pode ser ajustada ao longo do tempo via reforço (confirmações NOOP), e descartar fatos no write-time seria irreversível.
| `recency_half_life_days` | `int` | `14` | Half-life (em dias) para decay exponencial de recência |
| `enable_reranker` | `bool` | `True` | Se deve usar reranking LLM nos resultados de retrieval |
| `reranker_timeout_sec` | `float` | `5.0` | Timeout para chamadas LLM do reranker |

**Dicas:**

- Aumente `topk_facts` (ex: 50) para contexto mais amplo ao custo de mais ruído
- Reduza `min_similarity` (ex: 0.10) para capturar matches semânticos mais distantes
- Aumente `recency_half_life_days` (ex: 30) se fatos mais antigos devem permanecer relevantes por mais tempo
- Defina `enable_reranker=False` para retrieval mais rápido quando precisão é menos crítica

---

## Score Weights

Pesos para a fórmula de ranking híbrido que combina múltiplos sinais de retrieval.

| Parâmetro | Tipo | Default | Descrição |
|-----------|------|---------|-----------|
| `score_weights` | `dict` | `{"semantic": 0.70, "recency": 0.20, "importance": 0.10}` | Pesos para cada sinal de scoring (devem somar ~1.0) |

```python
config = MemoryConfig(
    score_weights={
        "semantic": 0.60,   # reduzir semântico, aumentar outros sinais
        "recency": 0.25,
        "importance": 0.15,
    },
)
```

**Dicas:**

- Aumente o peso de `"recency"` para aplicações onde frescor importa mais que relevância semântica
- Aumente o peso de `"importance"` para favorecer entidades bem estabelecidas e fatos frequentemente mencionados

---

## Confidence

Parâmetros que controlam os níveis de confiança atribuídos a fatos extraídos.

| Parâmetro | Tipo | Default | Descrição |
|-----------|------|---------|-----------|
| `confidence_level_map` | `dict` | `{"explicit_statement": 0.95, "strong_inference": 0.80, "weak_inference": 0.60, "speculation": 0.40}` | Mapeamento de nomes de nível de confiança para scores numéricos |
| `confidence_default` | `float` | `0.60` | Confiança padrão quando o LLM não especifica um nível |

---

## Spreading Activation

Parâmetros que controlam como o contexto se expande a partir de fatos semente ao longo de relacionamentos de entidades.

| Parâmetro | Tipo | Default | Descrição |
|-----------|------|---------|-----------|
| `spreading_activation_hops` | `int` | `2` | Número máximo de hops de relacionamento a partir de fatos semente |
| `spreading_decay_factor` | `float` | `0.50` | Multiplicador de decay de score por hop (0.5 = dividido pela metade a cada hop) |
| `spreading_max_related_entities` | `int` | `5` | Máximo de entidades relacionadas a seguir por semente |
| `spreading_facts_per_entity` | `int` | `3` | Máximo de fatos a puxar de cada entidade relacionada |

---

## Compressão de Contexto

Parâmetros que controlam como fatos recuperados são comprimidos na string de contexto final.

| Parâmetro | Tipo | Default | Descrição |
|-----------|------|---------|-----------|
| `context_max_tokens` | `int` | `2000` | Máximo de tokens no output de contexto formatado |
| `hot_tier_ratio` | `float` | `0.50` | Parcela do orçamento de tokens para fatos com scores mais altos |
| `warm_tier_ratio` | `float` | `0.30` | Parcela do orçamento de tokens para fatos de suporte |

O orçamento restante (1 - hot - warm = 0.20) vai para o cold tier (contexto de background).

---

## Tendências Emocionais

Parâmetros para detectar padrões emocionais em mensagens do usuário.

| Parâmetro | Tipo | Default | Descrição |
|-----------|------|---------|-----------|
| `emotional_trend_window_days` | `int` | `30` | Janela para análise de tendências emocionais |
| `emotional_trend_min_events` | `int` | `5` | Mínimo de eventos necessários para detectar uma tendência |

---

## Clustering

Parâmetros para o background job de fact clustering.

| Parâmetro | Tipo | Default | Descrição |
|-----------|------|---------|-----------|
| `cluster_max_age_days` | `int` | `90` | Idade máxima dos fatos a incluir no clustering |
| `cluster_min_facts` | `int` | `2` | Mínimo de fatos por cluster |
| `community_similarity_threshold` | `float` | `0.75` | Threshold de similaridade de cosseno para agrupar clusters em comunidades |
| `community_min_clusters` | `int` | `2` | Mínimo de clusters para formar uma comunidade |

---

## Consolidation

Parâmetros para o background job de consolidation.

| Parâmetro | Tipo | Default | Descrição |
|-----------|------|---------|-----------|
| `consolidation_min_events` | `int` | `3` | Mínimo de eventos antes de rodar consolidation |
| `consolidation_lookback_days` | `int` | `7` | Quantos dias olhar para trás (em dias) em busca de padrões |

---

## Sleep-Time Compute

Parâmetros para importance scoring e summary refresh em background.

| Parâmetro | Tipo | Default | Descrição |
|-----------|------|---------|-----------|
| `importance_recency_halflife_days` | `int` | `30` | Half-life para sinal de recência no importance scoring |
| `summary_refresh_interval_days` | `int` | `7` | Dias antes de um resumo de entidade ser considerado obsoleto |

---

## Memify

Parâmetros para o background job de memify (conhecimento episódico → procedural).

| Parâmetro | Tipo | Default | Descrição |
|-----------|------|---------|-----------|
| `vitality_stale_threshold` | `float` | `0.2` | Score de vitalidade abaixo do qual um fato é considerado obsoleto |
| `memify_merge_similarity_threshold` | `float` | `0.90` | Threshold de similaridade para mesclar procedimentos similares |

---

## Memória Procedural

Parâmetros para retrieval de memória diretiva/procedural.

| Parâmetro | Tipo | Default | Descrição |
|-----------|------|---------|-----------|
| `directive_max_tokens` | `int` | `300` | Máximo de tokens para diretivas procedurais |
| `directive_cache_ttl_minutes` | `int` | `30` | Cache TTL para lookups de diretivas |
| `contradiction_similarity_threshold` | `float` | `0.80` | Threshold para detectar diretivas contraditórias |

---

## Locale / Deploy

| Parâmetro | Tipo | Default | Descrição |
|-----------|------|---------|-----------|
| `timezone` | `str` | `"UTC"` | Timezone IANA para interpretar referências temporais relativas |

O parâmetro `timezone` afeta como referências temporais relativas ("ontem", "semana passada", "hoje de manhã") são interpretadas durante a extração de fatos e retrieval. Todos os timestamps no banco são armazenados em **UTC** independente desta configuração.

Por exemplo: se `timezone="Asia/Tokyo"` e o usuário diz "ontem", o SDK interpreta "ontem" relativo ao horário de Tokyo (JST), não UTC.

---

## Catálogo Aberto (Extensões do Deployer)

Parâmetros para estender o catálogo de atributos built-in com entradas customizadas.

| Parâmetro | Tipo | Default | Descrição |
|-----------|------|---------|-----------|
| `extra_attribute_keys` | `set[str]` | `set()` | Attribute keys adicionais reconhecidas durante extração |
| `attribute_aliases` | `dict[str, str]` | `{}` | Aliases para attribute keys (ex: `{"hometown": "city"}`) |
| `extra_namespaces` | `set[str]` | `set()` | Namespaces de entidade adicionais além dos tipos built-in |
| `extra_self_references` | `frozenset[str]` | `frozenset()` | Palavras adicionais tratadas como auto-referências (ex: `{"yo"}` para espanhol) |
| `extra_relationship_hints` | `frozenset[str]` | `frozenset()` | Palavras adicionais de dica de relacionamento para entity resolution |

---

## Limites

| Parâmetro | Tipo | Default | Descrição |
|-----------|------|---------|-----------|
| `max_facts_per_event` | `int` | `100` | Máximo de fatos extraídos de uma única mensagem |
| `embedding_dimensions` | `int` | `1536` | Dimensionalidade dos vetores de embedding (deve corresponder ao seu provider) |
