# Referência da API

Gerada automaticamente a partir dos docstrings do código-fonte. Para guias conceituais sobre como esses componentes funcionam juntos, veja a seção [Conceitos](../concepts/write-pipeline.md).

---

## Client

### MemoryClient

::: arandu.MemoryClient
    options:
      show_source: false
      heading_level: 4
      members_order: source

### WriteResult

::: arandu.WriteResult
    options:
      show_source: false
      heading_level: 4

### RetrieveResult

::: arandu.RetrieveResult
    options:
      show_source: false
      heading_level: 4

### ScoredFact

::: arandu.ScoredFact
    options:
      show_source: false
      heading_level: 4

### PipelineTrace

::: arandu.PipelineTrace
    options:
      show_source: false
      heading_level: 4

---

## Configuração

### MemoryConfig

::: arandu.MemoryConfig
    options:
      show_source: false
      heading_level: 4

---

## Protocolos

### LLMProvider

::: arandu.LLMProvider
    options:
      show_source: false
      heading_level: 4

### EmbeddingProvider

::: arandu.EmbeddingProvider
    options:
      show_source: false
      heading_level: 4

---

## Providers

### OpenAIProvider

::: arandu.providers.openai.OpenAIProvider
    options:
      show_source: false
      heading_level: 4

### AnthropicProvider

Provider LLM integrado para modelos Anthropic Claude. Implementa apenas `LLMProvider` — não fornece embeddings (use `OpenAIProvider` ou outro provider de embeddings junto).

```python
from arandu.providers.anthropic import AnthropicProvider

llm = AnthropicProvider(
    api_key="sk-ant-...",       # Chave de API Anthropic
    model="claude-sonnet-4-20250514",  # Modelo padrão
    timeout=30.0,               # Timeout da requisição em segundos
    max_tokens=4096,            # Máximo de tokens por resposta
)
```

Instalação: `pip install arandu[anthropic]`

**Comportamentos principais:**

- Mensagens de sistema são extraídas da lista de mensagens e passadas via parâmetro `system` da Anthropic
- `response_format={"type": "json_object"}` adiciona uma instrução JSON ao system prompt (Anthropic não suporta isso nativamente)
- Uso de tokens é rastreado via `LLMResult.usage`
- Code fences markdown são removidos automaticamente

---

## Exceções

Todas as exceções do SDK herdam de `MemoryError`. O SDK é **fail-safe por padrão** — a maioria dos erros é capturada internamente e resulta em degradação gradual (resultados vazios, warnings logados). Essas exceções são lançadas apenas quando explicitamente documentado.

```
MemoryError (base)
├── ExtractionError    — extração LLM falhou
├── ResolutionError    — resolução de entidades falhou
├── ReconciliationError — reconciliação de fatos falhou
├── RetrievalError     — recuperação de memória falhou
└── UpsertError        — persistência no banco falhou
```

### MemoryError

Exceção base para todos os erros do SDK arandu. Capture esta para tratamento genérico.

```python
from arandu import MemoryError

try:
    result = await memory.write(agent_id, message)
except MemoryError as e:
    print(f"Erro do SDK: {e}")
    print(f"Causado por: {e.__cause__}")  # exceção original, se houver
```

### ExtractionError

Lançada quando a extração de fatos/entidades de uma mensagem falha (timeout do LLM, resposta JSON inválida, rate limit). Na prática, o write pipeline captura isso internamente e retorna um `WriteResult` vazio com `success=True` — o evento ainda é registrado.

### ResolutionError

Lançada quando a resolução de entidades falha (provider de embeddings fora do ar, timeout de desambiguação do LLM). O pipeline captura isso internamente — entidades não resolvidas são criadas como novas entidades.

### ReconciliationError

Lançada quando a reconciliação de fatos contra o conhecimento existente falha (chamada LLM falha na avaliação de similaridade). O pipeline captura isso internamente — o padrão é ADD (melhor ter um quase-duplicado do que perder informação).

### RetrievalError

Lançada quando a recuperação de memória falha (erro na busca semântica, timeout do reranker). O read pipeline captura isso internamente — retorna resultados vazios em vez de crashar.

### UpsertError

Lançada quando o upsert de fatos ou entidades no banco de dados falha (violação de constraint, erro de conexão). Upserts individuais de fatos usam savepoints — se um fato falha, os outros prosseguem normalmente.

### Exemplo de tratamento de erros

```python
from arandu import MemoryError, ExtractionError, RetrievalError

# Write — fail-safe por padrão
result = await memory.write(agent_id, message, speaker_name="Rafael")
if not result.success:
    print(f"Write falhou: {result.error}")
# Não precisa de try/except — o pipeline trata erros internamente

# Retrieve — também fail-safe
result = await memory.retrieve(agent_id, query)
# Facts vazios = nada encontrado OU erro ocorreu
# Verifique result.duration_ms para detectar timeouts
```

---

## Funções de Background

### Clustering

#### cluster_user_facts

::: arandu.cluster_user_facts
    options:
      show_source: false
      heading_level: 5

#### detect_communities

::: arandu.detect_communities
    options:
      show_source: false
      heading_level: 5

### Consolidation

#### run_consolidation

::: arandu.run_consolidation
    options:
      show_source: false
      heading_level: 5

#### run_profile_consolidation

::: arandu.run_profile_consolidation
    options:
      show_source: false
      heading_level: 5

### Memify

#### run_memify

::: arandu.run_memify
    options:
      show_source: false
      heading_level: 5

#### compute_vitality

::: arandu.compute_vitality
    options:
      show_source: false
      heading_level: 5

### Sleep-Time Compute

#### compute_entity_importance

::: arandu.compute_entity_importance
    options:
      show_source: false
      heading_level: 5

#### refresh_entity_summaries

::: arandu.refresh_entity_summaries
    options:
      show_source: false
      heading_level: 5

#### detect_entity_communities

::: arandu.detect_entity_communities
    options:
      show_source: false
      heading_level: 5

---

## Dataclasses de Resultado

### ClusteringResult

::: arandu.ClusteringResult
    options:
      show_source: false
      heading_level: 4

### CommunityDetectionResult

::: arandu.CommunityDetectionResult
    options:
      show_source: false
      heading_level: 4

### ConsolidationResult

::: arandu.ConsolidationResult
    options:
      show_source: false
      heading_level: 4

### MemifyResult

::: arandu.MemifyResult
    options:
      show_source: false
      heading_level: 4

### EntityImportanceResult

::: arandu.EntityImportanceResult
    options:
      show_source: false
      heading_level: 4

### SummaryRefreshResult

::: arandu.SummaryRefreshResult
    options:
      show_source: false
      heading_level: 4

---

## Veja Tambem: API Avancada

Para documentacao de funcoes internas do pipeline, exports de sub-modulos e tipos de dados adicionais nao cobertos aqui, veja a secao **Avancado**:

- [API do Write Pipeline](../advanced/write-api.md) -- estrategia de extracao, canonicalizacao, helpers de entidades, deteccao de correcoes, operacoes pendentes e `run_write_pipeline()`.
- [API do Read Pipeline](../advanced/read-api.md) -- retrieval agent, expansao de query, retrieval de grafo, spreading activation, compressao de contexto, tendencias emocionais, importancia dinamica, memoria procedimental e `run_read_pipeline()`.
- [Utilitarios de Banco de Dados](../advanced/database.md) -- `create_engine()`, `create_session_factory()`, `init_db()` e visao geral do schema.
- [Referencia de Tipos de Dados](../advanced/data-types.md) -- todos os enums, dataclasses e tipos de resultado dos modulos de escrita, leitura e background.
