Guia — Luna AI

Inicio Rapido

O jeito mais rapido de comecar a usar a Luna e pelo Telegram. Nao precisa instalar nada.

Caminho rapido (30 segundos)

Abra t.me/LunaAIBot no Telegram, envie /start e aguarde a aprovacao de um administrador.

O que voce pode fazer

Conversa livre — mande qualquer mensagem como num chat normal
Audio — envie um voice note e a Luna transcreve e responde
Memoria — "lembra que eu prefiro cafe sem acucar"
Gastos — "gastei 45 reais no almoco"
Metas — "quero ler 2 livros por mes"
Agenda — "o que tenho hoje?"
Tarefas — "cria tarefa: comprar presente"
Email — "meus emails nao lidos"
Pesquisa — "pesquisa sobre energia solar no Brasil"

Para recursos avancados (CLI, GUI, voz, RAG), veja as secoes abaixo.

Telegram

O bot @LunaAIBot e a interface principal da Luna.

Como comecar

Abra o Telegram e busque por @LunaAIBot
Envie /start
Aguarde a aprovacao (o admin recebe uma notificacao)
Depois de aprovado, e so mandar mensagens!

Exemplos de uso

# Conversa normal
qual a diferenca entre machine learning e deep learning?

# Memoria
lembra que eu moro em Sao Paulo
o que voce sabe sobre mim?

# Gastos
gastei 120 de uber ontem
resumo de gastos do mes

# Metas e habitos
quero correr 3x por semana
fiz exercicio hoje

# Agenda e tarefas
o que tenho amanha?
cria tarefa: enviar relatorio
minhas tarefas pendentes

# Email
meus emails nao lidos
manda email pro Joao sobre o projeto

Comandos rapidos

Comando	Funcao
/briefing	Resumo do seu dia
/goals	Suas metas
/habits	Seus habitos
/status	Status da Luna
/feedback	Enviar feedback
/help	Ajuda completa

Dica

Voce nao precisa usar comandos. A Luna entende linguagem natural — "como estao minhas metas" funciona tao bem quanto /goals.

CLI (Terminal)

O CLI e a interface mais completa da Luna, com 50+ comandos e REPL interativo.

Uso basico

# REPL interativo
luna

# Chat direto
luna chat "qual a capital da Franca?"

# Executa tarefa com tools
luna do "pesquisa sobre energia solar"

# Salvar na memoria
luna remember "meu aniversario e 15 de marco"

# Busca semantica
luna recall "aniversario"

Comandos principais

Comando	Funcao
luna	REPL interativo
luna chat "msg"	Chat simples
luna do "tarefa"	Executa com tools
luna remember "fato"	Salva na memoria
luna recall "busca"	Busca semantica
luna profile	Gerencia perfil
luna status	Health check
luna ingest <arquivo>	Processa PDF/DOCX
luna ask "pergunta"	Pergunta sobre documentos
luna bot start	Inicia bot Telegram

Comandos no REPL

Dentro do REPL (luna), voce pode usar comandos com /:

/model qwen3:14b     # troca modelo
/remember algo       # salvar na memoria
/recall busca         # buscar na memoria
/voice start          # iniciar modo voz
/integrations         # ver integracoes
/help                  # ajuda

GUI (Interface Grafica)

Interface grafica nativa com avatar de particulas (Three.js), streaming de pensamentos em tempo real e integracao com voz.

# Abrir GUI
luna gui

# Abrir com ferramentas de desenvolvedor
luna gui --debug

# Tela cheia
luna gui --fullscreen

Funcionalidades

Avatar de particulas — animacao Three.js com estados (idle, listening, thinking, speaking)
Chat com streaming — resposta em tempo real com eventos de "thinking" e "tool_use"
Voz integrada — TTS (Kokoro) e STT (Faster-Whisper) direto na interface
Audio streaming — sintese de audio progressiva com playback no browser
Memoria — salve e busque memorias pela interface

Opcoes de janela

Opcao	Funcao
--debug, -d	Ativa DevTools do navegador
--width, -w	Largura da janela (padrao: 1200)
--height, -h	Altura da janela (padrao: 800)
--fullscreen, -f	Inicia em tela cheia

Requisitos

A GUI precisa do extra [gui]: pip install 'luna-cli[gui]'

Para voz na GUI, instale tambem: pip install 'luna-cli[gui,voice]'

Voz

Fale com a Luna usando voz — ela ouve, entende e responde em audio.

# Status do modulo de voz
luna voice

# Modo voz interativo
luna voice start

# Configuracao
luna voice config

TTS (Text-to-Speech): Kokoro-82M — o #1 no HuggingFace TTS Arena
STT (Speech-to-Text): Faster-Whisper — 4x mais rapido que o Whisper original

Requisitos

O modulo de voz precisa do extra [voice]: pip install 'luna-cli[voice]'

Memoria

A Luna tem memoria persistente — ela lembra de informacoes sobre voce entre conversas.

Como usar

# Salvar um fato
lembra que eu prefiro cafe sem acucar
lembra que meu aniversario e 15 de marco
lembra que estou estudando Python

# Buscar na memoria
o que voce sabe sobre mim?
o que voce lembra sobre cafe?

Como funciona

Memorias sao salvas em SQLite local (~/.luna/)
Busca semantica com embeddings — encontra por significado, nao so por palavras
Multi-device via Syncthing (sem cloud)

Controle de Gastos

Registre e analise despesas em linguagem natural.

# Registrar gastos
gastei 35 no almoco
50 reais de uber ontem
paguei 120 de internet

# Consultar
resumo de gastos do mes
quanto gastei com alimentacao?
gastos de janeiro

# No CLI
luna do "gastei 200 no mercado"

As despesas sao categorizadas automaticamente (alimentacao, transporte, moradia, etc.) e ficam em SQLite local.

Metas e Habitos

Defina metas e acompanhe habitos diarios com atualizacao automatica.

# Criar metas
quero ler 2 livros por mes
minha meta e correr 3x por semana
quero economizar 500 reais por mes

# Registrar progresso
fiz exercicio hoje
li 30 paginas do livro
corri 5km hoje

# Consultar
como estao minhas metas?
meus habitos da semana

Briefing Diario

A Luna prepara um resumo do seu dia automaticamente — agenda, tarefas, metas e lembretes.

# Pedir briefing
/briefing
o que tenho hoje?
meu briefing

# Briefing automatico (Telegram)
# Receba um push toda manha com o resumo do dia

O briefing inclui: eventos do calendario, tarefas pendentes, progresso de metas, habitos e aniversarios.

Documentos (RAG)

Ingira PDFs e DOCX e faca perguntas sobre o conteudo.

# Processar documento
luna ingest relatorio.pdf
luna ingest contrato.docx

# Perguntar sobre documentos
luna ask "qual o prazo de entrega no contrato?"
luna ask "resume os principais pontos do relatorio"

# Listar documentos
luna docs list

Formatos: PDF, DOCX
Engine: Docling para extracao + chunking inteligente
Busca: Hibrida (BM25 + embeddings semanticos)

Biblioteca

Gerencie suas leituras com notas e flashcards.

# Via chat natural
estou lendo "Sapiens" do Yuval Harari
terminei o livro "Habitos Atomicos"
meus livros

Instalacao CLI

Nao obrigatorio

Se voce so quer usar pelo Telegram, nao precisa instalar nada. A instalacao do CLI e para quem quer usar pelo terminal ou hospedar o bot.

Requisitos

Python 3.11+
Linux/macOS/WSL (Windows via WSL2)
Ollama (opcional, para modelo local)

Instalacao

# Basico
pip install git+ssh://git@github.com/pvnoleto/Luna.git#subdirectory=luna-cli

# Com voz e GUI
pip install 'git+ssh://git@github.com/pvnoleto/Luna.git#subdirectory=luna-cli[voice,gui]'

# De um arquivo .whl
pip install luna_cli-0.1.0-py3-none-any.whl

Primeiro uso

# Assistente de configuracao
luna init

# Verificar se esta tudo ok
luna status

# Iniciar REPL
luna

Configuracao

API Keys (opcional)

Para usar modelos cloud, configure as chaves no arquivo .env:

# ~/.luna/.env (ou na pasta do projeto)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AI...

Seguranca

Nunca compartilhe suas API keys. O arquivo .env deve ter permissoes restritas: chmod 600 .env

Multi-Perfil

A Luna suporta multiplos perfis, cada um com dados isolados:

# Perfis disponiveis
~/.luna/           # padrao
~/.luna/estella/   # perfil secundario

# Usar perfil especifico
LUNA_HOME=~/.luna/estella luna

Modelo Local (Ollama)

# Instalar e iniciar Ollama
ollama serve

# Baixar modelos
ollama pull qwen3:14b     # ~9GB
ollama pull llama3.1:8b   # ~5GB

# Verificar
ollama list

Integracoes

Conecte a Luna com seus servicos para funcionalidades extras.

# Ver integracoes disponiveis
luna integrations

# Setup interativo
luna integrations setup email

# Testar conexao
luna integrations test email

# Desconectar
luna integrations disconnect email

Email (Gmail)

Acesse console.cloud.google.com
Crie um projeto e ative a API do Gmail
Crie credenciais OAuth 2.0
Baixe o credentials.json para ~/.luna/
Configure em ~/.luna/integrations.json
Execute luna integrations auth email

Email (Outlook)

Acesse portal.azure.com
Registre um app em "App registrations"
Adicione permissoes: Mail.Read, Mail.Send
Copie o Client ID
Configure em ~/.luna/integrations.json
Execute luna integrations auth email

Tarefas (Todoist)

Acesse Todoist Developer
Copie seu API Token
Configure como variavel de ambiente ou em integrations.json

# Opcao A — Variavel de ambiente
export TODOIST_API_TOKEN='seu_token'

# Opcao B — Config file
# Em ~/.luna/integrations.json:
{
  "tasks": {
    "provider": "todoist",
    "api_token": "seu_token"
  }
}

Outros

Calendario: Google Calendar via OAuth
Storage: Google Drive, Dropbox
Busca Web: Brave Search API (2.000 buscas/mes gratis)

Perguntas Frequentes

Sim. A Luna usa modelos com custo zero: Codex via ChatGPT Plus ($20/mes que voce ja paga), Claude via subscription Max, e Qwen3 rodando localmente. Nao ha custos de API adicionais.

A Luna e local-first: todos os seus dados ficam no seu computador em SQLite (~/.luna/). Nao existe servidor cloud obrigatorio. Multi-device via Syncthing (peer-to-peer, sem cloud). Secrets sao mascarados na saida do Telegram.

Sim, via WSL2 (Windows Subsystem for Linux). O Telegram funciona de qualquer dispositivo sem instalacao. Para o CLI, use WSL2 com Ubuntu.

Ao enviar /start, seu acesso fica como "pendente". Um administrador recebe uma notificacao e pode aprovar ou bloquear. Isso garante que apenas pessoas autorizadas usem o bot.

Para o Telegram, nao — o bot ja esta configurado. Para o CLI com modelos cloud, voce pode configurar API keys, mas o modelo local (Qwen3 via Ollama) funciona sem nenhuma chave.

Sim. O bot Telegram e multi-tenant — cada usuario tem dados isolados. O admin controla aprovacoes via /admin. Cada usuario tem seu LUNA_HOME separado com rate limiting independente.