feat: wire semantic chunking, add preferences, metrics, and docs
- Wire semantic chunker into inlineFileSmart() for large file context selection - Use inlineFileSmart for knowledge file in buildExecuteTaskPrompt (TF-IDF relevance) - Add compression_strategy and context_selection preferences with profile defaults - Add resolveCompressionStrategy() and resolveContextSelection() resolvers - Add cacheHitRate and compressionSavings to UnitMetrics - Add aggregateCacheHitRate() for session-wide cache performance - Update token-optimization.md with compression, chunking, and distillation docs - Add 12 integration tests for optimization preferences and modules
This commit is contained in:
Jeremy McSpadden
parent
39b3daee6f
commit
d65da6c927
6 changed files with 341 additions and 3 deletions
|
|
@ -264,3 +264,57 @@ preferences.md
|
|||
```
|
||||
|
||||
The profile is resolved once and flows through the entire dispatch pipeline. Explicit preferences override profile defaults at every layer.
|
||||
|
||||
## Prompt Compression
|
||||
|
||||
*Introduced in v2.29.0*
|
||||
|
||||
GSD can apply deterministic prompt compression before falling back to section-boundary truncation. This preserves more information when context exceeds the budget.
|
||||
|
||||
### Compression Strategy
|
||||
|
||||
Set via preferences:
|
||||
|
||||
```yaml
|
||||
---
|
||||
version: 1
|
||||
compression_strategy: compress
|
||||
---
|
||||
```
|
||||
|
||||
Two strategies are available:
|
||||
|
||||
| Strategy | Behavior | Default For |
|
||||
|----------|----------|------------|
|
||||
| `truncate` | Drop entire sections at boundaries (pre-v2.29 behavior) | `quality` profile |
|
||||
| `compress` | Apply heuristic text compression first, then truncate if still over budget | `budget` and `balanced` profiles |
|
||||
|
||||
Compression removes redundant whitespace, abbreviates verbose phrases, deduplicates repeated content, and removes low-information boilerplate — all deterministically with no LLM calls.
|
||||
|
||||
### Context Selection
|
||||
|
||||
Controls how files are inlined into prompts:
|
||||
|
||||
```yaml
|
||||
---
|
||||
version: 1
|
||||
context_selection: smart
|
||||
---
|
||||
```
|
||||
|
||||
| Mode | Behavior | Default For |
|
||||
|------|----------|------------|
|
||||
| `full` | Inline entire files | `balanced` and `quality` profiles |
|
||||
| `smart` | Use TF-IDF semantic chunking for large files (>3KB), including only relevant portions | `budget` profile |
|
||||
|
||||
### Structured Data Compression
|
||||
|
||||
At `budget` and `balanced` inline levels, decisions and requirements are formatted in a compact notation that saves 30-50% tokens compared to full markdown tables.
|
||||
|
||||
### Summary Distillation
|
||||
|
||||
When a slice has 3+ dependency summaries and the total exceeds the summary budget, GSD extracts essential structured data (provides, requires, key_files, key_decisions) and drops verbose prose sections before falling back to section-boundary truncation.
|
||||
|
||||
### Cache Hit Rate Tracking
|
||||
|
||||
The metrics ledger now tracks `cacheHitRate` per unit (percentage of input tokens served from cache) and provides `aggregateCacheHitRate()` for session-wide cache performance.
|
||||
|
|
|
|||
|
|
@ -24,6 +24,7 @@ import { computeBudgets, resolveExecutorContextWindow } from "./context-budget.j
|
|||
import { compressToTarget } from "./prompt-compressor.js";
|
||||
import { distillSummaries } from "./summary-distiller.js";
|
||||
import { formatDecisionsCompact, formatRequirementsCompact } from "./structured-data-formatter.js";
|
||||
import { chunkByRelevance, formatChunks } from "./semantic-chunker.js";
|
||||
|
||||
// ─── Executor Constraints ─────────────────────────────────────────────────────
|
||||
|
||||
|
|
@ -84,6 +85,43 @@ export async function inlineFileOptional(
|
|||
return `### ${label}\nSource: \`${relPath}\`\n\n${content.trim()}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Smart file inlining — for large files, use semantic chunking to include
|
||||
* only the most relevant portions based on the task context.
|
||||
* Falls back to full content for small files or when no query is provided.
|
||||
*
|
||||
* @param absPath Absolute file path
|
||||
* @param relPath Relative display path
|
||||
* @param label Section label
|
||||
* @param query Task description for relevance scoring (optional)
|
||||
* @param threshold Character threshold for chunking (default: 3000)
|
||||
*/
|
||||
export async function inlineFileSmart(
|
||||
absPath: string | null, relPath: string, label: string,
|
||||
query?: string, threshold = 3000,
|
||||
): Promise<string> {
|
||||
const content = absPath ? await loadFile(absPath) : null;
|
||||
if (!content) {
|
||||
return `### ${label}\nSource: \`${relPath}\`\n\n_(not found — file does not exist yet)_`;
|
||||
}
|
||||
|
||||
// For small files or no query, include full content
|
||||
if (content.length <= threshold || !query) {
|
||||
return `### ${label}\nSource: \`${relPath}\`\n\n${content.trim()}`;
|
||||
}
|
||||
|
||||
// Use semantic chunking for large files
|
||||
const result = chunkByRelevance(content, query, { maxChunks: 5, minScore: 0.05 });
|
||||
|
||||
// If chunking didn't save much (< 20%), just include full content
|
||||
if (result.savingsPercent < 20) {
|
||||
return `### ${label}\nSource: \`${relPath}\`\n\n${content.trim()}`;
|
||||
}
|
||||
|
||||
const formatted = formatChunks(result, relPath);
|
||||
return `### ${label} (${result.omittedChunks} sections omitted for relevance)\nSource: \`${relPath}\`\n\n${formatted}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Load and inline dependency slice summaries (full content, not just paths).
|
||||
*/
|
||||
|
|
@ -730,15 +768,25 @@ export async function buildExecuteTaskPrompt(
|
|||
: priorSummaries;
|
||||
const carryForwardSection = await buildCarryForwardSection(effectivePriorSummaries, base);
|
||||
|
||||
// Inline project knowledge if available
|
||||
const knowledgeInlineET = await inlineGsdRootFile(base, "knowledge.md", "Project Knowledge");
|
||||
// Inline project knowledge if available (smart-chunked for relevance)
|
||||
const knowledgeAbsPath = resolveGsdRootFile(base, "KNOWLEDGE");
|
||||
const knowledgeInlineET = existsSync(knowledgeAbsPath)
|
||||
? await inlineFileSmart(
|
||||
knowledgeAbsPath,
|
||||
relGsdRootFile("KNOWLEDGE"),
|
||||
"Project Knowledge",
|
||||
`${tTitle} ${sTitle}`, // use task + slice title as relevance query
|
||||
)
|
||||
: null;
|
||||
// Only include if it has content (not a "not found" result)
|
||||
const knowledgeContent = knowledgeInlineET && !knowledgeInlineET.includes("not found") ? knowledgeInlineET : null;
|
||||
|
||||
const inlinedTemplates = inlineLevel === "minimal"
|
||||
? inlineTemplate("task-summary", "Task Summary")
|
||||
: [
|
||||
inlineTemplate("task-summary", "Task Summary"),
|
||||
inlineTemplate("decisions", "Decisions"),
|
||||
...(knowledgeInlineET ? [knowledgeInlineET] : []),
|
||||
...(knowledgeContent ? [knowledgeContent] : []),
|
||||
].join("\n\n---\n\n");
|
||||
|
||||
const taskSummaryPath = join(base, `${relSlicePath(base, mid, sid)}/tasks/${tid}-SUMMARY.md`);
|
||||
|
|
|
|||
|
|
@ -52,6 +52,8 @@ export interface UnitMetrics {
|
|||
tier?: string; // complexity tier (light/standard/heavy) if dynamic routing active
|
||||
modelDowngraded?: boolean; // true if dynamic routing used a cheaper model
|
||||
skills?: string[]; // skill names available/loaded during this unit (#599)
|
||||
cacheHitRate?: number; // percentage 0-100, computed from cacheRead/(cacheRead+input)
|
||||
compressionSavings?: number; // percentage 0-100, char savings from prompt compression
|
||||
}
|
||||
|
||||
/** Budget state passed to snapshotUnitMetrics for persistence in the metrics ledger. */
|
||||
|
|
@ -192,6 +194,12 @@ export function snapshotUnitMetrics(
|
|||
unit.skills = skills;
|
||||
}
|
||||
|
||||
// Compute cache hit rate
|
||||
if (tokens.cacheRead > 0 || tokens.input > 0) {
|
||||
const totalInput = tokens.cacheRead + tokens.input;
|
||||
unit.cacheHitRate = totalInput > 0 ? Math.round((tokens.cacheRead / totalInput) * 100) : 0;
|
||||
}
|
||||
|
||||
ledger.units.push(unit);
|
||||
saveLedger(basePath, ledger);
|
||||
|
||||
|
|
@ -381,6 +389,22 @@ export function formatTierSavings(units: UnitMetrics[]): string {
|
|||
return `Dynamic routing: ${downgraded.length}/${totalUnits} units downgraded (${pct}%), cost: ${formatCost(downgradedCost)}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Compute aggregate cache hit rate across all units.
|
||||
* Returns percentage 0-100.
|
||||
*/
|
||||
export function aggregateCacheHitRate(): number {
|
||||
if (!ledger || ledger.units.length === 0) return 0;
|
||||
let totalInput = 0;
|
||||
let totalCacheRead = 0;
|
||||
for (const unit of ledger.units) {
|
||||
totalInput += unit.tokens.input;
|
||||
totalCacheRead += unit.tokens.cacheRead;
|
||||
}
|
||||
const total = totalInput + totalCacheRead;
|
||||
return total > 0 ? Math.round((totalCacheRead / total) * 100) : 0;
|
||||
}
|
||||
|
||||
// ─── Formatting helpers ───────────────────────────────────────────────────────
|
||||
|
||||
export function formatCost(cost: number): string {
|
||||
|
|
|
|||
|
|
@ -82,6 +82,8 @@ const KNOWN_PREFERENCE_KEYS = new Set<string>([
|
|||
"verification_auto_fix",
|
||||
"verification_max_retries",
|
||||
"search_provider",
|
||||
"compression_strategy",
|
||||
"context_selection",
|
||||
]);
|
||||
|
||||
export interface GSDSkillRule {
|
||||
|
|
@ -186,6 +188,10 @@ export interface GSDPreferences {
|
|||
verification_max_retries?: number;
|
||||
/** Search provider preference. "brave"/"tavily"/"ollama" force that backend and disable native Anthropic search. "native" forces native only. "auto" = current default behavior. */
|
||||
search_provider?: "brave" | "tavily" | "ollama" | "native" | "auto";
|
||||
/** Compression strategy for context that exceeds budget. "truncate" (default) drops sections, "compress" applies heuristic compression first. */
|
||||
compression_strategy?: import("./types.js").CompressionStrategy;
|
||||
/** Context selection mode for file inlining. "full" inlines entire files, "smart" uses semantic chunking. Default derived from token profile. */
|
||||
context_selection?: import("./types.js").ContextSelectionMode;
|
||||
}
|
||||
|
||||
export interface LoadedGSDPreferences {
|
||||
|
|
@ -763,6 +769,30 @@ export function resolveInlineLevel(): InlineLevel {
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve the compression strategy from the active token profile.
|
||||
* budget/balanced → "compress", quality → "truncate".
|
||||
* Explicit preference always wins.
|
||||
*/
|
||||
export function resolveCompressionStrategy(): import("./types.js").CompressionStrategy {
|
||||
const prefs = loadEffectiveGSDPreferences();
|
||||
if (prefs?.preferences.compression_strategy) return prefs.preferences.compression_strategy;
|
||||
const profile = resolveEffectiveProfile();
|
||||
return profile === "quality" ? "truncate" : "compress";
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve the context selection mode from the active token profile.
|
||||
* budget → "smart", balanced/quality → "full".
|
||||
* Explicit preference always wins.
|
||||
*/
|
||||
export function resolveContextSelection(): import("./types.js").ContextSelectionMode {
|
||||
const prefs = loadEffectiveGSDPreferences();
|
||||
if (prefs?.preferences.context_selection) return prefs.preferences.context_selection;
|
||||
const profile = resolveEffectiveProfile();
|
||||
return profile === "budget" ? "smart" : "full";
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve the search provider preference from preferences.md.
|
||||
* Returns undefined if not configured (caller falls back to existing behavior).
|
||||
|
|
@ -815,6 +845,8 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
|
|||
verification_auto_fix: override.verification_auto_fix ?? base.verification_auto_fix,
|
||||
verification_max_retries: override.verification_max_retries ?? base.verification_max_retries,
|
||||
search_provider: override.search_provider ?? base.search_provider,
|
||||
compression_strategy: override.compression_strategy ?? base.compression_strategy,
|
||||
context_selection: override.context_selection ?? base.context_selection,
|
||||
};
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -408,3 +408,19 @@ test("formatChunks does not show omission for contiguous chunks", () => {
|
|||
const formatted = formatChunks(result, "src/test.ts");
|
||||
assert.ok(!formatted.includes("omitted"), "Contiguous chunks should not show omission");
|
||||
});
|
||||
|
||||
// ─── inlineFileSmart integration tests ─────────────────────────────────────
|
||||
|
||||
// These test the formatChunks function in the context of how it'll be used
|
||||
test("formatChunks includes file path in line range headers", () => {
|
||||
const result = chunkByRelevance(
|
||||
"export function foo() {}\n\nexport function bar() {}\n\nexport function baz() {}",
|
||||
"foo function",
|
||||
{ maxChunks: 1 },
|
||||
);
|
||||
const formatted = formatChunks(result, "src/utils.ts");
|
||||
assert.ok(
|
||||
formatted.includes("src/utils.ts") || formatted.includes("[Lines"),
|
||||
"Formatted output should include file path or line range markers",
|
||||
);
|
||||
});
|
||||
|
|
|
|||
|
|
@ -0,0 +1,164 @@
|
|||
import { describe, it } from "node:test";
|
||||
import assert from "node:assert/strict";
|
||||
|
||||
// Test the type definitions exist and are correct
|
||||
describe("token-optimization: types", () => {
|
||||
it("CompressionStrategy accepts valid values", async () => {
|
||||
const { } = await import("../types.js");
|
||||
// Type-level test — if this compiles, the types exist
|
||||
const truncate: import("../types.js").CompressionStrategy = "truncate";
|
||||
const compress: import("../types.js").CompressionStrategy = "compress";
|
||||
assert.equal(truncate, "truncate");
|
||||
assert.equal(compress, "compress");
|
||||
});
|
||||
|
||||
it("ContextSelectionMode accepts valid values", async () => {
|
||||
const full: import("../types.js").ContextSelectionMode = "full";
|
||||
const smart: import("../types.js").ContextSelectionMode = "smart";
|
||||
assert.equal(full, "full");
|
||||
assert.equal(smart, "smart");
|
||||
});
|
||||
});
|
||||
|
||||
// Test cache hit rate computation
|
||||
describe("token-optimization: cache hit rate", () => {
|
||||
it("computeCacheHitRate returns correct percentage", async () => {
|
||||
const { computeCacheHitRate } = await import("../prompt-cache-optimizer.js");
|
||||
assert.equal(computeCacheHitRate({ cacheRead: 900, cacheWrite: 100, input: 100 }), 90);
|
||||
assert.equal(computeCacheHitRate({ cacheRead: 0, cacheWrite: 0, input: 100 }), 0);
|
||||
assert.equal(computeCacheHitRate({ cacheRead: 0, cacheWrite: 0, input: 0 }), 0);
|
||||
assert.equal(computeCacheHitRate({ cacheRead: 500, cacheWrite: 0, input: 500 }), 50);
|
||||
});
|
||||
});
|
||||
|
||||
// Test structured data savings
|
||||
describe("token-optimization: structured data savings", () => {
|
||||
it("compact decisions format is shorter than markdown table", async () => {
|
||||
const { formatDecisionsCompact, measureSavings } = await import("../structured-data-formatter.js");
|
||||
const decisions = [
|
||||
{ id: "D001", when_context: "M001/S01", scope: "architecture", decision: "Use SQLite for storage", choice: "WAL mode", rationale: "Built-in, no external deps", revisable: "yes" },
|
||||
{ id: "D002", when_context: "M001/S02", scope: "testing", decision: "Unit test all parsers", choice: "node:test", rationale: "Fast, zero-dependency", revisable: "no" },
|
||||
];
|
||||
const compact = formatDecisionsCompact(decisions);
|
||||
// A realistic markdown table equivalent
|
||||
const markdown = [
|
||||
"| # | When | Scope | Decision | Choice | Rationale | Revisable? |",
|
||||
"|---|------|-------|----------|--------|-----------|------------|",
|
||||
"| D001 | M001/S01 | architecture | Use SQLite for storage | WAL mode | Built-in, no external deps | yes |",
|
||||
"| D002 | M001/S02 | testing | Unit test all parsers | node:test | Fast, zero-dependency | no |",
|
||||
].join("\n");
|
||||
const savings = measureSavings(compact, markdown);
|
||||
assert.ok(savings > 10, `Expected >10% savings, got ${savings}%`);
|
||||
});
|
||||
|
||||
it("compact requirements format drops low-value fields", async () => {
|
||||
const { formatRequirementsCompact } = await import("../structured-data-formatter.js");
|
||||
const requirements = [{
|
||||
id: "R001", class: "functional", status: "active",
|
||||
description: "API response time < 200ms",
|
||||
why: "User experience", primary_owner: "S01",
|
||||
validation: "Load test P99 < 200ms",
|
||||
}];
|
||||
const compact = formatRequirementsCompact(requirements);
|
||||
assert.ok(!compact.includes("source"), "Should not include source field");
|
||||
assert.ok(!compact.includes("supporting_slices"), "Should not include supporting_slices");
|
||||
assert.ok(compact.includes("R001"), "Should include requirement ID");
|
||||
});
|
||||
});
|
||||
|
||||
// Test compression levels
|
||||
describe("token-optimization: prompt compression", () => {
|
||||
it("light compression removes extra whitespace", async () => {
|
||||
const { compressPrompt } = await import("../prompt-compressor.js");
|
||||
const input = "Line 1\n\n\n\n\nLine 2\n\n\n\nLine 3";
|
||||
const result = compressPrompt(input, { level: "light" });
|
||||
assert.ok(result.savingsPercent > 0, "Should have positive savings");
|
||||
assert.ok(!result.content.includes("\n\n\n"), "Should collapse multiple blank lines");
|
||||
});
|
||||
|
||||
it("moderate compression abbreviates verbose phrases", async () => {
|
||||
const { compressPrompt } = await import("../prompt-compressor.js");
|
||||
const input = "In order to achieve this, it is important to note that the following steps are required.";
|
||||
const result = compressPrompt(input, { level: "moderate" });
|
||||
assert.ok(result.compressedChars < result.originalChars, "Should be shorter");
|
||||
});
|
||||
|
||||
it("code blocks are preserved during compression", async () => {
|
||||
const { compressPrompt } = await import("../prompt-compressor.js");
|
||||
const input = "In order to do this:\n\n```typescript\nconst x = 1;\n```\n\nIn order to verify:";
|
||||
const result = compressPrompt(input, { level: "aggressive" });
|
||||
assert.ok(result.content.includes("const x = 1;"), "Code block should be preserved");
|
||||
});
|
||||
});
|
||||
|
||||
// Test summary distillation
|
||||
describe("token-optimization: summary distillation", () => {
|
||||
it("distills summaries preserving key fields", async () => {
|
||||
const { distillSummaries } = await import("../summary-distiller.js");
|
||||
const summary = `---
|
||||
id: S01
|
||||
provides:
|
||||
- Core types
|
||||
key_files:
|
||||
- src/types.ts
|
||||
key_decisions:
|
||||
- D001
|
||||
---
|
||||
|
||||
# S01: Core Types
|
||||
|
||||
Built the foundation type system.
|
||||
|
||||
## What Happened
|
||||
|
||||
Long prose about implementation details that should be dropped...
|
||||
`;
|
||||
const result = distillSummaries([summary], 5000);
|
||||
assert.ok(result.savingsPercent > 0, "Should have savings");
|
||||
assert.ok(result.content.includes("Core types"), "Should preserve provides");
|
||||
assert.ok(result.content.includes("src/types.ts"), "Should preserve key_files");
|
||||
});
|
||||
});
|
||||
|
||||
// Test semantic chunker
|
||||
describe("token-optimization: semantic chunking", () => {
|
||||
it("chunks TypeScript code at function boundaries", async () => {
|
||||
const { splitIntoChunks } = await import("../semantic-chunker.js");
|
||||
const code = `export function alpha() {
|
||||
return 1;
|
||||
}
|
||||
|
||||
export function beta() {
|
||||
return 2;
|
||||
}
|
||||
|
||||
export function gamma() {
|
||||
return 3;
|
||||
}`;
|
||||
const chunks = splitIntoChunks(code);
|
||||
assert.ok(chunks.length >= 2, `Expected >=2 chunks, got ${chunks.length}`);
|
||||
});
|
||||
|
||||
it("scores chunks by relevance to query", async () => {
|
||||
const { chunkByRelevance } = await import("../semantic-chunker.js");
|
||||
const code = `export function createUser(name: string) {
|
||||
return { name, id: generateId() };
|
||||
}
|
||||
|
||||
export function deleteDatabase() {
|
||||
dropAllTables();
|
||||
clearCache();
|
||||
}
|
||||
|
||||
export function updateUser(id: string, name: string) {
|
||||
const user = findUser(id);
|
||||
user.name = name;
|
||||
return user;
|
||||
}`;
|
||||
const result = chunkByRelevance(code, "user creation and management", { maxChunks: 2 });
|
||||
// The user-related chunks should score higher
|
||||
const content = result.chunks.map(c => c.content).join("\n");
|
||||
assert.ok(content.includes("createUser") || content.includes("updateUser"),
|
||||
"Should include user-related chunks");
|
||||
});
|
||||
});
|
||||
Loading…
Add table
Reference in a new issue