jangada-ai 0.6.0__tar.gz

jangada_ai-0.6.0/.claude/settings.local.json

@@ -0,0 +1,29 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git -C /Volumes/SSD_EXT/lib-ai/jangada status)",
+      "Bash(gh auth *)",
+      "Bash(dot_clean .)",
+      "Bash(git init *)",
+      "Bash(git add *)",
+      "Bash(git commit -q -m 'Initial commit: jangada — camada adaptável sobre SDKs de LLM *)",
+      "Bash(gh repo *)",
+      "Bash(python3 *)",
+      "Bash(.venv/bin/python -m pip install -q --upgrade pip)",
+      "Bash(.venv/bin/python -m pip install -q pytest pytest-asyncio openpyxl python-docx pypdf pydantic)",
+      "Bash(.venv/bin/python -m pytest --version)",
+      "Bash(.venv/bin/python -m pytest -q)",
+      "Bash(.venv/bin/python -m pip install -q reportlab)",
+      "Bash(git check-ignore *)",
+      "Bash(git commit -q -m 'Estrutura do pacote + suporte a documentos \\(docx/pdf/csv/xlsx\\) *)",
+      "Bash(git push *)",
+      "Bash(git commit -q -m 'docs: README com seção de Documentos \\(docx/pdf/csv/xlsx\\) e extras [files]/[dev] *)",
+      "Bash(curl -s -o /dev/null -w \"%{http_code}\" https://pypi.org/pypi/jangada/json)",
+      "Bash(curl -s https://pypi.org/pypi/jangada/json)",
+      "Bash(rm -rf dist build *.egg-info)",
+      "Bash(.venv/bin/python -m pip install -q build twine)",
+      "Bash(.venv/bin/python -m build)",
+      "Bash(.venv/bin/python -m pip install -q --upgrade pip build twine)"
+    ]
+  }
+}

jangada_ai-0.6.0/.gitignore

@@ -0,0 +1,89 @@
+# Byte-compiled / optimizados
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribuição / empacotamento
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Ambientes virtuais
+.venv/
+venv/
+env/
+ENV/
+.env
+.env.*
+
+# Testes / cobertura
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+.cache
+coverage.xml
+*.cover
+
+# Type checkers / linters
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+.pyre/
+.pytype/
+
+# IDEs / editores
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Sistema operacional
+.DS_Store
+.AppleDouble
+.LSOverride
+._*
+.Spotlight-V100
+.Trashes
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Gerenciadores de pacote / lock
+uv.lock
+.pdm-python
+__pypackages__/
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Logs / temporários
+*.log
+*.tmp
+*.bak
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Chaves / segredos locais
+*.key
+secrets.json

jangada_ai-0.6.0/CLAUDE.md

@@ -0,0 +1,156 @@
+# CLAUDE.md
+
+Guia para o Claude Code trabalhar neste repositório. Leia antes de editar.
+
+## O que é
+
+`jangada` é uma camada fina e adaptável sobre os SDKs oficiais de LLM
+(Anthropic, OpenAI, Groq, Gemini). Objetivo: **trocar provider/model/api_key
+sem mudar o resto do código**, com templates `{{ }}`, fluxos encadeados,
+structured output (Pydantic), vision, async e fallback por erro.
+
+Princípio central: a complexidade de cada SDK fica isolada em um *adapter*;
+o resto da lib só conhece os tipos normalizados (`Message`, `Completion`).
+
+## Arquitetura
+
+```
+jangada/
+  message.py            # Message, Completion, TextPart, ImagePart, Image (tipos normalizados)
+  files.py              # Document/to_part: extrai TEXTO de docx/pdf/csv/xlsx (vision só opt-in)
+  template.py           # motor {{ }} (regex, acesso por ponto, strict)
+  errors.py             # hierarquia de erro normalizada + classify()
+  client.py             # LLM: API pública (complete/parse/stream + async + retry + fallback + debug)
+  pricing.py            # tabela de preços (aprox.) + compute_cost (custo na response)
+  profiles.py           # normalização de params por modelo (quirks gpt-5, gemini-3.x...)
+  debug.py              # Debugger: trace passo a passo da cadeia, por agente
+  flow.py               # Flow/Step/FlowResult (encadeamento sequencial)
+  graph.py              # Graph: roteamento condicional + paralelo (async-core)
+  env.py                # detecção de .env (não-destrutiva, na importação)
+  providers/
+    base.py             # ABC Provider: complete/acomplete/parse/aparse/stream/astream
+    anthropic.py        # adapter Claude (structured = tool-forcing)
+    openai_compat.py    # adapters OpenAI e Groq (compartilham chat.completions)
+    gemini.py           # adapter Gemini (async via client.aio)
+    registry.py         # get_provider/register com loaders preguiçosos
+```
+
+Fluxo de uma chamada: `LLM.complete()` → renderiza template → monta
+`list[Message]` → `_run()` percorre `[self, *fallbacks]` → chama
+`provider.complete(messages)` → o adapter traduz para o SDK nativo, executa,
+e devolve `Completion`. Erros do SDK passam por `errors.classify()` e viram
+`LLMError` normalizado, que a política de fallback usa para decidir failover.
+
+## Invariantes — NÃO QUEBRE
+
+- **Imports preguiçosos.** `import jangada` deve funcionar sem nenhum SDK
+  instalado. Os SDKs só podem ser importados dentro de `_build_client` /
+  `_build_async_client` ou dentro dos métodos do adapter (nunca no topo do módulo).
+- **Tipos normalizados na fronteira.** Fora dos adapters, só circula
+  `Message`/`Completion`. Não vaze objetos nativos de SDK (eles ficam em
+  `Completion.raw`).
+- **Tradução de erro sempre.** Toda chamada de SDK fica em `try/except` e
+  re-levanta via `classify(e, self.name)`. Nunca deixe erro nativo escapar.
+- **Paridade sync/async.** Todo método tem versão `a*` equivalente. Ao mudar
+  um, mude o outro.
+- **Params canônicos.** O `LLM` aceita params de geração comuns como nomes
+  canônicos (`temperature`, `max_tokens`, `top_p`, `top_k`, `stop`, `seed`).
+  Cada adapter implementa `_translate()` para o nome nativo e descarta os não
+  suportados (ex.: OpenAI não tem `top_k`; Anthropic não tem `seed`; Gemini usa
+  `max_output_tokens`/`stop_sequences`). Params específicos vão via `extra=`.
+  Ordem no adapter: `_translate()` (canônico→nativo) → `apply_profile()` (quirks
+  de modelo). NÃO inverta essa ordem.
+- **Retry antes de fallback.** Por candidato, o cliente tenta `max_retries+1`
+  vezes com backoff (`backoff_on`, padrão `errors.TRANSIENT`) antes de cair pro
+  próximo candidato (`retry_on`). NotFoundError não repete, mas faz fallback.
+- **Custo na response.** O cliente chama `pricing.compute_cost()` após cada
+  sucesso e seta `Completion.cost`. `FlowResult`/`GraphResult` agregam
+  `usage`/`cost`. Preços são aproximados — não trate como fonte de billing.
+- **Default de failover** (`errors.DEFAULT_FAILOVER`): rate limit, timeout,
+  connection, 5xx, 404. NÃO inclua auth nem bad_request por padrão.
+- **Normalização por modelo.** Os adapters chamam `profiles.apply_profile()`
+  ao montar o payload, para tratar quirks específicas de modelo (ex.: gpt-5
+  não aceita `temperature` e usa `max_completion_tokens`; gemini-3.x descarta
+  sampling e usa `thinking_level`). Ao suportar um modelo novo com contrato
+  diferente, adicione uma regra em `profiles.py` em vez de espalhar `if`s nos
+  adapters. Function calling multi-turn no Gemini 3.x exige preservar thought
+  signatures (não é problema de param — é integridade do histórico).
+
+## Como adicionar um provider
+
+1. Crie `providers/<nome>.py` com classe que herda de `Provider` e implementa
+   os 6 métodos + `_build_client`/`_build_async_client`.
+2. Defina `name` e `env_key`.
+3. Importe o SDK só dentro dos métodos.
+4. Registre em `registry.py` com um loader preguiçoso.
+5. Adicione o extra em `pyproject.toml`.
+
+Se o provider falar o dialeto `chat.completions` da OpenAI, herde de
+`_OpenAICompatible` e só ajuste `sdk_module`/`sync_class`/`async_class`/
+`supports_parse_helper` (veja `GroqProvider`).
+
+## Mapa de structured output (por provider)
+
+- OpenAI: `chat.completions.parse(response_format=Modelo)` → `.message.parsed`.
+- Groq: `response_format={"type":"json_schema",...}` + `model_validate_json`.
+- Gemini: `config.response_schema=Modelo` → `resp.parsed`.
+- Anthropic: tool-forcing (`tool_choice` fixo) → valida `tool_use.input`.
+
+## Vision
+
+Imagens entram como `ImagePart` (bytes + mime). Cada adapter traduz:
+OpenAI/Groq → `image_url` data URI; Anthropic → bloco `image/source base64`;
+Gemini → `types.Part.from_bytes`. Apenas bytes (use `Image.from_path/bytes/base64`).
+
+## Documentos (docx, pdf, csv, xlsx)
+
+`files=[...]` em `complete/parse/stream` (e async). `files.py` resolve cada item
+em `to_part()` **na fronteira do client** — vira `TextPart` ou `ImagePart`, então
+os adapters NÃO veem nenhum formato de documento (invariante de tipos preservada).
+
+Regra padrão (`mode="auto"`): **extrai texto, não usa vision**. csv/xlsx/docx e
+PDF com camada de texto viram markdown/texto (mais barato, funciona em modelo sem
+vision). xlsx percorre TODAS as abas. PDF sem texto (escaneado) levanta
+`DocumentError` sugerindo vision — nunca devolve bloco vazio. `mode="vision"`
+força o caminho de imagem; imagens em `auto` já vão para vision.
+
+Deps (`pypdf`, `python-docx`, `openpyxl`) são extra opcional `jangada[files]`,
+com import preguiçoso dentro dos extractors — `import jangada` funciona sem elas.
+
+## Testes
+
+Os testes ficam em `tests/` (pacote: tem `__init__.py`). `tests/conftest.py`
+expõe um `FakeProvider` (auto-registrado por fixture) e fixtures que geram
+xlsx/docx/pdf em memória. Config do pytest (`asyncio_mode=auto`, `testpaths`)
+está em `pyproject.toml`. Ambiente: `pip install -e ".[dev]"` numa venv (`.venv/`,
+ignorada no git).
+
+Os SDKs reais exigem chave e rede. Os testes cobrem a lógica com adapters
+*mockados* (clientes nativos falsos) e o `FakeProvider` registrado em runtime.
+Padrão ao testar:
+
+```python
+from jangada.providers.registry import register
+from jangada.providers.base import Provider
+# crie um Provider fake, registre com register("fake", lambda: FakeClass), e teste LLM/Flow/fallback.
+```
+
+Para testar um adapter real sem rede, injete um cliente nativo falso em
+`provider._client` (ou `._aclient`) e verifique os kwargs capturados.
+
+Rode: `.venv/bin/python -m pytest` (ou os scripts em `examples/` com chaves reais).
+
+## Convenções
+
+- Python 3.10+, type hints em tudo, `from __future__ import annotations`.
+- Pydantic v2 (`model_json_schema()`, `model_validate`/`model_validate_json`).
+- Sem dependências pesadas no core (só `pydantic`); SDKs são extras opcionais.
+- Mensagens de erro e docstrings em PT-BR (padrão deste projeto).
+
+## Comandos úteis
+
+```bash
+pip install -e ".[all]"      # instala com todos os SDKs
+pip install -e ".[anthropic,groq]"   # subconjunto
+python examples/structured_example.py
+```

jangada_ai-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.