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

## Documentação

- [Começando](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/getting-started.md): instalação, primeira chamada e como trocar de provider.
- [Providers e chaves](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/providers.md): os quatro providers, variáveis de ambiente e precedência de chave.
- [Matriz de capacidades](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/capabilities.md): o que cada provider suporta (vision, áudio, structured, params).
- [OpenAI](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/llm-openai.md): modelos, recursos e quirks do provider OpenAI.
- [Groq](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/llm-groq.md): modelos, recursos e quirks do provider Groq.
- [Gemini](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/llm-gemini.md): modelos, recursos e quirks do provider Gemini.
- [Anthropic](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/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-docs/main/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-docs/main/docs/structured-output.md): `parse()`/`aparse()` com Pydantic, uniforme entre providers.
- [Tools (function calling)](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/tools.md): `tools=[...]` (OpenAI/Groq), baixo nível, e ferramentas pré-prontas (`jangada_ai.prebuilt`, ex.: tavily_search).
- [MCP (Model Context Protocol)](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/mcp.md): `mcp_servers=[...]` — remoto por URL (Anthropic/OpenAI/Groq, server-side) e client-side por sessão (Gemini, async).
- [Vision](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/vision.md): imagens via `ImagePart`/`Image`, tradução por SDK.
- [Detecção de objetos](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/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-docs/main/docs/audio.md): `transcribe()` (OpenAI, Groq, Gemini); Anthropic não suporta áudio.
- [Documentos (docx/pdf/csv/xlsx)](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/documents.md): `files=` com extração de texto por padrão (vision só opt-in); xlsx multi-aba.
- [RAG (embeddings + busca vetorial/híbrida)](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/rag.md): `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://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/streaming.md): `stream()`/`astream()` com retry+fallback antes do primeiro token.
- [Retry e fallback](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/retry-fallback.md): backoff por candidato e failover por tipo de erro.
- [Custo e tokens](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/cost.md): `usage`/`cost` na resposta e tabela de preços aproximada.
- [Observabilidade](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/observability.md): `Observability`/`Trace` enviam lotes de chamadas para uma plataforma de observabilidade.
- [Erros normalizados](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/errors.md): hierarquia única via `classify()` e conjuntos TRANSIENT/DEFAULT_FAILOVER.
- [Fluxos e Graph](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/flows.md): encadeamento sequencial (`Flow`) e roteamento condicional/paralelo (`Graph`).
- [Agentes e times](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/agents.md): `Agent` (papel + tools/MCP + memória) e `Squad` (sequencial/hierárquico com delegação); `plan()` e `RAGMemory`.
- [Guardrails de escopo](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/guardrails.md): `ScopeGuard` mantém a LLM num domínio e barra falas (blocklist + judge LLM); recusa via `Completion`, input/output, sync/async.
- [Debug](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/debug.md): trace passo a passo por agente.
- [Estendendo (novo provider)](https://raw.githubusercontent.com/nerigleston/jangada-docs/main/docs/extending.md): 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://raw.githubusercontent.com/nerigleston/jangada-docs/main/README.md): visão geral completa com exemplos.
- [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.