Team Ai
Apppublic

senal88/simulador-consorcio-dev

sourceHugging Faceupdated 7mo agoView on Hugging Face
1likes
App README

MAIA v2 - Simulador de Consórcios Corporativo

Este é o ambiente de implantação otimizado do Simulador de Consórcio, parte da arquitetura MAIA v2. O contêiner hospeda nativamente o frontend (apps/web_comercial base Next.js) e o motor de simulação por trás (packages/simulation-engine), provendo visualizações de fluxos de caixa e regras de negócio para análise de crédito de alto desempenho.

🏗 Arquitetura do Contêiner

  • —Interface: Baseada em Next.js (Node 22), rodando em modo stand-alone (apps/web_comercial).
  • —Motor (Backend): Pacotes internos de agentes (packages/agents e packages/simulation-engine) que interagem dinamicamente para aplicar regras complexas de extração e validação do mercado secundário.
  • —Portabiblidade: Agnóstico à plataforma. Rodamos a mesma imagem Docker em desenvolvimento local e implantação cloud.

🚀 Capacidades Premium (Hugging Face PRO)

Este Space foi arquitetado sob governança estrita para uso máximo de Assinatura Hugging Face PRO:

  1. 1.Hardware Dedicado (CPU/Upgrades): Como Spaces em SDK Docker não suportam as instâncias de GPU fracionada (ZeroGPU - restritas ao Gradio), a arquitetura provisiona instâncias CPU-Basic ou submete upgrades (cpu-upgrade) por demanda corporativa. O utilitário interno Python (DeviceManager) é agnóstico: ele rebaixa graciosamente a execução da IA para instâncias CPU rodando em Nuvem, ou usa MPS (Apple Silicon) nativamente quando você testa local. Nunca altere bibliotecas obrigando a execução sob CUDA.
  1. 1.Depuração Viva (Dev Mode): Como assinante PRO, você pode realizar hot-fixes e testes de inferência na nuvem ativando o Dev Mode em Settings > Dev Mode do Space. Pode se conectar através de terminal SSH ou usar o VS Code Web injetado nativamente pela Hugging Face. As edições realizadas nesse ambiente SÃO TEMPORÁRIAS E DEVEM SER COMITADAS. O nosso fluxo padrão determina:
  2. 2.`develop` -> Space DEV: Use o Dev Mode para testes paralelos sem afetar instâncias públicas. Altere o código pelo VS Code do Space e faça git add, git commit e git push origin develop.
  3. 3.`main` -> Space PROD: Implantações em produção ocorrem automaticamente através de CI/CD limpo sem Dev Mode ativado.
  1. 1.Governança de Dados (Data Studio): Artefatos massivos e pesados (extrações .xlsm, logs e tabelas relacionais do simulador) nunca são commitados no repositório de código fonte do GitHub. A análise desses eventos confidenciais corporativos utiliza o portal visual Data Studio do ecossistema de dados privados da Hugging Face associado a esta organização.
  1. 1.Automação de Runtime e Governança de Ambiente: O pipeline de deploy sincroniza automaticamente variáveis públicas e segredos operacionais do Space para refletir o estágio (DEV ou PROD), o hardware ativo, janelas de sleep e chaves de provedores externos. Isso deixa a interface e a rota /api/health conscientes do ambiente real em execução sem precisar editar o repositório do Space manualmente.

⚙ Variáveis e Secrets do Space

O workflow do GitHub já injeta as variáveis públicas de runtime abaixo:

  • —NEXT_PUBLIC_RUNTIME_TARGET=huggingface
  • —NEXT_PUBLIC_SPACE_PROVIDER=Hugging Face Spaces
  • —NEXT_PUBLIC_SPACE_STAGE=DEV|PROD
  • —NEXT_PUBLIC_HF_HARDWARE=<tier ativo>
  • —NEXT_PUBLIC_HF_PRO_ENABLED=true
  • —NEXT_PUBLIC_HF_SPACE_ID=<org/space>

Secrets recomendados para o menu Settings > Variables and Secrets ou para o workflow:

  • —HF_TOKEN: O token da sua conta PRO. Necessário para Inference Providers e APIs avançadas.
  • —Qualquer chave adicional de LLMs (OPENAI_API_KEY, ANTHROPIC_API_KEY) deve ser adicionada neste mesmo painel da nuvem, de acordo com o padrão encontrado no .env do monorepo original.

🩺 Endpoints operacionais no app

O frontend expõe endpoints leves úteis para checagem do runtime:

  • —GET /api/health
  • —GET /api/runtime

Essas rotas retornam o estágio do Space, provedor, hardware, storage e sleep time efetivamente aplicados.

🔍 Acesso aos Logs (via API)

Para depuração avançada sem depender do painel web, a Hugging Face fornece endpoints SSE (Server-Sent Events) para observabilidade do Space. Você pode usar o script local que configuramos:

bash
# Exportar o token antes
export HF_TOKEN="seu_token_aqui"

# Obter logs de execução em tempo real
./scripts/deploy/hf_logs.sh sua-org/nome-do-space run

# Obter logs de build em tempo real
./scripts/deploy/hf_logs.sh sua-org/nome-do-space build

Ou através de chamadas brutas (cURL):

bash
curl -N -H "Authorization: Bearer $HF_TOKEN" "https://huggingface.co/api/spaces/sua-org/nome-do-space/logs/run"

🤖 CI/CD do GitHub

Para automação, este repositório é gerenciado upstream pelo GitHub, através do workflow `.github/workflows/simulador-consorcio-deploy-hf.yml`. Ele requer que os seguintes **Repository Secrets** do Github sejam provisionados:

  • —HF_SPACE_DEV: Caminho do Space de desenvolvimento (Ex: org/simulador-dev). Disparado em push na develop.
  • —HF_SPACE_PROD: Caminho do Space de produção (Ex: org/simulador-prod). Disparado em push na main.
  • —HF_TOKEN: token de automação com permissão de escrever no(s) Space(s).
  • —OPENAI_API_KEY e ANTHROPIC_API_KEY: opcionais. Se presentes, o deploy sincroniza esses secrets para o Space.

O workflow também aceita parâmetros manuais opcionais:

  • —hardware
  • —storage
  • —sleep_time
  • —duplicate_from

💻 Execução local do bundle

Para validar o empacotamento antes de subir para o GitHub ou para a Hugging Face:

bash
npm run deploy:hf:dry-run