Como usar o Jev para dar tags automáticas às notas do seu vault do Obsidian?

Fala aí, beleza? Deixar um LLM taguear suas notas quase sempre acaba do mesmo jeito: em duas semanas o vault tem #produtividade, #produtividade-pessoal, #produtivity e #foco-pessoal apontando pra mesma coisa

O problema não é o modelo ser ruim, é a tarefa estar mal modelada: você pediu texto livre quando o que você queria era uma ESCOLHA

E aqui entra o Jev, um System One Model da TypeSafe: em vez de devolver uma string, ele devolve uma decisão tipada (uma escolha, um score, uma probabilidade)

Pra tagueamento isso muda o jogo, porque o conjunto de tags possíveis passa a ser fechado e definido por você, não sugerido pelo modelo

No Obsidian, o caminho mais curto pra isso hoje é via plugin de comunidade, e é o que a gente vai montar aqui, do zero até a tag escrita na nota

O que você precisa antes de começar

A lista é curta, mas o primeiro item é o mais importante de todos:

• Um vault com tags já em uso: a lista de candidatas nasce das SUAS tags. Vault zerado de tags não tem vocabulário pra oferecer ao modelo
• Uma chave de API da TypeSafe, criada no console em console.typesafe.ai/keys
• Noção de custo: o preço de lista do Jev é de US$ 0,042 por 1 milhão de tokens de input e US$ 0 por 1 milhão de tokens de output. O output é zero porque o modelo não gera texto, só a decisão

Uma coisa pra você já saber: o Jev está em early access, e a versão atual é a Jev 1.13

No campo model você pode usar o alias jev-latest, que aponta pro modelo de ponta da TypeSafe, ou fixar um ID versionado

E o ID versionado dessa mesma 1.13 é jev-1.13.0: é a mesma versão, só escrita no formato que a API espera

Se você prefere reprodutibilidade (e em pipeline eu prefiro), fixar a versão é a escolha mais conservadora

Como usar o Jev para dar tags automáticas às notas do seu vault do Obsidian

Vamos com o plugin Auto Tagger (Jev), que é bem direto ao ponto: ele lê a nota atual, pega as tags mais usadas do seu vault e faz ao Jev UMA pergunta do tipo Choice, algo como "qual dessas tags combina melhor com esta nota?"

Uma nota, uma requisição, uma decisão

1. Instale o plugin pelo diretório de plugins da comunidade do Obsidian. Ele se chama Auto Tagger (Jev), o ID é auto-tagger-jev e a listagem oficial fica em community.obsidian.md/plugins/auto-tagger-jev. A versão mais recente publicada é a 0.1.0

O erro comum deste passo: procurar um plugin "oficial da TypeSafe". Não é oficial, é plugin de comunidade, mantido no repositório parthsidpara/obsidian-auto-tagger-jev

2. Cole a chave de API da TypeSafe nas configurações do plugin. A chave é a que você criou em console.typesafe.ai/keys

O erro comum deste passo: achar que a chave vai pra algum servidor do plugin. Ela fica armazenada localmente, no arquivo de dados do plugin dentro do próprio vault, e é usada apenas como credencial bearer da requisição, sem ser logada. Ou seja: se você sincroniza o vault, lembre que a chave viaja com ele 🙂

3. Ajuste a configuração "Tags to consider", que define quantas das suas tags mais usadas são enviadas como opções. A faixa é de 1 a 25, e o padrão é 15

O erro comum deste passo: deixar esse número baixo "pra economizar". Lista curta é a principal causa de tag errada, e eu explico o porquê na próxima seção

4. Ajuste "Note body characters", que define quantos caracteres do corpo da nota vão junto, contados a partir do início. O padrão é 2000

O erro comum deste passo: esquecer que é do INÍCIO da nota. Se a sua nota começa com um bloco de metadados, citação longa ou índice, o modelo vai ler isso e não o assunto de verdade

5. Abra a nota que você quer taguear e rode o comando Auto-tag current note na paleta de comandos. Se preferir mouse, tem o ícone de tag na ribbon

O erro comum deste passo: esperar que o plugin saia tagueando sozinho. Ele não faz nenhuma chamada de rede automática ou em background: só quando você aciona o comando ou o ícone

6. Leia a notificação. Depois de escolher, o plugin mostra a tag escolhida e a confiança do modelo naquela escolha. Essa confiança é a sua régua pra confiar ou revisar

7. Confira onde a tag foi escrita. Se a nota já tem frontmatter, a tag entra na lista tags dele. Se não tem frontmatter, o plugin acrescenta uma tag inline no formato #tag no fim da nota

O erro comum deste passo: rodar de novo esperando ver a tag duplicada e achar que quebrou. Tags que a nota já possui nunca são duplicadas pelo plugin

E se nenhuma tag serviu? Aí a resposta vem como None of these fit well, e nenhuma tag é aplicada

Isso não é bug, é o comportamento correto

Como montar a lista de tags candidatas (e por que o conjunto fechado importa)

Aqui está o coração da coisa

A primitiva Choice do Jev seleciona UMA opção dentro de um conjunto fixo que o desenvolvedor define de antemão. O modelo não tem a opção de inventar um rótulo novo, porque a lista de saídas possíveis já está fechada na requisição

É a diferença entre perguntar "que tag você daria pra essa nota?" e perguntar "qual dessas 18 tags?"

Agora o número que muda a cabeça de quem economiza opção: uma pergunta do tipo Choice aceita até 255 opções, e adicionar opção custa poucos tokens cada

Por isso a própria documentação da TypeSafe orienta a passar a lista COMPLETA de categorias em vez de uma lista curta

Na prática, dentro do Obsidian:

1. Levante seu vocabulário real de tags. Olhe o painel de tags do vault e veja quantas tags você de fato usa pra classificar assunto (não conte tags de status tipo #todo, que são outra dimensão)
2. Suba "Tags to consider" no Auto Tagger (Jev) até cobrir esse vocabulário, respeitando o teto de 25. Se você usa 20 tags de assunto e deixou em 15, cinco delas simplesmente não existem pro modelo
3. Se o seu vocabulário é maior que isso, faça curadoria em vez de sorteio. É exatamente aí que o outro plugin brilha: no Smart Tagger, a biblioteca de tags começa vazia, você sincroniza as tags já usadas no vault pra criar regras e depois liga ou desliga cada uma
4. Desligue as tags ambíguas. Duas tags que significam quase a mesma coisa dentro da mesma lista dividem a probabilidade entre si e derrubam a confiança da resposta

O erro comum da etapa toda é enviar cinco opções "pra gastar menos". Você economiza alguns tokens e paga com tag errada, o que custa muito mais caro em revisão manual

Essa mecânica de conjunto fechado não é exclusiva de tag, viu? É a mesma modelagem que aparece quando você usa o Jev pra qualificar leads dentro de um funil: categorias definidas antes, decisão tipada depois

Quando nenhuma tag serve: escolha forçada, opção de escape e confidence

Sintoma: o plugin aplicou uma tag claramente errada, ou aplicou uma tag plausível mas com confiança baixinha

Causa: conjunto fechado sem saída força o modelo a escolher. Se a resposta correta não está na lista, o modelo ainda vai distribuir probabilidade entre as opções que existem, e alguma delas vence

Tem um caso relatado que ilustra bem isso: com other disponível na lista, o Jev escolheu other. Com apenas três opções e nenhuma saída, escolheu uma delas com confiança 0,31

Repare que o modelo não mentiu, ele avisou. A confiança baixa É a mensagem

Solução, em duas camadas.

A primeira é garantir a opção de escape. A documentação da TypeSafe recomenda adicionar uma opção other ou none of the above sempre que a lista puder não cobrir todas as entradas, pra o modelo poder dizer que nenhuma das outras serve

No Auto Tagger (Jev) isso já vem de fábrica: a lista de candidatas inclui a opção literal None of these fit well, e se ela ganhar, nenhuma tag é aplicada na nota

A segunda camada é usar o confidence como filtro. Ele é um número de 0 a 1, calculado a partir de como as probabilidades estão distribuídas: distribuição concentrada em uma opção significa confiança alta, distribuição achatada entre várias significa confiança baixa

E é aí que entra o Smart Tagger, que tem um limiar de confiança configurável, ou seja, o score mínimo pra aplicação automática da tag. Abaixo do limiar, não aplica automático

Pra prevenir, então, o combo é esse: lista completa de tags, opção de escape sempre presente e limiar calibrado no seu vault

Quem trabalha com o Jev em outros contextos usa a mesma leitura de score, inclusive pra detectar jailbreak antes da resposta do modelo principal

Auto Tagger (Jev) x Smart Tagger: qual usar no seu vault

Os dois são plugins de comunidade e os dois usam o Jev embaixo. A diferença está em COMO montam a lista e em quanto controle te dão

Qual dos dois escolher

Veredito curto e honesto, olhando só o que está documentado em cada um

Se você quer o caminho mais direto (instalou, colou a chave, rodou o comando, ganhou uma tag por nota), o Auto Tagger (Jev) resolve com menos peças móveis, e ele está listado no diretório oficial de plugins da comunidade

Se o seu problema é vocabulário bagunçado e você quer decidir QUAIS tags entram na disputa, mais automação por limiar de confiança, o Smart Tagger é o que oferece essas alavancas

Vault pequeno e tags já organizadas: Auto Tagger. Vault grande com tag legada pra domar: Smart Tagger

E não tem nada de errado em instalar os dois e comparar a decisão numa mesma nota, já que nenhum dos dois faz chamada sem você pedir

Onde esse tipo de tagueamento compensa

Os cenários que casam bem com a mecânica de conjunto fechado:

• Inbox de notas rápidas sem frontmatter: você joga ideia solta o dia todo e passa o comando depois. Sem frontmatter, a tag entra como #tag inline no fim da nota, o que já é o suficiente pra ela aparecer nas buscas
• Backlog de notas antigas sem tag nenhuma: aquele bolo de arquivo de 2019 que nunca foi classificado. Aqui o ganho é grande porque o vocabulário de destino já existe e está estável
• Padronização em vault compartilhado: quando mais de uma pessoa escreve, o conjunto fechado é o que impede cada um de criar seu próprio sinônimo de tag
• Literature notes: nota de leitura costuma ter título descritivo e primeiros parágrafos sobre o tema, exatamente o que o plugin envia como contexto

E onde NÃO compensa, pra ser justo: quando o seu objetivo é DESCOBRIR categorias novas no material

Choice só escolhe dentro do que você forneceu. Ele é ótimo pra aplicar taxonomia, e não é a ferramenta pra inventar taxonomia

Pra esse trabalho de descoberta, um modelo generativo lendo o vault ainda faz mais sentido, e depois você fecha a lista e entrega pro Jev aplicar em escala

Sem plugin: chamando o Jev direto pela API

Se você quer um script próprio, taguear em lote fora do Obsidian ou plugar isso num pipeline que você já tem, dá pra falar direto com a API

1. Instale o SDK e exporte a chave:

pip install typesafe-sdk
export TYPESAFE_API_KEY="sua-chave-do-console"

2. Aponte pro endpoint de System One e escolha o modelo:

O endpoint é https://api.typesafe.ai/v1/systemone, e no campo model vai jev-latest ou um ID versionado como jev-1.13.0

3. Modele a requisição como um Choice, com o conteúdo da nota como state e as tags como opções. O esqueleto conceitual é este:

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer $TYPESAFE_API_KEY

model:  jev-latest          (ou jev-1.13.0)
state:  título da nota + primeiros caracteres do corpo

pergunta (Choice):
  "Qual destas tags descreve melhor esta nota?"
  opções: ["ia", "obsidian", "carreira", "financas", ..., "none of the above"]

resposta:
  choice         -> a opção escolhida
  probabilities  -> probabilidade de CADA opção
  confidence     -> 0 a 1 para a opção escolhida

O erro comum deste passo: ler só o choice e ignorar o resto. O probabilities é o que te mostra a segunda colocada, e é ouro pra debugar tag ambígua no seu vocabulário

4. Se for taguear em lote, aproveite o formato de state. O Jev ingere o state uma vez e avalia todas as perguntas contra ele em paralelo

Os orçamentos: 64k cobre o state mais todas as perguntas somadas, e 32k vale pro state mais a pergunta mais longa. Ou seja, nota gigante com lista de tags gigante precisa de conta antes de disparar

5. Nunca esqueça a opção de escape na lista, mesmo no script. É a diferença entre "nenhuma tag encaixou" e uma tag errada gravada em 400 notas de uma vez 😅

Pra quem quer começar pegando o jeito de usar IA que LÊ o seu material e devolve estrutura em cima dele, este vídeo do canal mostra uma skill que faz a IA ler o código e desenhar a arquitetura do projeto:

Conclusão

O ganho aqui não vem de pedir criatividade ao modelo, vem de tirar essa liberdade dele

Fecha o conjunto de tags, passa a lista completa (opção é barata, lembra?) e deixa SEMPRE uma saída pra quando nada encaixar

Com isso, tags automáticas no Obsidian com o Jev deixam de ser uma fábrica de sinônimos e viram aplicação de taxonomia, que é um problema muito mais fácil de auditar

No quesito controle, os dois plugins jogam limpo: a chave fica no arquivo de dados do plugin dentro do vault, usada só como bearer da requisição, e o Auto Tagger (Jev) não dispara nada em background, só sob comando

Próximo passo é simples: gera a chave em console.typesafe.ai/keys, instala um dos dois plugins, sobe o "Tags to consider" pro tamanho do seu vocabulário e testa em UMA nota do inbox antes de sair rodando em lote

Depois é só olhar o confidence e decidir se você confia ou revisa…

Até o próximo post!