toolnexus 0.26.0 → 0.28.0

package/src/classifier.ts

@@ -34,7 +34,7 @@ export const DEFAULT_BATCH_CONCURRENCY = 16
  * `typesafe/jev-1.14`, and mixing the two is issue #91. `custom` is a self-hosted System One
  * endpoint and requires `baseUrl` + `supports` (SPEC §8B "Backends, images, cache and validation").
  */
-export type ClassifierBackend = "typesafe" | "openrouter" | "cloudflare" | "vercel" | "custom"
+export type ClassifierBackend = "typesafe" | "openrouter" | "cloudflare" | "vercel" | "openai" | "custom"
 
 /** What a backend+model can take. DATA: a fail-fast for what the table says, never a claim about
  * the vendor. Override per classifier with `ClassifierOptions.supports`. */
@@ -48,8 +48,9 @@ export interface ClassifierBackendPreset {
   baseUrl: string
   model: string
   apiKeyEnv: string
-  /** `systemone`: POST {baseUrl}/systemone. `cloudflare`: POST {baseUrl}, `/ai/run` envelope. */
-  wire: "systemone" | "cloudflare"
+  /** `systemone`: POST {baseUrl}/systemone. `cloudflare`: POST {baseUrl}, `/ai/run` envelope.
+   * `decisions`: POST {baseUrl}/decisions, OpenAI's Decisions API (#157). */
+  wire: "systemone" | "cloudflare" | "decisions"
   /** Send `TypeSafe-Danger-Zone-Images: true` when a request carries images. */
   imagesHeader: boolean
   /** The default support for a model on this backend; absent on `custom`. */
@@ -101,15 +102,46 @@ export const CLASSIFIER_BACKENDS: Readonly<Record<ClassifierBackend, Readonly<Cl
     imagesHeader: true,
     supports: () => ({ images: false }),
   },
+  openai: {
+    baseUrl: "https://api.openai.com/v1",
+    model: "gpt-6-luna",
+    apiKeyEnv: "OPENAI_API_KEY",
+    wire: "decisions",
+    imagesHeader: false,
+    supports: () => ({ images: true }),
+  },
   custom: {
     baseUrl: "",
     model: DEFAULT_CLASSIFIER_MODEL,
-    apiKeyEnv: DEFAULT_CLASSIFIER_API_KEY_ENV,
+    apiKeyEnv: "",
     wire: "systemone",
     imagesHeader: true,
   },
 })
 
+/**
+ * The env var whose key may be sent to `baseUrl` (already `${NAME}`-expanded): the backend's own
+ * variable, and only when `baseUrl` is that backend's own host over https (OpenRouter also its
+ * subdomains). `""` when none may — `custom` has no preset key at all. A key is never sent to a
+ * host the caller did not name (#155, SPEC §8B).
+ */
+export function classifierKeyEnv(backend: ClassifierBackend, baseUrl: string): string {
+  const p = Object.prototype.hasOwnProperty.call(CLASSIFIER_BACKENDS, backend) ? CLASSIFIER_BACKENDS[backend] : undefined
+  if (!p || !p.apiKeyEnv || !p.baseUrl) return ""
+  const hostOf = (u: string): string => {
+    try {
+      const url = new URL(u)
+      return url.protocol === "https:" ? url.hostname.toLowerCase() : ""
+    } catch {
+      return ""
+    }
+  }
+  const h = hostOf(baseUrl)
+  const own = hostOf(p.baseUrl)
+  if (!h || !own) return ""
+  return h === own || (backend === "openrouter" && h.endsWith(".openrouter.ai")) ? p.apiKeyEnv : ""
+}
+
 /**
  * Raised BEFORE any network call when the backend table says the backend cannot take what the
  * request carries. Message, exact: `classifier: <backend> (<model>) does not support <feature>`.
@@ -650,6 +682,9 @@ export class Classifier {
   private readonly baseUrl: string
   private readonly model: string
   private readonly apiKeyEnv: string
+  /** The caller NAMED apiKeyEnv: sent wherever baseUrl points. Otherwise the preset's own key,
+   * and only to its own host (classifierKeyEnv, #155). */
+  private readonly explicitKeyEnv: boolean
   private readonly timeoutMs: number
   private readonly backend: ClassifierBackend
   private readonly preset: Readonly<ClassifierBackendPreset>
@@ -664,7 +699,7 @@ export class Classifier {
     this.backend = opts.backend ?? "typesafe"
     if (!Object.prototype.hasOwnProperty.call(CLASSIFIER_BACKENDS, this.backend)) {
       throw new Error(
-        `classifier: unknown backend "${this.backend}" (want "typesafe", "openrouter", "cloudflare", "vercel" or "custom")`,
+        `classifier: unknown backend "${this.backend}" (want "typesafe", "openrouter", "cloudflare", "vercel", "openai" or "custom")`,
       )
     }
     const preset = CLASSIFIER_BACKENDS[this.backend]
@@ -675,6 +710,7 @@ export class Classifier {
     this.baseUrl = opts.baseUrl || preset.baseUrl
     this.model = opts.model ?? preset.model
     this.apiKeyEnv = opts.apiKeyEnv ?? preset.apiKeyEnv
+    this.explicitKeyEnv = opts.apiKeyEnv !== undefined
     const mismatch = backendMismatch(this.baseUrl, this.model)
     if (mismatch) throw new Error(mismatch)
     this.timeoutMs = opts.timeoutMs ?? DEFAULT_CLASSIFIER_TIMEOUT_MS
@@ -893,7 +929,9 @@ export class Classifier {
     const qs: Record<string, unknown> = {}
     for (const [key, q] of Object.entries(questions)) qs[key] = questionWire(q)
     let body: Record<string, any>
-    if (this.preset.wire === "cloudflare") {
+    if (this.preset.wire === "decisions") {
+      body = { model: this.model, input: decisionsInput(p), questions: decisionsQuestions(this.backend, this.model, questions) }
+    } else if (this.preset.wire === "cloudflare") {
       const input: Record<string, unknown> = { questions: qs, state: p.state }
       if (p.images.length > 0) input.images = p.images.map((im) => `data:image/${im.format};base64,${im.data}`)
       body = { model: this.model, input }
@@ -968,6 +1006,9 @@ export class Classifier {
     if (this.preset.wire === "cloudflare") {
       parsed = unwrapCloudflare(parsed)
       text = canonicalJson(parsed)
+    } else if (this.preset.wire === "decisions") {
+      text = decisionsReply(parsed, questions)
+      parsed = JSON.parse(text)
     }
     const d = decodeDecision(parsed, this.model)
     const verr = validateDecision(questions, d)
@@ -993,7 +1034,8 @@ export class Classifier {
     // `endpoint` is what errors name: the CONFIGURED base, ${ENV} unexpanded, so an account id in
     // a templated URL never reaches an error. `url` is what is dialled, expanded at call time.
     let endpoint = this.baseUrl.replace(/\/+$/, "")
-    if (this.preset.wire !== "cloudflare") endpoint += "/systemone"
+    if (this.preset.wire === "decisions") endpoint += "/decisions"
+    else if (this.preset.wire !== "cloudflare") endpoint += "/systemone"
     const url = endpoint.includes("${") ? expandEnv(endpoint) : endpoint
     const retries = this.opts.retries ?? 2
     const base = this.opts.retryBaseMs ?? 500
@@ -1019,7 +1061,7 @@ export class Classifier {
       try {
         res = await doFetch(url, {
           method: "POST",
-          headers: this.requestHeaders(extraHeaders),
+          headers: this.requestHeaders(extraHeaders, url),
           body: payload,
           signal: timer.signal,
         })
@@ -1049,9 +1091,10 @@ export class Classifier {
   }
 
   /** Credential and `${ENV_VAR}` headers resolve AT CALL TIME. Never logged, never returned. */
-  private requestHeaders(extra: Record<string, string> = {}): Record<string, string> {
+  private requestHeaders(extra: Record<string, string>, url: string): Record<string, string> {
     const headers: Record<string, string> = { "Content-Type": "application/json" }
-    const key = process.env[this.apiKeyEnv]
+    const keyEnv = this.explicitKeyEnv ? this.apiKeyEnv : classifierKeyEnv(this.backend, url)
+    const key = keyEnv ? process.env[keyEnv] : undefined
     if (key) headers["Authorization"] = `Bearer ${key}`
     // The image opt-in header goes BEFORE host headers, which win.
     for (const [k, v] of Object.entries(extra)) headers[k] = v
@@ -1341,10 +1384,27 @@ function imageSize(format: string, b: Uint8Array): [number, number] | undefined
   return undefined
 }
 
-/** The System One reply inside a Cloudflare `/ai/run` envelope. Its error list is never echoed. */
+/**
+ * `: <code> <message>` from errors[0] of a failed envelope (SPEC §8B), through the same redaction
+ * and cap as cause(). Cloudflare reports a missing balance, a bad model id and a malformed
+ * request alike as HTTP 200 + success:false, so this is the only thing that tells them apart.
+ * `""` when there is nothing to show.
+ */
+function cloudflareCause(env: unknown): string {
+  const errs = env !== null && typeof env === "object" ? (env as any).errors : undefined
+  const e0 = Array.isArray(errs) ? errs[0] : undefined
+  if (e0 === null || typeof e0 !== "object") return ""
+  const parts: string[] = []
+  if ((typeof e0.code === "number" || typeof e0.code === "string") && String(e0.code) !== "") parts.push(String(e0.code))
+  if (typeof e0.message === "string" && e0.message !== "") parts.push(e0.message)
+  const s = capErrorBody(redactErrorBody(parts.join(" ")))
+  return s ? ": " + s : ""
+}
+
+/** The System One reply inside a Cloudflare `/ai/run` envelope. Only errors[0] is ever echoed. */
 function unwrapCloudflare(env: unknown): unknown {
   if (env === null || typeof env !== "object" || Array.isArray(env) || (env as any).success !== true) {
-    throw new Error("classifier: cloudflare: envelope not successful")
+    throw new Error("classifier: cloudflare: envelope not successful" + cloudflareCause(env))
   }
   let result = (env as any).result
   if (result !== null && typeof result === "object" && !Array.isArray(result) && typeof result.state === "string") {
@@ -1514,3 +1574,99 @@ export function chunkQuestions<Q extends AnyQuestion>(questions: Record<string,
   }
   return out
 }
+
+// ---------------------------------------------------------------- the Decisions wire (#157)
+
+/** The Decisions API's per-request question cap. */
+export const MAX_DECISIONS_QUESTIONS = 400
+
+/**
+ * Maps the question set to the Decisions API list, in ASCII key order. Caller keys are NOT sent
+ * (no `name`): §8B keys are addressing, not content, and answers come back in request order.
+ * Every check fires before any request.
+ */
+function decisionsQuestions(backend: string, model: string, questions: Record<string, AnyQuestion>): unknown[] {
+  const keys = Object.keys(questions).sort()
+  if (keys.length > MAX_DECISIONS_QUESTIONS) {
+    throw new Error(`classifier: the decisions wire takes at most ${MAX_DECISIONS_QUESTIONS} questions, got ${keys.length}`)
+  }
+  return keys.map((k) => {
+    const q = questions[k]
+    if (isRawQuestion(q)) throw new ClassifierUnsupported(backend, model, `raw question type "${q.type}"`)
+    const m = q as Question
+    switch (m.type) {
+      case "noul": {
+        let instructions = m.instructions
+        if (m.criteria !== undefined) instructions += `\n\nTrue means: ${m.criteria.true}\nFalse means: ${m.criteria.false}`
+        return { type: "predicate", instructions }
+      }
+      case "choice": {
+        const ids = Object.keys(m.criteria ?? {}).sort()
+        if (ids.length < 2) {
+          throw new Error(`classifier: question "${k}": the decisions wire needs 2..${MAX_CHOICE_OPTIONS} choice options, got ${ids.length}`)
+        }
+        const choices = ids.map((id) => (m.criteria[id] === "" ? { value: id } : { value: id, description: m.criteria[id] }))
+        return { type: "choice", instructions: m.instructions, choices }
+      }
+      case "score":
+        return { type: "score", instructions: m.instructions, levels: m.criteria.map((label) => ({ label })) }
+    }
+  })
+}
+
+/** The state as sent: a string verbatim, else canonical JSON text; with images, one user message. */
+function decisionsInput(p: PreparedRequest): unknown {
+  const text = typeof p.state === "string" ? p.state : canonicalJson(p.state)
+  if (p.images.length === 0) return text
+  const content: unknown[] = [{ type: "input_text", text }]
+  for (const im of p.images) content.push({ type: "input_image", image_url: `data:image/${im.format};base64,${im.data}` })
+  return [{ role: "user", content }]
+}
+
+/** A choice value or level index as the §8B key: string as written, boolean "true"/"false", number shortest. */
+function decisionsValue(v: unknown): string {
+  return typeof v === "string" ? v : String(v)
+}
+
+/**
+ * Reads a Decisions API reply back into a System One-shaped body (canonical JSON), so decode,
+ * validation and the cache are the one path. `calibrated` is false. Exported for conformance tests.
+ */
+export function decisionsReply(reply: unknown, questions: Record<string, AnyQuestion>): string {
+  const r = reply as any
+  if (r === null || typeof r !== "object" || Array.isArray(r) || !Array.isArray(r.answers)) {
+    throw new Error("classifier: decisions: malformed reply")
+  }
+  const keys = Object.keys(questions).sort()
+  if (r.answers.length !== keys.length) {
+    throw new Error(`classifier: decisions: ${r.answers.length} answers for ${keys.length} questions`)
+  }
+  const num = (v: unknown): number => (typeof v === "number" ? v : 0)
+  const want: Record<string, string> = { noul: "predicate", choice: "choice", score: "score" }
+  const answers: Record<string, unknown> = {}
+  keys.forEach((k, i) => {
+    const a = r.answers[i]
+    if (a === null || typeof a !== "object" || Array.isArray(a)) throw new Error("classifier: decisions: malformed reply")
+    if (a.type === "refusal") throw new Error(`classifier: decisions: question "${k}" was refused`)
+    const q = questions[k]
+    const w = want[q.type] ?? ""
+    if (a.type !== w) throw new Error(`classifier: decisions: answer "${k}" is a ${a.type} answer, not ${w}`)
+    const probs: Record<string, number> = {}
+    for (const p of Array.isArray(a.probabilities) ? a.probabilities : []) probs[decisionsValue(p?.value)] = num(p?.probability)
+    if (q.type === "noul") answers[k] = { type: "noul", noul: num(a.probability) }
+    else if (q.type === "choice") {
+      answers[k] = { type: "choice", choice: decisionsValue(a.choice), probabilities: probs, confidence: num(a.confidence) }
+    } else {
+      const legend: Record<string, string> = {}
+      ;(q as ScoreQuestion).criteria.forEach((l, j) => (legend[String(j)] = l))
+      answers[k] = { type: "score", score: num(a.score), legend, probabilities: probs, confidence: num(a.confidence) }
+    }
+  })
+  const u = r.usage ?? {}
+  return canonicalJson({
+    answers,
+    calibrated: false,
+    model: typeof r.model === "string" ? r.model : "",
+    usage: { input_tokens: num(u.input_tokens), output_tokens: num(u.output_tokens) },
+  })
+}