Fluxi - Assistente WhatsApp Inteligente

Plataforma completa para criar assistentes WhatsApp com IA, ferramentas customizadas e base de conhecimento

Sobre o Projeto

Fluxi é uma plataforma opensource para criar e gerenciar assistentes inteligentes no WhatsApp. Com ele, você pode:

Criar múltiplos agentes com personalidades únicas Configurar ferramentas customizadas (APIs, funções, integrações) Treinar bases de conhecimento (RAG) com seus documentos Integrar múltiplos provedores LLM (OpenRouter, OpenAI, Anthropic, etc.) Conectar ferramentas externas via MCP (Model Context Protocol) Gerenciar múltiplas sessões WhatsApp Monitorar métricas e performance

Casos de Uso

Atendimento ao Cliente - Automatize suporte 24/7
Vendas - Qualifique leads e agende reuniões
Suporte Técnico - Responda dúvidas com base de conhecimento
Educação - Assistentes educacionais personalizados
Agendamentos - Marque consultas e envie lembretes
Consultas de Dados - Busque informações em sistemas internos

Quick Start

Opção 1: Docker (Recomendado)

1. Clone o repositório

git clone https://github.com/jjhoow/fluxi.git
cd fluxi

2. Configure o ambiente

# Copie o arquivo de exemplo
cp config.example.env .env

# Edite as configurações (opcional)
nano .env

Arquivo .env básico:

# Configuração do Banco de Dados
DATABASE_URL=sqlite:///./fluxi.db

# Configuração do Servidor
HOST=0.0.0.0
PORT=8001
DEBUG=True

# Diretório de Upload de Imagens
UPLOAD_DIR=./uploads

3. Execute com Docker

# Criar diretórios necessários
mkdir -p uploads sessoes rags

# Método 1: Usando docker-compose
docker-compose up -d --build

# Método 2: Usando o script helper
chmod +x docker-run.sh
./docker-run.sh setup # Configuração inicial
./docker-run.sh start # Inicia o Fluxi

4. Acesse a interface

Abra seu navegador em http://localhost:8001

Opção 2: Instalação Local

1. Clone o repositório

git clone https://github.com/jjhoow/fluxi.git
cd fluxi

2. Instale as dependências

pip install -r requirements.txt

3. Execute o projeto

python main.py

4. Acesse a interface

Abra seu navegador em http://localhost:8001

Configuração Inicial

1. Configurar Provedor LLM

Opção A: OpenRouter (Mais Fácil)

Acesse http://localhost:8001/configuracoes
Adicione sua chave OpenRouter
Teste a conexão

Opção B: Provedor Local

Acesse http://localhost:8001/provedores-llm
Clique em "Novo Provedor"
Configure:

Tipo: LM Studio, llama.cpp ou Ollama
URL: http://localhost:11434 (Ollama) ou http://localhost:1234 (LM Studio)
Modelo: Seu modelo preferido

Teste a conexão

2. Criar Sessão WhatsApp

Acesse http://localhost:8001/sessoes
Clique em "Nova Sessão"
Preencha:

Nome: Nome da sessão
Descrição: Descrição opcional

Clique em "Criar"
Clique em "Conectar" na sessão criada
Escaneie o QR Code com seu WhatsApp

3. Criar Agente

Acesse http://localhost:8001/agentes/sessao/{id-da-sessao}
Clique em "Novo Agente"
Preencha os campos:

Nome: Nome do agente
Papel: Ex: "Assistente de Vendas"
Objetivo: Ex: "Ajudar clientes com produtos"
Políticas: Ex: "Sempre ser educado e profissional"
Tarefa: Ex: "Responder dúvidas sobre produtos"
Objetivo Explícito: Ex: "Aumentar vendas"
Público-alvo: Ex: "Clientes interessados em produtos"
Restrições: Ex: "Não fazer promessas que não posso cumprir"

Selecione o provedor LLM configurado
Clique em "Criar"

4. Testar o Sistema

Envie uma mensagem para o número conectado
O agente deve responder automaticamente
Verifique as métricas em http://localhost:8001/metricas

Comandos Docker

Comandos Básicos

# Criar diretórios necessários (primeira vez)
mkdir -p uploads sessoes rags

# Iniciar Fluxi
docker-compose up -d --build

# Parar Fluxi
docker-compose down

# Reiniciar Fluxi
docker-compose restart

# Ver logs
docker-compose logs -f

# Verificar status
docker-compose ps

# Abrir shell no container
docker-compose exec fluxi bash

Comandos Avançados

# Configurar porta personalizada
PORT=8080 docker-compose up -d

# Rebuild da imagem
docker-compose build --no-cache

# Limpeza completa
docker-compose down -v
docker system prune -f

# Usando script helper (alternativa)
./docker-run.sh start -p 8080
./docker-run.sh build
./docker-run.sh clean

Variáveis de Ambiente

# .env
# Configuração do Banco de Dados
DATABASE_URL=sqlite:///./fluxi.db

# Configuração do Servidor
HOST=0.0.0.0
PORT=8001
DEBUG=True

# Diretório de Upload de Imagens
UPLOAD_DIR=./uploads

Escaneie o QR Code com WhatsApp

Crie um Agente

Dentro da sessão, crie um agente
Configure seu system prompt (papel, objetivo, políticas)
Adicione ferramentas (opcional)

Envie uma mensagem!

Envie mensagem no WhatsApp vinculado
O agente responderá automaticamente

Arquitetura do Projeto

fluxi/
agente/ # Módulo de agentes inteligentes
config/ # Configurações do sistema
ferramenta/ # Ferramentas executáveis
llm_providers/ # Integrações com provedores LLM
mcp_client/ # Model Context Protocol
mensagem/ # Mensagens WhatsApp
metrica/ # Métricas e monitoramento
rag/ # Sistema RAG (bases de conhecimento)
sessao/ # Sessões WhatsApp
templates/ # Templates HTML (Jinja2)
uploads/ # Arquivos enviados
rags/ # Bases de conhecimento ChromaDB
database.py # Configuração SQLAlchemy
main.py # Aplicação FastAPI
requirements.txt # Dependências Python
README.md # Este arquivo

Documentação dos Módulos

Agente

Gerenciamento de agentes inteligentes com system prompts personalizados, ferramentas e bases de conhecimento.