Aula 5 • Projeto 5 • Adm Tech

Gradio: do Simples ao Top

Como transformar um notebook em produto utilizável

⚙️ Blocks 🧪 Validação 🎨 UX 🚀 Deploy

🎯 Meta da Aula

Resultado

Você vai sair com um app melhor que "só funciona"

Construir interface Gradio com upload e resultados financeiros.
Aplicar validação e mensagens de erro realmente úteis.
Melhorar experiência do usuário com layout, rótulos e feedback.
Organizar código para evoluir sem quebrar tudo.
Publicar e compartilhar de forma profissional.

🧭 O que separa simples de top

Visão

Nível	Como é	Problema	Upgrade
App simples	Input + botão + texto final	Usuário não entende erro nem contexto	Validação e saída explicada
App bom	Tabela, métricas, mensagens claras	Difícil manter quando cresce	Separação de camadas
App top	UX consistente, robusto, rápido	-	Pronto para demo e decisão

🛠️ Setup mínimo no Colab

Ambiente

Bloco inicial obrigatório

!pip install gradio pandas numpy plotly openpyxl -q

import pandas as pd
import numpy as np
import plotly.express as px
import gradio as gr

Boa prática: versão de dependências no topo da primeira célula e imports agrupados.

⚡ App mínimo com Interface

Começo rápido

Quando usar `gr.Interface`

Use quando você quer validar ideia rápido com uma função simples.

def calcular_simples(investimento, taxa, fluxo_anual, anos):
    fcls = [fluxo_anual] * int(anos)
    vpl = -investimento + sum(fc / ((1 + taxa) ** (i + 1)) for i, fc in enumerate(fcls))
    return f"VPL: R$ {vpl:,.2f}"

app = gr.Interface(
    fn=calcular_simples,
    inputs=[
        gr.Number(label="Investimento inicial"),
        gr.Slider(0.01, 0.5, value=0.14, step=0.01, label="Taxa de desconto"),
        gr.Number(label="Fluxo anual"),
        gr.Slider(1, 10, value=5, step=1, label="Anos")
    ],
    outputs=gr.Textbox(label="Resultado")
)
app.launch()

🏗️ Evoluindo para Blocks

Escala

Quando o app cresce, use `gr.Blocks`

Por que Blocks

Layout com `Row` e `Column`
Múltiplas saídas (texto + tabela + gráfico)
Eventos mais controlados
Melhor manutenção

Estrutura padrão

Header e descrição
Inputs agrupados
Botão principal e botão de limpar
Painel de resultados

🧱 Arquitetura recomendada

Código limpo

Separação em 3 camadas

# 1) io_layer.py
# leitura e limpeza de CSV/XLSX

# 2) domain_layer.py
# regras financeiras: VPL, TIR, projeções

# 3) ui_layer.py
# Gradio: inputs, eventos e outputs

Regra: a função de negócio não conhece Gradio. Ela recebe dados e retorna dados.

📥 Upload de arquivos de verdade

CSV/XLSX

Tratar diferentes formatos sem quebrar o app

def carregar_arquivo(file_obj):
    if file_obj is None:
        raise ValueError("Envie um arquivo CSV ou XLSX.")

    nome = file_obj.name.lower()
    if nome.endswith(".csv"):
        df = pd.read_csv(file_obj.name)
    elif nome.endswith(".xlsx"):
        df = pd.read_excel(file_obj.name)
    else:
        raise ValueError("Formato inválido. Use CSV ou XLSX.")

    df.columns = [c.strip().lower() for c in df.columns]
    return df

✅ Validação que ajuda o usuário

Robustez

Valide antes de calcular

Colunas obrigatórias: `ano`, `receita`, `custos`, `investimento`.
Tipos numéricos convertidos com `errors="coerce"`.
Checagem de `ano = 0` para investimento inicial.
Taxa entre 0 e 1.

Erro bom x erro ruim

Ruim: "KeyError"

Bom: "A coluna 'receita' não foi encontrada no arquivo enviado."

📊 Saídas que deixam o app top

Resultados

Não devolva só um número

Métrica principal

VPL formatado em moeda.

Métricas auxiliares

TIR, payback simples, cenário base.

Tabela detalhada

Ano, FCL, VP de cada período.

Visualização

Gráfico de barras/linha para interpretação.

fig = px.bar(df_resultado, x="ano", y="vp_fcl", title="Valor presente por ano")

🎨 UX: como deixar profissional

Polimento

5 ajustes de alto impacto

Títulos de campos orientados a negócio, não a código.
Valores padrão realistas para reduzir erro de input.
Textos curtos explicando cada output.
Botão `Limpar` e estado inicial previsível.
Theme e CSS leve para identidade visual.

with gr.Blocks(theme=gr.themes.Soft()) as demo:
    gr.Markdown("# Valuation App")
    ...

🔁 Fluxo de eventos

Interatividade

Use callbacks para fluidez

botao_calcular.click(
    fn=processar,
    inputs=[arquivo_input, taxa_input],
    outputs=[mensagem_out, tabela_out, grafico_out]
)

botao_limpar.click(
    fn=lambda: ("", None, None),
    inputs=[],
    outputs=[mensagem_out, tabela_out, grafico_out]
)

Meta: cada clique deve ter comportamento previsível e reversível.

⚡ Performance e estabilidade

Produção

Quando o app começa a travar

Evite recalcular tudo em cada mudança de slider.
Use `demo.queue()` para fila de requests.
Limite tamanho de arquivo aceito.
Faça cache de etapas pesadas quando possível.

demo = gr.Blocks()
...
demo.queue(max_size=20)
demo.launch()

🔐 Segurança e governança

Cuidados

Checklist mínimo antes de compartilhar

Não expor dados sensíveis no exemplo público.
Sanitizar nomes de arquivos e validar formato.
Descrever limitações do modelo no próprio app.
Registrar versão do notebook e das bibliotecas.

🌍 Deploy e compartilhamento

Entrega

Opções práticas

Colab (rápido)

`demo.launch(share=True)`
Link temporário
Bom para demo em aula

Hugging Face Spaces (estável)

Deploy contínuo por repositório
Link fixo para stakeholder
Melhor para portfólio

📌 Blueprint final de app top

Referência

Estrutura que vocês podem replicar

app/
  ui_gradio.py        # layout e callbacks
  service_finance.py  # VPL, TIR e projeções
  io_data.py          # leitura e limpeza de arquivo
  tests_quick.py      # validações principais

notebooks/
  aula5_gradio.ipynb

Critério de qualidade: qualquer pessoa do time consegue rodar e entender em menos de 5 minutos.

✅ Recap: como deixar top

Resumo

Interface clara e inputs guiados.
Validação robusta com mensagens humanas.
Saídas ricas: métricas + tabela + gráfico.
Código desacoplado para manutenção.
Deploy com link compartilhável e confiável.

Frase da aula

Um app top não é só cálculo certo. É cálculo certo + experiência certa.