# Spec: Completar AnthropicProvider (testes + docs)

> Generated via /vibeflow:gen-spec on 2026-03-25
> Budget: ≤ 6 files

## Objective

Completar a implementação do `AnthropicProvider` com testes unitários e documentação em todos os canais (docs EN/PT-BR, llms-full.txt, CHANGELOG, API Reference).

## Context

O `AnthropicProvider` foi implementado em `src/arandu/providers/anthropic.py` e funciona (CI passa, 365 tests). O cookbook foi atualizado. Mas faltam:

- Zero testes unitários pro provider (OpenAI também não tem, mas é o built-in principal — Anthropic como segundo provider precisa de confiança explícita)
- `llms-full.txt` EN/PT-BR não mencionam o AnthropicProvider
- `getting-started.md` não menciona como alternativa
- `CHANGELOG.md` não tem v0.6.39
- API Reference não tem entrada pro AnthropicProvider
- Seção "Custom Providers" nos docs precisa refletir que agora são 2 built-in

## Definition of Done

1. **[ ] Testes unitários existem** — `tests/test_anthropic_provider.py` com ≥4 testes: (a) system message separado, (b) JSON response_format → instrução appended, (c) token usage extraído, (d) markdown fences stripped. Usa mock do SDK Anthropic, sem chamada real.

2. **[ ] Docs EN atualizados** — `getting-started.md` menciona AnthropicProvider como alternativa ao OpenAI. `docs/en/reference/index.md` tem entrada pro AnthropicProvider. Seção "Custom Providers" no cookbook reflete 2 built-in.

3. **[ ] Docs PT-BR espelhados** — Mesmas mudanças do EN aplicadas no PT-BR.

4. **[ ] `llms-full.txt` EN/PT-BR sincronizado** — AnthropicProvider aparece com exemplo de uso, instalação (`pip install arandu[anthropic]`), e nota sobre embeddings separados.

5. **[ ] CHANGELOG atualizado** — v0.6.39 entrada com feat do AnthropicProvider.

6. **[ ] Pattern compliance** — Testes seguem `.vibeflow/patterns/testing.md` (mock-based, sem DB, FakeLLMProvider pattern adaptado). Provider segue `.vibeflow/patterns/dependency-injection.md` (lazy import, Protocol compliance, LLMResult return).

## Scope

### 1. `tests/test_anthropic_provider.py` — Novo arquivo

4 testes mínimos:

```python
class TestAnthropicProvider:
    def test_system_message_separated(self):
        """System messages são extraídas e passadas via param 'system'."""

    def test_json_response_format_appends_instruction(self):
        """response_format=json_object appenda instrução no system prompt."""

    def test_token_usage_extracted(self):
        """usage do response Anthropic é mapeado pra TokenUsage."""

    def test_markdown_fences_stripped(self):
        """Fences ```json são removidas do content."""
```

Mock: `unittest.mock.AsyncMock` pro `self._client.messages.create`. Retornar mock response com `content=[MockBlock(text="...")]` e `usage=MockUsage(input_tokens=100, output_tokens=50)`.

### 2. Docs — Atualizações pontuais

**getting-started.md EN/PT-BR:**
Adicionar após o exemplo OpenAI um bloco `=== "Anthropic (Claude)"` com:
```python
from arandu.providers.anthropic import AnthropicProvider
from arandu.providers.openai import OpenAIProvider

llm = AnthropicProvider(api_key="sk-ant-...")
embeddings = OpenAIProvider(api_key="sk-...")  # Anthropic não tem embeddings
```

**reference/index.md:**
Adicionar seção `### AnthropicProvider` com assinatura, params, e nota sobre embeddings.

**CHANGELOG.md:**
```
## v0.6.39 — Built-in AnthropicProvider
- **feat:** `AnthropicProvider` em `arandu.providers.anthropic`
- **feat:** `pip install arandu[anthropic]` como dependência opcional
```

**llms-full.txt EN/PT-BR:**
Adicionar bloco sobre AnthropicProvider na seção de providers/getting started.

### 3. Cookbook — Já atualizado ✅

O cookbook já foi atualizado de "Custom Provider (Anthropic)" pra "Using Anthropic (Claude)" com import do built-in.

## Anti-scope

- **Não mudar o código do provider** — `src/arandu/providers/anthropic.py` já tá feito e funciona. Só testes e docs.
- **Não adicionar EmbeddingProvider ao Anthropic** — Anthropic não tem API de embeddings. Documentar que precisa de provider separado.
- **Não adicionar outros providers** (Ollama, LiteLLM, etc.) — fora de escopo.
- **Não testar com API real** — testes são mock-based.

## Technical Decisions

### TD-1: Mock do SDK Anthropic nos testes
**Trade-off:** Poderia usar FakeLLMProvider (como os outros testes), mas isso não testa a conversão system→param, JSON instruction, etc.
**Decisão:** Mock `AsyncMock` no `self._client.messages.create` pra testar a lógica de conversão específica do Anthropic.

### TD-2: Tabs no getting-started (OpenAI vs Anthropic)
**Trade-off:** Poderia ser seção separada ou tab.
**Decisão:** Tab (`=== "OpenAI"` / `=== "Anthropic"`) — é o padrão MkDocs Material e o dev vê as duas opções lado a lado.

## Applicable Patterns

- **Testing** (`.vibeflow/patterns/testing.md`) — Mock-based, sem DB, `run_async()`, class grouping.
- **Dependency Injection** (`.vibeflow/patterns/dependency-injection.md`) — Protocol compliance, lazy import, `LLMResult` return.

## Risks

1. **Mock do Anthropic SDK pode divergir do real** — Mitigação: mockar no nível do `messages.create`, não em detalhes internos do SDK.
2. **llms-full.txt drift** — Mitigação: verificar no final que o conteúdo adicionado tá consistente com os docs renderizados.
