Groundwork

---

Tienes un prototipo: tus documentos, un modelo, una salida útil. Lo que no tienes es el aparato que lo hace responsable de su despliegue: un paso previo de privacidad, una evaluación construida a partir de tus propios fallos y una puerta que impida que un ajuste silencioso del prompt despliegue un sistema que fabrica. Ese aparato normalmente requiere un ingeniero de ML. Groundwork lo estructura en su lugar.

Las unidades de Groundwork son patrones de despliegue, no productos — piensa en módulos de Terraform para despliegues de IA confiables. groundwork init <archetype> estructura el arnés completo para un patrón:

Arquetipo	El patrón	Estado
document-qa	documentos → recuperación → respuestas fundamentadas → revisión humana	✅ publicado
extraction	documentos → campos estructurados → validación de esquema → revisión humana	✅ publicado
síntesis de investigación	preguntas → evidencia → síntesis → revisión humana	planificado — consulta la hoja de ruta

Cada verificación es determinista: mismas entradas, mismo resultado, siempre — sin juez LLM y sin clave de API para las verificaciones en sí.

Inicio rápido — 60 segundos, sin clave 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

El mismo bucle para extracción estructurada:

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")

Esa compilación en rojo es el producto: una cifra fabricada, un campo adivinado o una abstención fallida se convierte en un fallo de CI, no en una queja de usuario.

¿Listo para tu propio sistema?

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

Cómo funciona

Tú editas	Groundwork ejecuta	La puerta impone
adapter.mjs — un archivo: answer() para QA de documentos, extract() para extracción	Paso previo de redacción (Redacta) — los identificadores se convierten en tokens etiquetados localmente, antes de enviar cualquier cosa	check --baseline congela una buena ejecución como base mínima
datasets/cases/*.json — casos de oro a partir de preguntas y documentos reales, etiquetados a mano	La evaluación del arquetipo (OpenGATE) — QA de documentos: hechos anclados · números trazables al contexto · abstención. Extracción: validez del esquema · precisión de campos frente al oro · sin campos fabricados	check --ci en la acción de GitHub estructurada falla cualquier PR por debajo de ella
groundwork.config.json — configuración de arquetipo, redacción, evaluación y puerta	Perfilado de costos — uso de tokens medido, ahorros en orden de apalancamiento (caché → lotes → recorte → enrutamiento)	Un humano aún revisa las salidas de alto riesgo — la puerta es un piso, no una certificación

Para extracción, una elección de esquema hace la mayor parte del trabajo de seguridad: la nulabilidad es el contrato de abstención. Un campo que el sistema debe encontrar siempre es no anulable; un campo que el documento puede no declarar es anulable, y el sistema devuelve null para él — desconocido → null, nunca adivinado. Un valor adivinado en un campo de oro nulo falla por nombre: FABRICATED field "date_of_birth": document does not state it.

Ejemplos

Ejemplo	Qué muestra	Ejecutar
demo/	QA de documentos: el bucle completo en un sistema local diminuto — y la puerta detectando la fabricación por nombre. Cero red.	npm run demo / npm run demo:break
demo-extraction/	Extracción estructurada: validación de esquema, precisión de campos y la puerta nombrando una fecha de nacimiento adivinada y un campo obligatorio omitido. Cero red.	npm run demo:extraction / npm run demo:extraction:break
examples/claude-doc-qa/	Un sistema real basado en Claude: prompting de respuesta solo desde documentos, caché de prompts, evaluaciones con clave, uso medido que alimenta groundwork cost — además de una API simulada para que todo el bucle funcione sin conexión en CI.	npm run example:mock (sin conexión) / npm run example:check (en vivo)
examples/claude-extraction/	Claude completando un esquema a partir de cartas de referencia ficticias: desconocido → null en el contrato del prompt, el esquema como prefijo en caché y la puerta detectando una fecha de nacimiento adivinada — además de una API simulada para CI sin conexión.	npm run example:extraction:mock (sin conexión) / npm run example:extraction:check (en 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

Dos formas de aprenderlo: docs/GETTING-STARTED.md es el recorrido de referencia (aproximadamente media hora), y el curso cubre el mismo terreno con lecciones basadas en hitos — incluida la prueba de sabotaje, donde rompes deliberadamente tu propio sistema para demostrar que la puerta lo detecta, y una lección sobre el arquetipo de extracción. El manual estructurado (GROUNDWORK.md) vive dentro de tu repositorio, donde tu equipo realmente lo leerá.

Uso desde Claude

Las mismas verificaciones se distribuyen como un servidor MCP (groundwork-mcp, stdio) para que Claude Code, Cowork o Claude Desktop puedan ejecutarlas conversacionalmente — check_readiness en un repositorio, check_answer_grounding en una sola respuesta, check_extraction en un solo registro (sin necesidad de repositorio), scaffold_harness, cost_summary:

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

También hay una habilidad de agente (skills/groundwork-readiness/) que enseña a un agente a ejecutar la puerta e informar resultados con honestidad — incluido negarse a presentar una marca verde como certificación de seguridad.

Lo que Groundwork no es

Groundwork es un piso sólido, no una garantía. Las verificaciones deterministas detectan los fallos que pueden detectarse de forma determinista; no pueden certificar que un sistema de IA sea seguro. Para salidas de alto riesgo — cualquier cosa que toque salud, dinero, estatus legal o seguridad — un humano debe revisar antes de que la salida llegue a la persona afectada. La extracción aumenta las apuestas silenciosamente: el registro alimenta decisiones, así que un campo incorrecto es una decisión incorrecta. El manual estructurado también lo dice, a propósito.

Proyecto

• Estado — dos arquetipos publicados (QA de documentos, extracción estructurada) de un total planificado de tres. Profundidad antes que amplitud: cada patrón se termina correctamente antes de comenzar el siguiente. Consulta la hoja de ruta.
• Contribuir — los informes de errores, los patrones de casos de oro y los ejemplos son especialmente bienvenidos: CONTRIBUTING.md.
• Lanzamientos — etiquetados en GitHub, versiones en npm, historial en CHANGELOG.md.
• Construido sobre — OpenGATE (evaluación) y Redacta (privacidad), ambos de código abierto.

Licencia

MIT. Todo lo que init estructura en tu repositorio es MIT-0 — tuyo, sin necesidad de atribución.