Contrato CLI/JSON 0.2.0
patchinsight predict --text '...' --json usa BERT e exige um bundle local
ajustado. --backend heuristic seleciona explicitamente o baseline de regras.
Não existe fallback silencioso quando o modelo não carrega.
Entrada: string Unicode normalizada em NFC, espaços condensados, preservando maiúsculas e acentos. Vazio, controle não espacial e mais de 20.000 caracteres geram erro. O encoder limita a 192 tokens, incluindo tokens especiais.
Saída: um objeto JSON em stdout, validado por Pydantic. Erros de execução e entrada retornam código 2 e JSON em stderr; erros de argumentos usam o formato padrão do argparse em stderr. Logs das bibliotecas também podem ir para stderr.
| Campo | Significado |
|---|---|
components |
Exatamente os cinco rótulos; cada um com state e score |
state |
present, absent ou unknown |
score |
Sigmoid não calibrada por padrão; temperatura experimental opt-in; regra binária no baseline; null para desconhecido |
structures |
Zero ou mais de XYZ, STAR, Action–Result, Action–Technology, Action–Method |
task |
present se há objetivo/responsabilidade explícito, senão unknown |
technologies |
Nomes canônicos encontrados no léxico, sem extração de spans |
diagnostics |
Componentes ausentes/desconhecidos, task_unknown, unclassified, truncamento |
truncated / tokens |
Corte pelo tokenizer; tokens totais antes do corte; null no baseline |
versions |
schema_version, model_version, rules_version |
backend / score_kind |
Método efetivo e interpretação de seus valores |
Se houver truncamento, uma previsão negativa no prefixo fica unknown com
score null. Predições positivas referem-se ao trecho observado. A detecção
lexical de tecnologias e objetivo lê o texto normalizado completo; os
componentes semânticos do BERT leem o prefixo. Essa diferença pode limitar
a interpretação das combinações em entradas longas.
Regras, sempre exigindo componentes present:
| Estrutura | Componentes e auxiliares |
|---|---|
| XYZ | action + result + measurement + method |
| STAR | context + action + result + objetivo/responsabilidade explícito |
| Action–Result | action + result |
| Action–Technology | action + tecnologia do léxico |
| Action–Method | action + method |
Estas combinações verificam coocorrência, sem validar alinhamento causal,
ordem narrativa, qualidade ou adequação universal da estrutura. context
aproxima Situation; Task só é detectada por padrões explícitos como “meu
objetivo era” e “fui encarregado de”. A ausência desses padrões permanece
desconhecida. Não há score de qualidade ou ranking de pessoas. Na v0.2, a demo e o endpoint
HTTP são locais e restritos a loopback; não há API publicada.
O léxico usa limites de palavras, aliases como Postgres/K8s/sklearn e evita Java dentro de JavaScript. Uma menção lexical não prova uso da tecnologia pela pessoa; a estrutura Action–Technology é somente coocorrência.
Extensões da v0.2
versions.schema_version e rules_version são 0.2.0; model_version continua a
identificar o checkpoint efetivo, inclusive 0.1.0 para os pesos preservados.
score_kind aceita binary_rule, sigmoid_uncalibrated e
temperature_scaled_experimental. A política opt-in exige método BERT e hash de
manifest do mesmo bundle; sua identificação aparece em diagnostics.
Quando uma política de confiança válida encaminhar componente para revisão, state é unknown e score é null; nenhum match de estrutura pode usar unknown. A política fornecida nesta rodada não atingiu a meta de desenvolvimento e tem cutoff null, sem abstenção por confiança. Truncamento continua independente.
batch lê JSONL com text e id opcional; retorna envelope por linha com line,
id e prediction ou error. Código 1 indica erro por item; 2 erro global. O
carregamento ocorre uma vez e as previsões válidas são agrupadas. Limites,
timeout cooperativo e formato HTTP: v02.md.
A inferência em lote usa o mesmo contrato de componentes da inferência única. O timeout entre lotes não interrompe inferência ativa ou stdin bloqueado.