mirror of
https://github.com/garrytan/gbrain.git
synced 2026-07-27 22:15:33 +00:00
* feat(skillpack): enhance skillify with cross-modal eval quality gate Updates skillify from v1.0.0 to v2.0.0 with the key innovation: cross-modal evaluation runs BEFORE tests (step 3) to establish quality, then tests lock in the proven-good behavior. Key changes: - 11-item checklist (was 10) - adds cross-modal eval as step 3 - Cross-modal eval uses 3 models to score output on 5 dimensions - Quality gate: all dimensions ≥ 7 average before proceeding to tests - Prevents locking in mediocrity through tests-first approach - References cross-modal-review skill for eval pipeline - Updated all gbrain-specific paths (bun test, scripts/*.ts) - Maintains compatibility with gbrain check-resolvable workflow The meta-skill for turning raw features into properly-skilled, tested, resolvable capabilities. Cross-modal eval ensures output quality before tests cement the behavior. * feat: skillify hardened via 2 cross-modal eval cycles (8.1/10) Applied top improvements from GPT-5.5 + Opus 4-7 + DeepSeek V4 Pro: - Named 3 frontier models explicitly with provider table - Inlined eval prompt template with CONTEXT param + scoring calibration - Defined aggregation math: mean >= 7 AND no single dim < 5 - Added eval receipt JSON schema - Structured 3-cycle fix loop with before/after delta tracking - Added worked example (summarize-pr, end-to-end) - Added cost guardrails (skip < 200 tokens, max 9 API calls) - Added representative input selection rule - Added SKILL.md frontmatter template (copy-paste ready) - Added Phase 0 decision gate (is this worth skillifying?) Also includes cross-modal-eval runner recipe with robust JSON parsing for LLMs that return malformed JSON (3-tier repair). * chore(recipes): remove cross-modal-eval.mjs Superseded by `gbrain eval cross-modal` (next commit). The .mjs script was the original PR's hand-rolled provider stack; the replacement reuses src/core/ai/gateway.ts so config/auth/model-aliasing comes from the canonical recipe registry instead of a parallel stack. No code references the .mjs (it was invoked by skill prose only), so this delete is independently safe to bisect through. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(eval): cross-modal-eval core module + unit tests Pure-logic foundation for the new `gbrain eval cross-modal` command (wired in the next commit). All five modules are self-contained — no CLI surface, no I/O outside the receipt writer's mkdirSync. Imported from src/core/ai/gateway.ts at runtime via gwChat (no config impact at load time). Modules: - json-repair.ts: parseModelJSON 4-strategy fallback chain. Adversarial nuclear-option throws rather than fabricating scores (Q6 + Q3 in plan). - aggregate.ts: verdict logic. PASS = (>=2 successes) AND (every dim mean >= 7) AND (every dim min across models >= 5). INCONCLUSIVE when <2/3 models returned parseable scores — closes the v1 .mjs `Object.values({}).every(...) === true` empty-array silent-PASS bug (Q2 + Q3). - receipt-name.ts: receipt filename binds (slug, sha8 of SKILL.md) so `gbrain skillify check` can detect stale audits (T10 in plan). - receipt-write.ts: thin wrapper over writeFileSync that auto-mkdirs the parent directory. Standalone module because gbrainPath() does NOT auto-mkdir (T5 plan correction — Codex caught this). - runner.ts: orchestrator. Promise.allSettled across 3 slots per cycle; up to 3 cycles; stops early on PASS or INCONCLUSIVE. Default slots: openai:gpt-4o / anthropic:claude-opus-4-7 / google:gemini-1.5-pro. estimateCost() exports a small per-model pricing table (drifts; refresh alongside model-family bumps). Tests (32 cases total, all green): - json-repair.test.ts: 10 cases (clean JSON, fences, trailing commas, single quotes, embedded newlines, mismatched braces, nuclear-option success + adversarial throws, empty input, numeric-shorthand scores). - aggregate.test.ts: 8 cases pinning Q2/Q3/dedup. The 0-of-3 INCONCLUSIVE case is the regression guard for the v1 silent-PASS bug. - cli.test.ts: 12 cases on receipt-name / receipt-write / GBRAIN_HOME isolation. Uses withEnv() helper for env mutation (R1 isolation rule). Verifies bisect-clean: typecheck passes, all 32 unit cases green. The runner.ts import of gateway.chat() is dead until commit 3 wires the CLI surface. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(eval): wire `gbrain eval cross-modal` CLI subcommand User-facing surface for the multi-model quality gate. Three different- provider frontier models score the OUTPUT against the TASK on a 5-dim rubric. Verdict drives exit code: 0 PASS, 1 FAIL, 2 INCONCLUSIVE (<2/3 models returned parseable scores per Q3 in plan). Wiring touches three files: - src/commands/eval-cross-modal.ts (new, ~290 lines) CLI handler. Self-configures the AI gateway from loadConfig() + process.env so it works without `gbrain init` (the cli.ts no-DB branch bypasses connectEngine()). Defaults: cycles=3 in TTY, cycles=1 in non-TTY (T11 partial cost guardrail — limits scripted bulk spend; full --budget-usd hard cap is a v0.27.x TODO). Prints estimated max-cost-per-cycle to stderr before each run. Uses gbrainPath('eval-receipts') for receipt directory. - src/cli.ts (no-DB dispatch branch, 5-line addition) Special-cases `eval cross-modal` BEFORE the existing handleCliOnly path that requires connectEngine(). Mirrors the `dream` no-DB pattern but doesn't even attempt the connect — the command never touches the DB. New users can run the gate before `gbrain init` (T3 in plan). - src/commands/eval.ts (sub-subcommand dispatch) Adds `cross-modal` alongside `export`/`prune`/`replay`. The cli.ts branch takes precedence in the user-facing path; this branch only fires when callers re-enter runEvalCommand with an existing engine. Engine is intentionally unused — the handler self-routes. - test/e2e/cross-modal-eval.test.ts (new, 4 cases) Mocked-fetch E2E. Lives at test/e2e/* (NOT *.serial.test.ts) per plan T8: test/e2e/* is exempt from the test-isolation lint and already runs serially via scripts/run-e2e.sh, so the mock.module() call doesn't need a quarantine rename. Cases: PASS / FAIL (mean<7) / FAIL (min<5 — Q2 floor) / INCONCLUSIVE (2 mock 5xx — Q3 contract). The runner from commit 2 now has live callers. typecheck passes; the 4 E2E cases all green. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(skillify): add informational 11th item (cross-modal eval) Promotes the skillify contract from 10 to 11 items. The 11th item (cross-modal eval) is `required:false` per T7 in the plan — a missing or stale receipt surfaces in the audit output but does not fail the gate. Existing skills keep their current required-score; the bump is additive, not breaking. Changes: - src/commands/skillify.ts Header jsdoc updated 10-item -> 11-item. No code-flow changes. - src/commands/skillify-check.ts (the per-skill audit; not src/commands/skillpack-check.ts which is a different command — plan T6 corrected the conflation in the original plan) New informational item at position 11. Reuses findReceiptForSkill() helper from src/core/cross-modal-eval/receipt-name.ts to detect: * found — receipt matches current SKILL.md sha-8 * stale — receipt exists for an older SKILL.md * missing — no receipt yet Audit output cases pass through to existing pretty/JSON formats. - src/core/skillify/templates.ts Scaffolded SKILL.md now includes a "Phase 3: Cross-modal eval (informational)" section with copy-paste `gbrain eval cross-modal` invocation, pass criteria, and receipt-naming convention. Helps new skill authors discover the gate. - test/skillify-scaffold.test.ts New T9 case verifies the scaffold emits the Phase 3 section, points at the correct command, documents the receipt path, and appends exactly one resolver row. Replaces the original plan's `gbrain skillify scaffold demo-eleven` shell verification (which Codex caught as invalid + repo-mutating). Verifies: typecheck passes; scaffold test 19/19 (was 18, +1 T9 case). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: skillify v1.1.0 + cross-modal-eval references Documentation catches up with the new behavior shipped in commits 1-4. - skills/skillify/SKILL.md (1.0.0 -> 1.1.0) Full rewrite. Frontmatter version is additive (T7 in plan); the 11th item is informational, not breaking. Phase 3 now points at `gbrain eval cross-modal` with copy-paste invocation, default slot table, pass criteria, receipt-naming convention, cycles + cost guardrails (T11 partial cap), provider configuration via the AI gateway, and the cycle-1/2/3 fix loop. Adds Output Format section (skills-conformance.test.ts requires it). Drops the original `(or lib/cross-modal-eval.ts)` parenthetical (Q5 plan correction — that path never existed). - skills/cross-modal-review/SKILL.md Adds 4-line Relationship section pointing at `gbrain eval cross-modal` (D3 plan reciprocal). Distinguishes the manual second-opinion gate (this skill) from the automated multi-model score-and-iterate gate (the new command). - CLAUDE.md Key Files entries for src/commands/eval-cross-modal.ts and the five new src/core/cross-modal-eval/* modules. Commands list gains the `gbrain eval cross-modal` entry under v0.27.x. Notes the non-TTY default 1-cycle behavior + the gbrainPath('eval- receipts') resolution. - TODOS.md Four v0.27.x follow-ups filed under a new "cross-modal-eval" section: full --budget-usd cap (T11 follow-up), subagent integration (recovers cross-process rate-leases T4 deferred), skill adoption telemetry (revisit T7=C with data after 30 days), docs/cross-modal-eval.md user guide. - llms-full.txt Regenerated via `bun run build:llms` to match the CLAUDE.md edits — sync guard at test/build-llms.test.ts requires this. Verifies: typecheck passes; skills-conformance 199/199 green; build-llms 7/7 green; full unit fast loop 3861/3861 green. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: bump version and changelog (v0.28.4) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: garrytan-agents <garrytan-agents@users.noreply.github.com> Co-authored-by: Garry Tan <garrytan@gmail.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
144 lines
5.1 KiB
TypeScript
144 lines
5.1 KiB
TypeScript
import { describe, expect, test } from 'bun:test';
|
|
|
|
import { aggregate } from '../src/core/cross-modal-eval/aggregate.ts';
|
|
import type { SlotResult } from '../src/core/cross-modal-eval/aggregate.ts';
|
|
|
|
function ok(model: string, scores: Record<string, number>, improvements: string[] = []): SlotResult {
|
|
return {
|
|
ok: true,
|
|
modelId: model,
|
|
parsed: {
|
|
scores: Object.fromEntries(Object.entries(scores).map(([k, v]) => [k, { score: v }])),
|
|
improvements,
|
|
},
|
|
};
|
|
}
|
|
|
|
function err(model: string, message = 'fetch failed'): SlotResult {
|
|
return { ok: false, modelId: model, error: message };
|
|
}
|
|
|
|
describe('cross-modal-eval/aggregate', () => {
|
|
test('all 3 succeeded, all dims >=7 -> PASS', () => {
|
|
const out = aggregate({
|
|
slots: [
|
|
ok('openai:gpt-4o', { goal: 9, depth: 8 }),
|
|
ok('anthropic:claude-opus-4-7', { goal: 8, depth: 7 }),
|
|
ok('google:gemini-1.5-pro', { goal: 8, depth: 8 }),
|
|
],
|
|
});
|
|
expect(out.verdict).toBe('pass');
|
|
expect(out.successes).toBe(3);
|
|
expect(out.failures).toBe(0);
|
|
expect(out.dimensions.goal!.mean).toBeGreaterThanOrEqual(7);
|
|
expect(out.dimensions.depth!.mean).toBeGreaterThanOrEqual(7);
|
|
expect(out.dimensions.goal!.failReason).toBeUndefined();
|
|
expect(out.overall).toBeGreaterThan(7);
|
|
});
|
|
|
|
test('one dim mean below 7 -> FAIL with mean_below_7', () => {
|
|
const out = aggregate({
|
|
slots: [
|
|
ok('openai:gpt-4o', { goal: 9, depth: 6 }),
|
|
ok('anthropic:claude-opus-4-7', { goal: 8, depth: 6 }),
|
|
ok('google:gemini-1.5-pro', { goal: 8, depth: 6 }),
|
|
],
|
|
});
|
|
expect(out.verdict).toBe('fail');
|
|
expect(out.dimensions.depth!.failReason).toBe('mean_below_7');
|
|
expect(out.dimensions.goal!.failReason).toBeUndefined();
|
|
expect(out.verdictMessage).toContain('depth');
|
|
});
|
|
|
|
test('mean >=7 but one model scored <5 -> FAIL with min_below_5 (Q2 score-floor)', () => {
|
|
// [9, 8, 4] — mean = 7.0 ✓, but min = 4 → must FAIL per spec.
|
|
const out = aggregate({
|
|
slots: [
|
|
ok('openai:gpt-4o', { goal: 9 }),
|
|
ok('anthropic:claude-opus-4-7', { goal: 8 }),
|
|
ok('google:gemini-1.5-pro', { goal: 4 }),
|
|
],
|
|
});
|
|
expect(out.verdict).toBe('fail');
|
|
expect(out.dimensions.goal!.mean).toBeCloseTo(7.0, 1);
|
|
expect(out.dimensions.goal!.min).toBe(4);
|
|
expect(out.dimensions.goal!.failReason).toBe('min_below_5');
|
|
});
|
|
|
|
test('2 of 3 succeeded -> verdict is computable', () => {
|
|
const out = aggregate({
|
|
slots: [
|
|
ok('openai:gpt-4o', { goal: 8 }),
|
|
ok('anthropic:claude-opus-4-7', { goal: 9 }),
|
|
err('google:gemini-1.5-pro', 'rate limited'),
|
|
],
|
|
});
|
|
expect(out.verdict).toBe('pass');
|
|
expect(out.successes).toBe(2);
|
|
expect(out.failures).toBe(1);
|
|
expect(out.errors).toEqual([{ modelId: 'google:gemini-1.5-pro', error: 'rate limited' }]);
|
|
});
|
|
|
|
test('1 of 3 succeeded -> INCONCLUSIVE (Q3=A)', () => {
|
|
const out = aggregate({
|
|
slots: [
|
|
ok('openai:gpt-4o', { goal: 9 }),
|
|
err('anthropic:claude-opus-4-7', 'auth failed'),
|
|
err('google:gemini-1.5-pro', 'rate limited'),
|
|
],
|
|
});
|
|
expect(out.verdict).toBe('inconclusive');
|
|
expect(out.successes).toBe(1);
|
|
expect(out.overall).toBeUndefined();
|
|
expect(out.verdictMessage).toContain('INCONCLUSIVE');
|
|
});
|
|
|
|
test('0 of 3 succeeded -> INCONCLUSIVE (regression guard for empty-array .every() === true)', () => {
|
|
const out = aggregate({
|
|
slots: [
|
|
err('openai:gpt-4o'),
|
|
err('anthropic:claude-opus-4-7'),
|
|
err('google:gemini-1.5-pro'),
|
|
],
|
|
});
|
|
// The original v1 .mjs script returned PASS here because Object.values({}).every(...) === true.
|
|
// The fix: aggregate must require >=2 successes BEFORE evaluating dim means.
|
|
expect(out.verdict).toBe('inconclusive');
|
|
expect(out.successes).toBe(0);
|
|
expect(out.failures).toBe(3);
|
|
expect(out.errors).toHaveLength(3);
|
|
});
|
|
|
|
test('improvement dedup by 40-char prefix (case-insensitive)', () => {
|
|
// Dedup is `first-40-chars(lowercased, whitespace-collapsed)`. To trigger
|
|
// dedup, the first 40 chars must match — including any leading numeric
|
|
// prefix. Two entries below match across slots after lowercasing.
|
|
const out = aggregate({
|
|
slots: [
|
|
ok('a:m', { goal: 8 }, [
|
|
'Add concrete examples to the introduction section',
|
|
'Tighten the closing paragraph',
|
|
]),
|
|
ok('b:m', { goal: 8 }, [
|
|
'add concrete examples to the introduction SECTION', // dup of first by 40-char prefix
|
|
'Add citations',
|
|
]),
|
|
],
|
|
});
|
|
// Three uniques after dedup: "Add concrete examples...", "Tighten...", "Add citations".
|
|
expect(out.topImprovements).toHaveLength(3);
|
|
expect(out.topImprovements[0]).toContain('Add concrete examples');
|
|
});
|
|
|
|
test('top improvements capped at 10', () => {
|
|
const many = Array.from({ length: 30 }, (_, i) => `${i}. unique improvement number ${i}`);
|
|
const out = aggregate({
|
|
slots: [
|
|
ok('a:m', { goal: 8 }, many.slice(0, 15)),
|
|
ok('b:m', { goal: 8 }, many.slice(15)),
|
|
],
|
|
});
|
|
expect(out.topImprovements.length).toBeLessThanOrEqual(10);
|
|
});
|
|
});
|