@botbotgo/better-call 0.1.25 → 0.1.27

package/README.md

@@ -30,6 +30,8 @@ Try the built-in demo after installing:
 npx @botbotgo/better-call demo
 ```
 
+New users can start with `docs/adoption.md` for the shortest path from demo to integration.
+
 ## 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.
@@ -256,6 +258,7 @@ Latest completed remote run artifact: `benchmarks/bfcl-real-remote-completed-sum
 - `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/adoption.md`: start-here guide from demo to integration.
 - `docs/recipes/`: focused integration recipes.
 - `docs/faq.md`: adoption and boundary FAQ.
 - `docs/case-studies/stable-harness-tool-gateway.md`: production gateway integration pattern.

package/docs/adoption.md

@@ -0,0 +1,67 @@
+# Start Using BetterCall
+
+This guide is for developers who want to try BetterCall quickly and then decide where it belongs in their runtime.
+
+## 1. Run the Demo
+
+```bash
+npx @botbotgo/better-call demo
+```
+
+The demo shows three failure modes:
+
+- invalid tool arguments repaired before invocation
+- wrong tool name repaired into a visible tool
+- gateway repair diagnostics for audit logs
+
+Use JSON output when wiring the result into docs or tests:
+
+```bash
+npx @botbotgo/better-call demo --json
+```
+
+## 2. Pick Your Integration Path
+
+| If you use | Start here |
+| --- | --- |
+| LangChain-style tools | `examples/langchain-basic.mjs` |
+| A custom runtime or tool gateway | `examples/gateway-repair.mjs` |
+| MCP-style dispatch | `examples/adapters/mcp-gateway-boundary.mjs` |
+| Ollama local models | `examples/ollama-small-model.mjs` |
+| OpenAI-compatible local endpoints | `examples/adapters/openai-compatible-repair.mjs` |
+| A production tool gateway | `docs/case-studies/stable-harness-tool-gateway.md` |
+
+## 3. Decide the Boundary
+
+BetterCall should sit immediately before real tool execution:
+
+```text
+model/tool intent -> runtime gateway -> BetterCall -> real tool
+```
+
+Keep these responsibilities outside BetterCall:
+
+- planning
+- memory
+- human approval
+- authorization
+- agent orchestration
+
+Keep these responsibilities inside or near BetterCall:
+
+- tool-call schema validation
+- tool-name repair inside a visible inventory
+- argument normalization
+- repair diagnostics
+- block-on-failure behavior
+
+## 4. Bring a Broken Tool Call
+
+If you are not sure how to integrate your framework, open an adapter request with:
+
+- your current tool shape
+- the model's broken call
+- the call you expect after repair
+- any hidden tools, policy rules, or approval constraints
+
+Use the adapter request or broken tool-call issue templates in this repository.

package/docs/marketing/growth-checklist.md

@@ -16,6 +16,8 @@ The goal is to move developers through three stages:
 - [x] Add focused recipes for common integration problems.
 - [x] Add a stable-harness gateway case study.
 - [x] Add an adapter request issue template.
+- [x] Add a broken tool-call issue template.
+- [x] Add a start-here adoption guide.
 - [ ] Add a short GIF or terminal recording showing before and after repair.
 - [ ] Add a `good first issue` label set for example adapters and docs.
 
@@ -53,6 +55,7 @@ The goal is to move developers through three stages:
 - [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.
+- [x] Add LangChain, MCP, and OpenAI-compatible recipes.
 
 ## Conversion
 

package/docs/marketing/launch-post.md

@@ -12,7 +12,7 @@ LLM tool calling has a boring failure mode that shows up constantly with small m
 
 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.
+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 worst case is the wrong operation reaching production code.
 
 BetterCall is a small TypeScript reliability layer for that boundary.
 

package/docs/recipes/README.md

@@ -3,9 +3,12 @@
 Each recipe solves one integration problem with a small copyable pattern.
 
 - `wrong-tool-name.md`: Repair a tool name before gateway dispatch.
+- `langchain-wrapper.md`: Wrap LangChain-style tools.
+- `mcp-gateway.md`: Repair at an MCP-style gateway boundary.
 - `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.
+- `openai-compatible.md`: Use an OpenAI-compatible local endpoint 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/langchain-wrapper.md

@@ -0,0 +1,21 @@
+# Recipe: Wrap LangChain-style Tools
+
+Use `betterTools(...)` when your tool already has `name`, `schema`, and `invoke(input)`.
+
+```ts
+import { betterTools } from "@botbotgo/better-call";
+
+const tools = betterTools([searchTool, calculatorTool], {
+  repairModel,
+});
+```
+
+If you want a named helper in your own codebase:
+
+```ts
+export function withBetterCallLangChainTools(tools, options = {}) {
+  return betterTools(tools, options);
+}
+```
+
+See `examples/adapters/langchain-tool-wrapper.mjs` for a runnable version.

package/docs/recipes/mcp-gateway.md

@@ -0,0 +1,28 @@
+# Recipe: Repair at an MCP-style Gateway Boundary
+
+Use `repairToolCall(...)` before dispatching a tool request to an MCP server or gateway.
+
+```ts
+import { repairToolCall } from "@botbotgo/better-call";
+
+const repaired = await repairToolCall({
+  userInput,
+  visibleTools,
+  hiddenTools,
+  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 dispatch(repaired.toolName, repaired.args);
+```
+
+The gateway still owns authorization. BetterCall only repairs into the visible tool inventory.

package/docs/recipes/openai-compatible.md

@@ -0,0 +1,41 @@
+# Recipe: Use an OpenAI-compatible Repair Endpoint
+
+Use this pattern for local servers that expose `/v1/chat/completions`.
+
+```ts
+import { reliableToolCalls } from "@botbotgo/better-call";
+
+const result = await reliableToolCalls({
+  userInput,
+  tools,
+  calls,
+  repair: async ({ userInput, tools, calls, issues }) => {
+    const response = await fetch(`${baseUrl}/v1/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"),
+        }],
+      }),
+    });
+
+    const json = await response.json();
+    return JSON.parse(json.choices[0].message.content).calls;
+  },
+});
+```
+
+See `examples/adapters/openai-compatible-repair.mjs` for a runnable version.

package/examples/README.md

@@ -33,5 +33,5 @@ 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
+OPENAI_BASE_URL=http://127.0.0.1:8000 OPENAI_MODEL=local-model node examples/adapters/openai-compatible-repair.mjs
 ```

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

@@ -1,6 +1,6 @@
 import { reliableToolCalls } from "../../dist/index.js";
 
-const baseUrl = process.env.OPENAI_BASE_URL ?? "http://127.0.0.1:8000/v1";
+const baseUrl = process.env.OPENAI_BASE_URL ?? "http://127.0.0.1:8000";
 const model = process.env.OPENAI_MODEL ?? "local-model";
 const apiKey = process.env.OPENAI_API_KEY ?? "not-needed-for-local";
 
@@ -23,10 +23,10 @@ const result = await reliableToolCalls({
   tools,
   calls: [{ tool: "stock_price", args: { symbol: "Apple", market: "NASDAQ" } }],
   repair: async ({ userInput, tools, calls, issues }) => {
-    const response = await fetch(`${baseUrl}/chat/completions`, {
+    const response = await fetch(`${baseUrl}/v1/chat/completions`, {
       method: "POST",
       headers: {
-        "authorization": `Bearer ${apiKey}`,
+        "Authorization": `Bearer ${apiKey}`,
         "content-type": "application/json",
       },
       body: JSON.stringify({

package/examples/ollama-small-model.mjs

@@ -17,12 +17,12 @@ const tools = [{
   },
 }];
 
-const badCall = { tool: "stock_price", args: { symbol: "Apple", market: "NASDAQ" } };
+const invalidToolCall = { tool: "stock_price", args: { symbol: "Apple", market: "NASDAQ" } };
 
 const result = await reliableToolCalls({
   userInput: "Get Apple stock in the US market.",
   tools,
-  calls: [badCall],
+  calls: [invalidToolCall],
   repair: async ({ userInput, tools, calls, issues }) => {
     const prompt = [
       "Return corrected JSON only as {\"calls\":[{\"tool\":\"name\",\"args\":{}}]}.",
@@ -43,4 +43,4 @@ const result = await reliableToolCalls({
   },
 });
 
-console.log(JSON.stringify({ model, badCall, result }, null, 2));
+console.log(JSON.stringify({ model, invalidToolCall, result }, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/better-call",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Small-model tool-call reliability layer for LangChain and custom agent runtimes.",
   "type": "module",
   "license": "Apache-2.0",
@@ -41,6 +41,7 @@
     "benchmarks",
     "scripts",
     "examples",
+    "docs/adoption.md",
     "docs/banner.svg",
     "docs/benchmark-lift.svg",
     "docs/faq.md",

package/scripts/demo.mjs

@@ -34,6 +34,7 @@ const wrappedOutput = await wrappedStockQuote.invoke(badArgs);
 const reliableResult = await reliableToolCalls({
   userInput: "Get Apple stock in the US market.",
   tools: [stockQuote],
+  // The tool name is intentionally wrong to demonstrate repair to stock_quote.
   calls: [{ tool: "stock_price", args: badArgs }],
   repair() {
     return [{ tool: "stock_quote", args: { ticker: "AAPL", market: "US" } }];