@botbotgo/better-call 0.1.45 → 0.1.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/better-call",
-  "version": "0.1.45",
+  "version": "0.1.47",
   "description": "Small-model tool-call reliability layer for LangChain and custom agent runtimes.",
   "type": "module",
   "license": "Apache-2.0",

package/scripts/demo.mjs

@@ -65,6 +65,8 @@ function exitWithError(step, error) {
   process.exit(1);
 }
 
+// Demo tool definition: validates ticker and market arguments before returning
+// a normalized quote payload. Accepted markets are US, HK, and CN.
 const stockQuote = {
   name: "stock_quote",
   description: "Get a stock quote.",
@@ -98,8 +100,21 @@ const stockQuote = {
 
 // Intentionally malformed repair input: "symbol" should be "ticker", and
 // "NASDAQ" is not one of the schema-valid markets ("US", "HK", or "CN").
-const intentionallyMalformedArgs = { symbol: "Apple", market: "NASDAQ" };
-
+const DEMO_MALFORMED_INPUT = { symbol: "Apple", market: "NASDAQ" };
+
+/**
+ * Repairs malformed stock quote tool-call input into one schema-valid call.
+ *
+ * Diagnostics, when present, come from the surrounding reliableToolCalls run
+ * and explain validation/repair decisions such as fallback ticker or market values.
+ *
+ * @param {object} [repairInput={}] Optional repair payload that may include
+ *   `calls[0].args`.
+ * @returns {{ tool: string, args: { ticker: string, market: "US" | "HK" | "CN" } }[]}
+ *   A repaired `stock_quote` call with normalized arguments. Ticker input may
+ *   be provided as `ticker` or legacy `symbol`; missing values fall back to
+ *   AAPL, and unsupported markets fall back to US.
+ */
 function repairDemoStockCall(repairInput = {}) {
   const hasUsableArgsShape = (value) =>
     typeof value === "object" &&
@@ -108,9 +123,11 @@ function repairDemoStockCall(repairInput = {}) {
     ("ticker" in value || "symbol" in value || "market" in value);
 
   const attemptedArgs =
-    Array.isArray(repairInput?.calls) && hasUsableArgsShape(repairInput.calls[0]?.args)
+    Array.isArray(repairInput?.calls) &&
+    repairInput.calls.length > 0 &&
+    hasUsableArgsShape(repairInput.calls[0]?.args)
       ? repairInput.calls[0].args
-      : intentionallyMalformedArgs;
+      : DEMO_MALFORMED_INPUT;
 
   const attemptedTicker =
     typeof attemptedArgs.ticker === "string"
@@ -118,9 +135,8 @@ function repairDemoStockCall(repairInput = {}) {
       : typeof attemptedArgs.symbol === "string"
         ? attemptedArgs.symbol
         : "AAPL";
-  const normalizedTicker =
-    typeof attemptedTicker === "string" ? attemptedTicker.trim().toLowerCase() : "aapl";
-  // This demo falls back to AAPL when no ticker-like value is available.
+  const normalizedTicker = attemptedTicker.trim().toLowerCase();
+  // This demo maps empty input and the "apple" alias to AAPL.
   const ticker =
     normalizedTicker === ""
       ? "AAPL"
@@ -153,9 +169,9 @@ const wrappedStockQuote = wrappedTools[0];
 
 let wrappedOutput;
 try {
-  wrappedOutput = await wrappedStockQuote.invoke(intentionallyMalformedArgs);
+  wrappedOutput = await wrappedStockQuote.invoke(DEMO_MALFORMED_INPUT);
 } catch (error) {
-  const context = `tool=stock_quote args=${JSON.stringify(intentionallyMalformedArgs)}`;
+  const context = `tool=stock_quote args=${JSON.stringify(DEMO_MALFORMED_INPUT)}`;
   const message = `${errorMessage(error)} (${context})`;
   const contextualError =
     error instanceof Error ? new Error(message, { cause: error }) : new Error(message);
@@ -168,9 +184,9 @@ try {
     userInput: "Get Apple stock in the US market.",
     tools: [stockQuote],
     // Both the tool name and args are intentionally wrong to demonstrate repair:
-    // "stock_price" should be "stock_quote"; intentionallyMalformedArgs uses
+    // "stock_price" should be "stock_quote"; DEMO_MALFORMED_INPUT uses
     // "symbol"/"NASDAQ" instead of schema-valid stock_quote args.
-    calls: [{ tool: "stock_price", args: intentionallyMalformedArgs }],
+    calls: [{ tool: "stock_price", args: DEMO_MALFORMED_INPUT }],
     repair: repairDemoStockCall,
   });
 } catch (error) {
@@ -227,12 +243,13 @@ const repairedCall =
 
 const report = {
   wrappedTool: {
-    before: intentionallyMalformedArgs,
+    before: DEMO_MALFORMED_INPUT,
     after: wrappedOutput,
   },
   reliableToolCalls: {
-    before: { tool: "stock_price", args: intentionallyMalformedArgs },
+    before: { tool: "stock_price", args: DEMO_MALFORMED_INPUT },
     repaired: repairedCall,
+    // Optional validation/repair metadata; null means this run returned none.
     diagnostics: reliableResult?.diagnostics ?? null,
   },
   gatewayRepair: gatewayRepairResult,