Groundwork

---

Você tem um protótipo: seus documentos, um modelo, uma saída útil. O que você não tem é o aparato que o torna responsável por ser implantado — uma etapa prévia de privacidade, uma avaliação construída a partir de suas próprias falhas e um portão que impede que um pequeno ajuste de prompt implante um sistema que fabrica. Esse aparato geralmente exige um engenheiro de ML. O Groundwork o estrutura em seu lugar.

As unidades do Groundwork são padrões de implantação, não produtos — pense em módulos Terraform para implantações de IA confiáveis. groundwork init <archetype> estrutura o harness completo para um padrão:

Arquétipo	O padrão	Status
document-qa	documentos → recuperação → respostas fundamentadas → revisão humana	✅ implantado
extraction	documentos → campos estruturados → validação de esquema → revisão humana	✅ implantado
síntese de pesquisa	perguntas → evidências → síntese → revisão humana	planejado — veja o roteiro

Cada verificação é determinística: mesmas entradas, mesmo resultado, sempre — sem juiz de LLM e sem chave de API para as próprias verificações.

Início rápido — 60 segundos, sem chave de API

git clone https://github.com/nickjlamb/groundwork.git && cd groundwork
npm install && npm run build
npm run demo          # document QA: the whole loop passes, fully offline
npm run demo:break    # the system starts fabricating — watch the gate go red

✗ GROUNDING demo-savings: ungrounded number "14" — not in the provided context
✗ GROUNDING demo-unanswerable-appeals: unanswerable question — the answer did not abstain

O mesmo loop para extração estruturada:

npm run demo:extraction         # documents → fields, every check green
npm run demo:extraction:break   # a guessed date of birth, a dropped field — red, by name

✗ EXTRACTION demo-referral: SCHEMA: /referral_date must be string
✗ EXTRACTION demo-referral: FABRICATED field "date_of_birth": document does not state it (got "12 April 1988")

Esse build vermelho é o produto: uma figura fabricada, um campo adivinhado ou uma abstenção falha se torna uma falha de CI, não uma reclamação de usuário.

Pronto para o seu próprio sistema?

npm install -D @pharmatools/groundwork
npx groundwork init                # document QA
npx groundwork init extraction     # structured extraction

Como funciona

Você edita	O Groundwork executa	O portão impõe
adapter.mjs — um arquivo: answer() para QA de documentos, extract() para extração	Etapa prévia de redação (Redacta) — identificadores se tornam tokens rotulados localmente, antes de qualquer envio	check --baseline congela uma boa execução como piso
datasets/cases/*.json — casos de ouro a partir de perguntas e documentos reais, rotulados manualmente	A avaliação do arquétipo (OpenGATE) — QA de documentos: fatos ancorados · números rastreáveis ao contexto · abstenção. Extração: validade do esquema · precisão de campos vs. ouro · sem campos fabricados	check --ci na GitHub Action estruturada reprova qualquer PR abaixo dele
groundwork.config.json — configurações de arquétipo, redação, avaliação e portão	Perfil de custo — uso de tokens medido, economias em ordem de alavancagem (cache → lote → corte → roteamento)	Um humano ainda revisa saídas de alto risco — o portão é um piso, não uma certificação

Para extração, uma escolha de esquema faz a maior parte do trabalho de segurança: a nulabilidade é o contrato de abstenção. Um campo que o sistema deve sempre encontrar é não anulável; um campo que o documento pode não declarar é anulável, e o sistema retorna null para ele — desconhecido → null, nunca adivinhado. Um valor adivinhado em um campo de ouro nulo falha pelo nome: FABRICATED field "date_of_birth": document does not state it.

Exemplos

Exemplo	O que mostra	Executar
demo/	QA de documentos: o loop completo em um pequeno sistema local — e o portão capturando fabricação pelo nome. Zero rede.	npm run demo / npm run demo:break
demo-extraction/	Extração estruturada: validação de esquema, precisão de campos e o portão nomeando uma data de nascimento adivinhada e um campo obrigatório omitido. Zero rede.	npm run demo:extraction / npm run demo:extraction:break
examples/claude-doc-qa/	Um sistema real baseado em Claude: prompting somente a partir de documentos, cache de prompt, avaliações com chave, uso medido alimentando groundwork cost — além de uma API simulada para que todo o loop rode offline no CI.	npm run example:mock (offline) / npm run example:check (ao vivo)
examples/claude-extraction/	Claude preenchendo um esquema a partir de cartas de encaminhamento fictícias: desconhecido → null no contrato de prompt, o esquema como prefixo em cache e o portão capturando uma data de nascimento adivinhada — além de uma API simulada para CI offline.	npm run example:extraction:mock (offline) / npm run example:extraction:check (ao vivo)

Comandos

groundwork init [archetype]      scaffold the harness for a pattern (document-qa, extraction)
groundwork check                 redaction self-test + the archetype's eval
groundwork check --baseline      freeze this run as the regression floor
groundwork check --ci            exit non-zero on failure or regression vs baseline
groundwork cost                  measured token usage + savings, in leverage order

Duas maneiras de aprender: docs/GETTING-STARTED.md é o passo a passo de referência (cerca de meia hora), e o curso cobre o mesmo terreno com lições orientadas por marcos — incluindo o teste de sabotagem, onde você quebra deliberadamente seu próprio sistema para provar que o portão o captura, e uma lição sobre o arquétipo de extração. O playbook estruturado (GROUNDWORK.md) vive dentro do seu repositório, onde sua equipe realmente o lerá.

Uso a partir do Claude

As mesmas verificações são fornecidas como um servidor MCP (groundwork-mcp, stdio) para que Claude Code, Cowork ou Claude Desktop possam executá-las conversacionalmente — check_readiness em um repositório, check_answer_grounding em uma única resposta, check_extraction em um único registro (sem necessidade de repositório), scaffold_harness, cost_summary:

{ "mcpServers": { "groundwork": { "command": "npx", "args": ["-y", "@pharmatools/groundwork", "mcp"] } } }

Há também uma Agent Skill (skills/groundwork-readiness/) que ensina um agente a executar o portão e relatar resultados honestamente — incluindo recusar-se a apresentar uma marca de verificação verde como certificação de segurança.

O que o Groundwork não é

O Groundwork é um piso forte, não uma garantia. Verificações determinísticas capturam as falhas que podem ser capturadas deterministicamente; elas não podem certificar um sistema de IA como seguro. Para saídas de alto risco — qualquer coisa que toque saúde, dinheiro, situação legal ou segurança — um humano deve revisar antes que a saída alcance a pessoa afetada. A extração aumenta os riscos silenciosamente: o registro alimenta decisões, então um campo errado é uma decisão errada. O playbook estruturado também diz isso, de propósito.

Projeto

• Status — dois arquétipos implantados (QA de documentos, extração estruturada) de um total planejado de três. Profundidade antes de amplitude: cada padrão é finalizado adequadamente antes do próximo começar. Veja o roteiro.
• Contribuindo — relatórios de bugs, padrões de casos de ouro e exemplos são especialmente bem-vindos: CONTRIBUTING.md.
• Lançamentos — marcados no GitHub, versões no npm, histórico em CHANGELOG.md.
• Construído sobre — OpenGATE (avaliação) e Redacta (privacidade), ambos de código aberto.

Licença

MIT. Tudo o que init estrutura em seu repositório é MIT-0 — seu, sem necessidade de atribuição.