# 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/master/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/master/docs/tutorial-extracao-estruturada.md): texto e imagem → Pydantic com `parse()` (inclui vision).
- [RAG do zero](https://raw.githubusercontent.com/nerigleston/jangada/master/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/master/docs/tutorial-agente-mcp.md): `MCPClient` + `run_agent` — o modelo usando ferramentas sozinho.

## 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; thinking transparente (você passa só `thinking_budget`/`thinking_level` e a lib adapta à versão, empacotando no `thinking_config` nativo).
- [Anthropic](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/llm-anthropic.md): modelos, recursos e o que o Claude NÃO faz (áudio).
- [Azure OpenAI](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/llm-azure.md): provider `azure` — mesma API da OpenAI servida pela Azure; `model` = nome do deployment; env `AZURE_OPENAI_ENDPOINT`/`AZURE_OPENAI_API_KEY`.
- [AWS Bedrock](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/llm-bedrock.md): provider `bedrock` — Converse API via boto3 (Claude/Llama/Mistral/Nova), tools e structured (tool-forcing); credenciais AWS; async via to_thread.
- [Vertex AI](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/llm-vertex.md): provider `vertex` — Gemini no Google Cloud (ADC + project/location); herda tudo do provider `gemini`.
- [Mistral](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/llm-mistral.md): provider `mistral` — SDK oficial `mistralai`; texto, vision, streaming, structured (helper nativo `chat.parse`), tools, embeddings (`mistral-embed`), OCR/Document AI (`ocr()` com `mistral-ocr-latest`) e transcrição Voxtral; env `MISTRAL_API_KEY`.
- [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); thinking do Gemini via `extra=`/`params=`.
- [Structured output](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/structured-output.md): `parse()`/`aparse()` com Pydantic, uniforme entre providers; trunca por max_tokens levanta `TruncatedError`; JSON fora do schema levanta `OutputValidationError` e entra no failover (tenta o próximo modelo); `comp.parsed` é coagido do texto se o SDK devolver None.
- [Tools (function calling)](https://raw.githubusercontent.com/nerigleston/jangada/master/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/master/docs/mcp.md): CLIENTE — `mcp_servers=[...]` (remoto por URL: Anthropic/OpenAI/Groq, server-side; e client-side por sessão no Gemini) + `MCPClient` (tools/resources/prompts/roots/sampling). SERVIDOR — `serve_mcp(tools=[...]|agent=...)`/`build_mcp_app()` expõe suas funções/Agent como servidor MCP (stdio ou streamable-http), sobre o `Server` low-level (não FastMCP). Exemplo pronto: jangada-docs-mcp (https://github.com/nerigleston/jangada-docs-mcp) — serve a doc do jangada ao editor via `uvx`.
- [Vision](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/vision.md): imagens via `ImagePart`/`Image`, tradução por SDK; `images=[("rótulo", img)]` para rotular cada imagem; controle total via `Message`/`history`.
- [Detecção de objetos](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/detect.md): `detect_objects()` com bounding boxes em pixels; `detect_objects_full()` devolve também custo/uso (`DetectionResult`); funciona em qualquer provider com visão.
- [Step-back prompting](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/stepback.md): `step_back()` gera uma pergunta conceitualmente mais ampla a partir de uma específica, para recuperar contexto amplo em RAG; funciona em qualquer provider.
- [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.
- [RAG (embeddings + busca vetorial/híbrida)](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/rag.md): `embed()` (OpenAI/Gemini), módulo `jangada_ai.rag` com chunking, vector store (pgvector/Mongo por string de conexão), busca híbrida (RRF), **reranking** (`Reranker.cohere/voyage/fn`, `RAG(reranker=...)`), **semantic chunking** (`semantic_chunker`), **estratégias** (`search(strategy="multi_query"|"parent_document")`, `compress=True`) e **indexação incremental** (`sync_document`/`sync_texts`, dedup por hash) — tudo opt-in.
- [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; imagem já conta como input tokens, áudio por minuto (`register_audio_price`), `detect_objects_full` expõe custo.
- [Cache de respostas](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/cache.md): `ExactCache` (LRU/TTL) e `SemanticCache` (similaridade via embeddings + `vector_store`) plugados em `LLM(..., cache=...)`; economiza tokens/latência.
- [Observabilidade](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/observability.md): observabilidade automática (zero-config via .env) — cada chamada envia um trace; `observability_session` agrupa por lote; resposta truncada vira status `INCOMPLETE` + `finishReason`; `feedback(trace_id, value)` anexa 👍/👎 de produção (best-effort); `flush_observability()` + `atexit` garantem que o último trace não se perca no encerramento.
- [Avaliação (evals)](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/eval.md): `Dataset`/`Evaluator`/`evaluate()` — heurística (`Evaluator.fn`) + juiz LLM (`Evaluator.judge`); compara modelos por score × custo × latência; `push=True` envia ao painel (Experiments/Datasets). Offline por padrão.
- [Prompt registry](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/prompts.md): `PromptVersion.pull/push` — versiona prompts (histórico, tag `production`, rollback sem deploy) e referencia pelo nome; **opt-in**, convive com prompt no código.
- [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`).
- [Agentes e times](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/agents.md): `Agent` (papel + tools sync/async + MCP + memória + `history=` multi-turno + `astream` + `card()` A2A + servidor A2A `jangada[a2a]`: `A2AHandler`/`build_a2a_app`, com `resolver` multi-tenant e isolamento por `tenant_key`) e `Squad` (sequencial/hierárquico com delegação); `plan()` e `RAGMemory`.
- [Guardrails de escopo](https://raw.githubusercontent.com/nerigleston/jangada/master/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/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.
- [Casos de uso](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/casos-de-uso.md): do problema ao código — extração estruturada de nota fiscal (vision), fallback por erro entre providers e RAG sobre seus documentos.
- [Por que jangada (comparativo)](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/por-que-jangada.md): comparativo honesto com LiteLLM, LangChain e instructor — quando usar cada um e onde a jangada brilha.
- [Versionamento e estabilidade](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/semver.md): SemVer (0.x vs 1.0), o que é breaking e a política de deprecação (avisar 1 minor antes via DeprecationWarning).
- [Estabilidade da API](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/estabilidade.md): API pública (`__all__`) classificada em Estável × Experimental.
- [Melhores práticas](https://raw.githubusercontent.com/nerigleston/jangada/master/docs/best-practices.md): recomendações de produção — provider/model, structured output, guardrails, RAG (reranker + semantic chunking + multi-query/parent-document/compress + indexação incremental), retry/fallback, custo, cache, orquestração, agentes, transcrição (vídeo/mp4), async/FastAPI e pontos de atenção (contratos da lib).

## Migração e exemplos

- [Migração do LangChain](https://docs.jangada.dev.br/docs/migration-langchain): guia capacidade-por-capacidade de como cada coisa é feita no jangada vindo do LangChain (padrão próprio, não comparativo) + diferenciais e dependências.
- [Exemplos de código](https://docs.jangada.dev.br/docs/examples): apps FastAPI completos por cenário — assistente com tools, escritor com cache, fiscal-vision (visão+structured), pesquisa com agentes/Squad/MCP, reunião (áudio→ata via Flow) e suporte com RAG.

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