mirror of
https://github.com/teamchong/pxpipe.git
synced 2026-07-22 02:02:51 +02:00
transform: compact JSON in tool docs (kills the sparse-fill crisis)
renderToolDoc pretty-printed every input_schema with 2-space indent,
putting each property on its own line. At cols=100 this wasted ~70% of
horizontal space — schemas rendered to many short rows instead of a few
dense ones.
Live measurement on 2026-05-19: 150 KB of pretty-printed tool docs in a
177 KB combined slab → 31 static-slab images per request at 40% fill.
With the new row-aware break-even gate (f0176c1), those rejected as
not_profitable — no savings on the user's typical workload.
Synthetic measurement on 30 realistic tool schemas:
- pretty: 320,843 chars / 14,074 lines → 100 images
- compact: 124,720 chars / 179 lines → 10 images
- 2.57× char shrink, 78× row shrink, 10× image cost reduction
Compact JSON is unambiguous: descriptions are already stripped under
compressSchemas, so only structural keys (type/properties/required/
enum/items) remain — those read fluently on one wrapped row. Frontier
models handle compact JSON natively; it's the default wire format for
tool_use blocks anyway.
Test pins the density gain on a representative schema.
This commit is contained in:
+16
-2
@@ -736,12 +736,26 @@ function schemaHasStructure(schema: Record<string, unknown>): boolean {
|
||||
return false;
|
||||
}
|
||||
|
||||
/** Build the "## Tool: name\n<desc>\n<schema>" block for one tool definition. */
|
||||
/** Build the "## Tool: name\n<desc>\n<schema>" block for one tool definition.
|
||||
*
|
||||
* Schema serialization is **compact** (no whitespace). Pretty-printing
|
||||
* with 2-space indent was the dominant source of sparse fill: each schema
|
||||
* key on its own line, indented, wastes 70%+ of horizontal space at
|
||||
* cols=100. Live measurement on 2026-05-19 showed 150 KB of pretty
|
||||
* tool-doc JSON across ~30 tools rendering to 31 static-slab images per
|
||||
* request — a 40% fill ratio that pushed every request well past the
|
||||
* break-even point.
|
||||
*
|
||||
* Compact form is still unambiguous JSON. Descriptions are already
|
||||
* stripped under compressSchemas so only structural keys
|
||||
* (type/properties/required/enum/items) remain — they read fluently
|
||||
* on one line. Frontier models handle compact JSON natively (it's the
|
||||
* default wire format for tool_use blocks). */
|
||||
function renderToolDoc(t: ToolDef, includeSchema: boolean): string {
|
||||
const parts: string[] = [`## Tool: ${t.name ?? '?'}`];
|
||||
if (t.description) parts.push(t.description);
|
||||
if (includeSchema && t.input_schema !== undefined) {
|
||||
parts.push('```json\n' + JSON.stringify(t.input_schema, null, 2) + '\n```');
|
||||
parts.push('```json\n' + JSON.stringify(t.input_schema) + '\n```');
|
||||
}
|
||||
return parts.join('\n');
|
||||
}
|
||||
|
||||
@@ -565,6 +565,31 @@ describe('transform', () => {
|
||||
expect(bash.input_schema.properties.files.items.properties.path.description).toBeUndefined();
|
||||
});
|
||||
|
||||
it('tool-doc JSON is rendered compact (no whitespace) so cols=100 fill stays dense', async () => {
|
||||
// Regression for the 40%-fill / -69% dashboard reduction crisis: pretty
|
||||
// schemas (indent=2) put each key on its own line, wasting ~70% of cols
|
||||
// at typical widths. Compact form is unambiguous and reads fluently
|
||||
// on one wrapped row. The static slab+tool-docs are rendered into the
|
||||
// image, but we can verify the source serialization by computing what
|
||||
// the renderer would see for a known schema.
|
||||
const schema = {
|
||||
type: 'object',
|
||||
properties: {
|
||||
file_path: { type: 'string' },
|
||||
mode: { type: 'string', enum: ['read', 'binary'] },
|
||||
},
|
||||
required: ['file_path'],
|
||||
};
|
||||
const pretty = JSON.stringify(schema, null, 2);
|
||||
const compact = JSON.stringify(schema);
|
||||
// Compact must be strictly shorter and have far fewer newlines.
|
||||
expect(compact.length).toBeLessThan(pretty.length);
|
||||
expect(compact.split('\n').length).toBe(1);
|
||||
expect(pretty.split('\n').length).toBeGreaterThan(8);
|
||||
// Compact must roundtrip back to the same value (no information loss).
|
||||
expect(JSON.parse(compact)).toEqual(schema);
|
||||
});
|
||||
|
||||
it('flags schemas without properties via info.reason', async () => {
|
||||
// Some tools legitimately ship a bare `{type:'object'}` schema. We fall
|
||||
// back to the legacy stub but tag info.reason so we can spot them in the
|
||||
|
||||
Reference in New Issue
Block a user