Needle - Extensão do Chrome

Sobre

Needle é uma ferramenta de busca semântica em texto: em vez de procurar palavras exatas (como o Ctrl+F), o usuário descreve em linguagem natural o que procura e a ferramenta encontra os trechos relevantes, destacando a frase mais importante no próprio texto original.

• Formatos: extensão do Chrome (para páginas web) + app React (para texto colado)
• Motor: modelo typesafe-ai/jev (TypeSafe Jev), acessado via Vercel AI Gateway
• Repositório: awesome-llm-apps/advanced_llm_apps/needle
• Licença: Apache-2.0

O Jev não gera respostas — ele apenas seleciona e ranqueia frases existentes no texto-fonte. Não há "fallback" com matches inventados.

Funcionamento

1. A extensão extrai os trechos legíveis da página atual (ou o app usa o texto colado/selecionado)
2. Query + trechos são enviados ao backend local do Needle
3. O Jev pontua a relevância de cada trecho e escolhe a frase mais forte, em uma única requisição de avaliação
4. O Needle mapeia o resultado de volta no texto original

• Threshold de relevância: ≥ 0.58 (é um corte de ranking, não garante que todos os trechos relevantes foram encontrados)
• Destaque: verde forte = frase principal; verde claro = contexto ao redor

Principais Recursos

• Busca por significado (perguntas, ideias, detalhes lembrados pela metade)
• Navegação entre trechos encontrados sem sair da página
• Atalho Cmd+F (macOS) / Ctrl+F (demais) — reconfigurável em chrome://extensions/shortcuts
• App React com biblioteca de exemplos, Bring your own text, ranking e botão de copiar

Instalação e Uso

Pré-requisitos

• Node.js 22.12+ e npm
• Conta na Vercel AI Gateway com acesso ao typesafe-ai/jev e créditos
• AI_GATEWAY_API_KEY (chave OpenAI ou TypeSafe direta não serve)

Backend + app

git clone https://github.com/Shubhamsaboo/awesome-llm-apps.git
cd awesome-llm-apps/advanced_llm_apps/needle
npm ci
cp .env.example .env   # preencher AI_GATEWAY_API_KEY
npm run dev            # sobe UI + backend em http://127.0.0.1:4199

• Manter o terminal rodando enquanto usa a extensão
• .env só é lido na inicialização — reiniciar após alterações
• Servidor escuta apenas em loopback

Extensão

1. chrome://extensions → ativar Developer mode
2. Load unpacked → selecionar a pasta needle/extension/ (a que contém manifest.json)
3. Fixar o ícone; nas Options, definir server URL http://127.0.0.1:4199 (token em branco no setup local)
4. Abrir uma página comum e clicar no ícone ou usar o atalho

• Atualizar: puxar o código → Reload no card da extensão → recarregar a página
• ZIP: npm run package:extension gera o pacote; descompactar numa pasta fixa e usar Load unpacked

Configurações

Setting	Onde	Função
AI_GATEWAY_API_KEY	.env do backend / env vars da Vercel	Autentica e paga a inferência do Jev — nunca vai na extensão
NEEDLE_ACCESS_TOKEN	Backend + configurações da extensão	Protege o backend; obrigatório na Vercel
Needle server URL	Configurações da extensão	Backend local ou deploy HTTPS próprio

Nunca colocar a chave do Gateway na extensão, em variável VITE_, em screenshot ou em arquivo commitado.

Deploy opcional na Vercel

• Root Directory: advanced_llm_apps/needle, preset Vite
• Definir AI_GATEWAY_API_KEY e um NEEDLE_ACCESS_TOKEN aleatório:

node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"

• /api/health indica se a chave está configurada (não valida créditos)
• Sem autenticação por usuário, rate limit ou billing — adequado só para uso próprio ou grupo pequeno de confiança
• Incompatível com Vercel Deployment Protection

Estrutura do Projeto

needle/
|-- src/          App React, componentes e documentos de exemplo
|-- extension/    Extensão Chrome (manifest, settings, ícones)
|-- server/       Servidor local, requisições ao Jev, mapeamento de frases
|-- api/          Funções da Vercel
|-- public/       Assets e ZIP da extensão gerado
|-- scripts/      Empacotamento da extensão
|-- tests/        Testes de busca, frases, acesso e empacotamento
`-- .env.example

Comandos de desenvolvimento: npm test, npm run format:check, npm run build, npm run preview.

Casos de Uso

• Encontrar custos ocultos em páginas de preço (“custos além do preço anunciado”)
• Localizar cláusulas em políticas e termos (“o que acontece se eu cancelar?“)
• Explorar artigos e documentos longos colados no app

Limitações

• Privacidade: envia todos os trechos capturados + a query ao backend e à AI Gateway — usar só em páginas cujo conteúdo pode ser compartilhado
• A extensão só roda quando invocada; não coleta inputs/senhas, histórico, cookies ou screenshots
• Limites: 160 trechos / 60.000 caracteres, máx. 2.200 caracteres por trecho — páginas longas podem ser buscadas parcialmente
• Sem suporte: PDFs no visualizador do Chrome, páginas do sistema, Chrome Web Store, texto escaneado, iframes cross-origin e shadow DOM
  • Workaround para PDF: copiar o texto e usar Bring your own text
• Mudanças dinâmicas na página podem invalidar os resultados
• Custo: quem é dono da chave do Gateway paga as buscas

Troubleshooting

Sintoma	Ação
Cannot reach Needle	Rodar npm run dev e usar http://127.0.0.1:4199
Erro de chave/créditos	Verificar AI_GATEWAY_API_KEY, acesso ao modelo e créditos; reiniciar
Manifest não encontrado	Selecionar a pasta extension/ (descompactar o ZIP antes)
Alterações não aparecem	Reload em chrome://extensions e recarregar a página
Sem texto pesquisável	Usar uma página web comum

Referências

• Repositório - Needle (awesome-llm-apps)
• Vercel AI Gateway - Evaluation API
• Vercel AI Gateway Dashboard
• Chrome - Load unpacked extension
• Relacionado: GrepAI, Semantic Routing