@oh-my-pi/pi-ai 16.0.10 → 16.1.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [16.1.0] - 2026-06-19
+
+### Added
+
+- Added utility functions to strip schema descriptions for optimized LLM context usage
+
 ## [16.0.10] - 2026-06-18
 
 ### Added

package/dist/types/utils/schema/wire.d.ts

@@ -73,3 +73,20 @@ export declare function arkToWireSchema(schema: Type): Record<string, unknown>;
  * schema-valued positions and nullable scalar unions.
  */
 export declare function toolWireSchema(tool: Tool): Record<string, unknown>;
+/**
+ * Return a deep clone of `schema` with every `description` annotation removed.
+ * The result is memoized on the input via a non-enumerable symbol (`stamp`) so
+ * repeated provider requests reuse the same stripped object; the input is never
+ * mutated, so the stamped `toolWireSchema` cache stays intact for
+ * system-prompt/UI rendering.
+ */
+export declare function stripSchemaDescriptions(schema: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Strip a tool's human-readable text from its provider-bound spec: empties the
+ * top-level `description` and removes nested schema `description` annotations.
+ * Used when the full tool catalog is rendered into the system prompt instead, so
+ * the descriptions ride the wire once (in the prompt) rather than duplicated on
+ * every tool definition. Parameters are resolved to wire JSON Schema and cloned,
+ * leaving the original tool objects and the stamped schema cache untouched.
+ */
+export declare function stripToolDescriptions(tools: readonly Tool[]): Tool[];

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "16.0.10",
+	"version": "16.1.0",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,8 +38,9 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.0",
-		"@oh-my-pi/pi-catalog": "16.0.10",
-		"@oh-my-pi/pi-utils": "16.0.10",
+		"@oh-my-pi/pi-catalog": "16.1.0",
+		"@oh-my-pi/pi-utils": "16.1.0",
+		"@oh-my-pi/pi-wire": "16.1.0",
 		"arktype": "^2.2.0",
 		"partial-json": "^0.1.7",
 		"zod": "^4"

package/src/utils/schema/wire.ts

@@ -152,6 +152,7 @@ function arkJsonAstToWire(value: unknown): unknown {
 const kZodWireSchema = Symbol("pi.schema.zod.wire");
 const kJsonWireSchema = Symbol("pi.schema.json.wire");
 const kArkWireSchema = Symbol("pi.schema.ark.wire");
+const kStrippedSchema = Symbol("pi.schema.descriptions.stripped");
 
 /**
  * Post-process Zod-emitted JSON Schema so it matches the wire shape providers
@@ -634,3 +635,87 @@ export function toolWireSchema(tool: Tool): Record<string, unknown> {
 		return postProcessJsonSchema(upgraded);
 	});
 }
+
+/**
+ * Schema-valued keywords whose value is a single subschema (or an array of
+ * subschemas — the recursion dispatches on array-ness, so tuple forms like
+ * draft-07 `items: []` are handled too). Covers the draft 2020-12 surface plus
+ * the legacy `additionalItems` that may survive an incomplete upgrade.
+ */
+const STRIP_SCHEMA_VALUE_KEYS = [
+	"additionalProperties",
+	"unevaluatedProperties",
+	"unevaluatedItems",
+	"items",
+	"additionalItems",
+	"contains",
+	"propertyNames",
+	"contentSchema",
+	"if",
+	"then",
+	"else",
+	"not",
+	"anyOf",
+	"oneOf",
+	"allOf",
+	"prefixItems",
+] as const;
+
+/** Keywords whose value is a `{ name: Schema }` map — names are NOT annotations. */
+const STRIP_SCHEMA_MAP_KEYS = ["properties", "patternProperties", "$defs", "definitions", "dependentSchemas"] as const;
+
+/**
+ * Recursively strip human-readable `description` annotations from a JSON Schema,
+ * descending only through schema-valued keywords so a property literally named
+ * `"description"` inside a `properties`/`$defs` map keeps its schema (only its own
+ * annotation is dropped), and data-bearing keywords (`default`/`const`/`examples`)
+ * are never traversed. Mutates `node` in place — callers pass a clone.
+ */
+function stripSchemaDescriptionsInPlace(node: unknown): void {
+	if (Array.isArray(node)) {
+		for (const child of node) stripSchemaDescriptionsInPlace(child);
+		return;
+	}
+	if (!isSchemaRecord(node)) return;
+	delete node.description;
+	for (const key of STRIP_SCHEMA_VALUE_KEYS) {
+		if (Object.hasOwn(node, key)) stripSchemaDescriptionsInPlace(node[key]);
+	}
+	for (const mapKey of STRIP_SCHEMA_MAP_KEYS) {
+		const map = node[mapKey];
+		if (isSchemaRecord(map)) {
+			for (const key in map) stripSchemaDescriptionsInPlace(map[key]);
+		}
+	}
+}
+
+/**
+ * Return a deep clone of `schema` with every `description` annotation removed.
+ * The result is memoized on the input via a non-enumerable symbol (`stamp`) so
+ * repeated provider requests reuse the same stripped object; the input is never
+ * mutated, so the stamped `toolWireSchema` cache stays intact for
+ * system-prompt/UI rendering.
+ */
+export function stripSchemaDescriptions(schema: Record<string, unknown>): Record<string, unknown> {
+	return stamp(schema, kStrippedSchema, source => {
+		const clone = structuredClone(source);
+		stripSchemaDescriptionsInPlace(clone);
+		return clone;
+	});
+}
+
+/**
+ * Strip a tool's human-readable text from its provider-bound spec: empties the
+ * top-level `description` and removes nested schema `description` annotations.
+ * Used when the full tool catalog is rendered into the system prompt instead, so
+ * the descriptions ride the wire once (in the prompt) rather than duplicated on
+ * every tool definition. Parameters are resolved to wire JSON Schema and cloned,
+ * leaving the original tool objects and the stamped schema cache untouched.
+ */
+export function stripToolDescriptions(tools: readonly Tool[]): Tool[] {
+	return tools.map(tool => ({
+		...tool,
+		description: "",
+		parameters: stripSchemaDescriptions(toolWireSchema(tool)),
+	}));
+}