groundwork

---

プロトタイプはできています。ドキュメント、モデル、有用な出力もあります。しかし、責任を持って公開するための仕組みがありません。プライバシー保護の前処理、自分たちの失敗に基づく評価、そして目立たないプロンプトの変更によって、捏造するシステムがデプロイされるのを防ぐゲートです。通常、こうした仕組みを整えるには ML エンジニアが必要です。Groundwork がその仕組みを自動で組み立てます。

Groundwork の単位は製品ではなく、デプロイパターンです。信頼性の高い AI のデプロイに向けた Terraform モジュールのようなものです。groundwork init <archetype> で、パターンに必要なハーネス一式を組み立てられます。

アーキタイプ	パターン	ステータス
document-qa	ドキュメント → 検索 → 根拠に基づく回答 → 人によるレビュー	✅ 提供中
extraction	ドキュメント → 構造化フィールド → スキーマ検証 → 人によるレビュー	✅ 提供中
リサーチ統合	質問 → エビデンス → 統合 → 人によるレビュー	計画中 — ロードマップを参照

すべてのチェックは決定論的です。同じ入力には、毎回同じ結果が返されます。LLM による判定は不要で、チェック自体に API キーも必要ありません。

クイックスタート — 60 秒、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

構造化抽出でも、同じ手順で始められます。

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

ビルドが失敗することこそが、この製品の価値です。捏造された数値、推測されたフィールド、または棄却に失敗したケースを、ユーザーからの苦情ではなく CI の失敗として検出できます。

自分のシステムでも試してみませんか？

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

仕組み

編集するもの	Groundwork の実行内容	ゲートで適用されること
adapter.mjs — 1 つのファイルに、ドキュメント QA 用の answer() と抽出用の extract() を記述します	事前のレダクション（Redacta）— 識別子は、データが送信される前にローカルでラベル付きトークンに置き換えられます	check --baseline で良好な実行結果をベースラインとして固定します
datasets/cases/*.json — 実際の質問と実際のドキュメントから手作業でラベル付けしたゴールドケース	アーキタイプの評価（OpenGATE）— ドキュメント QA：根拠のある事実・数値とコンテキストの対応・回答の保留。抽出：スキーマの妥当性・ゴールドに対するフィールドの正確性・捏造されたフィールドがないこと	足場を作成する GitHub Action の check --ci が、基準を下回る PR をすべて失敗させます
groundwork.config.json — アーキタイプ、レダクション、評価、ゲートの設定	コストのプロファイリング — トークン使用量を測定し、効果が高い順に節約策を提示します（キャッシュ → バッチ処理 → トリミング → ルーティング）	重大な影響を伴う出力は、引き続き人間がレビューします。ゲートは最低基準であり、認証ではありません

抽出では、スキーマの選択が安全性の大部分を担います。null 許容性が回答保留の契約です。システムが必ず特定しなければならないフィールドは null 不許容にし、ドキュメントに記載されていない可能性があるフィールドは null 許容にします。その場合、システムは null を返します。不明なら null とし、決して推測しません。正解が null のフィールドで値を推測すると、フィールド名を示して失敗します。FABRICATED field "date_of_birth": document does not state it

例

例	内容	実行方法
demo/	ドキュメント QA：小規模なローカルシステムで一連の処理を実行し、ゲートが捏造をフィールド名で検出します。ネットワーク通信はありません。	npm run demo / npm run demo:break
demo-extraction/	構造化抽出：スキーマ検証、フィールドの正確性、推測した生年月日と欠落した必須フィールドをゲートが指摘する様子を示します。ネットワーク通信はありません。	npm run demo:extraction / npm run demo:extraction:break
examples/claude-doc-qa/	実際の Claude 対応システム：ドキュメント内の情報だけを使って回答するよう促すプロンプト、プロンプトキャッシュ、キーで制御する評価、groundwork cost に反映される使用量の測定を示します。CI で一連の処理をオフライン実行できるモック API も用意されています。	npm run example:mock（オフライン） / npm run example:check（ライブ）
examples/claude-extraction/	架空の紹介状から Claude がスキーマに沿って情報を抽出します。プロンプトの契約に「不明なら null」を含め、スキーマをキャッシュ対象のプレフィックスにし、ゲートが推測した生年月日を検出します。オフラインの CI 用にモック API も用意されています。	npm run example:extraction:mock（オフライン） / npm run example:extraction:check（ライブ）

コマンド

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

学習方法は 2 つあります。docs/GETTING-STARTED.md はリファレンス形式のチュートリアル（約 30 分）です。コース では、チェックポイント形式のレッスンで同じ内容を学べます。ゲートが問題を検出することを確かめるために、自分のシステムを意図的に壊すサボタージュテストや、抽出アーキタイプのレッスンも含まれています。足場とともに作成されるプレイブック（GROUNDWORK.md）はリポジトリ内に配置されるため、チームが実際に参照できます。

Claude からの利用

同じチェック機能は MCP サーバー（groundwork-mcp、stdio）としても提供されるため、Claude Code、Cowork、Claude Desktop から会話形式で実行できます。リポジトリに対する check_readiness、1 つの回答に対する check_answer_grounding、1 つのレコードに対する check_extraction（リポジトリ不要）、scaffold_harness、cost_summary を利用できます。

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

また、エージェントがゲートを実行して結果を正直に報告できるようにする Agent Skill（skills/groundwork-readiness/）もあります。安全性の認証であるかのように、緑色のチェック結果を提示することも拒否します。

Groundwork ではないもの

Groundwork は堅固な土台であり、安全を保証するものではありません。決定論的に検出できる失敗は決定論的なチェックで検出できますが、AI システムの安全性を証明することはできません。健康、お金、法的地位、安全に関わるものなど、重大な影響を及ぼす出力については、その影響を受ける人に届く前に人間が確認する必要があります。抽出では、リスクがいつの間にか高まります。記録は意思決定に使われるため、フィールドの誤りは意思決定の誤りにつながります。スキャフォールドされたプレイブックでも、意図的に同じことを伝えています。

プロジェクト

• ステータス — 予定されている 3 つのうち、2 つのアーキタイプ（ドキュメント QA、構造化抽出）をリリース済みです。幅より深さを重視し、次に進む前に各パターンを適切に仕上げます。ロードマップをご覧ください。
• コントリビューション — バグ報告、ゴールドケースのパターン、例を特に歓迎します：CONTRIBUTING.md。
• リリース — GitHubでタグ付けし、npmでバージョンを公開しています。履歴はCHANGELOG.mdをご覧ください。
• 基盤 — OpenGATE（評価）と Redacta（プライバシー）を基盤としており、どちらもオープンソースです。

ライセンス

MIT です。init があなたのリポジトリにスキャフォールドするものはすべて MIT-0 です。あなたのものであり、帰属表示は不要です。