# tempestroid

> Framework for building native Android apps in typed Python: one declarative, fully typed Pydantic widget tree is diffed by a renderer-agnostic reconciler into patches, applied by two leaf renderers — Qt (desktop simulator) and Jetpack Compose (device).

This file follows the llmstxt.org convention. For the full project inlined as one Markdown stream, fetch [https://mauriciobenjamin700.github.io/tempestroid/llms-full.txt](https://mauriciobenjamin700.github.io/tempestroid/llms-full.txt). The documentation is bilingual — Portuguese (default) here and English under [https://mauriciobenjamin700.github.io/tempestroid/en/](https://mauriciobenjamin700.github.io/tempestroid/en/).

## Start here

- [Tempestroid](https://mauriciobenjamin700.github.io/tempestroid/): Construa apps Android nativos em Python tipado.
- [Instalação](https://mauriciobenjamin700.github.io/tempestroid/instalacao/): Há dois públicos para o tempestroid, e cada um instala de um jeito:
- [Começo rápido](https://mauriciobenjamin700.github.io/tempestroid/inicio-rapido/): Quer uma subpasta? Passe um nome: uv run tempest new OutroApp cria
- [Arquitetura](https://mauriciobenjamin700.github.io/tempestroid/arquitetura/): O tempestroid separa o que renderizar (uma IR tipada e serializável) de

## User guide

- [Widgets](https://mauriciobenjamin700.github.io/tempestroid/guia/widgets/): Widgets são as primitivas declarativas da IR — uma árvore de modelos Pydantic que
- [Estilos](https://mauriciobenjamin700.github.io/tempestroid/guia/estilos/): O estilo é descrito por objetos de valor Pydantic frozen, diferenciados por
- [Tema e tokens](https://mauriciobenjamin700.github.io/tempestroid/guia/design-system/tokens/): Até aqui você estilizou cada widget na mão: Color.from_hex("#2563eb") aqui, um
- [Variantes ao estilo Chakra](https://mauriciobenjamin700.github.io/tempestroid/guia/design-system/variantes/): Com o [tema e os tokens](tokens.md) no lugar, você não precisa montar um Style
- [Kit de ação e entrada](https://mauriciobenjamin700.github.io/tempestroid/guia/design-system/kit/): A [API de variantes](variantes.md) que você viu no Button é a mesma em
- [Superfície e layout](https://mauriciobenjamin700.github.io/tempestroid/guia/design-system/superficie/): O [kit de ação e entrada](kit.md) deu ergonomia aos controles. Agora falta a
- [Data display e feedback](https://mauriciobenjamin700.github.io/tempestroid/guia/design-system/feedback/): Você já tem ação ([variantes](variantes.md), [kit](kit.md)) e moldura
- [Navegação](https://mauriciobenjamin700.github.io/tempestroid/guia/design-system/navegacao/): Você já tem ação ([variantes](variantes.md), [kit](kit.md)), moldura
- [Componentes de pesquisa](https://mauriciobenjamin700.github.io/tempestroid/guia/design-system/pesquisa/): O design system foi pensado para que pesquisadores acadêmicos montem apps
- [Storybook (galeria)](https://mauriciobenjamin700.github.io/tempestroid/guia/design-system/storybook/): Você percorreu o design system inteiro: [tokens](tokens.md) →
- [Eventos](https://mauriciobenjamin700.github.io/tempestroid/guia/eventos/): Eventos são o contrato tipado da fronteira Python↔Kotlin. Quando o lado nativo
- [CLI (`tempest`)](https://mauriciobenjamin700.github.io/tempestroid/guia/cli/): O ponto de entrada tempest cobre o ciclo de vida do app: criar, desenvolver no
- [Galeria de exemplos](https://mauriciobenjamin700.github.io/tempestroid/guia/exemplos/): Um conjunto de apps de exemplo executáveis vive em
- [Build, deploy e publicação](https://mauriciobenjamin700.github.io/tempestroid/guia/build/): Esta página mostra como sair do simulador e rodar seu app num aparelho
- [Rodar no dispositivo a partir do WSL](https://mauriciobenjamin700.github.io/tempestroid/guia/dispositivo-wsl/): O build estagia o Python a partir de toolchain/dist/ (symlink ou cópia) e o

## Reference

- [API pública](https://mauriciobenjamin700.github.io/tempestroid/referencia/api/): Tudo abaixo é importável do nível do pacote tempestroid. Importe sempre do nível
- [Lado do dispositivo (ponte)](https://mauriciobenjamin700.github.io/tempestroid/referencia/dispositivo/): A metade Python do lado do dispositivo é independente de hardware e testada sem um

## Project

- [Roadmap e fases](https://mauriciobenjamin700.github.io/tempestroid/roadmap/): O desenvolvimento segue duas trilhas-base e uma trilha de expansão. Trilho A
- [tempestroid — Plano do projeto](https://mauriciobenjamin700.github.io/tempestroid/plan/): Framework pessoal para construir apps Android nativos escrevendo Python tipado, com um simulador desktop (Qt) e dev loop por QR code estilo Expo/Flutter.
- [tempestroid — Plano de paridade (Flutter / React Native)](https://mauriciobenjamin700.github.io/tempestroid/plan-parity/): Trilho E — Paridade. Roadmap fase-a-fase para fechar o gap entre o
- [tempestroid — Plano de estabilização para uso pelo time (Trilho F)](https://mauriciobenjamin700.github.io/tempestroid/plan-stable/): Trilho F — Adoção. Roadmap fase-a-fase para o time usar o tempestroid em
- [Pesquisa — rodar CPython recente no Android (Trilho B)](https://mauriciobenjamin700.github.io/tempestroid/research/android-runtime/): Levantamento web (2025–2026) para fundamentar as fases B0–B6 do docs/plan.md.
- [Runbook executável — Trilho B (runtime Android)](https://mauriciobenjamin700.github.io/tempestroid/research/android-runbook/): Passo a passo para rodar numa máquina com toolchain Android (Linux x86_64 ou

## Optional

- [Dados e ML no dispositivo](https://mauriciobenjamin700.github.io/tempestroid/guia/dados-ml/): O tempestroid roda CPython de verdade no aparelho (não um subset). Isso abre
- [Navegação entre telas](https://mauriciobenjamin700.github.io/tempestroid/guia/navegacao/): Um app real tem mais de uma tela: lista de produtos, detalhe, carrinho, perfil.
- [Testes de UI (o "Playwright do nativo") 🎯](https://mauriciobenjamin700.github.io/tempestroid/guia/testing/): Você já sabe construir telas, ligar eventos e rodar no simulador. Agora vamos
- [Animação](https://mauriciobenjamin700.github.io/tempestroid/guia/widgets/animation/): O framework de animação do tempestroid vive no núcleo renderer-agnóstico: um
- [Texto, ação e indicadores](https://mauriciobenjamin700.github.io/tempestroid/guia/widgets/basics/): Os widgets desta família são os blocos mais usados em qualquer tela: um rótulo
- [Componentes compostos](https://mauriciobenjamin700.github.io/tempestroid/guia/widgets/components/): Componentes compostos são blocos de interface de alto nível prontos para uso.
- [Widgets de gestos](https://mauriciobenjamin700.github.io/tempestroid/guia/widgets/gestures/): Os widgets de gestos são invólucros de filho único (ou lista de filhos, no caso
- [Widgets de Entrada](https://mauriciobenjamin700.github.io/tempestroid/guia/widgets/inputs/): Ambos os renderizadores — simulador Qt (desktop) e Compose no
- [Widgets de layout](https://mauriciobenjamin700.github.io/tempestroid/guia/widgets/layout/): Os widgets de layout são os blocos estruturais de toda tela tempestroid.
- [Listas virtualizadas](https://mauriciobenjamin700.github.io/tempestroid/guia/widgets/lists/): Listas virtualizadas permitem exibir coleções de qualquer tamanho sem renderizar
- [Widgets de mídia e gráficos](https://mauriciobenjamin700.github.io/tempestroid/guia/widgets/media/): Os widgets de mídia e gráficos cobrem exibição de imagens, ícones vetoriais,
- [Navegação](https://mauriciobenjamin700.github.io/tempestroid/guia/widgets/navigation/): Um app móvel tem mais de uma tela. O tempestroid modela isso com uma pilha de
- [Overlays](https://mauriciobenjamin700.github.io/tempestroid/guia/widgets/overlays/): Overlays são widgets que flutuam em uma camada z-ordenada acima da árvore
- [Trilho H — design system: componentes estilizados (M3 + API Chakra)](https://mauriciobenjamin700.github.io/tempestroid/plan-design-system/): Plano dedicado para elevar o catálogo de componentes a um design system
- [Qt renderer fidelity roadmap](https://mauriciobenjamin700.github.io/tempestroid/qt-fidelity-roadmap/): Box-model fidelity gaps in the Qt desktop simulator (tempestroid/renderers/qt/)
- [Cobertura de renderizadores (Qt vs Compose)](https://mauriciobenjamin700.github.io/tempestroid/referencia/cobertura/): O tempestroid tem um reconciliador e dois renderizadores-folha: o Qt
- [Enums](https://mauriciobenjamin700.github.io/tempestroid/referencia/enums/): Os enums do tempestroid são constantes tipadas que descrevem intenção — valores
- [Feature-gating das capacidades nativas pesadas (F4 · trim de tamanho)](https://mauriciobenjamin700.github.io/tempestroid/research/feature-gating/): Objetivo. Tornar opcionais as dependências Android pesadas (CameraX, ML
- [Trilho G — Polars no device (investigação de viabilidade)](https://mauriciobenjamin700.github.io/tempestroid/research/g-polars-feasibility/): app Android nativo, incluindo o caminho de reading/writing (CSV/JSON/Parquet)
- [G0 — spike de viabilidade (Trilho G): resultados](https://mauriciobenjamin700.github.io/tempestroid/research/g0-feasibility/): Execução do G0 definido em [onnx-ml-stack.md](onnx-ml-stack.md) §6.
- [G1 — onnxruntime no device: caminho (A) wheel vs (B) AAR](https://mauriciobenjamin700.github.io/tempestroid/research/g1-onnxruntime-path/): Spike de decisão da fase G1 (após o marco numpy de
- [G6 — viabilidade de `scipy` + `scikit-learn` no device (Trilho G): resultados](https://mauriciobenjamin700.github.io/tempestroid/research/g6-sklearn-feasibility/): Spike de viabilidade do G6 (docs/research/onnx-ml-stack.md §G6, o "calcanhar":
- [Pesquisa — inferência ONNX + stack científica no device (Trilho G)](https://mauriciobenjamin700.github.io/tempestroid/research/onnx-ml-stack/): Levantamento para fundamentar o Trilho G: rodar inferência de modelos