# API Reference

Auto-generated from source code docstrings. For conceptual guides on how these components work together, see the [Concepts](../concepts/write-pipeline.md) section.

---

## 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

---

## Configuration

### MemoryConfig

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

---

## Protocols

### 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

Built-in LLM provider for Anthropic Claude models. Implements `LLMProvider` only — does not provide embeddings (use `OpenAIProvider` or another embedding provider alongside).

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

llm = AnthropicProvider(
    api_key="sk-ant-...",       # Anthropic API key
    model="claude-sonnet-4-20250514",  # Default model
    timeout=30.0,               # Request timeout in seconds
    max_tokens=4096,            # Default max tokens per response
)
```

Install: `pip install arandu[anthropic]`

**Key behaviors:**

- System messages are extracted from the messages list and passed via Anthropic's `system` parameter
- `response_format={"type": "json_object"}` appends a JSON instruction to the system prompt (Anthropic doesn't support this natively)
- Token usage is tracked via `LLMResult.usage`
- Markdown code fences are stripped automatically

---

## Exceptions

All SDK exceptions inherit from `MemoryError`. The SDK is **fail-safe by default** — most errors are caught internally and result in graceful degradation (empty results, logged warnings). These exceptions are raised only when explicitly documented.

```
MemoryError (base)
├── ExtractionError    — LLM extraction failed
├── ResolutionError    — entity resolution failed
├── ReconciliationError — fact reconciliation failed
├── RetrievalError     — memory retrieval failed
└── UpsertError        — database persistence failed
```

### MemoryError

Base exception for all arandu SDK errors. Catch this for catch-all handling.

```python
from arandu import MemoryError

try:
    result = await memory.write(agent_id, message, speaker_name="Rafael")
except MemoryError as e:
    print(f"SDK error: {e}")
    print(f"Caused by: {e.__cause__}")  # original exception, if any
```

### ExtractionError

Raised when fact/entity extraction from a message fails (LLM timeout, invalid JSON response, rate limit). In practice, the write pipeline catches this internally and returns an empty `WriteResult` with `success=True` — the event is still logged.

### ResolutionError

Raised when entity resolution fails (embedding provider down, LLM disambiguation timeout). The pipeline catches this internally — unresolved entities are created as new entities.

### ReconciliationError

Raised when fact reconciliation against existing knowledge fails (LLM call fails for similarity evaluation). The pipeline catches this internally — defaults to ADD (better to have a near-duplicate than lose information).

### RetrievalError

Raised when memory retrieval fails (semantic search error, reranker timeout). The read pipeline catches this internally — returns empty results rather than crashing.

### UpsertError

Raised when upserting facts or entities into the database fails (constraint violation, connection error). Individual fact upserts use savepoints — if one fact fails, the others proceed normally.

### Error handling example

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

# Write — fail-safe by default
result = await memory.write(agent_id, message, speaker_name="Rafael")
if not result.success:
    print(f"Write failed: {result.error}")
# No try/except needed — the pipeline handles errors internally

# Retrieve — also fail-safe
result = await memory.retrieve(agent_id, query)
# Empty facts = nothing found OR error occurred
# Check result.duration_ms to detect timeouts
```

---

## Background Functions

### 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

---

## Result Dataclasses

### 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

---

## See Also: Advanced API

For documentation of internal pipeline functions, sub-module exports, and additional data types not covered here, see the **Advanced** section:

- [Write Pipeline API](../advanced/write-api.md) -- extraction strategy, canonicalization, entity helpers, correction detection, pending operations, and `run_write_pipeline()`.
- [Read Pipeline API](../advanced/read-api.md) -- retrieval agent, query expansion, graph retrieval, spreading activation, context compression, emotional trends, dynamic importance, procedural memory, and `run_read_pipeline()`.
- [Database Utilities](../advanced/database.md) -- `create_engine()`, `create_session_factory()`, `init_db()`, and schema overview.
- [Data Types Reference](../advanced/data-types.md) -- all enums, dataclasses, and result types across write, read, and background modules.
