buildExtractorPrompt function

String buildExtractorPrompt(List<FunctionTool> functions, String request, { ToolChoice choice = ToolChoice.auto, })

Builds the extractor prompt.

Every rule below was earned by a failing measurement, not written from taste. The two that carry the most weight:

• The manifest goes in the user turn of a throwaway session, never in a live conversation's system prompt. Measured on the same request, the latter produced a usable envelope 0 times out of 5 — the model answered from its own web search instead — while the former went 4 for 4, and 25 of 28 over a wider battery.
• "You have NO knowledge about anything a function covers." Without it the model answers the request itself whenever it believes it knows how, weather being the worst offender.

Implementation

String buildExtractorPrompt(
  List<FunctionTool> functions,
  String request, {
  ToolChoice choice = ToolChoice.auto,
}) {
  final forcedName = choice is NamedToolChoice ? choice.name : null;
  final mustCall = choice is! AutoToolChoice;

  final options = <String>[
    '  A) $kToolCallMarker{"calls":[{"name":"<function name>","arguments":{...}}]}',
    if (!mustCall)
      '  B) $kNoToolMarker   (no declared function fits the request)',
    '  C) $kNeedInfoMarker{"function":"<name>","missing":["<param>"]}   '
        '(a REQUIRED parameter is not stated in the request)',
  ];

  return [
    'You are a function-call extractor. You do not chat and you do not answer '
        'questions.',
    '',
    'AVAILABLE FUNCTIONS (JSON Schema):',
    jsonEncode([for (final f in functions) f.toJson()]),
    '',
    if (mustCall)
      'You MUST call a function. Output ONLY one of these:'
    else
      'Read the USER REQUEST below and output ONLY one of these:',
    ...options,
    '',
    'RULES:',
    '- Nothing before or after the output. No prose, no markdown fences, no '
        'explanation.',
    '- Output the marker exactly once.',
    '- You have NO knowledge and NO live data about anything a function covers. '
        'If a',
    '  function covers the request you MUST emit the call, even if you think '
        'you know',
    '  the answer. Answering it yourself is an ERROR.',
    '- "arguments" must satisfy that function\'s JSON Schema exactly. Never '
        'invent parameters.',
    '- One entry per distinct set of arguments: two cities means two calls.',
    '- Only omit an OPTIONAL parameter when the request does not specify it.',
    '- NEVER guess, infer or default a REQUIRED parameter the request does not '
        'state',
    '  (no made-up cities, dates, ids or amounts). If one is missing, output '
        'option C.',
    '- Never invent or simulate the RESULT of a function.',
    '- Capture EVERY condition stated in the request. Dropping one is an error.',
    if (forcedName != null)
      '- You MUST call the function "$forcedName" and no other.'
    else if (mustCall)
      '- Emitting $kNoToolMarker is forbidden for this request.',
    '',
    '---',
    'USER REQUEST:',
    request,
  ].join('\n');
}