animaflow 0.1.0

Diagramas e fluxogramas de arquitetura declarativos, animados e programáveis em Python
_{Projete fluxos técnicos modernos uma única vez e renderize para Manim (MP4, GIF), Web Canvas/SVG interativo ou Remotion}

Por que o animaflow? · Galeria & Exemplos · Arquitetura · Instalação · Começando Rápido · Exemplos Prontos · Identidade Visual · Estrutura · Roadmap · Autoria & Licença

Galeria & Exemplos

Streaming Contínuo — fluxo em tempo real de partículas	Multi-Agent Swarm — DAG de orquestração em camadas	RAG Pipeline — arquitetura de busca e LLM

Por que o animaflow?

Criar diagramas de arquitetura de software para redes profissionais (LinkedIn, X/Twitter), vídeos técnicos (YouTube, Reels) e apresentações corporativas geralmente exige:

• Escrever centenas de linhas manuais de geometria, coordenadas absolutas e updaters no Manim ou After Effects, ou
• Usar geradores estáticos (Graphviz, PlantUML, Diagrams) sem qualquer suporte a movimento, ritmo narrativo ou pulso de dados.

O animaflow resolve isso separando a definição semântica do fluxo dos motores de renderização:

1. Declare Nós e Conexões: especifique nós, serviços, banco de dados, labels e metadados via DSL simples em Python.
2. Auto-Layout Inteligente: organize automaticamente nós em camadas (DAGs), colunas ou sequências horizontais/verticais com alinhamento e margens dinâmicas anti-sobreposição.
3. Timeline Narrativa: anime pacotes individuais, streams contínuos de partículas, transições de estado e realces de nós de forma declarativa.
4. Múltiplos Backends: exporte diretamente para Manim CE (vídeos MP4 e GIFs em alta definição) e HTML/Web Canvas interativo.

Como funciona a arquitetura

O núcleo do animaflow é modular e extensível:

Instalação

# Instalação básica (Core + exportação Web Canvas)
pip install animaflow

# Core com todos os renderizadores opcionais, incluindo Manim (MP4 / GIF)
pip install "animaflow[all]"

# Ferramentas de teste, lint, tipos e publicação
pip install -e ".[dev]"

Nota: Para renderização via Manim, é necessário ter o ffmpeg instalado no seu sistema operacional.

Publicar uma versão

O workflow publish.yml testa em Python 3.10–3.12 e valida o wheel e o sdist. Para publicar no PyPI, crie uma GitHub Release com a tag vX.Y.Z; a tag deve corresponder às versões em pyproject.toml e src/animaflow/__init__.py. Para testar, execute o workflow manualmente com o destino testpypi.

Antes da primeira publicação, cadastre um pending publisher em cada índice:

No PyPI, configure o pending publisher em Publishing; no TestPyPI, use Publishing. Os environments pypi e testpypi do GitHub já estão criados. O OIDC não usa tokens ou secrets do PyPI.

Começando Rápido

1. Criando um fluxo com animação contínua (Stream de Partículas)

from manim import Scene
import animaflow as af

class MyArchitectureScene(Scene):
    def construct(self):
        # 1. Cria o fluxo de arquitetura
        flow = af.Flow(title="Real-Time Event Processing")

        # 2. Declara os nós do sistema
        client = flow.add_node("Mobile / IoT", subtitle="MQTT Producer")
        broker = flow.add_node("Event Bus", subtitle="Kafka Cluster")
        worker = flow.add_node("Stream Worker", subtitle="Flink / Python")
        store  = flow.add_node("Data Lake", subtitle="ClickHouse")

        # 3. Organiza o layout em camadas automáticas
        flow.auto_layout_layers([[client], [broker], [worker], [store]], h_gap=1.6, v_gap=0.8)

        # 4. Conecta os componentes
        flow.connect(client, broker, label="telemetry")
        flow.connect(broker, worker, label="ingest")
        flow.connect(worker, store, label="batch write")

        # 5. Programa a narrativa de animação
        flow.timeline.reveal_sequence(delay=0.3)
        flow.timeline.stream_packets(count=6, speed=0.8, duration=3.0)
        flow.timeline.wait(1.0)

        # 6. Renderiza na cena Manim
        flow.render_manim(self)

2. Exportando para Web Interativa (HTML/SVG)

# Exportação simples para arquivo HTML estático
html_content = flow.export_html()

with open("arquitetura.html", "w", encoding="utf-8") as f:
    f.write(html_content)

Exemplos Prontos

O repositório inclui exemplos completos na pasta examples/:

Identidade Visual (Nordic Sage & Carbon)

A identidade visual do animaflow foi concebida com princípios de design editorial nórdico e precisão industrial, evitando gradientes genéricos e priorizando contraste técnico:

• Símbolo: Três nós de arquitetura dispostos em triangulação fechada por um circuito orbital contínuo de dados.
• Tipografia: IBM Plex Sans SemiBold com curvas vetoriais extraídas via fontTools (sem dependência de fontes externas instaladas).
• Pacote Completo: Disponível no diretório brand/ com versões em SVG puro, PNGs rasterizados via PyCairo (16px a 1600px), favicons e guia de uso em brand/README.md.

Estrutura do Repositório

animaflow/
├── brand/                      # Identidade visual oficial (Nordic Sage & Carbon)
│   ├── README.md               # Especificação de design, paleta e regras de aplicação
│   ├── scripts/                # Scripts autônomos de geração (PyCairo + fontTools)
│   ├── svg/                    # SVGs de alta precisão com tipografia em curvas
│   └── png/                    # PNGs rasterizados em alta resolução (16px a 1600px)
├── docs/                       # Documentação técnica de implementação e assets
│   ├── IMPLEMENTATION_OVERVIEW.md  # Status detalhado das implementações e roadmap
│   └── assets/                 # Demonstrações, capturas e GIFs do pipeline
├── src/
│   └── animaflow/
│       ├── core/               # Modelos (Flow, Node, Edge, Layout, Timeline)
│       │   ├── flow.py
│       │   ├── layout.py
│       │   └── timeline.py
│       └── backends/           # Renderizadores plugáveis
│           ├── manim/          # Integração Manim CE (Mobjects vetoriais e animações)
│           └── web/            # Gerador de Canvas SVG interativo
├── examples/                   # Scripts de demonstração prontos para rodar
├── tests/                      # Bateria de testes unitários e de integração
├── pyproject.toml              # Metadados de empacotamento e dependências
└── README.md                   # Documentação principal

Roadmap e Próximos Passos

Para uma visão detalhada do que já foi construído e das próximas entregas, consulte o documento docs/IMPLEMENTATION_OVERVIEW.md.

• DSL semântica de fluxos em Python
• Motor de auto-layout em camadas (DAGs) com margens dinâmicas anti-sobreposição
• Renderizador vetorial Manim com suporte a temas e subtítulos
• Animação de pacotes discretos e stream contínuo de partículas
• Exportador para Web Canvas SVG interativo
• Identidade visual oficial Nordic Sage & Carbon (SVGs, PNGs, Favicons, Banner)
• Controles interativos no Web Canvas (Play/Pause, Zoom e Pan)
• Suporte nativo a Diagramas de Sequência (SequenceDiagram)
• API de estilização avançada (formas de nós customizadas, estilos de setas e gradientes)
• CLI dedicada (animaflow render <script> --backend manim|web)
• Exportação direta para formatos adicionais (JSON para Remotion, GraphViz DOT)

Autoria & Licença

Desenvolvido por Oséias Farias.

Distribuído sob a licença MIT. Consulte LICENSE para mais detalhes.