Supplier Bot V2 — Integration Spec

Overview

This document specifies the tool-calling interface contract between Eric's supplier bot V2 pipeline and Sourcy's production infrastructure. It covers: what tools fire, what signals they produce, the exact API format, grounding guarantees, and what Sourcy needs to build to consume the output.

1. Architecture: Two Agents, Two Tool Sets

The system has two LLM agents that run sequentially. The conversation bot talks to suppliers in real-time and captures data via tools. The summary agent analyzes the completed conversation and emits operational signals.

Data Flow

// 1. Conversation bot runs, produces:
{
  history: [/* bot ↔ supplier message array */],
  botToolTrace: [/* structured data captures */],
  status: "completed" | "no_reply" | "rejected" | "wechat_redirect"
}

// 2. Summary agent reads the outcome, produces:
{
  signals: [/* operational signals for brain/ops */],
  brainReceipt: {/* confirmation from brain endpoint */}
}

2. Conversation Bot Tools (4)

These are data-capture tools. They write to an in-memory array (botToolTrace) that is returned as part of the conversation outcome. They do not call external APIs. Sourcy reads botToolTrace from the outcome object.

log_data — Schema

{
  "turn": 2,
  "name": "log_data",
  "args": {
    "goalId": "moq",          // matches goal taxonomy
    "value": "300",           // extracted value
    "supplierQuote": "300起"  // exact supplier wording
  }
}

note_blocker — Schema

{
  "turn": 4,
  "name": "note_blocker",
  "args": {
    "goalId": "customization",
    "blockerType": "quantity_too_low",  // moq_mismatch | spec_refusal | authority_boundary | price_dead_end | quantity_too_low
    "reason": "50个数量太少，无法做胶标Logo",
    "supplierQuote": "这么少，做不了"
  }
}

note_file_request — Schema

{
  "turn": 5,
  "name": "note_file_request",
  "args": {
    "assetType": "logo",       // logo | design | spec_sheet | sample_photo | other
    "urgency": "blocking_quote", // blocking_quote | nice_to_have
    "supplierQuote": "要不你们提供给我们？"
  }
}

acknowledge_media — Schema

{
  "turn": 3,
  "name": "acknowledge_media",
  "args": {
    "mediaType": "image",   // image | file
    "description": "产品图和包装图",
    "supplierQuote": "[图片] 这是我们的产品图和包装图"
  }
}

3. Summary Agent Tools (3)

These tools emit operational signals that need a downstream consumer. Currently wired to a local JSON file (dummy-brain-endpoint.js). Sourcy must replace this with their brain/ops API.

Signal Schema — human_escalation

{
  "sessionId": "mes2-01-moq-rejection",
  "supplierId": "supplier-123",
  "supplierName": "常箱伴皮具源头工厂",
  "source": "summary-agent-llm",
  "timestamp": "2026-04-02T10:04:56.947Z",
  "signalType": "human_escalation",
  "severity": "medium",             // low | medium | high
  "reason": "quantity_too_low: Buyer needs to increase order quantity.",
  "goalId": "customization",
  "blockerType": "quantity_too_low",
  "supplierQuote": "这么少，做不了",
  "suggestedUnlock": "Buyer increases quantity to 300+"
}

Signal Schema — schedule_follow_up

{
  "sessionId": "mes2-08-timing-tomorrow",
  "signalType": "schedule_follow_up",
  "severity": "medium",
  "reason": "Supplier indicated timing: \"明天出去找一下五金\" (~24h).",
  "followUpTiming": {
    "delayHours": 24,
    "rawPhrase": "明天出去找一下五金",
    "confidence": "high"        // high | medium | low
  }
}

Signal Schema — asset_request

{
  "sessionId": "mes2-06-file-request",
  "signalType": "asset_request",
  "severity": "high",
  "reason": "Supplier needs logo file before quoting on customization.",
  "goalId": "customization",
  "supplierQuote": "logo发我一下可以吗？"
}

4. Gemini API Format

The pipeline calls Gemini's generateContent endpoint with function declarations. Sourcy's chatServer must be able to pass through or adapt this format.

Request (tool-calling)

POST /v1beta/models/gemini-3.1-pro-preview:generateContent?key=API_KEY

{
  "systemInstruction": { "parts": [{ "text": "<system prompt>" }] },
  "contents": [
    { "role": "user", "parts": [{ "text": "supplier message" }] },
    { "role": "model", "parts": [{ "text": "bot reply" }] }
  ],
  "tools": [{
    "functionDeclarations": [
      { "name": "log_data", "description": "...", "parameters": {/* JSON Schema */} },
      { "name": "note_blocker", /* ... */ },
      { "name": "note_file_request", /* ... */ },
      { "name": "acknowledge_media", /* ... */ }
    ]
  }],
  "generationConfig": {
    "maxOutputTokens": 4000,
    "temperature": 0.1
  }
}

Response (with tool calls)

{
  "candidates": [{
    "content": {
      "parts": [
        { "text": "您好！请问起订量是多少？" },
        { "functionCall": {
            "name": "log_data",
            "args": { "goalId": "moq", "value": "300", "supplierQuote": "300起" }
          }
        }
      ]
    }
  }],
  "usageMetadata": { "promptTokenCount": 1840, "candidatesTokenCount": 95 }
}

5. Grounding System

Every tool call includes a supplierQuote field. The eval harness verifies that this quote actually appears in the conversation history. Ungrounded tool calls (where the quote can't be found in the transcript) are stripped in strict mode.

Grounding Results — Latest Benchmark (Apr 2, 2026)

Overall: Bot trace ~82% grounded, Summary ~85% grounded. Ungrounded items are primarily from runtime-replay generating slightly different supplier text than the fixture, not from hallucination. Grounding data shown for original 10 cases (Gemini Pro). Three additional cases (mes2-12 silence, mes2-13 auto-response, mes2-14 wechat_redirect) added Apr 5 — grounding data pending full Gemini Pro rerun.

6. Model Pinning & Migration

Migration procedure

When Google releases a new model version:

1. Update the model string in llm.js GEMINI_MODELS object
2. Run the full 10-case benchmark: node run-eval-v2.js --backend gemini-pro
3. Compare aggregate score against the 90.7% baseline
4. If score drops >5%, investigate per-dimension regressions before deploying

7. Production Wiring — What You Need to Build

Usage

const { handleIncomingMessage, handleConversationEnd } = require('./pipeline/handle-incoming-message');

// On each incoming supplier message:
const history = loadFromDB(conversationId);
history.push({ role: 'supplier', content: incomingMessage });

const result = await handleIncomingMessage({ sr, goals, history });
saveToDB(conversationId, result.history, result.toolCalls);
sendToSupplier(result.reply);  // → { reply, toolCalls, status, history }

if (result.status !== 'continue') {
  const summary = await handleConversationEnd({ sr, goals, history, botToolTrace });
  deliverToBrain(summary.signals);  // → { summaryText, signals, toolCalls }
}

Sourcy-owned responsibilities

Key point: All functions listed above are stateless and independently callable. callBotWithTools takes a history array and returns a reply — it has no memory between calls. The eval harness tests these same functions, so benchmark scores remain valid after integration.

8. Known Gaps & Out-of-Scope

9. Error Handling & Edge Cases

What happens when things go wrong:

10. What Sourcy Keeps vs. Replaces

10. Running the Eval

Sourcy can validate the full pipeline by running:

# Full 13-case benchmark (strict grounding)
node run-eval-v2.js --backend gemini-pro --grounding strict

# With brain signal delivery
node run-eval-v2.js --backend gemini-pro --send-to-brain

# Single case for debugging
node run-eval-v2.js --case-ids mes2-01-moq-rejection --backend gemini-pro

# Inspect brain signals after run
cat pipeline/output/brain-signals-log.json | python3 -m json.tool