Buscar documentação de uma URL

Quando uma tecnologia não tem código para você apontar — uma prática, por exemplo, ou uma ferramenta cujo conhecimento útil está na documentação —, você entrega ao pipeline de conhecimento uma lista de URLs no lugar do código. A busca transforma cada página ou vídeo em um arquivo markdown limpo, que os comandos de identificação e o rascunho da tecnologia conseguem ler.

Esta página cobre escrever a lista de URLs, rodar a busca e ler o que ela deixa para trás. Este é o caminho reserva. Quando você tem um projeto no disco, uma árvore de código-fonte é a entrada melhor — veja Ingerir uma árvore de código-fonte.

Antes de começar

Uma sessão do pi em um diretório de trabalho seu, com o Fito instalado nele. Veja Preparar um diretório de trabalho.
Um provedor de LLM configurado no pi. Quem faz a busca é a sua sessão, que escreve e roda um pequeno script Python para isso.
Um python3 capaz de criar um ambiente virtual (python3 -m venv). A busca instala os pacotes Python dela ali, e não no seu sistema.
Acesso de rede a cada URL da lista.

Você não precisa estar logado no Fito. A busca nunca fala com o servidor do Fito.

Escrever a lista de URLs

Coloque uma URL por linha em um arquivo de texto. Linhas em branco são puladas, uma linha que começa com # é um comentário, e uma URL que aparece duas vezes é buscada uma vez só.

# Picocli
https://picocli.info/quick-guide.html
https://github.com/remkop/picocli#readme

Dois tipos de URL são diferenciados:

Um vídeo do YouTube — um link youtube.com/watch, youtu.be/ ou youtube.com/shorts/. A transcrição dele é buscada.
Todo o resto — buscado como página web.

Buscar a lista

Salve a lista no seu diretório de trabalho. O nome padrão é urls.txt.
Na sua sessão do pi, rode:
```
/fito-fetch-urls-content urls.txt
```
Troque urls.txt pelo caminho da sua lista. Sem argumento, o comando procura um urls.txt no diretório de trabalho. O comando não aceita flags: o caminho da lista é o único argumento.
Leia o resumo com que ele termina: quantas URLs deram certo, quantas falharam, e o erro de cada falha.

Você também pode buscar como a primeira parte de outro comando. Tanto os comandos de identificação quanto o /fito-create-or-update-technology aceitam --fetch, com a lista indicada por --urls:

/fito-identify-domain-concepts Picocli --technology picocli --technology-version 4 --fetch --urls urls.txt

O --urls tem urls.txt como padrão. Passe o arquivo com --urls, e não como valor do --fetch. O comando de identificação também precisa da tecnologia já provisionada — aqui, picocli@4. Veja Provisionar uma tecnologia.

Confirme que deu certo: um arquivo markdown por URL resolvida fica em ./output/1-ingest/extracted_links_content/. Toda URL que não gerou arquivo aparece em _errors.md, na mesma pasta, com o motivo.

O que cada arquivo guarda

Cada arquivo leva o nome do título da página, em minúsculas e separado por hifens, e abre com um bloco de frontmatter:

Campo	O que guarda
`source_url`	A URL de origem
`title`	O título da página ou do vídeo
`type`	`webpage` ou `youtube`
`fetched_at`	Quando foi buscado, em ISO 8601
`author`	O autor, quando a página nomeia um
`summary`	Um resumo do conteúdo nas palavras da sua própria sessão, com no máximo 50 palavras

O corpo é o texto principal da página em markdown: títulos, links no texto, listas, citações e blocos de código. Navegação, rodapés, barras laterais, anúncios, avisos de cookies, botões sociais e blocos de cadastro são removidos. Uma transcrição é quebrada em parágrafos, sem as linhas repetidas das legendas automáticas.

Uma transcrição fica no idioma que tiver. Ela não é traduzida, e nenhuma nota é acrescentada sobre o idioma ou a origem dela.

Como a busca se comporta

Páginas web passam por uma biblioteca de extração de conteúdo. Uma página que volta com 200 caracteres ou menos de conteúdo real — ou com muito menos do que o título promete — é tratada como renderizada por JavaScript. A busca tenta de novo através de um renderizador, e só analisa o HTML puro como último recurso.
Vídeos usam a transcrição publicada, preferindo legendas manuais às automáticas. Quando não há transcrição nenhuma, a busca recorre às legendas geradas automaticamente.
Cada requisição web expira depois de 15 segundos.

Ela não deixa rastro. O ambiente virtual, o script gerado e qualquer arquivo de legenda vivem em um diretório temporário fora do seu diretório de trabalho, e a execução remove esse diretório no fim — depois de uma falha, tanto quanto depois de um sucesso. A única coisa que a execução acrescenta ao seu diretório de trabalho são os documentos que ela escreve. O que já estava ali, incluindo outras etapas dentro de output/ e a sua lista de URLs, fica intocado.

Ler os documentos

Os comandos de identificação leem a pasta da busca por padrão: a flag --docs deles tem ./output/1-ingest/extracted_links_content/ como padrão. Então, depois de uma busca, rode um comando de identificação sem --source e sem --fetch:

/fito-identify-domain-concepts Picocli --technology picocli --technology-version 4

O /fito-create-or-update-technology lê a mesma pasta por padrão, então uma busca pode fundamentar tanto as descrições da tecnologia quanto os componentes dela.

Quando uma URL falha

Uma URL que não gera arquivo vai para o _errors.md com o motivo, e a busca passa para a próxima. Uma URL ruim nunca interrompe a execução.

Uma transcrição em outro idioma não é falha, e uma página cuja extração precisou do plano B também não é. Só uma URL que terminou sem arquivo é registrada.

Quando uma URL falhar, abra-a em um navegador antes de buscar de novo.

O que vem a seguir

Identificar componentes de conhecimento — transforme os documentos buscados em candidatos.
Ingerir uma árvore de código-fonte — a entrada preferida, quando existe um projeto.