ITS-FINE

Framework orientado por intenção para fine-tuning de LLMs abertas, instalado dentro do projeto e operado por Codex ou Claude Code. O usuário descreve o que deseja, aponta os dados e escolhe local ou Colab. As skills conduzem preparação, treinamento, avaliação e entrega usando três motores: hf-peft para modelos gerativos (chat, texto), hf-encoder para decisões tipadas (categoria, sim ou não, nível, várias perguntas sobre cada texto, com probabilidade calibrada) e hf-tts para voz (texto para fala com a voz do usuário). RAG está fora do escopo.

Começar

Invoque /fine-start (ou $fine-start no Codex). /fine-help responde dúvidas e informa estado/próximos passos sem iniciar treinamento.

Fluxo: intenção → ambiente e dados preliminares → modelo/tokenização → calibração e baseline → objetivo congelado → receita aprovada → sondagem e treino supervisionados → avaliação → exportação e avaliação no consumidor → entrega. Rascunhos permitem preparar as pré-condições antes de publicar o objetivo. O usuário não precisa escrever código de treinamento.

Instalação

Requisitos: Node.js 18+ e Python 3.10+. O pacote se chama @sandeco/itsfine; o nome its-fine no NPM pertence a outro projeto, sem relação com este.

Dentro da pasta do projeto:

npx @sandeco/itsfine install

O bootstrap cria .its-fine/runtime-env para dependências do runtime e instala as 14 skills nos harness escolhidos. O verbo aceita install, init ou instalar, e --target escolhe outra pasta. Para atualizar uma instalação existente:

npx @sandeco/itsfine update

update reaproveita os harness e o usuário do manifesto, não pergunta nada, consulta a versão publicada no registro e, se a cópia em cache do npx for mais antiga, delega para a versão publicada. Políticas, estado, rodadas e arquivos editados pelo usuário são preservados. A partir de um arquivo local, use npm pack e depois npm exec --package ./sandeco-itsfine-<versão>.tgz -- itsfine install.

Harness suportados, os mesmos 14 do Reversa: claude-code, codex, cursor, gemini-cli, windsurf, antigravity, kiro, opencode, hermes, cline, roo-code, github-copilot, aider e amazon-q. No terminal a instalação mostra a lista marcável, já com os detectados no projeto; sem terminal, ou com --engines lista, não pergunta nada.

claude-code recebe .claude/skills e o hook em .claude/settings.json, kiro recebe .kiro/skills, e todos recebem .agents/skills. Cada harness escreve um bloco delimitado por <!-- its-fine:start --> no seu arquivo de entrada (CLAUDE.md, AGENTS.md, .cursorrules, GEMINI.md e assim por diante), preservando o resto do arquivo. Desmarcar um harness numa reinstalação remove as cópias e o bloco dele, desde que intactos.

O projeto recebe ainda .its-fine/README.md com a operação e os limites, e .its-fine/bin/verify.py, que confere hashes, links das skills, hook e CLI:

python .its-fine/bin/verify.py --root .

O nome do usuário vem do sistema; --user <nome> só é preciso para mudá-lo.

Para desenvolvimento: python scripts/install.py --target [--user nome] [--engines lista], com jsonschema 4.x disponível no interpretador. Reinstalação preserva políticas, estado e alterações do usuário; conflitos são recusados. Este repositório só constrói o ITS-FINE e não tem instalação própria: testes, certificação e ensaios rodam numa venv de desenvolvimento em .venv/ (python -m venv --system-site-packages .venv e as dependências do hf-peft mais jsonschema), e scripts/verify_installation.py instala numa pasta temporária para verificar.

O motor prepara sua própria venv com setup.py --install-torch, após autorização de download; o hf-encoder entra na mesma venv pelo seu setup.py e o hf-tts cria a sua em .its-fine/venvs/hf-tts/. O treino local roda em GPU NVIDIA (CUDA) ou em Mac com chip M (Metal, mps); itsfine/device.py escolhe o acelerador para os três motores. No Mac não há QLoRA nem Docker com GPU, e bf16 exige macOS 14. O caminho Mac foi testado com torch simulado; ainda não há sondagem registrada em hardware Apple. Ausência de driver compatível é diagnosticada; instalação não inicia treino.

Privacidade

A política .its-fine/policy.json é manual, exclusiva do usuário. Permissões ausentes são falsas; JSON/tipos inválidos recusam processamento.

| Permissão | Autoriza | |---|---| | allow_data_to_harness | Leitura de conteúdo pelo harness | | allow_external_generator + external_generator_endpoints | Geração em endpoints externos exatos | | allow_data_transfer + transfer_destinations | Transferência aos destinos exatos | | allow_process | Executor de processo, com reconhecimento explícito dos limites | | require_isolated_executor | Recusa processamento local no ambiente do harness |

As três permissões de dados são independentes. API autorizada pode gerar exemplos sem permitir leitura pelo harness. Redirecionamentos e proxies implícitos são bloqueados nos clientes de dados. Conteúdo, respostas e logs ficam privados; entrypoints de dados retornam somente campos agregados permitidos.

O hook do Claude cobre Read/Grep/Glob/Bash e edições configuradas. Codex não recebe esse hook. Nenhum hook impede todos os acessos de um harness com as mesmas permissões do sistema operacional. Garantia corporativa exige executor em conta/VM administrada separadamente e documentos inacessíveis à identidade do harness. O perfil require_isolated_executor recusa o caminho local; não provisiona nem certifica essa separação. Veja limites e implantação.

Motor incluído

| Script | Resultado | |---|---| | setup / hardware / estimate | Ambiente isolado, inventário e estimativas | | ingest | Extração, pares com suporte literal e journal transacional retomável | | entities | Cobertura lexical de entidades; não mede correção factual | | check | Tokenização, máscara de loss e comprimento | | metric | Validação adversarial de respostas aceitas e revisadas | | train | Sondagem/treino sob supervisor; checkpoint verificável e retomada | | evaluate | Baseline, comparação, texto contínuo, pacote e consumidor Ollama | | export | Mesclagem CPU, sanidade CPU, GGUF/Ollama e recibo | | colab / colab_server | Notebook, sessão em arquivo, jobs persistentes e retorno por hash |

Motor hf-encoder (decisão tipada)

| Script | Resultado | |---|---| | setup / estimate | Mesma venv do hf-peft; custo por estados vezes perguntas | | download / loader | Qualquer encoder do Hugging Face, baixado e conferido contra o Hub (lock com sha256); checkpoint de decisão ou encoder com cabeças novas | | ingest | Mapeamento declarativo para linhas tipadas e task.json | | check | Marcadores, truncamento, comprimentos e suporte por opção | | metric | Casos de resultado conhecido do avaliador e validação da política | | train | LoRA no encoder, cabeças treináveis, act_head congelada; checkpoint com recibo e retomada | | evaluate | Baseline calibrado contra candidato; log-loss, Brier, ECE, ponto de operação; pacote e servidor | | export | Pacote com pesos mesclados, calibrador, política e manifesto; sanidade em processo novo | | predict / serve | Consumidores em CPU: linha de comando e HTTP local (POST /v1/decide) |

Os dois motores usam nomes de script iguais e rodam em processos separados. O hf-encoder aceita qualquer encoder do Hugging Face com token de máscara: sobre um encoder comum as cabeças nascem novas; um checkpoint de decisão (formato do Laya) continua as cabeças já treinadas. catalogo.json traz sugestões, não lista fechada. download.py fixa a revisão num commit, confere cada arquivo contra o Hub e grava itsfine-download.json, que o motor confere antes de usar a pasta. scripts/certify_encoder.py parte sempre de um download novo e grava certification.json; verify_npm_package.py exige um encoder comum e um checkpoint de decisão com paridade contra a referência. Os dois motores rodam local ou no Colab. Atribuição do código de referência em framework/engines/hf-encoder/third_party/laya/.

Motor hf-tts (voz)

| Script | Resultado | |---|---| | setup / estimate | Venv própria (ambiente: proprio no engine.json); memória por modelo e duração de clipe, com opção de memória unificada do Mac | | ingest | Áudio ou vídeo (mp4, mov, mkv, webm: faixa de áudio extraída pelo PyAV); gravações longas transcritas pelo faster-whisper com marca por palavra e cortadas entre palavras; clipes com .txt conferidos | | check | Clipes legíveis, durações, minutos, clipe de referência, idioma da família | | metric | Régua calibrada só com áudio real: mesma voz, voz com tom deslocado, texto trocado | | train | LoRA genérico; porta de sanidade (perda do base abaixo de 80% do acaso); melhor época pela validação; checkpoint com recibo e retomada | | evaluate | Base clonando, candidato fundido e recarregado, ou pacote; similaridade_inteligivel | | export | Pacote com modelo fundido, familia.py, falar.py, reavaliado em processo novo | | escuta | Página local de escuta cega A/B, diagnóstico de naturalidade |

O núcleo não conhece arquitetura: cada família entra por um adaptador em familias/ (carregar, alvos de LoRA, preparar exemplo, perda, salvar, falar), declarado no engine.json. Famílias incluídas: Qwen3-TTS (LM sobre codec de 16 camadas, com o layout derivado da inferência do modelo, porque o script oficial de fine-tuning tem rótulos deslocados duas vezes) e CSM (nativo do transformers). Um teste garante que nenhum arquivo do núcleo cita família. Flow matching (F5-TTS) fica fora: pede outro laço de treino.

Contratos: artifact.schema.json tem versão 1 (gerativo; só ganha campos opcionais, artefatos antigos seguem válidos) e versão 2 (decisão tipada: quatro partições, task_hash, política, limites obrigatórios, calibração); encoder.schema.json valida task, linhas, mapeamento, receita, calibração, predição e pacote. Ambos gerados por _reversa_sdd/contracts/build_schema.py.

Continuação: a pedido do usuário, uma rodada nova parte do adapter aprovado de outra rodada (start_from na receita), com otimizador e passos do zero; não é retomada. engine-spec confere mãe aprovada, hash do adapter, modelo base e tarefa; dataset --base mantém validação, calibração e teste da mãe e só acrescenta dados ao treino; a avaliação reprova candidato abaixo da mãe no mesmo teste. Spec em _reversa_sdd/sdd/continuacao-spec.md.

A ingestão usa SQLite para retomada e índices; splits são processados em disco. Mudança de fonte/seed/modelo exige outro lote. PDFs são processados por página; documentos sem texto exigem OCR. Arquivos de texto/DOCX/HTML têm limite de 64 MiB de conteúdo por documento. Não há certificação de capacidade para milhões de PDFs.

Sobreposição lexical e entity_recall não comprovam fatos. accepted_match reconhece somente alternativas revisadas: paráfrases não cadastradas exigem revisão. A amostra humana/protocolo precisam ser adequados à intenção; loss menor, rank maior ou mais épocas não garantem incorporação de todo o acervo.

Local e Colab

Sondagem e treino usam engine-spec, approve e submit. Não há fallback direto sem supervisor. Docker usa imagem por digest, rede desabilitada e inputs explícitos; pesos/dependências precisam estar provisionados previamente. Processo requer política e autorização. Avaliação QLoRA usa carregamento 4 bits; GPU sem BF16 nativo usa FP16.

No Colab, o usuário executa o notebook e baixa conexao-itsfine.json. Informa apenas o caminho local do arquivo; nunca cola token no chat. O transporte verifica hashes, registra submissão e preserva jobs após reinício do servidor. Cancelamento e prazo são supervisionados. Perda da VM continua podendo perder seu disco.

Exportação só é aprovada após avaliação no consumidor e quantização entregues. Sanidade do merged não comprova qualidade do Ollama quantizado.

Validação e manutenção

python -m unittest discover -s tests -v
python -m unittest discover -s _reversa_sdd/contracts/tests -v
node --test _reversa_bugs/politica-arquivos/policy.test.mjs
npm test
python scripts/verify_installation.py

Os testes desta revisão usam dados sintéticos, CPU e servidor HTTP em loopback. Não substituem treinamento em GPU, sessão real do Colab nem ensaio corporativo de isolamento. Correções e evidências.

Versão

Regra fixa: só o último número muda. A série começa em 0.0.1 e segue 0.0.2, 0.0.3, sem exceção. package.json é a fonte da versão, e scripts/bump_version.py propaga para pyproject.toml, itsfine/init.py, engine.json e as skills:

python scripts/bump_version.py

O script recusa qualquer mudança no primeiro ou no segundo número.

Fonte das skills: scripts/build_skills.py; gere e reinstale após editar. Motores canônicos: framework/engines/hf-peft, framework/engines/hf-encoder e framework/engines/hf-tts. Runtime: itsfine. As cópias em .its-fine, .agents e .claude são gerenciadas pelo manifesto, que registra os harness em engines e os motores em training_engines. Teste de atualização real de uma instalação 0.0.5: tests/test_upgrade_005.py.