chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,214 @@
|
||||
"""Stdlib tool registry with JSON Schema subset validation and parallel dispatch.
|
||||
|
||||
Subset: required fields, string/int/number/bool/array/object, enum, minimum/maximum.
|
||||
Returns structured observations for every validation failure so an agent can retry.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any, Callable
|
||||
|
||||
|
||||
@dataclass
|
||||
class ToolDef:
|
||||
name: str
|
||||
description: str
|
||||
input_schema: dict[str, Any]
|
||||
executor: Callable[..., str]
|
||||
timeout_s: float = 5.0
|
||||
|
||||
|
||||
@dataclass
|
||||
class ToolCall:
|
||||
tool_use_id: str
|
||||
name: str
|
||||
args: dict[str, Any]
|
||||
|
||||
|
||||
@dataclass
|
||||
class ToolResult:
|
||||
tool_use_id: str
|
||||
ok: bool
|
||||
content: str
|
||||
|
||||
|
||||
def _coerce(value: Any, schema: dict[str, Any]) -> tuple[Any, str | None]:
|
||||
t = schema.get("type")
|
||||
if t == "integer":
|
||||
if isinstance(value, int) and not isinstance(value, bool):
|
||||
return value, None
|
||||
if isinstance(value, str):
|
||||
try:
|
||||
return int(value), None
|
||||
except ValueError:
|
||||
return value, f"cannot coerce string {value!r} to integer"
|
||||
return value, f"expected integer, got {type(value).__name__}"
|
||||
if t == "number":
|
||||
if isinstance(value, (int, float)) and not isinstance(value, bool):
|
||||
return float(value), None
|
||||
if isinstance(value, str):
|
||||
try:
|
||||
return float(value), None
|
||||
except ValueError:
|
||||
return value, f"cannot coerce string {value!r} to number"
|
||||
return value, f"expected number, got {type(value).__name__}"
|
||||
if t == "boolean":
|
||||
if isinstance(value, bool):
|
||||
return value, None
|
||||
return value, f"expected boolean, got {type(value).__name__}"
|
||||
if t == "string":
|
||||
if isinstance(value, str):
|
||||
return value, None
|
||||
return value, f"expected string, got {type(value).__name__}"
|
||||
if t == "array":
|
||||
if isinstance(value, list):
|
||||
return value, None
|
||||
return value, f"expected array, got {type(value).__name__}"
|
||||
if t == "object":
|
||||
if isinstance(value, dict):
|
||||
return value, None
|
||||
return value, f"expected object, got {type(value).__name__}"
|
||||
return value, None
|
||||
|
||||
|
||||
def validate(args: dict[str, Any], schema: dict[str, Any]) -> tuple[dict[str, Any], list[str]]:
|
||||
errors: list[str] = []
|
||||
props = schema.get("properties", {})
|
||||
required = schema.get("required", [])
|
||||
out: dict[str, Any] = {}
|
||||
|
||||
for name in required:
|
||||
if name not in args:
|
||||
errors.append(f"missing required: {name}")
|
||||
|
||||
for name, value in args.items():
|
||||
prop = props.get(name)
|
||||
if prop is None:
|
||||
errors.append(f"unknown field: {name}")
|
||||
continue
|
||||
coerced, err = _coerce(value, prop)
|
||||
if err:
|
||||
errors.append(f"{name}: {err}")
|
||||
continue
|
||||
if "enum" in prop and coerced not in prop["enum"]:
|
||||
errors.append(f"{name}: {coerced!r} not in {prop['enum']}")
|
||||
continue
|
||||
if prop.get("type") in ("number", "integer"):
|
||||
if "minimum" in prop and coerced < prop["minimum"]:
|
||||
errors.append(f"{name}: {coerced} < minimum {prop['minimum']}")
|
||||
continue
|
||||
if "maximum" in prop and coerced > prop["maximum"]:
|
||||
errors.append(f"{name}: {coerced} > maximum {prop['maximum']}")
|
||||
continue
|
||||
out[name] = coerced
|
||||
|
||||
return out, errors
|
||||
|
||||
|
||||
class ToolRegistry:
|
||||
def __init__(self) -> None:
|
||||
self._tools: dict[str, ToolDef] = {}
|
||||
|
||||
def register(self, tool: ToolDef) -> None:
|
||||
self._tools[tool.name] = tool
|
||||
|
||||
def catalog(self) -> list[dict[str, Any]]:
|
||||
return [
|
||||
{"name": t.name, "description": t.description,
|
||||
"input_schema": t.input_schema}
|
||||
for t in self._tools.values()
|
||||
]
|
||||
|
||||
def dispatch(self, call: ToolCall) -> ToolResult:
|
||||
tool = self._tools.get(call.name)
|
||||
if tool is None:
|
||||
return ToolResult(call.tool_use_id, False,
|
||||
f"error: unknown tool {call.name!r}")
|
||||
validated, errors = validate(call.args, tool.input_schema)
|
||||
if errors:
|
||||
return ToolResult(call.tool_use_id, False,
|
||||
"validation error: " + "; ".join(errors))
|
||||
try:
|
||||
return ToolResult(call.tool_use_id, True, tool.executor(**validated))
|
||||
except Exception as e:
|
||||
return ToolResult(call.tool_use_id, False,
|
||||
f"execution error: {type(e).__name__}: {e}")
|
||||
|
||||
def dispatch_many(self, calls: list[ToolCall]) -> list[ToolResult]:
|
||||
return [self.dispatch(c) for c in calls]
|
||||
|
||||
|
||||
def add(a: int, b: int) -> str:
|
||||
return str(a + b)
|
||||
|
||||
|
||||
def multiply(a: int, b: int) -> str:
|
||||
return str(a * b)
|
||||
|
||||
|
||||
def classify(status: str) -> str:
|
||||
return f"classified as {status}"
|
||||
|
||||
|
||||
def main() -> None:
|
||||
print("=" * 70)
|
||||
print("TOOL USE and FUNCTION CALLING — Phase 14, Lesson 06")
|
||||
print("=" * 70)
|
||||
|
||||
reg = ToolRegistry()
|
||||
reg.register(ToolDef(
|
||||
name="add",
|
||||
description="Add two integers a and b. Use for any integer addition.",
|
||||
input_schema={
|
||||
"type": "object",
|
||||
"properties": {"a": {"type": "integer"}, "b": {"type": "integer"}},
|
||||
"required": ["a", "b"],
|
||||
},
|
||||
executor=add,
|
||||
))
|
||||
reg.register(ToolDef(
|
||||
name="multiply",
|
||||
description="Multiply two integers a and b. Prefer multiplication over looped addition.",
|
||||
input_schema={
|
||||
"type": "object",
|
||||
"properties": {"a": {"type": "integer"}, "b": {"type": "integer"}},
|
||||
"required": ["a", "b"],
|
||||
},
|
||||
executor=multiply,
|
||||
))
|
||||
reg.register(ToolDef(
|
||||
name="classify",
|
||||
description="Classify a status as one of the allowed labels.",
|
||||
input_schema={
|
||||
"type": "object",
|
||||
"properties": {"status": {"type": "string",
|
||||
"enum": ["open", "closed", "pending"]}},
|
||||
"required": ["status"],
|
||||
},
|
||||
executor=classify,
|
||||
))
|
||||
|
||||
print("\ncatalog (as presented to the model)")
|
||||
for entry in reg.catalog():
|
||||
print(f" - {entry['name']}: {entry['description']}")
|
||||
|
||||
calls = [
|
||||
ToolCall("u01", "add", {"a": 2, "b": 3}),
|
||||
ToolCall("u02", "multiply", {"a": "4", "b": 5}),
|
||||
ToolCall("u03", "classify", {"status": "in_progress"}),
|
||||
ToolCall("u04", "classify", {"status": "open"}),
|
||||
ToolCall("u05", "subtract", {"a": 1, "b": 2}),
|
||||
]
|
||||
print("\nparallel dispatch (5 calls in one turn)")
|
||||
for result in reg.dispatch_many(calls):
|
||||
tag = "OK " if result.ok else "ERR"
|
||||
print(f" {result.tool_use_id} {tag}: {result.content}")
|
||||
|
||||
print()
|
||||
print("observation shape: every validation failure is a structured error")
|
||||
print("string the agent can read and retry against. never raise to the loop.")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,266 @@
|
||||
// Phase 14 Lesson 06 — tool use and function calling, in TypeScript.
|
||||
//
|
||||
// Stdlib tool registry with JSON Schema subset validation and parallel dispatch.
|
||||
// Subset: required fields, string/integer/number/boolean/array/object,
|
||||
// enum, minimum/maximum. Every validation failure becomes a structured
|
||||
// observation so an agent can retry.
|
||||
//
|
||||
// References:
|
||||
// OpenAI function-calling https://platform.openai.com/docs/guides/function-calling
|
||||
// Anthropic tool-use https://docs.anthropic.com/en/docs/build-with-claude/tool-use
|
||||
// JSON Schema 2020-12 https://json-schema.org/draft/2020-12
|
||||
//
|
||||
// Run: npx tsx code/main.ts
|
||||
|
||||
type Primitive = "integer" | "number" | "boolean" | "string" | "array" | "object";
|
||||
|
||||
type PropSchema = {
|
||||
type: Primitive;
|
||||
enum?: unknown[];
|
||||
minimum?: number;
|
||||
maximum?: number;
|
||||
};
|
||||
|
||||
type ToolInputSchema = {
|
||||
type: "object";
|
||||
properties: Record<string, PropSchema>;
|
||||
required?: string[];
|
||||
};
|
||||
|
||||
type ToolArgs = Record<string, unknown>;
|
||||
|
||||
type ToolDef = {
|
||||
name: string;
|
||||
description: string;
|
||||
inputSchema: ToolInputSchema;
|
||||
executor: (args: ToolArgs) => string;
|
||||
timeoutMs?: number;
|
||||
};
|
||||
|
||||
type ToolCall = {
|
||||
toolUseId: string;
|
||||
name: string;
|
||||
args: ToolArgs;
|
||||
};
|
||||
|
||||
type ToolResult = {
|
||||
toolUseId: string;
|
||||
ok: boolean;
|
||||
content: string;
|
||||
};
|
||||
|
||||
function describeType(value: unknown): string {
|
||||
if (value === null) return "null";
|
||||
if (Array.isArray(value)) return "array";
|
||||
if (typeof value === "number" && Number.isInteger(value)) return "integer";
|
||||
return typeof value;
|
||||
}
|
||||
|
||||
function coerce(value: unknown, schema: PropSchema): { value: unknown; error: string | null } {
|
||||
const t = schema.type;
|
||||
if (t === "integer") {
|
||||
if (typeof value === "number" && Number.isInteger(value)) return { value, error: null };
|
||||
if (typeof value === "string") {
|
||||
const parsed = Number(value);
|
||||
if (Number.isInteger(parsed)) return { value: parsed, error: null };
|
||||
return { value, error: `cannot coerce string ${JSON.stringify(value)} to integer` };
|
||||
}
|
||||
return { value, error: `expected integer, got ${describeType(value)}` };
|
||||
}
|
||||
if (t === "number") {
|
||||
if (typeof value === "number") return { value, error: null };
|
||||
if (typeof value === "string") {
|
||||
const parsed = Number(value);
|
||||
if (Number.isFinite(parsed)) return { value: parsed, error: null };
|
||||
return { value, error: `cannot coerce string ${JSON.stringify(value)} to number` };
|
||||
}
|
||||
return { value, error: `expected number, got ${describeType(value)}` };
|
||||
}
|
||||
if (t === "boolean") {
|
||||
if (typeof value === "boolean") return { value, error: null };
|
||||
return { value, error: `expected boolean, got ${describeType(value)}` };
|
||||
}
|
||||
if (t === "string") {
|
||||
if (typeof value === "string") return { value, error: null };
|
||||
return { value, error: `expected string, got ${describeType(value)}` };
|
||||
}
|
||||
if (t === "array") {
|
||||
if (Array.isArray(value)) return { value, error: null };
|
||||
return { value, error: `expected array, got ${describeType(value)}` };
|
||||
}
|
||||
if (t === "object") {
|
||||
if (typeof value === "object" && value !== null && !Array.isArray(value)) {
|
||||
return { value, error: null };
|
||||
}
|
||||
return { value, error: `expected object, got ${describeType(value)}` };
|
||||
}
|
||||
return { value, error: null };
|
||||
}
|
||||
|
||||
function validate(args: ToolArgs, schema: ToolInputSchema): { out: ToolArgs; errors: string[] } {
|
||||
const errors: string[] = [];
|
||||
const props = schema.properties;
|
||||
const required = schema.required ?? [];
|
||||
const out: ToolArgs = {};
|
||||
|
||||
for (const name of required) {
|
||||
if (!(name in args)) errors.push(`missing required: ${name}`);
|
||||
}
|
||||
|
||||
for (const [name, value] of Object.entries(args)) {
|
||||
const prop = props[name];
|
||||
if (!prop) {
|
||||
errors.push(`unknown field: ${name}`);
|
||||
continue;
|
||||
}
|
||||
const { value: coerced, error } = coerce(value, prop);
|
||||
if (error) {
|
||||
errors.push(`${name}: ${error}`);
|
||||
continue;
|
||||
}
|
||||
if (prop.enum && !prop.enum.includes(coerced as never)) {
|
||||
errors.push(`${name}: ${JSON.stringify(coerced)} not in ${JSON.stringify(prop.enum)}`);
|
||||
continue;
|
||||
}
|
||||
if (prop.type === "number" || prop.type === "integer") {
|
||||
const numVal = coerced as number;
|
||||
if (prop.minimum !== undefined && numVal < prop.minimum) {
|
||||
errors.push(`${name}: ${numVal} < minimum ${prop.minimum}`);
|
||||
continue;
|
||||
}
|
||||
if (prop.maximum !== undefined && numVal > prop.maximum) {
|
||||
errors.push(`${name}: ${numVal} > maximum ${prop.maximum}`);
|
||||
continue;
|
||||
}
|
||||
}
|
||||
out[name] = coerced;
|
||||
}
|
||||
|
||||
return { out, errors };
|
||||
}
|
||||
|
||||
class ToolRegistry {
|
||||
private tools = new Map<string, ToolDef>();
|
||||
|
||||
register(tool: ToolDef): void {
|
||||
this.tools.set(tool.name, tool);
|
||||
}
|
||||
|
||||
catalog(): Array<Pick<ToolDef, "name" | "description" | "inputSchema">> {
|
||||
return [...this.tools.values()].map((t) => ({
|
||||
name: t.name,
|
||||
description: t.description,
|
||||
inputSchema: t.inputSchema,
|
||||
}));
|
||||
}
|
||||
|
||||
dispatch(call: ToolCall): ToolResult {
|
||||
const tool = this.tools.get(call.name);
|
||||
if (!tool) {
|
||||
return { toolUseId: call.toolUseId, ok: false, content: `error: unknown tool ${JSON.stringify(call.name)}` };
|
||||
}
|
||||
const { out, errors } = validate(call.args, tool.inputSchema);
|
||||
if (errors.length > 0) {
|
||||
return {
|
||||
toolUseId: call.toolUseId,
|
||||
ok: false,
|
||||
content: `validation error: ${errors.join("; ")}`,
|
||||
};
|
||||
}
|
||||
try {
|
||||
return { toolUseId: call.toolUseId, ok: true, content: tool.executor(out) };
|
||||
} catch (err) {
|
||||
const e = err as Error;
|
||||
return {
|
||||
toolUseId: call.toolUseId,
|
||||
ok: false,
|
||||
content: `execution error: ${e.name}: ${e.message}`,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
dispatchMany(calls: ToolCall[]): ToolResult[] {
|
||||
return calls.map((c) => this.dispatch(c));
|
||||
}
|
||||
}
|
||||
|
||||
function add(args: ToolArgs): string {
|
||||
const a = args.a as number;
|
||||
const b = args.b as number;
|
||||
return String(a + b);
|
||||
}
|
||||
|
||||
function multiply(args: ToolArgs): string {
|
||||
const a = args.a as number;
|
||||
const b = args.b as number;
|
||||
return String(a * b);
|
||||
}
|
||||
|
||||
function classify(args: ToolArgs): string {
|
||||
return `classified as ${args.status as string}`;
|
||||
}
|
||||
|
||||
function main(): void {
|
||||
console.log("=".repeat(70));
|
||||
console.log("TOOL USE and FUNCTION CALLING — Phase 14, Lesson 06 (TypeScript port)");
|
||||
console.log("=".repeat(70));
|
||||
|
||||
const reg = new ToolRegistry();
|
||||
reg.register({
|
||||
name: "add",
|
||||
description: "Add two integers a and b. Use for any integer addition.",
|
||||
inputSchema: {
|
||||
type: "object",
|
||||
properties: { a: { type: "integer" }, b: { type: "integer" } },
|
||||
required: ["a", "b"],
|
||||
},
|
||||
executor: add,
|
||||
});
|
||||
reg.register({
|
||||
name: "multiply",
|
||||
description: "Multiply two integers a and b. Prefer multiplication over looped addition.",
|
||||
inputSchema: {
|
||||
type: "object",
|
||||
properties: { a: { type: "integer" }, b: { type: "integer" } },
|
||||
required: ["a", "b"],
|
||||
},
|
||||
executor: multiply,
|
||||
});
|
||||
reg.register({
|
||||
name: "classify",
|
||||
description: "Classify a status as one of the allowed labels.",
|
||||
inputSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
status: { type: "string", enum: ["open", "closed", "pending"] },
|
||||
},
|
||||
required: ["status"],
|
||||
},
|
||||
executor: classify,
|
||||
});
|
||||
|
||||
console.log("\ncatalog (as presented to the model)");
|
||||
for (const entry of reg.catalog()) {
|
||||
console.log(` - ${entry.name}: ${entry.description}`);
|
||||
}
|
||||
|
||||
const calls: ToolCall[] = [
|
||||
{ toolUseId: "u01", name: "add", args: { a: 2, b: 3 } },
|
||||
{ toolUseId: "u02", name: "multiply", args: { a: "4", b: 5 } },
|
||||
{ toolUseId: "u03", name: "classify", args: { status: "in_progress" } },
|
||||
{ toolUseId: "u04", name: "classify", args: { status: "open" } },
|
||||
{ toolUseId: "u05", name: "subtract", args: { a: 1, b: 2 } },
|
||||
];
|
||||
|
||||
console.log("\nparallel dispatch (5 calls in one turn)");
|
||||
for (const result of reg.dispatchMany(calls)) {
|
||||
const tag = result.ok ? "OK " : "ERR";
|
||||
console.log(` ${result.toolUseId} ${tag}: ${result.content}`);
|
||||
}
|
||||
|
||||
console.log();
|
||||
console.log("observation shape: every validation failure is a structured error");
|
||||
console.log("string the agent can read and retry against. never raise to the loop.");
|
||||
}
|
||||
|
||||
main();
|
||||
Reference in New Issue
Block a user