@spendgraph/tools 0.2.0

package/dist/types/tool.js

@@ -0,0 +1 @@
+export {};

package/dist/wire/index.d.ts

@@ -0,0 +1,3 @@
+export { type JsonSchema, type JsonSchemaProperty, toJsonSchema, } from "./json-schema.js";
+export { toMarkdown } from "./markdown.js";
+export { type AnthropicTool, type OpenAITool, toAnthropic, toOpenAI, } from "./providers.js";

package/dist/wire/index.js

@@ -0,0 +1,3 @@
+export { toJsonSchema, } from "./json-schema.js";
+export { toMarkdown } from "./markdown.js";
+export { toAnthropic, toOpenAI, } from "./providers.js";

package/dist/wire/json-schema.d.ts

@@ -0,0 +1,26 @@
+import type { FieldSpec } from "@spendgraph/sdk";
+export interface JsonSchema {
+    type: "object";
+    properties: Record<string, JsonSchemaProperty>;
+    required: string[];
+}
+export interface JsonSchemaProperty {
+    type: "string" | "number" | "boolean" | "array" | "object";
+    description?: string;
+    enum?: string[];
+    default?: string | number | boolean;
+    minimum?: number;
+    maximum?: number;
+    maxLength?: number;
+    items?: {
+        type: "string";
+    };
+}
+export declare const JSON_TYPE: Record<FieldSpec["type"], JsonSchemaProperty["type"]>;
+/**
+ * `FieldSpec[]` as a JSON Schema object.
+ *
+ * `separator`, `trueText` and `falseText` are dropped: they interpolate a value
+ * into a string, which a tool call does not do. So is `datasetKey`.
+ */
+export declare function toJsonSchema(args: FieldSpec[]): JsonSchema;

package/dist/wire/json-schema.js

@@ -0,0 +1,81 @@
+export const JSON_TYPE = {
+    string: "string",
+    text: "string",
+    number: "number",
+    boolean: "boolean",
+    enum: "string",
+    list: "array",
+    json: "object",
+};
+/**
+ * A field's default as a value of its own type.
+ *
+ * `FieldSpec.default` is already-rendered text, so `"5"` on a number field has
+ * to come back as `5` — a schema saying `number` and defaulting to `"5"` is
+ * something providers accept and models then copy.
+ *
+ * `list` and `json` defaults are joined and printed forms that cannot be parsed
+ * back, so they are dropped rather than guessed at.
+ */
+function coerceDefault(field) {
+    const raw = field.default;
+    if (raw === undefined)
+        return undefined;
+    switch (field.type) {
+        case "number": {
+            const n = Number(raw);
+            return Number.isFinite(n) ? n : undefined;
+        }
+        case "boolean": {
+            const t = raw.trim().toLowerCase();
+            if (t === "true" || t === field.trueText?.trim().toLowerCase())
+                return true;
+            if (t === "false" || t === field.falseText?.trim().toLowerCase())
+                return false;
+            return undefined;
+        }
+        case "enum":
+            return field.options?.includes(raw) ? raw : undefined;
+        case "list":
+        case "json":
+            return undefined;
+        default:
+            return raw;
+    }
+}
+/**
+ * `FieldSpec[]` as a JSON Schema object.
+ *
+ * `separator`, `trueText` and `falseText` are dropped: they interpolate a value
+ * into a string, which a tool call does not do. So is `datasetKey`.
+ */
+export function toJsonSchema(args) {
+    const properties = {};
+    for (const field of args) {
+        const property = { type: JSON_TYPE[field.type] };
+        if (field.description)
+            property.description = field.description;
+        if (field.type === "enum" && field.options?.length)
+            property.enum = [...field.options];
+        if (field.type === "list")
+            property.items = { type: "string" };
+        if (field.type === "number") {
+            if (field.min !== undefined)
+                property.minimum = field.min;
+            if (field.max !== undefined)
+                property.maximum = field.max;
+        }
+        if ((field.type === "string" || field.type === "text") && field.maxLength !== undefined) {
+            property.maxLength = field.maxLength;
+        }
+        const fallback = coerceDefault(field);
+        if (fallback !== undefined)
+            property.default = fallback;
+        properties[field.name] = property;
+    }
+    return {
+        type: "object",
+        properties,
+        required: args.filter((a) => a.required).map((a) => a.name),
+    };
+}

package/dist/wire/markdown.d.ts

@@ -0,0 +1,9 @@
+import type { ToolDeclaration } from "../types/index.js";
+/**
+ * Declarations as markdown, for a model with no tools API.
+ *
+ * About a quarter cheaper than the JSON, since JSON Schema is mostly
+ * scaffolding — but you give up structured tool calls and parse intent out of
+ * prose instead. Only worth it where there is no native `tools` array.
+ */
+export declare function toMarkdown(decls: ToolDeclaration[], heading?: string): string;

package/dist/wire/markdown.js

@@ -0,0 +1,42 @@
+import { JSON_TYPE } from "./json-schema.js";
+/**
+ * Neutralises headings inside text about to become markdown.
+ *
+ * A `###` at the start of a line would close the tool's own section and open one
+ * the prompt author never wrote.
+ */
+function escapeHeadings(text) {
+    return text.replace(/^(\s*)(#{1,6})(\s|$)/gm, "$1\\$2$3");
+}
+function argLine(field) {
+    const type = JSON_TYPE[field.type];
+    const notes = [];
+    if (field.description)
+        notes.push(escapeHeadings(field.description.trim()).replace(/\.$/, ""));
+    if (field.type === "enum" && field.options?.length) {
+        notes.push(`one of ${field.options.join(", ")}`);
+    }
+    if (field.type === "number" && (field.min !== undefined || field.max !== undefined)) {
+        notes.push(`between ${field.min ?? "any"} and ${field.max ?? "any"}`);
+    }
+    if (field.default !== undefined)
+        notes.push(`defaults to ${field.default}`);
+    const head = `- \`${field.name}\` (${type}${field.required ? ", required" : ""})`;
+    return notes.length ? `${head} ${notes.join(". ")}.` : `${head}`;
+}
+/**
+ * Declarations as markdown, for a model with no tools API.
+ *
+ * About a quarter cheaper than the JSON, since JSON Schema is mostly
+ * scaffolding — but you give up structured tool calls and parse intent out of
+ * prose instead. Only worth it where there is no native `tools` array.
+ */
+export function toMarkdown(decls, heading = "## Tools") {
+    if (decls.length === 0)
+        return "";
+    const sections = decls.map((d) => {
+        const args = d.args.length ? d.args.map(argLine).join("\n") : "_Takes no arguments._";
+        return `### ${d.name}\n${escapeHeadings(d.description)}\n\n${args}`;
+    });
+    return `${heading}\n\n${sections.join("\n\n")}`;
+}

package/dist/wire/providers.d.ts

@@ -0,0 +1,26 @@
+import type { ToolDeclaration } from "../types/index.js";
+import { type JsonSchema } from "./json-schema.js";
+/**
+ * A tool as one provider wants it.
+ *
+ * Envelope work: every provider asks for the same three things differently. It
+ * lives here because the easy mistakes — which `FieldSpec` keys map, and which
+ * lie about their type — are the same for everyone.
+ */
+export interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: JsonSchema;
+}
+export interface OpenAITool {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: JsonSchema;
+    };
+}
+/** Declarations in the shape the Anthropic Messages API takes. */
+export declare function toAnthropic(decls: ToolDeclaration[]): AnthropicTool[];
+/** Declarations in the shape the OpenAI chat completions API takes. */
+export declare function toOpenAI(decls: ToolDeclaration[]): OpenAITool[];

package/dist/wire/providers.js

@@ -0,0 +1,20 @@
+import { toJsonSchema } from "./json-schema.js";
+/** Declarations in the shape the Anthropic Messages API takes. */
+export function toAnthropic(decls) {
+    return decls.map((d) => ({
+        name: d.name,
+        description: d.description,
+        input_schema: toJsonSchema(d.args),
+    }));
+}
+/** Declarations in the shape the OpenAI chat completions API takes. */
+export function toOpenAI(decls) {
+    return decls.map((d) => ({
+        type: "function",
+        function: {
+            name: d.name,
+            description: d.description,
+            parameters: toJsonSchema(d.args),
+        },
+    }));
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@spendgraph/tools",
+  "version": "0.2.0",
+  "description": "Declare a tool once, offer the right few, and record what was called.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fnLog0/spendgraph.git",
+    "directory": "packages/tools"
+  },
+  "homepage": "https://github.com/fnLog0/spendgraph#readme",
+  "bugs": {
+    "url": "https://github.com/fnLog0/spendgraph/issues"
+  },
+  "keywords": [
+    "llm",
+    "tools",
+    "function-calling",
+    "agent",
+    "anthropic",
+    "openai"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./wire": {
+      "types": "./dist/wire/index.d.ts",
+      "import": "./dist/wire/index.js"
+    },
+    "./internals": {
+      "types": "./dist/internals.d.ts",
+      "import": "./dist/internals.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "examples": "npm run build && node examples/02-select/01-shortlist.mjs"
+  },
+  "dependencies": {
+    "@locusgraph/client": "^0.8.1",
+    "@spendgraph/sdk": "^0.2.0"
+  },
+  "devDependencies": {
+    "@spendgraph/prompt": "^0.2.0",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}