capstone-data-guard

Claude API를 보고서 작성 시스템에 붙일 때, 원문 근거 없이 데이터가 바뀌거나 꾸며지는 일을 막는 작은 TypeScript 라이브러리와 CLI입니다.

중요한 전제: 어떤 LLM도 “100% 절대 무오류”를 보장할 수는 없습니다. 대신 이 도구는 원문 파싱, SHA-256 해시, 근거 chunk, JSON Schema, exact quote 검증으로 검증되지 않은 결과가 보고서 시스템에 들어가지 못하게 만듭니다.

작동 방식

1. ingest: .md, .txt, .csv, .tsv, .json, .docx, .xlsx, .pdf 파일을 읽고 원본 해시와 근거 chunk가 담긴 manifest.json을 만듭니다.
2. ask: Claude API에 원문 chunk와 작업 지시를 보내고, 구조화된 JSON을 받습니다.
3. verify: 모든 비어있지 않은 값이 chunkId와 원문에 실제 존재하는 quote를 갖는지 로컬에서 검사합니다.
4. 검증 실패 시 exit code 2를 반환하므로, 보고서 생성 파이프라인에서 중단시킬 수 있습니다.

빠른 시작

git clone https://github.com/fakeminjun7321/capstone-data-guard.git
cd capstone-data-guard
npm install
npm run build

export ANTHROPIC_API_KEY="your_claude_api_key"

npx capstone-guard ingest ./capstone-files -o manifest.json
npx capstone-guard ask \
  -m manifest.json \
  -s examples/report-schema.json \
  -p examples/report-task.txt \
  -o result.json

npx capstone-guard verify result.json -m manifest.json -s examples/report-schema.json

내 보고서 시스템에 의존성으로 넣으려면:

npm install github:fakeminjun7321/capstone-data-guard

보고서 시스템에 넣기

import { createManifest, extractWithClaude } from "capstone-data-guard";

const manifest = await createManifest(["./capstone-files"]);

const extraction = await extractWithClaude({
  manifest,
  dataSchema: {
    type: "object",
    properties: {
      projectTitle: { type: ["string", "null"] },
      technologies: { type: "array", items: { type: "string" } }
    },
    required: ["projectTitle", "technologies"],
    additionalProperties: false
  },
  instruction: "Extract capstone report facts. Use only provided source chunks."
});

if (!extraction.verification.passed) {
  throw new Error("Source verification failed");
}

const reportData = extraction.result.data;

결과 형식

{
  "data": {
    "projectTitle": "Smart Campus Energy Monitor"
  },
  "evidence": [
    {
      "jsonPath": "$.projectTitle",
      "chunkId": "chk_...",
      "quote": "Smart Campus Energy Monitor"
    }
  ],
  "missing": [],
  "warnings": [],
  "verification": {
    "passed": true,
    "errors": []
  }
}

Claude API 메모

• 기본 모델은 claude-sonnet-4-6입니다. --model이나 CLAUDE_MODEL 패턴으로 바꿔서 래핑해도 됩니다.
• Claude API는 x-api-key, anthropic-version, content-type 헤더를 요구합니다.
• 이 도구는 Claude의 structured outputs를 사용해 JSON Schema 형태를 강제하고, 로컬 검증기로 한 번 더 확인합니다.
• 큰 파일은 요청 크기와 컨텍스트 제한 때문에 chunk 선택이 일어납니다. 중요한 추출 작업에서는 스키마와 task prompt를 구체적으로 작성하세요.

지원 파일

• 텍스트: .txt, .md
• 표: .csv, .tsv, .xlsx
• 구조 데이터: .json
• 문서: .docx, .pdf

스캔 PDF처럼 텍스트 레이어가 없는 파일은 OCR을 먼저 거쳐야 합니다.

Development

npm run typecheck
npm test
npm run build

License

MIT