@botbotgo/better-call 0.1.23 → 0.1.25

package/README.md

@@ -8,10 +8,14 @@
 [![license](https://img.shields.io/npm/l/@botbotgo/better-call.svg)](LICENSE)
 [![release](https://github.com/botbotgo/better-call/actions/workflows/release.yml/badge.svg)](https://github.com/botbotgo/better-call/actions/workflows/release.yml)
 
-BetterCall is a small runtime reliability layer for LangChain and LLM tool calls.
+BetterCall is a small-model tool-call reliability layer for LangChain and custom agent runtimes.
 
 Wrap your existing tools, validate model-generated calls before execution, and optionally ask a repair model to fix rejected calls. In full BFCL v4 remote Ollama runs, the best measured lift was `granite4.1:3b`: **73.4% raw -> 83.8% with BetterCall**.
 
+<p align="center">
+  <img src="docs/benchmark-lift.svg" alt="BetterCall improved granite4.1:3b tool-call accuracy from 73.4% to 83.8% on BFCL v4 remote Ollama runs">
+</p>
+
 ```ts
 import { betterTools } from "@botbotgo/better-call";
 
@@ -20,6 +24,12 @@ const tools = betterTools([searchTool, calculatorTool]);
 
 No model means validate and block only. Add `repairModel` when you want automatic repair.
 
+Try the built-in demo after installing:
+
+```bash
+npx @botbotgo/better-call demo
+```
+
 ## Why BetterCall?
 
 Small models often know that a tool is needed but still fail at the boundary: wrong tool names, malformed arguments, schema drift, extra fields, or raw tool-call-shaped text. BetterCall sits at that boundary and gives you a typed, auditable way to accept, repair, or reject the call before the real tool runs.
@@ -30,6 +40,17 @@ Small models often know that a tool is needed but still fail at the boundary: wr
 - Repair rejected calls with a LangChain chat model or custom callback.
 - Keep lower-level primitives available for custom runtimes and gateways.
 
+## Examples
+
+The `examples/` directory has copyable starting points:
+
+- `examples/langchain-basic.mjs`: wrap a LangChain-style tool and repair bad args.
+- `examples/ollama-small-model.mjs`: use an Ollama repair callback for a small local model.
+- `examples/gateway-repair.mjs`: repair an invalid tool name at a custom runtime or MCP gateway boundary.
+- `examples/adapters/langchain-tool-wrapper.mjs`: tiny adapter helper for LangChain-style tools.
+- `examples/adapters/mcp-gateway-boundary.mjs`: MCP-style gateway boundary pattern.
+- `examples/adapters/openai-compatible-repair.mjs`: OpenAI-compatible local endpoint repair callback.
+
 ## Installation
 
 ```bash
@@ -230,6 +251,15 @@ Latest completed remote run artifact: `benchmarks/bfcl-real-remote-completed-sum
 | `qwen3.5:4b` | 3,625 | 43.6% | 43.4% | -0.2pp | 1,847 |
 | `gemma4:e2b` | 3,625 | 24.3% | 24.7% | +0.4pp | 2,641 |
 
+## Positioning and Launch Assets
+
+- `docs/marketing/positioning.md`: product positioning, audience, differentiators, and calls to action.
+- `docs/marketing/launch-post.md`: launch-post draft and short social version.
+- `docs/marketing/growth-checklist.md`: channel-by-channel launch and adoption checklist.
+- `docs/recipes/`: focused integration recipes.
+- `docs/faq.md`: adoption and boundary FAQ.
+- `docs/case-studies/stable-harness-tool-gateway.md`: production gateway integration pattern.
+
 ## Requirements
 
 BetterCall is an ESM package for modern Node.js runtimes. It has one runtime dependency: `zod`.

package/docs/benchmark-lift.svg

@@ -0,0 +1,30 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="760" height="330" viewBox="0 0 760 330" role="img" aria-labelledby="title desc">
+  <title id="title">BetterCall BFCL small-model lift</title>
+  <desc id="desc">BetterCall improves granite4.1:3b tool-call accuracy from 73.4 percent raw to 83.8 percent on BFCL v4 remote Ollama runs.</desc>
+
+  <rect width="760" height="330" rx="18" fill="#0f172a"/>
+  <rect x="26" y="26" width="708" height="278" rx="16" fill="#111827" stroke="#334155"/>
+
+  <text x="54" y="70" fill="#f8fafc" font-family="Inter, Arial, sans-serif" font-size="27" font-weight="800">Tool-call reliability lift</text>
+  <text x="54" y="100" fill="#cbd5e1" font-family="Inter, Arial, sans-serif" font-size="14">BFCL v4 remote Ollama · granite4.1:3b · 3,625 cases</text>
+
+  <g>
+    <text x="54" y="148" fill="#e2e8f0" font-family="Inter, Arial, sans-serif" font-size="17" font-weight="700">Raw model</text>
+    <rect x="54" y="164" width="480" height="30" rx="15" fill="#1e293b"/>
+    <rect x="54" y="164" width="352" height="30" rx="15" fill="#64748b"/>
+    <text x="560" y="188" fill="#f8fafc" font-family="Inter, Arial, sans-serif" font-size="25" font-weight="800">73.4%</text>
+  </g>
+
+  <g>
+    <text x="54" y="226" fill="#e2e8f0" font-family="Inter, Arial, sans-serif" font-size="17" font-weight="700">With BetterCall</text>
+    <rect x="54" y="242" width="480" height="30" rx="15" fill="#1e293b"/>
+    <rect x="54" y="242" width="402" height="30" rx="15" fill="#22c55e"/>
+    <text x="560" y="266" fill="#f8fafc" font-family="Inter, Arial, sans-serif" font-size="25" font-weight="800">83.8%</text>
+  </g>
+
+  <rect x="560" y="204" width="106" height="30" rx="15" fill="#052e16" stroke="#22c55e" stroke-opacity="0.55"/>
+  <text x="613" y="225" fill="#bbf7d0" font-family="Inter, Arial, sans-serif" font-size="15" font-weight="800" text-anchor="middle">+10.4pp</text>
+
+  <line x1="54" y1="288" x2="332" y2="288" stroke="#334155"/>
+  <text x="352" y="293" fill="#94a3b8" font-family="Inter, Arial, sans-serif" font-size="13">Validate, repair, then execute.</text>
+</svg>

package/docs/case-studies/stable-harness-tool-gateway.md

@@ -0,0 +1,42 @@
+# Case Study: BetterCall Inside a Tool Gateway
+
+`stable-harness` uses BetterCall at the tool gateway boundary, not as a replacement for the agent loop.
+
+## Boundary
+
+- The agent or workflow backend decides that a tool should be called.
+- The runtime gateway owns the visible tool inventory and hidden or blocked tools.
+- BetterCall validates, repairs, or rejects the selected tool call before the real tool executes.
+- The original tool implementation still executes only after the repaired call passes the boundary.
+
+## Flow
+
+```mermaid
+sequenceDiagram
+  participant Agent as Agent backend
+  participant Gateway as Tool gateway
+  participant BC as BetterCall
+  participant Tool as Real tool
+
+  Agent->>Gateway: tool id + args
+  Gateway->>BC: visible tools + candidate call
+  BC-->>Gateway: accepted, repaired, or rejected
+  alt accepted or repaired
+    Gateway->>Tool: execute safe args
+    Tool-->>Gateway: result
+  else rejected
+    Gateway-->>Agent: structured validation error
+  end
+```
+
+## Why This Matters
+
+The gateway can keep runtime policy and authorization local while BetterCall handles tool-call contract reliability:
+
+- wrong or unavailable tool names
+- malformed arguments
+- schema drift
+- enum and type errors
+- raw tool-call-shaped text
+
+This keeps BetterCall small: it is the reliability layer inside an agent runtime, not another agent framework.

package/docs/faq.md

@@ -0,0 +1,25 @@
+# BetterCall FAQ
+
+## When should I use BetterCall?
+
+Use BetterCall when your model already emits tool calls, but those calls sometimes fail before execution because of wrong tool names, malformed arguments, schema drift, invalid enum values, extra fields, or raw tool-call-shaped text.
+
+## When should I not use BetterCall?
+
+Do not use BetterCall as a planning system, memory layer, agent loop, authorization system, or replacement for human approval. Keep those responsibilities in your runtime. BetterCall belongs at the tool-call boundary.
+
+## Does BetterCall require a repair model?
+
+No. Without `repair` or `repairModel`, BetterCall validates and blocks invalid calls. Add a repair model or callback only when automatic repair is acceptable for your application.
+
+## Can BetterCall execute hidden or blocked tools?
+
+No. Tool selection repair is constrained by the visible tool inventory you pass in. Hidden tools remain blocked.
+
+## Is BetterCall only for LangChain?
+
+No. `betterTools(...)` works with LangChain-style tools, but the lower-level APIs work in custom runtimes and tool gateways.
+
+## Where should semantic policy live?
+
+Keep semantic policy in your tool boundary with `validate(...)` or your gateway. BetterCall can carry the validation result and block or repair around it, but your runtime should own domain policy.

package/docs/marketing/growth-checklist.md

@@ -0,0 +1,73 @@
+# BetterCall Growth Checklist
+
+The goal is to move developers through three stages:
+
+1. Notice the problem.
+2. Run a small example.
+3. Keep BetterCall in their runtime or tool gateway.
+
+## Repository
+
+- [x] Use a precise GitHub description.
+- [x] Add discoverable GitHub topics: `tool-calling`, `function-calling`, `langchain`, `ollama`, `mcp`, `small-models`, `tool-call-repair`.
+- [x] Put the benchmark lift near the top of the README.
+- [x] Add copyable examples.
+- [x] Add `npx @botbotgo/better-call demo`.
+- [x] Add focused recipes for common integration problems.
+- [x] Add a stable-harness gateway case study.
+- [x] Add an adapter request issue template.
+- [ ] Add a short GIF or terminal recording showing before and after repair.
+- [ ] Add a `good first issue` label set for example adapters and docs.
+
+## npm
+
+- [x] Improve package description and keywords.
+- [x] Include examples and README assets in the package allowlist.
+- [x] Add a package binary for the built-in demo.
+- [ ] Publish the next patch version so npm metadata and tarball include the new assets.
+- [ ] Verify the npm package page renders the README image and examples.
+
+## Content
+
+- [x] Write launch-post draft.
+- [x] Write short social version.
+- [ ] Publish a technical post using the launch draft.
+- [ ] Publish a benchmark-focused post explaining the BFCL wrapper methodology.
+- [ ] Publish a comparison post: BetterCall vs structured-output retries vs guardrails.
+
+## Developer Communities
+
+- [ ] Hacker News: launch with the problem-first title, not a marketing title.
+- [ ] Reddit: post to relevant LLM engineering communities with the benchmark and example.
+- [ ] X/LinkedIn: short thread with before/after tool call examples.
+- [ ] LangChain community: share the `betterTools(...)` example.
+- [ ] Ollama/local-model community: share the BFCL small-model result.
+- [ ] MCP community: share the gateway repair example.
+
+## Ecosystem
+
+- [x] Add LangChain-style example.
+- [x] Add Ollama small-model example.
+- [x] Add custom gateway repair example.
+- [x] Add MCP server/client gateway example.
+- [x] Add LangChain adapter helper example.
+- [x] Add OpenAI-compatible local model example.
+- [x] Add LangGraph/stable-harness integration note when stable-harness is the public case study.
+
+## Conversion
+
+- [x] Add a one-command reproduction path for the smallest local demo.
+- [x] Add a "When should I use BetterCall?" FAQ.
+- [x] Add a "When should I not use BetterCall?" FAQ to build trust.
+- [x] Add a simple issue template for adapter requests.
+- [ ] Track install/download/star movement after each post.
+
+## Launch Sequence
+
+1. Publish the next patch version with the README/assets/examples.
+2. Verify GitHub and npm pages.
+3. Post the short social version.
+4. Post the technical launch article.
+5. Share the three examples to the matching communities.
+6. Collect adapter requests as issues.
+7. Build the top requested adapter/example first.

package/docs/marketing/launch-post.md

@@ -0,0 +1,50 @@
+# Launch Post Draft
+
+## Title Options
+
+- Small models can choose the right tool and still break at the execution boundary
+- BetterCall: a tiny reliability layer for LLM tool calls
+- Fix malformed LLM tool calls before they execute
+
+## Post
+
+LLM tool calling has a boring failure mode that shows up constantly with small models:
+
+The model knows a tool is needed, but the actual call is not executable.
+
+It may pick a near-miss tool name, send `symbol` instead of `ticker`, use an enum value the schema rejects, include extra fields, or emit raw tool-call-shaped text. If your runtime sends that straight to a real tool, the best case is a failed request. The worse case is the wrong operation reaching production code.
+
+BetterCall is a small TypeScript reliability layer for that boundary.
+
+```ts
+import { betterTools } from "@botbotgo/better-call";
+
+const tools = betterTools([searchTool, calculatorTool], {
+  repairModel,
+});
+```
+
+It wraps existing LangChain-style tools, validates model-generated calls before execution, optionally asks a repair model or custom callback to fix rejected calls, validates again, and only then invokes the original tool.
+
+The lower-level API also works at a custom runtime or MCP gateway boundary:
+
+```ts
+import { repairToolCall } from "@botbotgo/better-call";
+```
+
+In full BFCL v4 remote Ollama runs, the best measured lift was `granite4.1:3b`: `73.4%` raw to `83.8%` with BetterCall across `3,625` cases.
+
+BetterCall is not an agent framework. It is the small reliability layer inside one.
+
+Repo: https://github.com/botbotgo/better-call
+Package: https://www.npmjs.com/package/@botbotgo/better-call
+
+## Short Social Version
+
+Small models often know which tool they need, then fail at the execution boundary: wrong tool name, malformed args, schema drift, extra fields, raw tool-call-shaped text.
+
+BetterCall wraps existing tools and validates, repairs, or rejects calls before real execution.
+
+`granite4.1:3b`: `73.4%` raw to `83.8%` with BetterCall on BFCL v4 remote Ollama runs.
+
+https://github.com/botbotgo/better-call

package/docs/marketing/positioning.md

@@ -0,0 +1,43 @@
+# BetterCall Positioning
+
+## One-line Positioning
+
+BetterCall is a small-model tool-call reliability layer for LangChain and custom agent runtimes.
+
+## Short Pitch
+
+Small models often know that a tool is needed but fail at the execution boundary: wrong tool names, malformed arguments, schema drift, extra fields, or raw tool-call-shaped text. BetterCall wraps existing tools and validates, repairs, or rejects the call before the real tool runs.
+
+## Primary Audience
+
+- Developers building LangChain JS or custom TypeScript agent runtimes.
+- Teams using small local models through Ollama or OpenAI-compatible endpoints.
+- Runtime authors who need a tool gateway boundary, not another full agent framework.
+- MCP or tool-server authors who need schema-aware call repair before execution.
+
+## Differentiation
+
+| Alternative | What it usually solves | BetterCall position |
+| --- | --- | --- |
+| Agent frameworks | Agent loop, memory, planning, tool invocation | Drop-in reliability layer at the tool boundary |
+| Guardrails frameworks | Input/output safety and policy checks | Tool-call contract validation and repair |
+| Structured-output libraries | JSON/object extraction and retries | Existing tool-call repair before execution |
+| MCP platforms | Hosted API/tool surfaces | Independent npm package for any JS runtime |
+
+## Proof Point
+
+In full BFCL v4 remote Ollama runs, the best measured lift was `granite4.1:3b`: `73.4%` raw to `83.8%` with BetterCall across `3,625` cases.
+
+## Core Messages
+
+- Small models can pick the right intent and still break at the tool boundary.
+- BetterCall validates and repairs before execution, so unsafe or malformed calls do not reach real tools.
+- It works with existing LangChain-style tools and lower-level custom gateways.
+- It is not an agent framework; it is the reliability layer inside one.
+
+## Calls To Action
+
+- Install: `npm install @botbotgo/better-call`
+- Try the 30-line examples in `examples/`
+- Run `npm run bench:bfcl` to reproduce the wrapper sanity benchmark
+- Use `repairToolCall(...)` at a runtime or MCP gateway boundary

package/docs/recipes/README.md

@@ -0,0 +1,11 @@
+# BetterCall Recipes
+
+Each recipe solves one integration problem with a small copyable pattern.
+
+- `wrong-tool-name.md`: Repair a tool name before gateway dispatch.
+- `zod-schema.md`: Use Zod object schemas or Zod-shaped records.
+- `validate-only.md`: Run without a repair model and block invalid calls.
+- `ollama-repair.md`: Use a local Ollama model as the repair callback.
+- `semantic-validator.md`: Keep domain validation in your tool boundary.
+
+See also `../faq.md` for adoption and boundary guidance.

package/docs/recipes/ollama-repair.md

@@ -0,0 +1,33 @@
+# Recipe: Use Ollama as the Repair Model
+
+Use `reliableToolCalls(...)` when you want full control over the repair callback.
+
+```ts
+import { reliableToolCalls } from "@botbotgo/better-call";
+
+const result = await reliableToolCalls({
+  userInput,
+  tools,
+  calls,
+  repair: async ({ userInput, tools, calls, issues }) => {
+    const prompt = [
+      "Return corrected JSON only as {\"calls\":[{\"tool\":\"name\",\"args\":{}}]}.",
+      `User: ${userInput}`,
+      `Tools: ${JSON.stringify(tools)}`,
+      `Rejected calls: ${JSON.stringify(calls)}`,
+      `Issues: ${JSON.stringify(issues)}`,
+    ].join("\n");
+
+    const response = await fetch("http://127.0.0.1:11434/api/generate", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ model: "granite4.1:3b", prompt, stream: false, format: "json" }),
+    });
+
+    const json = await response.json();
+    return JSON.parse(json.response).calls;
+  },
+});
+```
+
+See `examples/ollama-small-model.mjs` for a runnable version.

package/docs/recipes/semantic-validator.md

@@ -0,0 +1,25 @@
+# Recipe: Add Semantic Validation
+
+Schema validation checks shape. Semantic validation checks whether an argument is allowed in your runtime.
+
+```ts
+import { betterTools } from "@botbotgo/better-call";
+
+const [safeTool] = betterTools([{
+  name: "deploy",
+  schema: deploySchema,
+  validate: ({ call }) => {
+    if (call.args.environment === "prod") {
+      return [{
+        kind: "semantic",
+        path: "$.args.environment",
+        message: "production deploys require a separate approval path",
+      }];
+    }
+    return [];
+  },
+  invoke: deploy,
+}]);
+```
+
+Keep business policy in `validate(...)`; keep model repair constrained to calls that still pass the tool boundary.

package/docs/recipes/validate-only.md

@@ -0,0 +1,17 @@
+# Recipe: Validate and Block Only
+
+You do not need a repair model. Without `repair` or `repairModel`, BetterCall validates the call and blocks invalid execution.
+
+```ts
+import { betterTools } from "@botbotgo/better-call";
+
+const [safeTool] = betterTools([tool]);
+
+try {
+  await safeTool.invoke(modelArgs);
+} catch (error) {
+  console.error(error.issues);
+}
+```
+
+Use this mode when the cost of a wrong repair is higher than the cost of asking the model or user to try again.

package/docs/recipes/wrong-tool-name.md

@@ -0,0 +1,24 @@
+# Recipe: Repair a Wrong Tool Name
+
+Use `repairToolCall(...)` before a custom runtime, gateway, or MCP-style dispatcher executes a tool.
+
+```ts
+import { repairToolCall } from "@botbotgo/better-call";
+
+const repaired = await repairToolCall({
+  userInput: "Research the current market.",
+  visibleTools: [taskTool],
+  hiddenTools: [shellTool],
+  invalidToolName: "research",
+  args: {
+    subagent_type: "research",
+    description: "Research the current market.",
+  },
+});
+
+if (repaired.status === "repaired") {
+  await dispatch(repaired.toolName, repaired.args);
+}
+```
+
+BetterCall only repairs into the visible tool inventory. Hidden tools remain blocked.

package/docs/recipes/zod-schema.md

@@ -0,0 +1,19 @@
+# Recipe: Use Zod Schemas
+
+BetterCall accepts JSON Schema, Zod object schemas, and Zod-shaped records.
+
+```ts
+import { z } from "zod";
+import { betterTools } from "@botbotgo/better-call";
+
+const tools = betterTools([{
+  name: "stock_quote",
+  schema: z.object({
+    ticker: z.string(),
+    market: z.enum(["US", "HK", "CN"]),
+  }),
+  invoke: async (args) => getStockQuote(args),
+}]);
+```
+
+The same schema normalization is used by the lower-level `reliableToolCalls(...)` and `guardToolCalls(...)` APIs.

package/examples/README.md

@@ -0,0 +1,37 @@
+# BetterCall Examples
+
+Each example is intentionally small enough to copy into an app.
+
+## Examples
+
+- `langchain-basic.mjs`: Wrap a LangChain-style tool and repair invalid args before execution.
+- `ollama-small-model.mjs`: Use an Ollama-compatible repair model callback with `reliableToolCalls`.
+- `gateway-repair.mjs`: Repair an invalid tool name at a custom runtime or MCP gateway boundary.
+- `adapters/langchain-tool-wrapper.mjs`: Tiny adapter helper for LangChain-style tools.
+- `adapters/mcp-gateway-boundary.mjs`: Gateway-boundary pattern for MCP-style tool dispatch.
+- `adapters/openai-compatible-repair.mjs`: Repair callback pattern for OpenAI-compatible local endpoints.
+
+## Run
+
+Build the package first:
+
+```bash
+npm install
+npm run build
+```
+
+Then run an example:
+
+```bash
+node examples/langchain-basic.mjs
+node examples/gateway-repair.mjs
+node examples/adapters/langchain-tool-wrapper.mjs
+node examples/adapters/mcp-gateway-boundary.mjs
+```
+
+The Ollama and OpenAI-compatible examples expect local model endpoints:
+
+```bash
+OLLAMA_BASE_URL=http://127.0.0.1:11434 OLLAMA_MODEL=granite4.1:3b node examples/ollama-small-model.mjs
+OPENAI_BASE_URL=http://127.0.0.1:8000/v1 OPENAI_MODEL=local-model node examples/adapters/openai-compatible-repair.mjs
+```

package/examples/adapters/langchain-tool-wrapper.mjs

@@ -0,0 +1,39 @@
+import { betterTools } from "../../dist/index.js";
+
+export function withBetterCallLangChainTools(tools, options = {}) {
+  return betterTools(tools, options);
+}
+
+const searchTool = {
+  name: "search",
+  description: "Search docs.",
+  schema: {
+    type: "object",
+    properties: {
+      query: { type: "string" },
+      limit: { type: "integer", minimum: 1, maximum: 5 },
+    },
+    required: ["query"],
+    additionalProperties: false,
+  },
+  async invoke(args) {
+    return { searched: args };
+  },
+};
+
+const [search] = withBetterCallLangChainTools([searchTool], {
+  userInput: "Search BetterCall docs.",
+  repairPolicy: {
+    allowCoercion: true,
+    allowClamp: true,
+    allowDropUnknownKeys: true,
+  },
+});
+
+const result = await search.invoke({
+  query: "BetterCall tool repair",
+  limit: "50",
+  debug: true,
+});
+
+console.log(JSON.stringify(result, null, 2));

package/examples/adapters/mcp-gateway-boundary.mjs

@@ -0,0 +1,51 @@
+import { repairToolCall } from "../../dist/index.js";
+
+const tools = [{
+  name: "docs.search",
+  description: "Search project documentation.",
+  schema: {
+    type: "object",
+    properties: {
+      query: { type: "string" },
+      max_results: { type: "integer", minimum: 1, maximum: 10 },
+    },
+    required: ["query"],
+    additionalProperties: false,
+  },
+}];
+
+async function dispatchMcpToolCall(request) {
+  const repaired = await repairToolCall({
+    userInput: request.userInput,
+    visibleTools: tools,
+    invalidToolName: request.name,
+    args: request.arguments,
+    repairPolicy: {
+      allowCoercion: true,
+      allowClamp: true,
+      allowDropUnknownKeys: true,
+    },
+  });
+
+  if (repaired.status === "rejected") {
+    return { error: repaired.reason, violations: repaired.violations };
+  }
+
+  return {
+    name: repaired.toolName,
+    arguments: repaired.args,
+    executed: false,
+  };
+}
+
+const response = await dispatchMcpToolCall({
+  userInput: "Search the docs for BetterCall examples.",
+  name: "search_docs",
+  arguments: {
+    query: "BetterCall examples",
+    max_results: "50",
+    debug: true,
+  },
+});
+
+console.log(JSON.stringify(response, null, 2));

package/examples/adapters/openai-compatible-repair.mjs

@@ -0,0 +1,53 @@
+import { reliableToolCalls } from "../../dist/index.js";
+
+const baseUrl = process.env.OPENAI_BASE_URL ?? "http://127.0.0.1:8000/v1";
+const model = process.env.OPENAI_MODEL ?? "local-model";
+const apiKey = process.env.OPENAI_API_KEY ?? "not-needed-for-local";
+
+const tools = [{
+  name: "stock_quote",
+  description: "Get a stock quote.",
+  schema: {
+    type: "object",
+    properties: {
+      ticker: { type: "string" },
+      market: { type: "string", enum: ["US", "HK", "CN"] },
+    },
+    required: ["ticker", "market"],
+    additionalProperties: false,
+  },
+}];
+
+const result = await reliableToolCalls({
+  userInput: "Get Apple stock in the US market.",
+  tools,
+  calls: [{ tool: "stock_price", args: { symbol: "Apple", market: "NASDAQ" } }],
+  repair: async ({ userInput, tools, calls, issues }) => {
+    const response = await fetch(`${baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        "authorization": `Bearer ${apiKey}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        model,
+        response_format: { type: "json_object" },
+        messages: [{
+          role: "user",
+          content: [
+            "Return corrected JSON only as {\"calls\":[{\"tool\":\"name\",\"args\":{}}]}.",
+            `User: ${userInput}`,
+            `Tools: ${JSON.stringify(tools)}`,
+            `Rejected calls: ${JSON.stringify(calls)}`,
+            `Issues: ${JSON.stringify(issues)}`,
+          ].join("\n"),
+        }],
+      }),
+    });
+    if (!response.ok) throw new Error(`OpenAI-compatible request failed: ${response.status}`);
+    const json = await response.json();
+    return JSON.parse(json.choices[0].message.content).calls;
+  },
+});
+
+console.log(JSON.stringify({ model, result }, null, 2));

package/examples/gateway-repair.mjs

@@ -0,0 +1,25 @@
+import { repairToolCall } from "../dist/index.js";
+
+const visibleTools = [{
+  name: "task",
+  description: "Delegate a task to a visible specialist.",
+  schema: {
+    type: "object",
+    properties: {
+      subagent_type: { type: "string", enum: ["research", "ops"] },
+      description: { type: "string" },
+    },
+    required: ["subagent_type", "description"],
+    additionalProperties: false,
+  },
+}];
+
+const result = await repairToolCall({
+  userInput: "Research the current market.",
+  visibleTools,
+  hiddenTools: [{ name: "shell" }],
+  invalidToolName: "research",
+  args: { subagent_type: "research", description: "Research the current market." },
+});
+
+console.log(JSON.stringify(result, null, 2));

package/examples/langchain-basic.mjs

@@ -0,0 +1,30 @@
+import { betterTools } from "../dist/index.js";
+
+const stockQuote = {
+  name: "stock_quote",
+  description: "Get a stock quote.",
+  schema: {
+    type: "object",
+    properties: {
+      ticker: { type: "string" },
+      market: { type: "string", enum: ["US", "HK", "CN"] },
+    },
+    required: ["ticker", "market"],
+    additionalProperties: false,
+  },
+  async invoke(args) {
+    return { ok: true, quote: args };
+  },
+};
+
+const [safeStockQuote] = betterTools([stockQuote], {
+  userInput: "Get Apple stock in the US market.",
+  repair() {
+    return [{ tool: "stock_quote", args: { ticker: "AAPL", market: "US" } }];
+  },
+});
+
+const before = { symbol: "Apple", market: "NASDAQ" };
+const after = await safeStockQuote.invoke(before);
+
+console.log(JSON.stringify({ before, after }, null, 2));

package/examples/ollama-small-model.mjs

@@ -0,0 +1,46 @@
+import { reliableToolCalls } from "../dist/index.js";
+
+const baseUrl = process.env.OLLAMA_BASE_URL ?? "http://127.0.0.1:11434";
+const model = process.env.OLLAMA_MODEL ?? "granite4.1:3b";
+
+const tools = [{
+  name: "stock_quote",
+  description: "Get a stock quote.",
+  schema: {
+    type: "object",
+    properties: {
+      ticker: { type: "string" },
+      market: { type: "string", enum: ["US", "HK", "CN"] },
+    },
+    required: ["ticker", "market"],
+    additionalProperties: false,
+  },
+}];
+
+const badCall = { tool: "stock_price", args: { symbol: "Apple", market: "NASDAQ" } };
+
+const result = await reliableToolCalls({
+  userInput: "Get Apple stock in the US market.",
+  tools,
+  calls: [badCall],
+  repair: async ({ userInput, tools, calls, issues }) => {
+    const prompt = [
+      "Return corrected JSON only as {\"calls\":[{\"tool\":\"name\",\"args\":{}}]}.",
+      `User: ${userInput}`,
+      `Tools: ${JSON.stringify(tools)}`,
+      `Rejected calls: ${JSON.stringify(calls)}`,
+      `Issues: ${JSON.stringify(issues)}`,
+    ].join("\n");
+
+    const response = await fetch(`${baseUrl}/api/generate`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ model, prompt, stream: false, format: "json" }),
+    });
+    if (!response.ok) throw new Error(`Ollama request failed: ${response.status}`);
+    const json = await response.json();
+    return JSON.parse(json.response).calls;
+  },
+});
+
+console.log(JSON.stringify({ model, badCall, result }, null, 2));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@botbotgo/better-call",
-  "version": "0.1.23",
-  "description": "LLM tool-call reliability layer.",
+  "version": "0.1.25",
+  "description": "Small-model tool-call reliability layer for LangChain and custom agent runtimes.",
   "type": "module",
   "license": "Apache-2.0",
   "repository": {
@@ -18,7 +18,14 @@
     "tool-calling",
     "function-calling",
     "guardrails",
-    "reliability"
+    "reliability",
+    "langchain",
+    "ollama",
+    "mcp",
+    "tool-call-repair",
+    "function-call-repair",
+    "small-models",
+    "agent-runtime"
   ],
   "exports": {
     ".": {
@@ -26,11 +33,20 @@
       "import": "./dist/index.js"
     }
   },
+  "bin": {
+    "better-call": "./scripts/demo.mjs"
+  },
   "files": [
     "dist",
     "benchmarks",
     "scripts",
+    "examples",
     "docs/banner.svg",
+    "docs/benchmark-lift.svg",
+    "docs/faq.md",
+    "docs/case-studies",
+    "docs/marketing",
+    "docs/recipes",
     "README.md",
     "NOTICE",
     "LICENSE"

package/scripts/demo.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { betterTools, repairToolCall, reliableToolCalls } from "../dist/index.js";
+
+const json = process.argv.includes("--json");
+
+const stockQuote = {
+  name: "stock_quote",
+  description: "Get a stock quote.",
+  schema: {
+    type: "object",
+    properties: {
+      ticker: { type: "string" },
+      market: { type: "string", enum: ["US", "HK", "CN"] },
+    },
+    required: ["ticker", "market"],
+    additionalProperties: false,
+  },
+  async invoke(args) {
+    return { quote: args };
+  },
+};
+
+const badArgs = { symbol: "Apple", market: "NASDAQ" };
+
+const [wrappedStockQuote] = betterTools([stockQuote], {
+  userInput: "Get Apple stock in the US market.",
+  repair() {
+    return [{ tool: "stock_quote", args: { ticker: "AAPL", market: "US" } }];
+  },
+});
+
+const wrappedOutput = await wrappedStockQuote.invoke(badArgs);
+
+const reliableResult = await reliableToolCalls({
+  userInput: "Get Apple stock in the US market.",
+  tools: [stockQuote],
+  calls: [{ tool: "stock_price", args: badArgs }],
+  repair() {
+    return [{ tool: "stock_quote", args: { ticker: "AAPL", market: "US" } }];
+  },
+});
+
+const gatewayResult = await repairToolCall({
+  userInput: "Research the current market.",
+  visibleTools: [{
+    name: "task",
+    description: "Delegate a task to a visible specialist.",
+    schema: {
+      type: "object",
+      properties: {
+        subagent_type: { type: "string", enum: ["research", "ops"] },
+        description: { type: "string" },
+      },
+      required: ["subagent_type", "description"],
+      additionalProperties: false,
+    },
+  }],
+  invalidToolName: "research",
+  args: {
+    subagent_type: "research",
+    description: "Research the current market.",
+  },
+});
+
+const report = {
+  wrappedTool: {
+    before: badArgs,
+    after: wrappedOutput,
+  },
+  reliableToolCalls: {
+    before: { tool: "stock_price", args: badArgs },
+    repaired: reliableResult.calls[0],
+    diagnostics: reliableResult.diagnostics,
+  },
+  gatewayRepair: gatewayResult,
+};
+
+if (json) {
+  console.log(JSON.stringify(report, null, 2));
+} else {
+  console.log("BetterCall demo");
+  console.log("");
+  console.log("1. Wrapped tool args");
+  console.log(`   before: ${JSON.stringify(report.wrappedTool.before)}`);
+  console.log(`   after:  ${JSON.stringify(report.wrappedTool.after)}`);
+  console.log("");
+  console.log("2. Tool-call repair");
+  console.log(`   before: ${JSON.stringify(report.reliableToolCalls.before)}`);
+  console.log(`   after:  ${JSON.stringify(report.reliableToolCalls.repaired)}`);
+  console.log("");
+  console.log("3. Gateway tool-name repair");
+  console.log(`   status: ${report.gatewayRepair.status}`);
+  console.log(`   tool:   ${report.gatewayRepair.originalToolName} -> ${report.gatewayRepair.toolName}`);
+  console.log(`   reason: ${report.gatewayRepair.reason}`);
+  console.log("");
+  console.log("Run with --json for the full structured result.");
+}