Ir para o conteúdo

Arquitetura

Como os dados fluem pelo asiai — dos sensores de hardware até seu terminal, navegador e agentes de IA.

Visão Geral

asiai architecture overview

Arquivos-chave

Camada Arquivos Papel
Engines src/asiai/engines/ ABC InferenceEngine + 7 adaptadores (Ollama, LM Studio, mlx-lm, llama.cpp, oMLX, vllm-mlx, Exo). Classe base OpenAICompatEngine para engines compatíveis com OpenAI.
Coletores src/asiai/collectors/ Métricas do sistema: gpu.py (ioreg), system.py (CPU, memória, térmico), processes.py (atividade de inferência via lsof).
Benchmark src/asiai/benchmark/ runner.py (warmup + N execuções, mediana, desvio padrão, CI95), prompts.py (prompts de teste), card.py (geração de card SVG).
Armazenamento src/asiai/storage/ db.py (SQLite WAL, todo CRUD), schema.py (tabelas + migrações).
CLI src/asiai/cli.py Ponto de entrada argparse, todos os 12 comandos.
Web src/asiai/web/ FastAPI + htmx + SSE + dashboard ApexCharts. Rotas em routes/.
MCP src/asiai/mcp/ Servidor FastMCP, 11 ferramentas + 3 recursos. Transportes: stdio, SSE, streamable-http.
Advisor src/asiai/advisor/ Recomendações baseadas em hardware (dimensionamento de modelos, seleção de engine).
Display src/asiai/display/ Formatadores ANSI (formatters.py), renderizador CLI (cli_renderer.py), TUI (tui.py).

Fluxo de dados

Monitoramento (modo daemon)

A cada 60s:
  coletores → dict snapshot → store_snapshot(db) → tabela models
                                                 → tabela metrics
  engines   → status da engine → store_engine_status(db)

Benchmark

CLI --bench → detectar engines → escolher modelo → warmup → N execuções
           → calcular mediana/desvio/CI95 → store_benchmark(db)
           → renderizar tabela (ANSI ou JSON)
           → opcional: --share → POST para API comunitária
           → opcional: --card  → gerar card SVG

Dashboard web

Navegador → FastAPI → template Jinja2 (renderização inicial)
          → htmx SSE → /api/v1/stream → atualizações em tempo real
          → ApexCharts → /api/v1/metrics?hours=N → gráficos históricos

Servidor MCP

Agente IA → stdio/SSE/HTTP → FastMCP → chamada de ferramenta
          → executa coletor/benchmark em thread pool (asyncio.to_thread)
          → retorna JSON estruturado

Princípios de design

  1. Zero dependências no core — CLI, coletores, engines, armazenamento usam apenas a stdlib do Python. Extras opcionais ([web], [tui], [mcp]) adicionam dependências apenas quando necessário.
  2. Camada de dados compartilhada — O mesmo banco SQLite serve CLI, web, MCP e Prometheus. Sem armazenamentos separados.
  3. Padrão adaptador — Todas as 7 engines implementam a ABC InferenceEngine. Adicionar uma nova engine = 1 arquivo + registrar em detect.py.
  4. Imports lazy — Cada comando CLI importa suas dependências localmente, mantendo o tempo de inicialização rápido.
  5. Nativo macOS — ioreg para GPU, launchd para daemons, lsof para atividade de inferência. Sem abstrações Linux.