harn-stdlib 0.10.201

Embedded Harn standard library source catalog
Documentation
// @harn-entrypoint-category llm.stdlib
//
// std/llm/tool_call_schema - tool registry parameter readers and the call-envelope output schema.
fn __tcs_dict(value: unknown) -> dict {
  if type_of(value) == "dict" {
    return value
  }
  return {}
}

fn __tcs_list(value: unknown) -> list {
  if type_of(value) == "list" {
    return value
  }
  return []
}

fn __tcs_string(value: any) -> string {
  if value == nil {
    return ""
  }
  return to_string(value)
}

fn __tcs_string_list(value: unknown) -> list {
  let out = []
  for item in __tcs_list(value) {
    const text = trim(__tcs_string(item))
    if text != "" {
      out.push(text)
    }
  }
  return out
}

fn __tcs_registry_tool_entry(registry: dict, name: any) {
  const tools = __tcs_dict(registry)
  let entries = __tcs_list(tools?.tools)
  for entry in entries {
    const direct_name = __tcs_string(entry?.name)
    const function = entry?.function
    const function_name = if type_of(function) == "dict" {
      __tcs_string(function?.name)
    } else {
      ""
    }
    if direct_name == name || function_name == name {
      return entry
    }
  }
  return nil
}

fn __tcs_tool_entry_parameters(entry: dict) {
  const function = entry?.function
  if type_of(function) == "dict" && type_of(function?.parameters) == "dict" {
    return function.parameters
  }
  if type_of(entry?.parameters) == "dict" {
    return entry.parameters
  }
  if type_of(entry?.inputSchema) == "dict" {
    return entry.inputSchema
  }
  return {}
}

fn __tcs_parameter_entries(parameters: dict) {
  if type_of(parameters?.properties) == "dict" {
    return parameters.properties
  }
  let entries = {}
  for name in __tcs_dict(parameters).keys() {
    if !contains(
      ["type", "properties", "required", "additionalProperties", "description", "title", "$schema"],
      name,
    ) {
      entries = entries + {[name]: parameters[name]}
    }
  }
  return entries
}

fn __tcs_param_is_required(parameters: dict, name: any, schema: dict) -> bool {
  if type_of(parameters?.properties) == "dict" {
    return contains(__tcs_string_list(parameters?.required), name)
  }
  if type_of(schema) == "dict" {
    if schema?.default != nil {
      return false
    }
    if type_of(schema?.required) == "bool" {
      return schema.required
    }
    if type_of(schema?.optional) == "bool" {
      return !schema.optional
    }
  }
  return true
}

/**
 * The names of a tool's REQUIRED parameters, for the corrective that asks a
 * model to emit a call it described but never sent.
 *
 * Names only, never values. An earlier form of this returned `[{key, value}]`
 * with a type placeholder for each value (`"<string>"`), on the theory that a
 * model copying the exemplar verbatim would produce an obviously unfilled call.
 * It does not: live smoke showed a model copy `"<string>"` into the repair call
 * and then into every subsequent call for the rest of the session, filling
 * optional parameters it had never used before with the same token. A
 * placeholder inside a JSON string is indistinguishable from a value, so the
 * only safe exemplar is one that carries no values at all — the corrective
 * renders the bare call envelope and names the required keys in prose.
 *
 * Empty for an unknown tool, a tool that declares no parameters, and a tool
 * whose parameters are all optional. Underscore-prefixed parameters are the
 * harness's to fill rather than the model's, but a REQUIRED one still has to
 * be sent, so it is still named.
 *
 * This lives beside the parameter readers because this module already owns the
 * shape tolerance for a tool entry's parameters: JSON-schema
 * `properties`/`required`, and the flat `{name: schema}` form with per-field
 * `required`/`optional`/`default`. A corrective that re-derived those rules
 * would be a second owner of the same policy.
 *
 * @effects: []
 * @errors: []
 * @api_stability: experimental
 */
pub fn tool_required_argument_names(registry: dict, tool_name: any) -> list<string> {
  const entry = __tcs_registry_tool_entry(registry, __tcs_string(tool_name))
  if entry == nil {
    return []
  }
  const parameters = __tcs_tool_entry_parameters(entry)
  const entries = __tcs_parameter_entries(parameters)
  let out: list<string> = []
  for name in __tcs_dict(entries).keys() {
    if __tcs_param_is_required(parameters, name, entries[name]) {
      out.push(name)
    }
  }
  return out
}

/**
 * The output schema that makes a turn's completion a single parseable tool
 * call and nothing else.
 *
 * Projects the registry into a JSON Schema for the flat call envelope the
 * text parser already accepts, keyed with the CANONICAL argument alias
 * (`{"name": .., "args": {..}}`) so the forced completion matches the shape
 * every standing prompt and corrective teaches, one `anyOf` branch per tool:
 * `name` is pinned to that tool and `args` must carry the tool's REQUIRED
 * parameter keys (live smoke evidence: with an open arguments object the
 * model lazily emits `{}` and burns a turn re-issuing the call). Argument
 * values stay shallow — presence is enforced by the grammar, value shape by
 * the dispatch-time validator that owns it. Internal underscore-prefixed
 * parameters are the harness's to fill, not the model's to write, so they
 * are left out of the grammar unless the registry marks one required (live
 * smoke evidence: an offered `_nl_intent` key is what the model reaches for
 * under constraint).
 *
 * When the corrective claimed the turn for one named tool, `claimed_tool`
 * narrows the schema to that tool's branch: the claim already told the model
 * which call to make, and the full `anyOf` lets it wander to a different
 * tool instead (observed live: a `look` claim answered with a junk `search`).
 * An empty or unrecognized `claimed_tool` keeps every branch.
 *
 * A tool with no model-facing parameters gets a bare `{"type": "object"}` args
 * branch rather than an empty `properties` object, which llama.cpp's grammar
 * conversion mishandles in a way that fails the whole request.
 *
 * Returns nil for an empty or unreadable registry, in which case no
 * contract should be applied.
 *
 * This lives beside the parameter readers for the same reason as
 * `tool_required_argument_names`: this module owns the shape tolerance
 * for tool registry entries, and a second reader would be a second owner of
 * the same policy.
 *
 * @effects: []
 * @errors: []
 * @api_stability: experimental
 */
pub fn tool_call_output_schema(registry: dict, claimed_tool: string = "") -> any? {
  const tools = __tcs_list(__tcs_dict(registry)?.tools)
  const claimed = trim(__tcs_string(claimed_tool))
  let branches = []
  let claimed_branch = nil
  let seen = []
  for entry in tools {
    const direct_name = __tcs_string(entry?.name)
    const function = entry?.function
    const function_name = if type_of(function) == "dict" {
      __tcs_string(function?.name)
    } else {
      ""
    }
    const name = if direct_name != "" {
      direct_name
    } else {
      function_name
    }
    if name == "" || contains(seen, name) {
      continue
    }
    seen.push(name)
    const parameters = __tcs_tool_entry_parameters(entry)
    const entries = __tcs_parameter_entries(parameters)
    let props = {}
    let req = []
    for pname in __tcs_dict(entries).keys() {
      const schema = entries[pname]
      const required = __tcs_param_is_required(parameters, pname, schema)
      if starts_with(pname, "_") && !required {
        continue
      }
      props = props + {[pname]: __tcs_argument_property_schema(schema)}
      if required {
        req.push(pname)
      }
    }
    // A tool with nothing for the model to write gets the bare object type, and
    // in particular no empty `properties`. llama.cpp's grammar conversion
    // mishandles `{"type": "object", "properties": {}}` (ggml-org/llama.cpp
    // #25923) and the malformed production fails the WHOLE combined request,
    // so one zero-parameter tool in the registry would take every other branch
    // down with it. Nothing is lost by leaving the keys open here: there are no
    // enumerated keys to close against, and dispatch still rejects an argument
    // the tool does not declare.
    //
    // Otherwise additionalProperties stays false: llama.cpp's grammar
    // conversion treats an open object as an arbitrary key-value production,
    // which is both slow and an invitation to hallucinate argument names; every
    // accepted key is already enumerated from the registry, which dispatch
    // validates against.
    let args_schema = if len(__tcs_dict(props).keys()) == 0 {
      {type: "object"}
    } else {
      {type: "object", properties: props, additionalProperties: false}
    }
    if len(req) > 0 {
      args_schema = args_schema + {required: req}
    }
    const branch = {
      type: "object",
      properties: {name: {type: "string", enum: [name]}, args: args_schema},
      required: ["name", "args"],
      additionalProperties: false,
    }
    if claimed != "" && name == claimed {
      claimed_branch = branch
    }
    branches.push(branch)
  }
  if claimed_branch != nil {
    return claimed_branch
  }
  if len(branches) == 0 {
    return nil
  }
  if len(branches) == 1 {
    return branches[0]
  }
  return {anyOf: branches}
}

/**
 * Project one named registry tool into the canonical call-envelope schema.
 *
 * Unlike `tool_call_output_schema`, this fails closed for an absent name. A
 * one-turn execution claim must never degrade into the full tool union: doing
 * so would turn "call verify next" into "call anything next" while still
 * looking structurally constrained to its caller.
 *
 * @effects: []
 * @errors: []
 * @api_stability: experimental
 */
pub fn exact_tool_call_output_schema(registry: dict, claimed_tool: string) -> any? {
  const claimed = trim(claimed_tool)
  if claimed == "" {
    return nil
  }
  const schema = tool_call_output_schema(registry, claimed)
  if schema == nil || schema?.properties?.name?.enum != [claimed] {
    return nil
  }
  return schema
}

/**
 * A deliberately shallow JSON-Schema fragment for one tool argument.
 *
 * Only a single unambiguous scalar/container type is projected; anything
 * richer (unions, nested objects, enums) becomes a permissive `{}` so the
 * decode grammar never forbids a value the dispatch-time validator would
 * accept. Constrained emission against a deep union schema is a known
 * field-dropping hazard on llama.cpp; presence is enforced here, shape is
 * enforced where it is owned — at dispatch.
 *
 * @effects: []
 * @errors: []
 * @api_stability: experimental
 */
fn __tcs_argument_property_schema(schema: dict) -> dict {
  const types = __tcs_schema_type_names(schema)
  if len(types) != 1 {
    return {}
  }
  const mapped = __tcs_json_schema_type_name(types[0])
  if mapped == "" {
    return {}
  }
  return {type: mapped}
}

fn __tcs_json_schema_type_name(name: string) -> string {
  if name == "string" {
    return "string"
  }
  if name == "integer" || name == "int" {
    return "integer"
  }
  if name == "number" || name == "float" {
    return "number"
  }
  if name == "boolean" || name == "bool" {
    return "boolean"
  }
  if name == "array" || name == "list" {
    return "array"
  }
  if name == "object" || name == "dict" {
    return "object"
  }
  return ""
}

fn __tcs_schema_type_names(schema: dict) {
  let raw = nil
  if type_of(schema) == "string" {
    raw = schema
  } else if type_of(schema) == "dict" {
    raw = schema?.type
  }
  let names = []
  if type_of(raw) == "list" {
    for item in raw {
      const name = lowercase(trim(__tcs_string(item)))
      if name != "" {
        names.push(name)
      }
    }
  } else {
    const name = lowercase(trim(__tcs_string(raw)))
    if name != "" {
      names.push(name)
    }
  }
  return names
}

/**
 * Compatibility projection for embedders that consumed the former exemplar
 * helper. New model-facing code must use `tool_required_argument_names` and
 * keep placeholder values out of the call envelope; this function preserves
 * the published experimental API without making it a second owner of which
 * parameters are required.
 *
 * @effects: []
 * @errors: []
 * @api_stability: experimental
 */
pub fn tool_required_argument_exemplar(registry: dict, tool_name: any) -> list {
  const entry = __tcs_registry_tool_entry(registry, __tcs_string(tool_name))
  if entry == nil {
    return []
  }
  const entries = __tcs_parameter_entries(__tcs_tool_entry_parameters(entry))
  let out = []
  for name in tool_required_argument_names(registry, tool_name) {
    const types = __tcs_schema_type_names(entries[name])
    const placeholder = if len(types) > 0 {
      "<" + types[0] + ">"
    } else {
      "<value>"
    }
    out.push({key: name, value: placeholder})
  }
  return out
}