Em um mundo onde assistentes de inteligência artificial se tornam cada vez mais presentes no desenvolvimento de software, a capacidade de realizar buscas eficientes e inteligentes em bases de código é fundamental. No entanto, encontrar o código certo não é uma tarefa trivial.
É preciso ir além da simples busca por palavras-chave, compreendendo o contexto semântico do que o desenvolvedor realmente procura. Como acompanhamos aqui no Brasil Vibe Coding, essa demanda por uma busca mais sofisticada levou ao desenvolvimento de soluções inovadoras.
O srclight é um servidor MCP de indexação profunda de código – ele fornece aos agentes de IA a compreensão do seu código (busca de símbolos, grafos de chamadas, git blame, busca semântica) em uma única instalação com
pip install.
Ao construir assistentes de codificação com IA, a busca deve operar de duas maneiras essenciais. Primeiramente, a busca por palavras-chave, para quando você já sabe o nome da função e precisa encontrá-la rapidamente. Em segundo lugar, a busca semântica, que permite localizar código que "lida com autenticação" sem conhecer o termo exato. Muitos sistemas escolhem apenas uma dessas abordagens, mas a solução ideal integra ambas.
A Complexidade da Busca de Código para IAs
Limitações da Busca por Palavras-chave Pura
O FTS5, um módulo de busca de texto completo do SQLite, é excelente para correspondências exatas. Contudo, o código-fonte possui diversas convenções de nomenclatura, como calculateTotalPrice, calculate_total_price ou CalculateTotalPrice.
Um único índice FTS5 padrão tem dificuldades em lidar com todas essas variações de forma eficaz. Além disso, muitas vezes o desenvolvedor não sabe o nome exato e precisa encontrar um conceito, como "código que valida entrada do usuário", o que escapa à busca puramente textual.
Desafios da Busca Semântica Pura
Os embeddings, representações vetoriais que capturam o significado semântico, são ótimos para entender o contexto. No entanto, eles apresentam desafios em cenários específicos.
Isso inclui a busca por nomes de símbolos exatos (buscar handleAuth deve encontrar handleAuth), correspondências de substrings (buscar parse deve encontrar parseJSON) e consultas curtas, pois embeddings geralmente exigem mais contexto. As convenções de nomenclatura também podem ser um problema para embeddings puros.
srclight: A Inovadora Solução Híbrida
A solução desenvolvida pelo srclight combina o melhor dos dois mundos, utilizando quatro índices distintos. Três deles são baseados em FTS5, cada um otimizado para um tipo específico de busca, e um índice de embeddings para a compreensão semântica.
1. Índice de Nomes de Símbolos
Este índice FTS5 utiliza um tokenizador unicode61 que divide os termos com base em mudanças de caixa e underscores. Por exemplo, calculateTotalPrice se torna calculate, Total, Price, e handle_user_auth se torna handle, user, auth.
calculateTotalPrice → calculate, Total, Price
handle_user_auth → handle, user, auth
Essa abordagem garante que convenções como CamelCase, snake_case e outras sejam tratadas de forma eficaz, aumentando a precisão da busca por nomes de funções e variáveis.
2. Índice de Conteúdo do Código-Fonte
Com um tokenizador de trigramas, este índice FTS5 indexa cada substring de três caracteres do código-fonte. Isso permite a captura eficiente de correspondências de substrings, mesmo dentro de palavras complexas, sendo crucial para buscas parciais.
3. Índice de Docstrings
Utilizando um algoritmo de stemming Porter, este índice FTS5 reduz as palavras às suas raízes (por exemplo, "running", "ran", "runner" se tornam "run"). Isso torna a busca em docstrings (documentação interna do código) muito mais útil e flexível, independentemente das variações morfológicas das palavras.
4. Embeddings Semânticos com Ollama
Para a busca baseada em significado, são empregados vetores semânticos gerados por Ollama. São utilizados modelos como qwen3-embedding (com 4096 dimensões) ou nomic-embed-text (com 768 dimensões), permitindo que a IA entenda o conceito por trás da consulta, não apenas as palavras-chave.
O Segredo da Eficiência: Reciprocal Rank Fusion (RRF)
A combinação dos resultados desses quatro índices é o verdadeiro diferencial. O sistema executa cada consulta contra todos os índices, obtém resultados ranqueados e, em seguida, mescla esses resultados usando a técnica Reciprocal Rank Fusion (RRF).
RRF_score(d) = Σ 1 / (k + rank(d))
Nesta fórmula, k é uma constante padrão, geralmente 60. Um resultado que aparece na posição 1 no FTS5 e na posição 2 nos embeddings receberá uma pontuação combinada de 0,0325. Isso contrasta com um resultado na posição 10 nos embeddings, que receberia apenas 0,0143. Isso significa que as correspondências exatas ainda podem se destacar, mesmo que os embeddings também encontrem o item, e vice-versa. Com o RRF, obtém-se o melhor dos dois mundos, garantindo relevância tanto textual quanto semântica.
Mais do que Apenas Busca: Outros Recursos Essenciais
Além da busca híbrida, o srclight oferece outras funcionalidades que o tornam uma ferramenta completa para assistentes de IA no desenvolvimento:
Cache de vetores GPU: Os embeddings são carregados na VRAM uma única vez (cerca de 300ms na primeira vez), e as consultas subsequentes são processadas em aproximadamente 3ms via CuPy, garantindo agilidade.
Indexação incremental: Apenas os símbolos modificados são reindexados, usando um hash de conteúdo para rastrear as mudanças. Isso otimiza o desempenho e o uso de recursos.
Inteligência Git: Permite consultas sobre "o que mudou recentemente?", integrando dados de git blame, identificando pontos quentes e trabalho em progresso não commitado.
Workspaces multi-repositório: Possibilita a união de dados de diversos repositórios usando o recurso SQLite ATTACH+UNION, o que é crucial para projetos grandes e distribuídos.
Por Que Não Apenas Elasticsearch?
Apesar de ferramentas como o Elasticsearch serem poderosas, a proposta do srclight é oferecer uma solução de fácil instalação e uso. A ideia é que tudo possa ser configurado com um único comando pip install, tornando-o acessível e rápido para desenvolvedores que buscam integrar recursos avançados de busca em seus fluxos de trabalho de IA.
pip <span class="nb">install </span>srclight
srclight index <span class="nt">--embed</span>...
Essa abordagem simplificada democratiza o acesso a uma busca de código de ponta, fundamental para a próxima geração de assistentes de programação inteligentes. Continue acompanhando o Brasil Vibe Coding para mais novidades sobre as inovações em IA e desenvolvimento!