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

## Tutoriais (passo a passo)

- [Primeiros passos](https://docs.jangada.dev.br/docs/tutorial-primeiros-passos): do zero ao fallback — instalar, primeira chamada, trocar provider, templates, async, retry+fallback.
- [Extração estruturada](https://docs.jangada.dev.br/docs/tutorial-extracao-estruturada): texto e imagem → Pydantic com `parse()` (inclui vision).
- [RAG do zero](https://docs.jangada.dev.br/docs/tutorial-rag): embeddings + busca híbrida + resposta, em memória ou com pgvector/Mongo.
- [Agente MCP do zero](https://docs.jangada.dev.br/docs/tutorial-agente-mcp): `MCPClient` + `run_agent` — o modelo usando ferramentas sozinho.

## Documentação

- [Começando](https://docs.jangada.dev.br/docs/getting-started): instalação, primeira chamada e como trocar de provider.
- [Providers e chaves](https://docs.jangada.dev.br/docs/providers): os cinco providers (Anthropic, OpenAI, Groq, Gemini, OpenRouter), variáveis de ambiente e precedência de chave.
- [Matriz de capacidades](https://docs.jangada.dev.br/docs/capabilities): o que cada provider suporta (vision, áudio, structured, params).
- [OpenAI](https://docs.jangada.dev.br/docs/llm-openai): modelos, recursos e quirks do provider OpenAI.
- [Groq](https://docs.jangada.dev.br/docs/llm-groq): modelos, recursos e quirks do provider Groq.
- [Gemini](https://docs.jangada.dev.br/docs/llm-gemini): modelos, recursos e quirks do provider Gemini.
- [Anthropic](https://docs.jangada.dev.br/docs/llm-anthropic): modelos, recursos e o que o Claude NÃO faz (áudio).
- [Parâmetros e perfis](https://docs.jangada.dev.br/docs/parameters): params canônicos (temperature, max_tokens, ...) e normalização por modelo (gpt-5, gemini-3.x).
- [Structured output](https://docs.jangada.dev.br/docs/structured-output): `parse()`/`aparse()` com Pydantic, uniforme entre providers.
- [Tools (function calling)](https://docs.jangada.dev.br/docs/tools): `tools=[...]` (OpenAI/Groq), baixo nível, e ferramentas pré-prontas (`jangada_ai.prebuilt`, ex.: tavily_search).
- [MCP (Model Context Protocol)](https://docs.jangada.dev.br/docs/mcp): `mcp_servers=[...]` — remoto por URL (Anthropic/OpenAI/Groq, server-side) e client-side por sessão (Gemini, async).
- [Vision](https://docs.jangada.dev.br/docs/vision): imagens via `ImagePart`/`Image`, tradução por SDK.
- [Detecção de objetos](https://docs.jangada.dev.br/docs/detect): `detect_objects()` com bounding boxes em pixels; funciona em qualquer provider com visão.
- [Transcrição de áudio](https://docs.jangada.dev.br/docs/audio): `transcribe()` (OpenAI, Groq, Gemini); Anthropic não suporta áudio.
- [Documentos (docx/pdf/csv/xlsx)](https://docs.jangada.dev.br/docs/documents): `files=` com extração de texto por padrão (vision só opt-in); xlsx multi-aba.
- [RAG (embeddings + busca vetorial/híbrida)](https://docs.jangada.dev.br/docs/rag): `embed()` (OpenAI/Gemini), módulo `jangada_ai.rag` com chunking, vector store (pgvector/Mongo por string de conexão) e busca híbrida (RRF).
- [Streaming](https://docs.jangada.dev.br/docs/streaming): `stream()`/`astream()` com retry+fallback antes do primeiro token.
- [Retry e fallback](https://docs.jangada.dev.br/docs/retry-fallback): backoff por candidato e failover por tipo de erro.
- [Custo e tokens](https://docs.jangada.dev.br/docs/cost): `usage`/`cost` na resposta e tabela de preços aproximada.
- [Observabilidade](https://docs.jangada.dev.br/docs/observability): `Observability`/`Trace` enviam lotes de chamadas para uma plataforma de observabilidade.
- [Erros normalizados](https://docs.jangada.dev.br/docs/errors): hierarquia única via `classify()` e conjuntos TRANSIENT/DEFAULT_FAILOVER.
- [Fluxos e Graph](https://docs.jangada.dev.br/docs/flows): encadeamento sequencial (`Flow`) e roteamento condicional/paralelo (`Graph`).
- [Agentes e times](https://docs.jangada.dev.br/docs/agents): `Agent` (papel + tools/MCP + memória) e `Squad` (sequencial/hierárquico com delegação); `plan()` e `RAGMemory`.
- [Guardrails de escopo](https://docs.jangada.dev.br/docs/guardrails): `ScopeGuard` mantém a LLM num domínio e barra falas (blocklist + judge LLM); recusa via `Completion`, input/output, sync/async.
- [Debug](https://docs.jangada.dev.br/docs/debug): trace passo a passo por agente.
- [Estendendo (novo provider)](https://docs.jangada.dev.br/docs/extending): contrato `Provider`, atalho `_OpenAICompatible` e invariantes.

## Referência

- [Documentação completa (llms-full.txt)](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/llms-full.txt): todos os guias de docs/ concatenados, para consumo em um único fetch.
- [README](https://docs.jangada.dev.br/): visão geral completa com exemplos.
- [CLAUDE.md](https://docs.jangada.dev.br/): 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-docs): código-fonte, issues e workflow de publicação.

## Optional

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