Como preencher as propriedades do frontmatter das notas do Obsidian com o Jev?

Fala aí, beleza? Se você já pediu pra uma IA "montar o frontmatter dessa nota" e recebeu de volta um YAML com aspas faltando, indentação torta e um campo inventado que não existe no seu vault, você conhece o problema

O bloco de propriedades do Obsidian é frágil por natureza: uma vírgula fora do lugar e a nota inteira fica com as propriedades inválidas

E aí entra uma abordagem diferente. O Jev é o primeiro modelo System One da TypeSafe, e ele não gera texto: ele devolve decisões tipadas com probabilidades calibradas, sem fase de geração de texto (docs.typesafe.ai)

Sacou onde isso casa? O frontmatter não é um texto, é um conjunto de campos tipados. Status é uma escolha dentro de uma lista. Área é uma escolha dentro de uma lista. "Precisa de revisão" é sim ou não

Ninguém precisa escrever YAML pra responder isso. Bora ver como fica na prática?

Por que pedir um YAML pronto ao modelo quebra a nota

Primeiro o PORQUÊ, como sempre

No Obsidian, as propriedades ficam num bloco YAML no topo do arquivo, delimitado por linhas com três traços, e esse bloco precisa começar na primeira linha da nota (documentação oficial)

Uma linha em branco antes do primeiro --- já é suficiente pra estragar tudo

E cada propriedade tem um tipo nativo: Text, List, Number, Checkbox, Date, Date & time e Tags. Se o modelo devolve uma string onde o seu vault espera uma lista, a propriedade até aparece, mas ela deixa de se comportar como você espera nas queries e nas views

Desde a versão 1.4.9 do desktop o Obsidian pelo menos te avisa: quando as propriedades do arquivo não podem ser interpretadas, ele destaca o ponto exato em que o YAML está inválido e a visão de Propriedades indica que as propriedades daquele arquivo estão inválidas

Ou seja: o editor melhorou em te mostrar o estrago, mas o estrago continua sendo seu pra limpar 😅

O problema real é geração de texto livre

Quando você pede YAML pra um LLM, ele está escrevendo caracteres, um atrás do outro. As chaves, os dois pontos, as aspas, a indentação, tudo é texto gerado

Qualquer desvio ali vira sintaxe quebrada

O Jev ataca isso por outro lado: ele não gera texto livre, não escreve código e não mantém conversa. Ele faz decisões estruturadas rápidas, enquanto um LLM continua cuidando de raciocínio aberto e de qualquer coisa que precise ser escrita em palavras (resumo do modelo)

Então a pergunta deixa de ser "escreva o frontmatter dessa nota"

E vira "dessas cinco opções de status, qual é a certa pra esse conteúdo?"

Quem monta o YAML é o seu código, com os valores que você já sabe que são válidos. O modelo só escolhe. E isso muda tudo

O que você precisa antes de começar

Lista curta:

• Uma conta na TypeSafe: o Jev não tem mais lista de espera, então qualquer pessoa pode se cadastrar em console.typesafe.ai e recebe US$ 5 de crédito grátis (cerca de 120 milhões de tokens)
• Uma chave de API, que vai no header Authorization: Bearer de cada requisição
• Obsidian com propriedades, ou seja, notas usando o bloco YAML no topo
• Um jeito de rodar código: pode ser um plugin seu, um script Node em cima da pasta do vault, o que preferir

E uma expectativa calibrada, que é o item mais importante da lista: o Jev não escreve a sua nota

Ele não vai resumir o conteúdo, não vai gerar um título bonito, não vai criar aquele campo de descrição em uma frase. Pra isso você continua precisando de um LLM

Se o que você quer é justamente a parte de escrever, tem um caminho diferente pra isso, e eu já falei sobre resumir, conectar e revisar notas com Claude Code aqui no blog

Aqui a gente está resolvendo outro problema: classificação

Passo a passo: preenchendo as propriedades campo a campo

1. Defina o esquema de propriedades e o tipo de cada uma

Antes de qualquer chamada de API, escreva no papel (ou num arquivo de config) quais propriedades a nota tem e qual o tipo nativo de cada uma no Obsidian

Exemplo de um esquema simples:

---
status: inbox        # Text, valores fixos
tipo: permanente     # Text, valores fixos
area: engenharia     # Text, valores fixos
maturidade: 3        # Number, 1 a 5
precisa_revisao: true # Checkbox
---

O erro comum deste passo: deixar o vocabulário aberto. Se "status" pode ser qualquer palavra que o modelo achar bonita, você volta pro problema de sempre e o vault vira uma coleção de sinônimos (em andamento, andamento, wip, WIP…)

2. Escolha a primitiva certa pra cada campo

O Jev tem três primitivas de pergunta: Choice, Score e Noul, e elas podem ser misturadas livremente na mesma requisição (documentação das primitivas)

• Choice escolhe uma opção dentro de um conjunto definido por você, e devolve a opção escolhida, a distribuição de probabilidade completa e um valor de confiança de 0 a 1
• Score posiciona o state numa escala ordenada de 2 a 10 níveis descritos por você, e devolve um valor ponderado por probabilidade, a distribuição por nível, a legenda e a confiança
• Noul responde uma pergunta de sim ou não e devolve a probabilidade de a resposta ser sim, de 0 a 1, sem campo de confiança separado

Se você conhece enum, escala Likert e boolean, é exatamente isso: cada campo do seu frontmatter é um desses três

O erro comum deste passo: usar Choice pra uma coisa que é claramente ordenada. "Quão madura está essa nota" com opções rascunho, meio pronta, pronta funciona, mas você joga fora a noção de ordem. Score existe pra isso

3. Monte o state com título e início do corpo

O endpoint recebe um state, que pode ser string, objeto ou array JSON. É o material que o modelo vai olhar pra decidir

Na prática, pra uma nota do Obsidian, o suficiente costuma ser o título do arquivo mais o começo do corpo:

const state = {
  titulo: file.basename,
  corpo: (await app.vault.cachedRead(file)).slice(0, 2000)
};

O erro comum deste passo: mandar a nota inteira sempre. Você paga por token de entrada, e nota longa nem sempre decide melhor que os primeiros parágrafos. Comece pequeno e só aumenta se a confiança estiver baixa

4. Monte o mapa de questions e mande tudo num único POST

Essa é a sacada que resolve o problema do YAML quebrado

Várias perguntas podem ir na mesma requisição: todas veem o mesmo state, são avaliadas em paralelo e de forma isolada, e cada resposta volta sob a chave (ID) que você escolheu

Então use como ID o nome exato da propriedade do frontmatter. Fica um mapeamento direto entre resposta e campo

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": {
      "titulo": "Migrando o build pro Vite",
      "corpo": "Anotações soltas da migração. Ainda falta testar o HMR..."
    },
    "questions": {
      "status": { ... },
      "tipo": { ... },
      "area": { ... },
      "maturidade": { ... },
      "precisa_revisao": { ... }
    }
  }'

O formato exato do corpo de cada primitiva (os nomes dos campos de opções, de níveis e da pergunta em si) você confere direto na documentação de primitivas

O que importa aqui na arquitetura é: um request, cinco decisões, cinco chaves de volta

O erro comum deste passo: fazer uma pergunta ampla demais, tipo "classifique essa nota". A própria documentação da TypeSafe descreve as perguntas System One como julgamentos rápidos e estreitos, e orienta decompor julgamentos complexos em várias perguntas estreitas, recombinadas no software. Uma pergunta por campo, sempre

5. Leia a resposta pelas chaves que você definiu

A resposta volta organizada pelos mesmos IDs. Cada Choice traz a opção escolhida, a distribuição de probabilidades e a confiança:

const data = await res.json();

const status = data.status.choice;
const confiancaStatus = data.status.confidence; // 0 a 1
const distribuicao = data.status.probabilities;

const maturidade = data.maturidade.score;
const precisaRevisao = data.precisa_revisao.noul > 0.5;

Repara numa coisa: confidence não é enfeite

É ela que vai decidir, no passo seguinte, se você grava sozinho ou se pergunta pro humano

O erro comum deste passo: tratar Noul como booleano direto. Noul devolve uma probabilidade de 0 a 1, e sem campo de confiança separado. Quem escolhe o corte é você

6. Grave no frontmatter com processFrontMatter

Aqui vem a parte que fecha o ciclo: a gravação automática, feita pela API do próprio Obsidian. NÃO edite o YAML na mão

A documentação de desenvolvedor do Obsidian recomenda usar FileManager.processFrontMatter em vez de extrair e editar o YAML por conta própria: o método lê, modifica e salva o frontmatter de forma atômica, e te entrega o frontmatter como objeto JS que você deve mutar diretamente

app.fileManager.processFrontMatter(file, (frontmatter) => {
  frontmatter['status'] = status;
  frontmatter['tipo'] = tipo;
  frontmatter['area'] = area;
  frontmatter['maturidade'] = maturidade;
  frontmatter['precisa_revisao'] = precisaRevisao;
});

Se liga no que aconteceu: em nenhum momento o modelo escreveu um caractere de YAML

Ele escolheu valores de listas que você definiu, e a API do Obsidian serializou. Não tem como quebrar a sintaxe porque ninguém gerou sintaxe

O erro comum deste passo: fazer regex no arquivo pra trocar o bloco entre os três traços. Funciona nos seus dez primeiros arquivos e destrói o décimo primeiro, aquele que tinha um --- no meio do corpo. Já vi gente se ferrar feio com isso

Exemplos de campos e a primitiva certa para cada um

Mapeamento prático pra você copiar:

Duas regras que valem pra todos eles

Primeira: sempre inclua uma opção de escape explícita. O Jev sempre retorna uma das opções que você forneceu na Choice, então se a sua taxonomia não cobre todo input, a recomendação é ter um other ou none of the above na lista

Sem isso, a nota sobre a receita de bolo que você jogou no vault vai ser classificada como engenharia com cara de quem sabe o que está fazendo 😛

Segunda: decomponha. Não tente resolver status, tipo e área numa pergunta só com 60 combinações. Três perguntas estreitas na mesma requisição rodam em paralelo e são muito mais fáceis de auditar

E cuidado com o outro extremo: o limite é de 255 opções por Choice. Se o seu vault tem mais tags que isso, você não manda todas, manda as mais usadas (e mantém a opção de escape)

Confiança e custo: quando gravar automático e quando só sugerir

Essa é a parte que separa um script útil de um script que bagunça 2000 notas de uma vez

A proposta é simples: use a confiança como porteiro

• Confiança alta: grava direto com processFrontMatter
• Confiança média: grava, mas marca a nota pra revisão (aquele precisa_revisao ali de cima serve pra isso também)
• Confiança baixa: não grava nada, só sugere na interface e deixa o humano clicar

E olha a distribuição de probabilidades, não só o vencedor. Um resultado com 0.51 contra 0.49 entre duas opções é tecnicamente uma escolha, mas é praticamente um cara ou coroa. A distribuição te mostra isso, a escolha sozinha esconde

E o custo?

O preço do Jev é cobrado só na entrada: US$ 0,042 por milhão de tokens de entrada, e os tokens de saída não são cobrados porque o modelo não tem fase de geração

A latência ponta a ponta informada pela TypeSafe fica entre 70 ms e 500 ms

Com os US$ 5 de crédito do cadastro você tem cerca de 120 milhões de tokens de entrada pra brincar, o que dá muita nota classificada antes de você precisar pensar em cartão

Um detalhe honesto: quanto custa em média uma chamada com um bloco de nota do Obsidian como state depende inteiramente do tamanho do seu state, então rode primeiro numa pasta pequena e meça com a sua própria realidade

E antes de sair classificando o vault inteiro, vale dar uma faxina: nota órfã e duplicata classificada continua sendo nota órfã e duplicata. Se esse for o seu caso, dá pra limpar links quebrados e duplicatas do vault antes de ligar o automático

Plugins que já fazem isso no Obsidian

Vale conhecer o que já existe, nem que seja pra roubar a arquitetura

Auto Tagger (Jev), plugin da comunidade, aplica ou sugere uma tag à nota aberta usando o Jev e as tags que já existem no vault. O funcionamento dele é quase um resumo deste post inteiro: ele lê o título e o início do corpo, junta as tags mais usadas e faz uma única pergunta Choice, com a opção literal None of these fit well na lista de candidatos

Você dispara pelo comando "Auto-tag current note" na paleta de comandos ou pelo ícone de tag na ribbon, e a notificação mostra a tag escolhida junto com a confiança do modelo

Versão 0.1.0, compatível com Obsidian 1.13.0+, desktop e mobile, licença MIT

Repara no padrão: título mais início do corpo como state, vocabulário tirado do próprio vault, opção de escape sempre presente, confiança exibida pro usuário. É exatamente o que a gente montou no passo a passo, só que pra um campo só

Jev Lens, mantido por JoseEchave, vai por outro caminho: ele avalia continuamente a nota em edição contra as "lenses" que você definiu, usando o Jev, e mostra um emoji de semáforo na aba da nota. A avaliação roda na troca de nota e a cada N segundos (padrão 120). O código está em github.com/JoseEchave/obsidian-jev-lens

É uma boa referência de como fazer avaliação em background sem travar a edição

E um aviso pra não te vender ilusão: eu não encontrei nenhum plugin publicado que preencha o frontmatter completo (status, tipo, área) com o Jev

O Auto Tagger cuida de tag. Pro resto do bloco de propriedades, por enquanto, é você e o endpoint

Obsidian e IA na prática

Pra começar do zero com IA rodando em cima do vault, esse vídeo aqui do canal mostra o Claude Code trabalhando junto com o Obsidian:

Conclusão

A ideia toda cabe em uma frase: pare de pedir YAML e comece a pedir valores

Frontmatter não é texto, é um conjunto de campos tipados. Quando você trata cada campo como uma pergunta separada (Choice pro que é enum, Score pro que é escala, Noul pro que é sim ou não), o modelo nunca toca na sintaxe, e a sintaxe nunca quebra

O resto é engenharia normal: um POST com o mapa de questions, leitura das chaves de volta, corte por confiança, e processFrontMatter pra gravar

Próximo passo, se quiser tirar do papel hoje: cria a conta, escolhe duas ou três propriedades do seu vault (status e área já bastam), monta o esquema com opção de escape e dispara uma única requisição em cima de uma nota só

Olha a confiança que voltou antes de automatizar qualquer coisa

Depois é só escalar pra pasta inteira 🙂

Até o próximo post!