@botbotgo/better-call 0.1.23 → 0.1.24

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";
 
@@ -30,6 +34,14 @@ 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.
+
 ## Installation
 
 ```bash
@@ -230,6 +242,12 @@ 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.
+
 ## 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,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="920" height="360" viewBox="0 0 920 360" role="img" aria-labelledby="title desc">
+  <title id="title">BetterCall BFCL small-model lift</title>
+  <desc id="desc">Bar chart showing granite4.1:3b improving from 73.4 percent raw to 83.8 percent with BetterCall on BFCL v4 remote Ollama runs.</desc>
+  <rect width="920" height="360" fill="#0f172a"/>
+  <rect x="34" y="28" width="852" height="304" rx="16" fill="#111827" stroke="#334155"/>
+  <text x="64" y="72" fill="#f8fafc" font-family="Inter, Arial, sans-serif" font-size="28" font-weight="700">Small models fail at the tool boundary</text>
+  <text x="64" y="104" fill="#cbd5e1" font-family="Inter, Arial, sans-serif" font-size="16">BFCL v4 remote Ollama run, granite4.1:3b, 3,625 cases</text>
+  <line x1="86" y1="282" x2="820" y2="282" stroke="#475569"/>
+  <g>
+    <text x="132" y="314" fill="#cbd5e1" font-family="Inter, Arial, sans-serif" font-size="15" text-anchor="middle">Raw</text>
+    <rect x="86" y="127" width="92" height="155" rx="8" fill="#64748b"/>
+    <text x="132" y="116" fill="#f8fafc" font-family="Inter, Arial, sans-serif" font-size="24" font-weight="700" text-anchor="middle">73.4%</text>
+  </g>
+  <g>
+    <text x="328" y="314" fill="#cbd5e1" font-family="Inter, Arial, sans-serif" font-size="15" text-anchor="middle">BetterCall</text>
+    <rect x="282" y="105" width="92" height="177" rx="8" fill="#22c55e"/>
+    <text x="328" y="94" fill="#f8fafc" font-family="Inter, Arial, sans-serif" font-size="24" font-weight="700" text-anchor="middle">83.8%</text>
+  </g>
+  <path d="M190 146 C226 118 238 118 268 112" fill="none" stroke="#38bdf8" stroke-width="3"/>
+  <polygon points="270,112 258,106 260,120" fill="#38bdf8"/>
+  <text x="224" y="142" fill="#38bdf8" font-family="Inter, Arial, sans-serif" font-size="18" font-weight="700">+10.4pp</text>
+  <rect x="476" y="126" width="312" height="104" rx="12" fill="#0f172a" stroke="#334155"/>
+  <text x="502" y="163" fill="#f8fafc" font-family="Inter, Arial, sans-serif" font-size="20" font-weight="700">Validate, repair, then execute</text>
+  <text x="502" y="193" fill="#cbd5e1" font-family="Inter, Arial, sans-serif" font-size="15">Unknown tools, malformed args,</text>
+  <text x="502" y="216" fill="#cbd5e1" font-family="Inter, Arial, sans-serif" font-size="15">schema drift, raw tool-call-shaped text.</text>
+</svg>

package/docs/marketing/growth-checklist.md

@@ -0,0 +1,67 @@
+# 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.
+- [ ] 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.
+- [ ] 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.
+- [ ] Add MCP server/client gateway example.
+- [ ] Add OpenAI-compatible local model example.
+- [ ] Add LangGraph/stable-harness integration note when stable-harness is the public case study.
+
+## Conversion
+
+- [ ] Add a one-command reproduction path for the smallest local benchmark.
+- [ ] Add a "When should I use BetterCall?" FAQ.
+- [ ] Add a "When should I not use BetterCall?" FAQ to build trust.
+- [ ] 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/examples/README.md

@@ -0,0 +1,31 @@
+# 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.
+
+## 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
+```
+
+The Ollama example expects an Ollama-compatible `/api/generate` endpoint:
+
+```bash
+OLLAMA_BASE_URL=http://127.0.0.1:11434 OLLAMA_MODEL=granite4.1:3b node examples/ollama-small-model.mjs
+```

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.24",
+  "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": {
     ".": {
@@ -30,7 +37,10 @@
     "dist",
     "benchmarks",
     "scripts",
+    "examples",
     "docs/banner.svg",
+    "docs/benchmark-lift.svg",
+    "docs/marketing",
     "README.md",
     "NOTICE",
     "LICENSE"