🧠 Nexus — Personal Organizer Bot

Seu segundo cérebro no Telegram: mande a vida em mensagens soltas — a IA classifica, organiza, conecta e te devolve insights.

#💡 A ideia

Ao longo do dia batem ideias, tarefas, compromissos e anotações — e quase sempre elas se perdem. O Nexus é um agente pessoal que você alimenta com mensagens soltas no Telegram. Ele:

1. Classifica cada mensagem com IA (tipo, título, prazo, prioridade, projeto, pessoas);
2. Guarda tudo de forma estruturada no SQLite;
3. Conecta notas parecidas e sugere links;
4. Responde perguntas e gera insights sobre a sua rotina;
5. Exporta um vault navegável para o Obsidian.

Tudo com uma regra de ouro: a IA nunca inventa prazo, prioridade ou fato que não esteja no texto.

#🌊 Como funciona

flowchart TD
    A[📥 Mensagem solta no Telegram] --> B{Classificação<br/>Claude Haiku}
    B --> C[(🗄️ SQLite<br/>camada de repositório)]
    C --> D[🔎 Embedding local<br/>sentence-transformers → sqlite-vec]
    D --> E[🔗 Sugestão de conexão<br/>aceita / ignora]
    C --> F[💬 Consultas & RAG<br/>/buscar · /perguntar]
    C --> G[🧠 Review semanal<br/>Claude Sonnet]
    C --> H[📤 Export para o Obsidian<br/>PARA + Zettelkasten + LYT]
    E -. feedback .-> I[📈 Calibração do limiar<br/>/calibrar · F1-ótimo]

#✨ Destaques

• 🤖 Classificação estruturada com Claude Haiku (structured output) em tarefa · evento · acontecimento · ideia · nota, com aprendizado incremental: cada correção sua vira few-shot nas próximas classificações. (📔 Acontecimento = um registro pessoal/emocional — algo que te aconteceu e mexeu com você.)
• 🏃 Rastreamento leve de hábitos + padrões — mensagens como "corri 5km" viram registros estruturados (atividade, valor, unidade, data), aparecem no /habitos e cruzam com o review semanal: o bot calcula relações reais (ex.: "semanas com 2+ corridas → 100% mais ideias registradas") e o Sonnet as narra — números computados no código, nunca alucinados.
• 🎨 Camada de Temas + graph legível — cada entrada recebe ≥1 tema (área da vida) de um vocabulário fechado (relacionamentos · saúde · estudos · lazer · pessoal) e, nos acontecimentos, um mood (−2..+2). O export do Obsidian usa o tema como eixo primário: colore o graph por área da vida, transforma hábitos em nós ("corrida", "leitura") e agrupa tudo em MOCs — dá pra bater o olho e entender o que está acontecendo com você.
• 🧭 Memória semântica local — embeddings offline (sentence-transformers) + sqlite-vec no próprio banco, sem custo de API. Ao salvar uma nota, o bot sugere conexões com as parecidas.
• 💬 RAG conversacional (/perguntar) — pergunte em linguagem natural e receba respostas ancoradas nas suas notas, citando #id e data.
• ✍️ Edição em linguagem natural (/editar) — "adia o relatório pra sexta e marca alta"; o bot descobre qual entrada e o que mudar.
• 🔮 Insights proativos — /review semanal com Claude Sonnet e envio automático agendado quando o histórico fica rico o bastante.
• 📈 Ciclo de ML fechado — /calibrar aprende o limiar de conexões a partir do seu próprio feedback (coleta → treino → uso).
• 🗂️ Export para Obsidian idempotente, num híbrido PARA + Zettelkasten + LYT/MOCs.
• 🔒 Privado por padrão — restrito ao seu chat_id; nenhum dado pessoal vai para o repositório.

#💬 Comandos

Basta enviar qualquer texto para capturar e classificar uma entrada. Os comandos abaixo aparecem no menu do Telegram:

#🛠️ Stack

#🚀 Setup

Requer Python 3.11+.

# 1. Ambiente virtual
python -m venv .venv
.venv\Scripts\Activate.ps1        # Windows (PowerShell)
# source .venv/bin/activate       # Linux/macOS

# 2. Instalar em modo editável (com deps de dev)
pip install -e ".[dev]"

# 3. Variáveis de ambiente
copy .env.example .env            # Windows  (cp no Linux/macOS)

Edite o .env:

As demais opções (busca semântica, limiares, review semanal, fuso) têm padrões sensatos e estão documentadas no .env.example.

# Rodar
python -m organizer.main

No Telegram, envie /start e depois qualquer mensagem. O bot responde com um card-resumo da classificação e botões de correção — cada correção é gravada e reinjetada como few-shot.

Migração & backfill (Fase 11). O schema evolui sozinho ao subir o bot (migração leve, idempotente — adiciona a coluna mood e a tabela entry_themes). Para preencher temas/mood nas entradas antigas (e canonicalizar slugs de projeto), rode uma vez:

python -m organizer.backfill_themes

É idempotente: reclassifica só quem ainda não tem tema.

#🗂️ Export para o Obsidian

/export (ou python -m organizer.export) gera, de forma idempotente e sem custo de API, um vault num híbrido PARA + Zettelkasten + LYT/MOCs — pensado para poucos links, todos com significado:

Home.md                        # MOC-raiz (LYT): liga todas as seções
Themes/<slug>.md               # 🎨 área da vida — eixo primário e cor do graph
Habits/<nome>.md               # 🏃 hábito como nó (corrida, leitura, academia…)
Projects/<slug>.md             # PARA · trabalho acionável por projeto
Areas/Tarefas.md · Agenda.md   # PARA · tarefas abertas e eventos
Areas/People/<nome>.md         # PARA · MOC por pessoa
Resources/Ideias · Notas · Acontecimentos · Reviews.md   # PARA · conhecimento, acontecimentos e reviews
Archive/Concluidas.md          # PARA · tarefas concluídas
Journal/YYYY-MM-DD.md          # log cronológico do dia
Slipbox/<id>-<slug>.md         # Zettelkasten: 1 nota atômica por entrada

Cada nota atômica tem frontmatter YAML (id, tipo, status, prazo, prioridade, projeto, temas, mood, pessoas, tags) e, no corpo, só links com significado: o up-link primário é o Tema (hub colorido no graph), seguido do MOC-lar de tipo, do projeto, das pessoas, dos hábitos e das conexões aceitas. O vault fica fora do git — nenhum dado pessoal vai para o repositório.

#🎨 Legenda de cores do graph

O exportador faz merge automático de colorGroups no .obsidian/graph.json (preserva suas outras configurações de layout). Regra: no Obsidian o primeiro match vence, então os temas vêm antes — as notas ficam coloridas pela área da vida, e as MOCs genéricas recuam em cinza.

📸 (screenshot do Graph View aqui)

#🧠 Decisões de IA

• Haiku para o barato e frequente (classificar, buscar, editar); Sonnet para o analítico (review semanal, RAG) — equilíbrio custo × qualidade.
• Anti-alucinação em todos os prompts: campos não inferíveis ficam null; respostas do RAG e do review são ancoradas nos dados e citam a fonte.
• Structured output (pydantic) para classificação, busca e edição — parsing confiável e testável.
• Embeddings locais: privacidade e custo zero na memória semântica; a API só entra quando agrega valor.

#🧪 Testes

pytest

99 testes cobrindo repositório, parsers dos modelos (LLM mockado, sem rede), consultas, export (temas, cores do graph, hábitos como nós), edição, remoção, hábitos, RAG e calibração.

#🛣️ Roadmap — 100% concluído

#🔭 Próximos passos (ideias)

🎙️ entrada por áudio/foto (Whisper / visão) · 🏗️ CI (GitHub Actions + ruff) · 📊 gráficos no review · 🐘 migração para Postgres + Alembic · 💬 memória de conversa no /perguntar.

Feito como projeto de portfólio · foco em IA aplicada e backend.
_{Licença: a definir (sugestão: MIT).}