Chat IA

O Sulfite Chat é um agente LLM integrado ao Studio que permite gerar relatórios completos a partir de descrições em linguagem natural. Basta descrever o que precisa — o agente gera o JSON do ReportDefinition, valida contra o schema, e aplica direto no canvas.

Como funciona

┌─────────────────┐     ┌─────────────┐     ┌──────────────┐     ┌──────────┐
│  "Crie uma nota │────▶│  LlmService │────▶│  Schema      │────▶│ Relatório│
│   fiscal com    │     │  (provider) │     │  Validator   │     │ aplicado │
│   itens e total"│     └─────────────┘     └──────────────┘     │ no canvas│
└─────────────────┘            │                   │             └──────────┘
                               ▼                   ▼
                        Resposta do LLM     Se inválido, re-envia
                        com JSON embutido   com erros (até 3x)

1. O usuário descreve o relatório em linguagem natural
2. O ReportGenerator envia o prompt com o system prompt Sulfite ao LLM
3. O LLM retorna JSON de ReportDefinition
4. O SchemaValidator valida e parseia o JSON
5. Se inválido, re-envia automaticamente com os erros para auto-correção (até 3 tentativas)
6. O relatório válido é aplicado no canvas do Studio

Comportamento do system prompt:

• Se ChatConfig.systemPrompt vier preenchido, ele é usado.
• Se vier vazio, o ReportGenerator usa o prompt padrão do Sulfite (sulfiteSystemPrompt).

Instalação

Adicione sulfite_chat ao seu projeto:

dependencies:
  sulfite_chat:
    git:
      url: https://github.com/rafaelgazani/sulfite.git
      path: packages/sulfite_chat

Integração com o Studio

Passe um ChatConfig ao SulfiteDesigner:

import 'package:sulfite_chat/sulfite_chat.dart';
import 'package:sulfite_studio/sulfite_studio.dart';

SulfiteDesigner(
  initialReport: myReport,
  chatConfig: const ChatConfig(
    name: 'Sulfite AI',
    provider: 'openai',
    model: 'gpt-4o',
    apiKey: 'sk-...',
    systemPrompt: sulfiteSystemPrompt,
  ),
)

O botão de chat aparece na AppBar. O painel pode ser usado de duas formas:

Modo flutuante

Clique no ícone de chat na AppBar. O painel flutuante é arrastável e pode ser reposicionado. Fechar o painel não destrói a conversa — ela é preservada.

Modo fixo (dockado)

Clique no ícone 📌 no painel flutuante para fixá-lo como terceira aba no painel lateral:

┌─────────────────────────────────────────┐
│  Propriedades  │  Bandas  │  Chat IA    │
├─────────────────────────────────────────┤
│                                         │
│  (conteúdo da aba selecionada)          │
│                                         │
└─────────────────────────────────────────┘

Para voltar ao modo flutuante, clique no ícone ↗ no header do chat dockado.

Provedores suportados

Provider	Identificador	Requer API Key	Descrição
OpenAI	openai	Sim	API oficial da OpenAI
Anthropic	anthropic	Sim	API oficial da Anthropic
GitHub Copilot	gh_copilot	Opcional	Usa o Copilot CLI do VS Code
GitHub Models	gh_models	Sim	API de modelos do GitHub
Ollama	ollama	Não	Modelos locais via Ollama

Modelos disponíveis

// OpenAI
'gpt-4o', 'gpt-4o-mini', 'gpt-4-turbo', 'gpt-3.5-turbo', 'o4-mini'

// Anthropic
'claude-sonnet-4-20250514', 'claude-opus-4-20250514', 'claude-3-5-haiku-20241022'

// Ollama (local)
'llama3.1', 'llama3', 'mistral', 'codellama', 'qwen2.5-coder'

// GitHub Models
'openai/gpt-4o', 'openai/gpt-4o-mini', 'meta/llama-4-scout-17b-16e-instruct', 'mistral/mistral-large-2411'

// GitHub Copilot
'copilot'

Configuração in-line

O painel de chat inclui uma tela de configurações (ícone ⚙️) onde o usuário pode trocar provider, modelo, API key e base URL sem sair do chat. As credenciais não são persistidas — existem apenas na sessão atual.

ChatConfig

const ChatConfig({
  required String name,         // Nome exibido no header do chat
  required String model,        // Modelo a usar (ex: 'gpt-4o')
  required String provider,     // Identificador do provider
  String? apiKey,               // API key / token (opcional para alguns)
  String? baseUrl,              // URL base customizada (opcional)
  required String systemPrompt, // System prompt do agente
  String iconName = 'smart_toy',// Ícone do Material Icons
  int colorValue = 0xFF2196F3,  // Cor tema do chat (ARGB)
});

Ícones disponíveis

smart_toy, auto_awesome, psychology, code, description, label, table_chart, bar_chart

Uso programático

O sulfite_chat também pode ser usado fora do Studio:

ReportGenerator

import 'package:sulfite_chat/sulfite_chat.dart';

final config = ChatConfig(
  name: 'Meu Agente',
  provider: 'openai',
  model: 'gpt-4o',
  apiKey: 'sk-...',
  systemPrompt: sulfiteSystemPrompt,
);

final generator = ReportGenerator(config: config);
final result = await generator.generate(
  'Crie uma nota fiscal com cabeçalho, tabela de itens e total',
);

if (result.success) {
  print('Relatório gerado: ${result.report!.reportName}');
  print('Explicação: ${result.explanation}');
} else {
  print('Erros: ${result.errors}');
}

LlmService (chamada direta)

final response = await LlmService.executar(
  config,
  'Qual a estrutura de um Band no Sulfite?',
  maxRetries: 3,
);
print(response);

SchemaValidator

final result = SchemaValidator.validate(jsonString);
if (result.isValid) {
  final report = result.report!;
} else {
  print('Erros: ${result.errors}');
}

SulfiteChatScreen (widget standalone)

O widget de chat pode ser incorporado em qualquer app Flutter:

SulfiteChatScreen(
  config: chatConfig,
  currentReport: myReport,           // contexto para o agente
  onReportGenerated: (report) {      // callback com o report parseado
    // aplicar no seu app
  },
  onJsonGenerated: (json) {          // callback com o JSON bruto
    // salvar ou processar
  },
)

GitHub Copilot (CLI)

Para usar o provider gh_copilot:

1. Tenha a extensão GitHub Copilot Chat instalada no VS Code
2. O Sulfite detecta automaticamente o binário do Copilot CLI
3. Opcionalmente, forneça um GitHub Token no campo API Key

Alternativa via terminal:

# Login interativo
copilot
> /login

# Ou exporte seu token
export GITHUB_TOKEN="ghp_..."

Dica: GitHub Token

Crie um Personal Access Token em github.com/settings/tokens com o escopo copilot. Cole no campo API Key nas configurações do chat.

Exemplos de prompts

"Crie uma nota fiscal com cabeçalho contendo logo e dados da empresa,
tabela de itens com produto, quantidade e valor, e rodapé com total"

"Crie etiquetas de 3 colunas para produtos com nome, código de barras
EAN-13 e preço"

"Relatório de vendas mensal com gráfico de barras mostrando vendas
por categoria e tabela detalhada abaixo"

"Adapte o relatório atual para adicionar uma banda de resumo com
totais de quantidade e valor"

API pública

// Configuração
ChatConfig

// Widgets
SulfiteChatScreen

// Serviços
LlmService
ReportGenerator
SchemaValidator

// Modelos
SulfiteChatMessage
GenerationResult
ValidationResult

// System prompt padrão
sulfiteSystemPrompt