feat: Korean summary generation with fail-closed provider contract — closes #10, #4 - #21
Merged
Conversation
Implements the summary generation interface (#10) and the first Korean-first summary flow (#4). New @study-os/summary package: - SummaryProvider contract: study unit in, Korean summary card out (shortSummary, keyConcepts, confusionPoints, tonePreset) plus GenerationRun provenance (provider, model, prompt version, SHA-256 input hash, token usage) so every card stays attributable - AnthropicSummaryProvider: claude-opus-4-8 with adaptive thinking and structured outputs (JSON schema, additionalProperties: false); Korean grounding prompt that treats source material as untrusted data, never as instructions - Fail-closed everywhere: empty/too-short content, model-judged insufficient evidence (evidence_sufficient=false), refusal stop reason, truncation, malformed JSON, and out-of-bounds cards all throw — a fabricated summary is never returned - MockSummaryProvider: deterministic, offline, derived verbatim from the source; default when ANTHROPIC_API_KEY is absent so dev/CI never need network or a key - Tone presets: teacher / tutor / concise-exam API: POST /api/demo/summary demonstrates the flow end to end (400 on invalid input, 502 on generation failure). 15 new tests (provider contract, fail-closed paths via injected fake client, API route); 52 total. Closes #10 Closes #4 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Implements the summary generation interface (#10) and the first Korean-first summary flow (#4) as a new
@study-os/summarypackage + demo API route.Closes #10
Closes #4
Design
Contract (#10) —
SummaryProvider: study unit in → Korean summary card out (shortSummary,keyConcepts,confusionPoints,tonePreset) plusGenerationRunprovenance: provider, model, prompt version, SHA-256 hash of the exact grounded content, token usage. Every card stays attributable and reproducible — this is the same provenance shape the M2ErrorEpisodemodel (#2) will persist.Implementation (#4) — two providers behind the one contract:
AnthropicSummaryProvider:claude-opus-4-8, adaptive thinking, structured outputs (JSON schema,additionalProperties: false). The Korean grounding prompt wraps source material in<자료>tags and instructs the model to treat it as untrusted data, never instructions (per the repo's AI safety gates).MockSummaryProvider: deterministic, offline, derived verbatim from the source. Default whenANTHROPIC_API_KEYis absent — dev/CI never need a key or network.Fail-closed on every path (a fabricated summary is never returned):
SummaryValidationError(400 at the API)evidence_sufficient: falsein schema)stop_reason: refusal/max_tokensAPI:
POST /api/demo/summary— demonstrates the flow end to end; 400 invalid input, 502 generation failure.Verified
🤖 Generated with Claude Code