Vectora

Vectora

Vectora é um assistente de IA self-hosted para equipes de desenvolvimento — roda inteiramente no seu servidor, com um workbench completo (arquivos, git, terminal, RAG, Context Graph, browser) compartilhado entre você e o agente, e vem com um chat web multi-usuário.

No seu núcleo, o Vectora resolve o problema do abismo de conhecimento: os LLMs não conhecem sua base de código, sua documentação ou as versões mais recentes da sua stack. O Vectora preenche essa lacuna por dois caminhos complementares: RAG híbrido (BM25 + vetores densos + reranker Cohere/VoyageAI) para recuperação por similaridade, e o Context Graph — um grafo de conhecimento nativo do workspace (funções, classes, conceitos e suas relações, via tree-sitter + extração semântica por LLM) para contexto estrutural.

---

Por que o Vectora?

• Motor nativo — o loop de execução (backend/engine/conversation_loop.py::run_conversation) é um while imperativo, não um grafo compilado. Isso dá HITL configurável por modo de permissão, backends de filesystem pluggable e um supervisor que delega para 2 subagentes especializados com instruções explícitas — sem hops de roteamento desnecessários.
• Pipeline RAG híbrido — cada recuperação roda BM25 + busca vetorial densa + reranker antes de voltar para o supervisor sintetizar a resposta.
• Context Graph nativo — analisa o workspace (AST via tree-sitter para Python/JS/TS/Go/Rust/Java/C/C++, + extração semântica por LLM) e gera um grafo de conhecimento com god nodes, comunidades e perguntas sugeridas. Configurável por tipo de arquivo (ex.: só markdown, deixando o código para o RAG).
• 70+ ferramentas nativas — filesystem, git (14 operações), GitHub (gh), terminal (PTY real), web, RAG, memória, integrações opcionais (Jira, Slack, Linear, Google Drive, Gmail, Notion) e utilitárias (hash, JWT, regex, HTTP) — sempre disponíveis, sem instalar plugins.
• Resiliência de provider — fallback automático de LLM por quota (429 troca de provider sozinho, com aviso visível) e de embeddings/rerank (Cohere↔VoyageAI). O model selector reflete o provider ativo.
• Embeddings curados — resultados da busca web passam por um gate de curadoria (reranker + LLM judge) antes de serem indexados. Sua base de conhecimento nunca é contaminada.
• Chat web multi-usuário — interface React 19 (Vite + TanStack Router) com autenticação, RBAC, workspaces e a workbench (terminal, git, arquivos, context graph, memória, planos — ver abaixo).
• Memória persistente entre sessões — memória isolada por usuário, com checkpoint nativo (SessionStore) por thread.
• Infraestrutura zero no modo lite — SQLite + LanceDB. Sem Docker ou Postgres para uso local ou times pequenos. O modo complete (Postgres + Qdrant + Redis) já existe como caminho alternativo para quem precisa de mais escala.
• Multi-LLM — Google Gemini, OpenAI, Anthropic, Cohere, ou Ollama (totalmente local). O model selector lista apenas os providers com API key configurada.

---

Arquitetura

Supervisor + Subagentes (motor nativo)

O agente principal (backend/services/agent_factory.py) roda sobre o motor nativo (backend/engine/conversation_loop.py::run_conversation) — um loop while imperativo, não um grafo compilado. O supervisor responde direto para consultas simples ou delega, via a tool nativa delegate_to_subagent, para um dos 2 subagentes especializados:

HITL (Human-in-the-Loop) roda via should_require_approval (backend/engine/hitl.py), configurável por modo de permissão (perguntar sempre / aceitar edições / autônomo / plano).

Pipeline de RAG (dentro das tools search/rag)

---

Workbench (painel lateral)

No modo Code, o chat vem com um painel lateral multi-aba — a workbench. Cada aba renderiza a partir de dados do backend em tempo real:

Os artefatos do Context Graph e o cache ficam em .vectora/context-graph/ dentro do workspace; o que estiver no .vectoraignore (ignore unificado, vale para context graph, RAG, filesystem e chat) é invisível para o Vectora.

---

Pré-requisitos

---

Início rápido (a partir do código fonte)

git clone https://github.com/vectora-ltda/vectora.git

cd vectora

Instalar dependências Python

uv sync

Copiar e preencher suas chaves de API

cp .env.example .env

Edite o .env: GOOGLE_API_KEY, COHERE_API_KEY, TAVILY_API_KEY

Instalar dependências do frontend (SPA Vite)

pnpm --dir frontend install

Terminal 1 — backend completo + SPA (porta 8080)

uv run vectora start --port 8080

Terminal 2 — frontend dev (Vite, porta 3000, faz proxy p/ a API)

pnpm --dir frontend dev

Abra http://localhost:3000. O primeiro usuário a se cadastrar vira administrador root.

CLI de operação (VPS via SSH)

O frontend cobre toda a configuração, mas em VPS via SSH a CLI Rich expõe o essencial:

uv run vectora config keys         # wizard de API keys + provider de LLM

uv run vectora config docker up # sobe Postgres + Redis + Qdrant local uv run vectora start --headless # backend sem Electron (modo servidor) uv run vectora web # HTTP + Electron/Chromium, sem bandeja Python

---

Build (SCons)

O sistema de build usa SCons, incluído como dependência de dev, invocado a partir da raiz do repositório. Funciona direto no PowerShell, cmd, bash ou zsh — sem dependência de sintaxe shell específica.

Produto final (do zero ao instalador)

scons release          Build completo + instalador nativo para o SO atual

Bump de versão, build dos instaladores e publicação no canal de update rodam só via GitHub Actions, disparados por uma tag v* real (criada quando o usuário mescla o PR de release acumulado que release-please.yml mantém automaticamente) ou por workflow_dispatch manual.

Pipeline executado em sequência (encadeado automaticamente por release):

build frontend (Vite)  -->  build híbrido do backend  -->  Electron + electron-builder

frontend/dist/ dist/vectora/vectora(.exe) frontend/dist-electron/

O "build híbrido" (build-hybrid.py, chamado pelo scons) compila só o pacote `backend/` em C via Nuitka --mode=package (gera backend.pyd) e depois usa PyInstaller para empacotar o launcher + backend.pyd + libs Python num único vectora.exe. Compilar só o backend (em vez de onefile puro) evita OOM ao compilar dependências gigantes (google.genai.types, LanceDB) para C. O pipeline de CI (GitHub Actions) ainda usa Nuitka onefile direto para as builds nativas de release — os dois caminhos convivem hoje.

Qualidade

scons tests            Suíte completa: pytest tests/ (unit+integration+e2e+stress) + vitest

scons coverage Mesma suíte com relatório de cobertura scons lint ruff + ty + bandit (Python) + tsc + oxlint (TypeScript) scons tests-storage Só testes de storage (Postgres/Redis/Qdrant — sobe docker automaticamente) scons clean Remove dist/ frontend/dist/ frontend/electron/dist* scons help Lista completa com descrições

Nota: no Windows basta abrir o PowerShell ou cmd na r