refactor(sutta-studio): consolidate LLM caller (PR B / Phase 3)#63
Open
anantham wants to merge 1 commit into
Open
refactor(sutta-studio): consolidate LLM caller (PR B / Phase 3)#63anantham wants to merge 1 commit into
anantham wants to merge 1 commit into
Conversation
…ion (PR B / Phase 3) CONSOLIDATION.md and task tracking both marked Phase 3 complete after Phase 2 landed, but no services/sutta-studio/llm.ts ever existed and both legacy callers remained concrete and divergent. The 2026-05-16 doc audit (doc-audit skill, scoped to Sutta Studio) caught this and surfaced it as the only P0 finding. Same failure mode as the schema divergence that PR #62 fixed: phase marked complete based on partial scope rather than completed work. This PR actually closes Phase 3. What landed: - NEW services/sutta-studio/llm.ts: canonical caller, based on the richer suttaStudioLLM shape — exports CompilerLLMOptions / CompilerLLMResult types, passes providerPreferences through to chatJSON, and exposes both the rich callCompilerLLM (returns CompilerLLMResult) and a callCompilerLLMText helper. - services/suttaStudioLLM.ts: thin re-export shim. Phase 4 deletes it. - services/compiler/llm.ts: thin re-export shim that aliases callCompilerLLMText AS callCompilerLLM, preserving the legacy string-return contract for the 7 existing call sites in compiler/index.ts (lines 394, 490, 529, 571, 596, 646) and compiler/skeleton.ts (line 63) with zero call-site churn. Those consumers move to the rich signature when the orchestrator is ported (Phase 2d / PR D). - services/sutta-studio/passes/_defaultCaller.ts + passes/types.ts: imports updated to point at the canonical path instead of the (now-shim) suttaStudioLLM path. CONSOLIDATION.md status header rewritten with a per-phase table reflecting merged reality (Phases 0, 1, 2a, 2b, 2c, 3 done; 2d + 4 pending). Tests: 1718 passed / 83 skipped / 0 failed (vitest, full suite). Net diff: +78 / -320 (262 lines of duplication removed). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
3 tasks
anantham
added a commit
that referenced
this pull request
May 17, 2026
* docs(sutta-studio): close 2026-05-16 audit P1 findings The doc-audit skill scan of the Sutta Studio subsystem (2026-05-16, code hash 11e7bb2) surfaced one P0 (Phase 3 caller divergence — closed by PR #63) and 9 P1 findings. This PR closes 5 of those P1s. The remaining 4 are either already addressed inline by PR #63's CONSOLIDATION.md status rewrite or are larger structural follow-ups not appropriate to bundle here. Fixes in this PR: - GROUNDING.md §"File layout": corrected filenames to match reality — commentarialProvider → commentarialGlossProvider, translatorBankProvider → translatorBank, removed nonexistent urlMinter.ts (URL minting is inlined in services/providers/citationHelpers.ts), added types.ts entry, noted that translator-bank wires in separately, not via buildDefaultProviders. - IR.md: replaced soft "staleness warning" with stronger SUPERSEDED banner. The 2026-03-05 verification date is 2.5 months stale; in the interim SUTTA-008 ratified Sense.epistemicBasis / sourceCitationIds / Provenance / ParallelRef / CompoundType and the grounding pass landed. New banner directs readers to types/suttaStudio.ts, FEATURES.md, SUTTA-008, TEXT_GRAPH.md rather than relying on the MVP schema as documentation. - CONSOLIDATION.md §"What does NOT change": added Grounding step to the pass order. Earlier formulation omitted it because Grounding was inserted into the live compiler in 2026-05-14 (task #47), after CONSOLIDATION.md was originally drafted. - SUTTA-007 ADR: added an Amendment section per CONVENTIONS.md §9. The original "should not be merged" claim was reversed by CONSOLIDATION.md, which merged the two stacks because operational experience showed silent drift at schema-contract and prompt-content boundaries. ADR is immutable, so the original text is preserved and the amendment explains the reversal + current state (both files are now shims). - FEATURES.md §"Compiler Service" + §"Key Files Reference": rewrote to reflect the post-decomposition tree. The old §Compiler Service named a 1900-line file that's been a 3-line shim since March 2026; the §Key Files table omitted the entire services/sutta-studio/ canonical layer + the grounding providers + the CONSOLIDATION/GROUNDING/SUTTA-008 docs. Deferred to follow-up PRs: - Quote-corner integrations of the audit's P2/P3 findings (naming inconsistency in grounding/translatorBank.ts, postPasses/syllabify.ts GAP coverage, archived-status header on assembly-line-roadmap.md and sutta-studio-case-studies.md, P3 component coverage gaps). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(sutta-studio): mark SUTTA_STUDIO.md as historical, point at authoritative FEATURES.md Per review feedback on PR #65: this file's own §Key Files Reference table declared docs/sutta-studio/FEATURES.md as the authoritative architecture doc, leaving the file the audit was editing in self-contradiction. Added a top-of-file banner directing readers to the canonical doc. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <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.
Summary
Why this PR exists
CONSOLIDATION.md and task tracking both marked Phase 3 complete after Phase 2 landed, but no `services/sutta-studio/llm.ts` ever existed and both legacy callers remained concrete with divergent signatures (compiler/llm.ts returned string; suttaStudioLLM.ts returned the richer `CompilerLLMResult` + supported `providerPreferences`). The 2026-05-16 doc audit (doc-audit skill, scoped to Sutta Studio) caught this and surfaced it as the only P0 finding — same failure mode as the schema divergence #62 fixed.
Behavior preservation
The legacy compiler/llm.ts contract returned `Promise`. Seven existing call sites (compiler/index.ts:394,490,529,571,596,646 + compiler/skeleton.ts:63) destructure it that way. To preserve that contract with zero call-site churn the shim aliases `callCompilerLLMText AS callCompilerLLM` — same string return, no behavioral delta. Those consumers move to the rich `CompilerLLMResult` signature when the orchestrator is ported (Phase 2d / PR D).
Test plan
Doc audit follow-ups (out of scope for this PR)
The 2026-05-16 audit surfaced additional P1 findings (CONSOLIDATION.md pass-order missing grounding step, SUTTA-007 ADR contradiction needing amendment, GROUNDING.md filename references wrong, FEATURES.md "Key Files" stale). Those should land in a separate doc-fix PR — scope discipline.
🤖 Generated with Claude Code