# Filosofia de Design

O `arandu` é projetado em torno de duas bases: **princípios de engenharia de software** que o tornam confiável e extensível, e **modelos de ciência cognitiva** que informam sua arquitetura. Esta página cobre ambos — as decisões de engenharia e os paralelos com neurociência que as inspiraram.

---

## Princípios de Engenharia

### Injeção de Dependência Baseada em Protocol

O SDK usa `typing.Protocol` do Python para todas as dependências externas (LLM, embeddings). Sem herança necessária — apenas implemente as assinaturas dos métodos:

```python
@runtime_checkable
class LLMProvider(Protocol):
    async def complete(
        self,
        messages: list[dict],
        temperature: float = 0,
        response_format: dict | None = None,
        max_tokens: int | None = None,
    ) -> str: ...
```

**Por quê:** Vendor lock-in mata adoção. Ao usar tipagem estrutural (duck typing), qualquer LLM provider funciona sem herdar de uma classe base. O provider OpenAI está incluído por conveniência, mas você pode trocar por Anthropic, modelos locais ou endpoints customizados sem nenhuma mudança no SDK.

### Fail-Safe por Padrão

Todo estágio do pipeline tem comportamento de fallback:

| Estágio | Falha | Fallback |
|---------|-------|----------|
| Extraction | Timeout/erro do LLM | Retorna extração vazia; evento ainda é registrado |
| Entity Resolution | Fallback LLM falha | Cria nova entidade (prefere duplicatas a dados perdidos) |
| Reconciliation | Erro do LLM | Default para ADD |
| Reranking | Reranker falha | Mantém ranking original |
| Background jobs | Qualquer job falha | Outros jobs continuam independentemente |

**Por quê:** Em um agente de IA em produção, a memória é um sistema de suporte — nunca deve crashar o fluxo principal. Uma resposta degradada (faltando algum contexto) é sempre melhor que um erro.

### Composição Sobre Herança

O SDK não tem classes base abstratas, nem hierarquias profundas de classes. É construído com módulos pequenos e focados compostos em pipelines:

- `write/extract.py` → `write/entity_resolution.py` → `write/reconcile.py` → `write/upsert.py`
- `read/retrieval_agent.py` → `read/retrieval.py` → `read/reranker.py`

**Por quê:** Cada módulo tem uma única responsabilidade com inputs e outputs claros. Você pode entender, testar e substituir qualquer módulo independentemente. Segue a filosofia Unix: faça uma coisa bem feita.

### Segurança Transacional com Savepoints

Operações de escrita usam savepoints do banco de dados (`session.begin_nested()`) para que uma falha em um fato não aborte o batch inteiro:

```python
async with session.begin_nested():
    # Se isso falhar, apenas este savepoint faz rollback
    session.add(new_fact)
    await session.flush()
```

**Por quê:** Em um pipeline que processa múltiplos fatos por mensagem, transações atômicas tudo-ou-nada são frágeis demais. Savepoints dão atomicidade por fato mantendo a transação externa viva.

---

## Paralelos com Neurociência

A arquitetura do `arandu` se inspira em modelos estabelecidos de neurociência cognitiva. Cada paralelo abaixo mapeia um componente do sistema para seu correspondente biológico.

### Codificação: O Write Pipeline

**Sistema:** Message → Extract → Resolve → Reconcile → Upsert

**Cérebro:** Input sensorial → Percepção → Associação → Consolidação → Armazenamento

Quando você vivencia algo, seu cérebro não grava um vídeo bruto. Ele codifica uma **representação seletiva** — extraindo características salientes, vinculando-as ao conhecimento existente, e armazenando o resultado de forma que possa ser recuperado depois. O write pipeline faz o mesmo:

- **Extraction** é a percepção: um LLM seleciona o que importa da mensagem bruta
- **Entity resolution** é a associação: vincular novas menções a traços de memória existentes
- **Reconciliation** é a reconsolidação: atualizar memórias existentes quando nova informação chega
- **Upsert** é o armazenamento: comprometer o traço processado na memória de longo prazo

### Memória Associativa: Entity Resolution

**Sistema:** Resolução em 3 fases (exact → fuzzy → LLM)

**Cérebro:** Pattern completion em circuitos hipocampais-neocorticais

O cérebro não armazena memórias como registros isolados — armazena como padrões de ativação em redes neurais. Quando você encontra uma pista parcial ("Carol"), seu cérebro completa o padrão para recuperar a representação completa ("Carolina, minha colega do trabalho").

A entity resolution espelha esse processo:

- **Exact match** = recuperação direta (associações fortes e bem estabelecidas)
- **Fuzzy match** = pattern completion (pista parcial ativa o padrão existente mais similar)
- **LLM fallback** = recall deliberado (esforço consciente para desambiguar quando a recuperação automática falha)

O **fuzzy threshold** (0.85) e a **faixa de fallback LLM** (0.50-0.85) modelam o gradiente de confiança do cérebro: matches fortes são automáticos, matches ambíguos requerem deliberação.

### Reconsolidação: Reconciliação de Fatos

**Sistema:** Decisões ADD / UPDATE / NOOP / DELETE

**Cérebro:** Reconsolidação de memória (Nader, Schiller, & LeDoux, 2000)

Quando uma memória é recuperada, ela entra em um **estado lábil** onde pode ser modificada. Isso é a reconsolidação — o mecanismo do cérebro para atualizar memórias com nova informação preservando o traço original.

O estágio de reconciliação modela esse processo:

- **NOOP** = recuperação sem modificação (memória confirmada, `last_confirmed_at` atualizado)
- **UPDATE** = reconsolidação (memória antiga substituída, nova versão criada com link de proveniência via `supersedes_fact_id`)
- **ADD** = nova codificação (sem memória existente para reconsolidar)
- **DELETE** = esquecimento ativo (retração explícita, modelado definindo `invalidated_at`)

O sistema de versionamento de fatos (`valid_from`, `valid_to`, `supersedes_fact_id`) preserva o histórico completo — assim como o cérebro retém traços de memórias originais mesmo após a reconsolidação.

### Spreading Activation: Graph Retrieval

**Sistema:** Traversal BFS 2-hop com fator de decay

**Cérebro:** Spreading activation em redes semânticas (Collins & Loftus, 1975)

No modelo de Collins e Loftus, quando um conceito é ativado (ex: "caminhão de bombeiros"), a ativação se espalha ao longo de links associativos para conceitos relacionados ("vermelho", "caminhão", "emergência"), com a força diminuindo conforme a distância aumenta.

O graph retrieval implementa isso diretamente:

- **Entidades semente** da query ativam os nós iniciais
- **Hop 1** ativa vizinhos diretos (sem pruning — todas as conexões disparam)
- **Hop 2** ativa conexões de segundo grau (com pruning por `min_edge_strength`)
- **Fator de decay** (0.50 por hop) modela a atenuação da ativação ao longo da distância
- **Edge strength** modela a força associativa entre conceitos (reforçada por co-menção repetida)

O `query_bonus` (1.5x) para entidades cujos nomes aparecem na query modela **priming top-down** — quando você menciona explicitamente uma entidade, suas conexões são mais fortemente ativadas.

### Sleep-Time Compute: Processamento em Background

**Sistema:** Clustering, consolidation, importance scoring, summary refresh

**Cérebro:** Consolidação de memória durante o sono (Diekelmann & Born, 2010)

Durante o sono, o cérebro realiza manutenção crítica:

1. **Replay hipocampal** — Experiências recentes são reexecutadas em forma comprimida, transferindo-as do armazenamento de curto prazo (hipocampal) para longo prazo (neocortical)
2. **Homeostase sináptica** — Sinapses fortemente ativadas são mantidas enquanto fracamente ativadas são podadas (Tononi & Cirelli)
3. **Detecção de padrões** — O neocórtex detecta regularidades estatísticas entre episódios
4. **Extração de essência** — Memórias episódicas detalhadas são comprimidas em conhecimento semântico

Os background jobs mapeiam para esses processos:

| Processo cerebral | Job do sistema | Mecanismo |
|-------------------|---------------|-----------|
| Replay hipocampal | Consolidation | Revisa eventos recentes, detecta padrões e contradições |
| Homeostase sináptica | Importance scoring | Pontua entidades por densidade + recência + frequência de retrieval + conectividade |
| Detecção de padrões | Community detection | Encontra grupos de entidades relacionadas via análise de grafos |
| Extração de essência | Summary refresh + Memify | Gera resumos comprimidos a partir de fatos detalhados |

### Curva de Esquecimento: Vitalidade e Recência

**Sistema:** Decay de recência, scoring de vitalidade, pruning baseado em importância

**Cérebro:** Curva de esquecimento de Ebbinghaus (1885)

Hermann Ebbinghaus demonstrou que a retenção de memória decai exponencialmente ao longo do tempo, mas cada recuperação (prática) reseta a curva e desacelera o decay futuro. Este é o **efeito de espaçamento** — o achado mais robusto na pesquisa sobre memória.

O `arandu` modela isso com:

- **Decay de recência** — Decay exponencial com half-life configurável (`recency_half_life_days`). Fatos recentes pontuam mais alto. Isso modela a curva básica de esquecimento.
- **Reforço por retrieval** — Cada decisão NOOP (fato confirmado durante write) atualiza `last_confirmed_at`, efetivamente "praticando" o fato e resetando sua curva de decay.
- **Scoring de vitalidade** — Combina recência, recência de confirmação (`last_confirmed_at`) e importância para determinar quão "vivo" um fato está. Fatos de baixa vitalidade são candidatos a consolidation ou pruning.

### Atenção Seletiva: Reranking

**Sistema:** LLM reranker em candidatos de retrieval

**Cérebro:** Atenção seletiva (Broadbent, 1958; Treisman, 1964)

O cérebro não processa todo input sensorial igualmente — a atenção seletiva filtra e prioriza informações com base nos objetivos atuais. O efeito cocktail party demonstra isso: você consegue focar em uma conversa em um ambiente barulhento filtrando sinais irrelevantes.

O reranker age como o filtro de atenção:

- Sinais brutos de retrieval (semantic, keyword, graph) produzem um conjunto amplo de candidatos — como o input sensorial completo
- O reranker avalia cada candidato contra a intenção da query — como a seleção atencional
- Apenas os fatos mais relevantes passam para o contexto — como o sinal atendido

É por isso que o reranker usa um LLM (não apenas heurísticas de scoring): a atenção é direcionada a objetivos e requer compreender o **significado** tanto da query quanto dos candidatos.

### Working Memory: Orçamento de Contexto

**Sistema:** Orçamento de tokens com tiers hot/warm/cold

**Cérebro:** Working memory (Baddeley & Hitch, 1974; Cowan, 2001)

A working memory tem um limite de capacidade estrito — Cowan estima que 4 mais ou menos 1 itens podem ser mantidos no foco de atenção simultaneamente. O orçamento de contexto modela essa restrição:

- **Orçamento de tokens** = limite de capacidade (você não pode enviar contexto infinito para um LLM)
- **Hot tier** (50%) = foco de atenção (os fatos mais relevantes para a query atual)
- **Warm tier** (30%) = memória de longo prazo ativada (contexto de suporte que está disponível mas não focal)
- **Cold tier** (20%) = ativação periférica (fatos de background que podem se tornar relevantes)

Essa abordagem em tiers garante que o LLM receba um contexto focado e priorizado, em vez de um despejo barulhento de tudo que o sistema sabe.

---

## Tabela Resumo

| Componente do Sistema | Modelo de Neurociência | Referência |
|----------------------|----------------------|------------|
| Write Pipeline | Codificação | -- |
| Entity Resolution | Memória associativa / Pattern completion | -- |
| Reconciliation | Reconsolidação | Nader, Schiller, & LeDoux (2000) |
| Graph Retrieval | Spreading activation | Collins & Loftus (1975) |
| Decay de Recência | Curva de esquecimento | Ebbinghaus (1885) |
| Background Jobs | Consolidação durante o sono | Diekelmann & Born (2010) |
| Importance Scoring | Homeostase sináptica | Tononi & Cirelli (SHY) |
| Summary Refresh | Formação de memória de essência | -- |
| Reranking | Atenção seletiva | Broadbent (1958) |
| Orçamento de Contexto | Capacidade da working memory | Baddeley & Hitch (1974); Cowan (2001) |
| Vitalidade/Reforço | Efeito de espaçamento | Ebbinghaus (1885) |

!!! note "Estes são analogias, não afirmações"
    Os paralelos acima são inspirações arquiteturais, não afirmações científicas. O `arandu` é um sistema de engenharia, não um modelo cognitivo. O cérebro é vastamente mais complexo — esses paralelos destacam as intuições de design, não os mecanismos biológicos.
