MDRecord

Seu cérebro externo para reuniões. Grava o áudio do sistema e do microfone em trilhas separadas, transcreve, resume com LLM e salva tudo como notas Markdown pesquisáveis — local, offline e seu.

Gravou a reunião → semanas depois você digita "o que decidimos sobre o deploy?" e a nota certa aparece. É esse o produto.

---

Por que este repositório tem benchmark

A parte difícil de uma "memória pessoal" não é gravar — é reencontrar. Por isso o coração do MDRecord é o ranker de busca, e por isso ele é medido de verdade, não no olho.

Este repositório traz um benchmark de information retrieval reproduzível e com conjunto de teste separado (held-out): um corpus rotulado de notas em PT-BR, queries com julgamento de relevância, e métricas padrão (nDCG, MRR, Precision, Recall) para cada camada do motor de busca. Os pesos do ranker foram otimizados contra o split de desenvolvimento e reportados no split de teste — ninguém afina e reporta no mesmo conjunto.

No conjunto de teste (held-out) — 21 queries, 48 notas:

• Híbrido nDCG@10 = 0.747, contra 0.606 do FTS ingênuo (fts_raw) → +23% relativo.
• MRR = 0.703 · P@1 = 0.619 · Recall@10 = 0.921.
• Latência mediana 57.8 ms por busca (caminho real do app).

Reproduza em 2 comandos (sem chave de API, 100% offline):

pip install -e ".[dev]"
python benchmarks/run_benchmark.py --split test

Detalhes de metodologia, ablação por camada e otimização de pesos: BENCHMARKS.md.

---

Recursos

• 🎙️ Trilhas separadas — áudio do sistema e microfone capturados isoladamente (FFmpeg WASAPI/dshow).
• 📝 Transcrição + resumo — STT (ElevenLabs Scribe ou faster-whisper local) e resumo via LLM OpenAI-compatible.
• 🔎 Busca híbrida — FTS5 (bm25) + escore lexical (cobertura, cosseno, título, frase) com expansão de sinônimos, stemming PT-BR e tolerância a acento.
• 📅 Dashboard diário — timeline local das notas, em http://127.0.0.1:8765.
• 🩺 Saúde de gravação — detecta FFmpeg falho antes de processar.
• 📦 Executável Windows — empacotável com PyInstaller (scripts/build_exe.bat).

Instalação

git clone https://github.com/gbbragadev/mdrecord
cd mdrecord
pip install -e .            # núcleo
pip install -e ".[dev]"     # + pytest/ruff (rodar testes e benchmark)
pip install -e ".[local-stt]"  # opcional: faster-whisper local

Requer FFmpeg no PATH (ou em MDRECORD_FFMPEG).

Uso rápido

python -m mdrecord devices                 # listar dispositivos de áudio
python -m mdrecord desktop                 # widget de gravação
python -m mdrecord web                     # dashboard + busca em 127.0.0.1:8765
python -m mdrecord search "o que decidimos sobre audio"

Passo a passo completo: docs/como_usar.md.

Como a busca funciona

consulta → normaliza (sem acento) → expande (sinônimos + stemming)
        → FTS5/bm25  ┐
        → escore lexical (cobertura+cosseno+título+frase) ┘→ ranking híbrido

Os pesos dessa combinação ficam em RankingWeights (src/mdrecord/search.py) e são exatamente o que o benchmark otimiza.

Arquitetura

Visão geral em docs/architecture.md.

Desenvolvimento

pytest -q                                  # testes (inclui guard de regressão do ranker)
ruff check src benchmarks                  # lint
python benchmarks/optimize_weights.py      # re-otimiza pesos no split de dev

Licença

MIT — veja LICENSE.