# jangada

> `jangada` é uma camada fina e adaptável sobre os SDKs oficiais de LLM
> (Anthropic, OpenAI, Groq, Gemini). Permite trocar **provider / model /
> api_key** sem mudar o resto do código, com templates `{{ }}`, structured
> output (Pydantic), vision, ingestão de documentos (docx/pdf/csv/xlsx),
> streaming, async, retry com backoff e fallback automático por tipo de erro.

Instalação: `pip install jangada-ai` (importa-se como `import jangada_ai`).
Princípio central: a complexidade de cada SDK fica isolada em um *adapter*; o
resto da lib só conhece os tipos normalizados `Message` e `Completion`. Os
imports dos SDKs são preguiçosos — `import jangada_ai` funciona sem nenhum SDK
instalado.

## Documentação

- [Começando](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/getting-started.md): instalação, primeira chamada e como trocar de provider.
- [Providers e chaves](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/providers.md): os quatro providers, variáveis de ambiente e precedência de chave.
- [Matriz de capacidades](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/capabilities.md): o que cada provider suporta (vision, áudio, structured, params).
- [OpenAI](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/llm-openai.md): modelos, recursos e quirks do provider OpenAI.
- [Groq](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/llm-groq.md): modelos, recursos e quirks do provider Groq.
- [Gemini](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/llm-gemini.md): modelos, recursos e quirks do provider Gemini.
- [Anthropic](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/llm-anthropic.md): modelos, recursos e o que o Claude NÃO faz (áudio).
- [Parâmetros e perfis](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/parameters.md): params canônicos (temperature, max_tokens, ...) e normalização por modelo (gpt-5, gemini-3.x).
- [Structured output](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/structured-output.md): `parse()`/`aparse()` com Pydantic, uniforme entre providers.
- [Vision](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/vision.md): imagens via `ImagePart`/`Image`, tradução por SDK.
- [Detecção de objetos](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/detect.md): `detect_objects()` com bounding boxes em pixels; funciona em qualquer provider com visão.
- [Transcrição de áudio](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/audio.md): `transcribe()` (OpenAI, Groq, Gemini); Anthropic não suporta áudio.
- [Documentos (docx/pdf/csv/xlsx)](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/documents.md): `files=` com extração de texto por padrão (vision só opt-in); xlsx multi-aba.
- [Streaming](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/streaming.md): `stream()`/`astream()` com retry+fallback antes do primeiro token.
- [Retry e fallback](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/retry-fallback.md): backoff por candidato e failover por tipo de erro.
- [Custo e tokens](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/cost.md): `usage`/`cost` na resposta e tabela de preços aproximada.
- [Erros normalizados](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/errors.md): hierarquia única via `classify()` e conjuntos TRANSIENT/DEFAULT_FAILOVER.
- [Fluxos e Graph](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/flows.md): encadeamento sequencial (`Flow`) e roteamento condicional/paralelo (`Graph`).
- [Debug](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/debug.md): trace passo a passo por agente.
- [Estendendo (novo provider)](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/extending.md): contrato `Provider`, atalho `_OpenAICompatible` e invariantes.

## Referência

- [Documentação completa (llms-full.txt)](https://raw.githubusercontent.com/nerigleston/jangada/master/llms-full.txt): todos os guias de docs/ concatenados, para consumo em um único fetch.
- [README](https://raw.githubusercontent.com/nerigleston/jangada/master/README.md): visão geral completa com exemplos.
- [CLAUDE.md](https://raw.githubusercontent.com/nerigleston/jangada/master/CLAUDE.md): arquitetura, invariantes e convenções do projeto.
- [Pacote no PyPI](https://pypi.org/project/jangada-ai/): instalação e versões publicadas.
- [Repositório no GitHub](https://github.com/nerigleston/jangada): código-fonte, issues e workflow de publicação.

## Optional

- [Exemplos executáveis](https://github.com/nerigleston/jangada/tree/master/examples): scripts por recurso (vision, structured, fallback, graph, async, debug).
- [Testes](https://github.com/nerigleston/jangada/tree/master/tests): suíte com `FakeProvider` e fixtures de documento.
- [Código do adapter OpenAI/Groq](https://raw.githubusercontent.com/nerigleston/jangada/master/jangada_ai/providers/openai_compat.py): referência de como um adapter traduz mensagens e params.
