qmd

# QMD - Query Markup Documents O QMD é um mecanismo de busca no dispositivo projetado para bases de conhecimento pessoais, documentação, notas de reuniões e qualquer conteúdo baseado em markdown. Ele executa inteiramente localmente, combinando busca de texto completo BM25, busca semântica vetorial e reclassificação baseada em LLM para entregar resultados de alta qualidade sem enviar dados a serviços externos. ## Principais Recursos - **Hybrid Search Pipeline**: Combina busca por similaridade vetorial e reclassificação por LLM com BM25 (FTS5). A expansão de consulta gera subconsultas tipadas (`lex` para palavras-chave, `vec` para vetores densos, `hyde` para embeddings hipotéticos de documentos) que são roteadas para os backends apropriados, fundidas via Reciprocal Rank Fusion (RRF) e reclassificadas por um LLM. - **Context Tree**: Adicione contexto hierárquico às coleções (ex.: `qmd://notes` → "Notas e ideias pessoais") que é retornado junto com os documentos correspondentes, ajudando LLMs a tomar melhores decisões contextuais. - **Local Models**: Usa modelos GGUF baixados do HuggingFace e armazenados em cache localmente. O modelo de embedding padrão é `embeddinggemma-300M-Q8_0` (~300MB). Modelos personalizados podem ser definidos pela variável de ambiente `QMD_EMBED_MODEL` (por exemplo, para corpora multilíngues). - **AST-Aware Chunking**: O chunking opcional baseado em tree-sitter para arquivos de código (TypeScript, JavaScript, Python, Go, Rust) produz blocos de maior qualidade; outros tipos de arquivo usam chunking baseado em regex. - **MCP Server**: Expõe um servidor Model Context Protocol com ferramentas para consultar, recuperar documentos, recuperação em lote e verificação de status. Suporta transportes stdio e HTTP com recursos de segurança (validação de origem/host para prevenir ataques de DNS rebinding). - **SDK**: Acesso programático via SDK TypeScript/JavaScript com métodos para busca, recuperação de documentos, gerenciamento de contexto e expansão de consulta. ## Início Rápido ```sh # Instalação global (Node ou Bun) npm install -g @tobilu/qmd # ou bun install -g @tobilu/qmd # Criar coleções qmd collection add ~/notes --name notes qmd collection add ~/Documents/meetings --name meetings # Adicionar contexto qmd context add qmd://notes "Notas e ideias pessoais" # Gerar embeddings qmd embed # Buscar qmd search "project timeline" # Busca rápida por palavras-chave qmd vsearch "how to deploy" # Busca semântica qmd query "quarterly planning process" # Híbrida + reclassificação (melhor qualidade) ``` ## Comandos da CLI - `qmd collection add <path> --name <name> [--mask <glob>]` — Adicionar uma coleção - `qmd collection show <name>` — Mostrar detalhes da coleção - `qmd collection include/exclude <name>` — Alternar inclusão da coleção - `qmd collection update-cmd <name> '<command>'` — Definir comando de atualização - `qmd embed [--chunk-strategy auto]` — Gerar embeddings vetoriais - `qmd search <query> [-c <collection>] [--json] [--files] [--min-score <n>]` — Busca por palavras-chave - `qmd vsearch <query>` — Busca semântica - `qmd query <query>` — Busca híbrida com reclassificação - `qmd get <path|docid>` — Recuperar um documento - `qmd multi-get <glob>` — Recuperar múltiplos documentos - `qmd mcp [--http] [--port <n>] [--host <addr>] [--daemon]` — Iniciar servidor MCP - `qmd status` — Mostrar saúde do índice e status do MCP ## Servidor MCP Ferramentas expostas: - `query` — Busca com subconsultas tipadas, fusão RRF e reclassificação opcional - `get` — Recupera documento por caminho, docid ou intervalo de linhas - `multi_get` — Recuperação em lote por glob, lista separada por vírgulas ou docids - `status` — Saúde do índice e informações da coleção O transporte HTTP (porta padrão 8181) fornece: - `POST /mcp` — MCP Streamable HTTP - `POST /query` (alias `/search`) — Busca estruturada sem protocolo MCP - `GET /health` — Verificação de disponibilidade Segurança: Requisições com cabeçalhos `Origin` não loopback são rejeitadas (403). A validação de `Host` previne DNS rebinding. As variáveis de ambiente `QMD_ALLOWED_ORIGINS` e `QMD_ALLOWED_HOSTS` podem estender as origens/hosts permitidos. ## Uso do SDK ```js const { QmdStore } = require('@tobilu/qmd') const store = new QmdStore({ dbPath: './qmd.db', collections: { notes: { path: '/path/to/notes' } } }) // Busca simples (autoexpandida) const results = await store.search({ query: 'authentication flow' }) // Consulta estruturada com subconsultas tipadas const results2 = await store.search({ queries: [ { type: 'vec', query: 'why do database connections time out under load' }, { type: 'lex', query: 'connection timeout' } ], collections: ['docs', 'notes'] }) // Desabilitar reclassificação para velocidade const fast = await store.search({ query: 'auth', rerank: false }) // Filtragem de metadados const published = await store.search({ query: 'typescript', filter: { key: 'topics', operator: 'all', value: ['typescript'] } }) // Acesso direto ao backend const bm25Results = await store.bm25Search('auth') const vectorResults = await store.vectorSearch('auth') // Expansão de consulta const expanded = await store.expandQuery('auth flow', { intent: 'user login' }) // Recuperação de documentos const doc = await store.get('docs/readme.md') const body = await store.getDocumentBody('docs/readme.md', { maxLines: 100 }) // Gerenciamento de contexto await store.addContext('docs', '/api', 'REST API reference documentation') await store.removeContext('docs', '/api') ``` ## Detalhes do Pipeline de Busca 1. **Expansão de Consulta**: consulta original (peso ×2) + 1 variação do LLM 2. **Recuperação Paralela**: cada consulta busca nos índices FTS e vetorial 3. **Bônus de Topo do Ranking**: documentos classificados em #1 em qualquer lista recebem +0.05, #2-3 recebem +0.02 4. **Seleção Top-K**: pegar os 30 melhores candidatos para reclassificação 5. **Reclassificação**: o LLM pontua cada documento (sim/não com confiança logprobs) Faixa de pontuação: 0.0–0.2 baixa relevância, valores maiores indicam melhores correspondências. ## Configuração de Modelos Modelos padrão: - Embedding: `embeddinggemma-300M-Q8_0` (~300MB) - Reclassificação: baseado em LLM (baixado sob demanda) Exemplo de modelo de embedding personalizado: ```sh export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf" ``` Observação: alterar os modelos de embedding exige re-embedding de todas as coleções, pois os vetores não são compatíveis entre si. ## Requisitos - Node.js ou runtime Bun - Armazenamento local suficiente para modelos e embeddings - Opcional: GPU/VRAM para inferência de LLM mais rápida (os modelos permanecem carregados na VRAM entre requisições) ## Licença Software de código aberto. Consulte o repositório para obter detalhes.