@hawkeyexl/inference 0.0.1

package/dist/index.js

@@ -0,0 +1,722 @@
+// src/types.ts
+var InferenceError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InferenceError";
+  }
+};
+
+// src/providers/anthropic.ts
+import Anthropic from "@anthropic-ai/sdk";
+var DEFAULT_TOOL_NAME = "record_result";
+var AnthropicProvider = class {
+  constructor(model, apiKeyEnv, options = {}) {
+    this.model = model;
+    const apiKey = process.env[apiKeyEnv];
+    if (!apiKey) {
+      throw new InferenceError(
+        `Anthropic provider needs ${apiKeyEnv} set (or choose another provider)`
+      );
+    }
+    this.client = new Anthropic({ apiKey });
+    this.toolName = options.toolName ?? DEFAULT_TOOL_NAME;
+    this.toolDescription = options.toolDescription ?? "Record the structured result.";
+    this.maxTokens = options.maxTokens ?? 1024;
+  }
+  model;
+  client;
+  toolName;
+  toolDescription;
+  maxTokens;
+  provider() {
+    return "anthropic";
+  }
+  modelName() {
+    return this.model;
+  }
+  async completeJSON(req) {
+    const response = await this.client.messages.create({
+      model: this.model,
+      max_tokens: this.maxTokens,
+      temperature: req.temperature,
+      system: req.system,
+      messages: [{ role: "user", content: req.user }],
+      tools: [
+        {
+          name: this.toolName,
+          description: this.toolDescription,
+          input_schema: req.schema
+        }
+      ],
+      tool_choice: { type: "tool", name: this.toolName }
+    });
+    if (response.stop_reason === "max_tokens") {
+      throw new Error(
+        `Anthropic response hit max_tokens (${this.maxTokens}) before completing the tool call \u2014 raise the anthropic.maxTokens option.`
+      );
+    }
+    const toolUse = response.content.find(
+      (block) => block.type === "tool_use"
+    );
+    if (!toolUse) {
+      throw new Error("Anthropic response contained no tool_use block");
+    }
+    return {
+      json: toolUse.input,
+      usage: {
+        inputTokens: response.usage.input_tokens,
+        outputTokens: response.usage.output_tokens
+      }
+    };
+  }
+};
+
+// src/providers/openai-compat.ts
+function extractJson(content) {
+  const trimmed = content.replace(/^\s*```(?:json)?\s*/i, "").replace(/\s*```\s*$/, "").trim();
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    const start = trimmed.indexOf("{");
+    const end = trimmed.lastIndexOf("}");
+    if (start >= 0 && end > start) {
+      return JSON.parse(trimmed.slice(start, end + 1));
+    }
+    throw new Error("Response contained no parseable JSON object");
+  }
+}
+function toStrictSchema(schema) {
+  const clone = structuredClone(schema);
+  const walk = (node) => {
+    if (node === null || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      for (const item of node) walk(item);
+      return;
+    }
+    const obj = node;
+    delete obj["minLength"];
+    delete obj["uniqueItems"];
+    const properties = obj["properties"];
+    if (properties && typeof properties === "object") {
+      obj["required"] = Object.keys(properties);
+      obj["additionalProperties"] = false;
+      for (const prop of Object.values(properties)) {
+        walk(prop);
+        if (prop && typeof prop === "object" && !Array.isArray(prop)) {
+          const p = prop;
+          if (typeof p["type"] === "string" && p["type"] !== "null") {
+            p["type"] = [p["type"], "null"];
+          }
+        }
+      }
+    }
+    walk(obj["items"]);
+  };
+  walk(clone);
+  return clone;
+}
+function stripNulls(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.entries(value).filter(
+      ([, v]) => v !== null
+    )
+  );
+}
+var OpenAICompatProvider = class {
+  constructor(baseUrl, model, apiKeyEnv, apiKey = process.env[apiKeyEnv], options = {}) {
+    this.baseUrl = baseUrl;
+    this.model = model;
+    this.apiKey = apiKey;
+    if (!this.apiKey && baseUrl.includes("api.openai.com")) {
+      throw new InferenceError(
+        `OpenAI provider needs ${apiKeyEnv} set (or point baseUrl at a local server)`
+      );
+    }
+    this.schemaName = options.schemaName ?? "result";
+  }
+  baseUrl;
+  model;
+  apiKey;
+  supportsJsonSchema = true;
+  schemaName;
+  provider() {
+    return "openai";
+  }
+  modelName() {
+    return this.model;
+  }
+  async chat(body) {
+    const response = await fetch(
+      `${this.baseUrl.replace(/\/$/, "")}/chat/completions`,
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          ...this.apiKey ? { authorization: `Bearer ${this.apiKey}` } : {}
+        },
+        body: JSON.stringify(body)
+      }
+    );
+    const json = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      const message = json.error?.message ?? `HTTP ${response.status}`;
+      throw new Error(`${message}`);
+    }
+    return json;
+  }
+  async completeJSON(req) {
+    const base = {
+      model: this.model,
+      temperature: req.temperature,
+      messages: [
+        { role: "system", content: req.system },
+        { role: "user", content: req.user }
+      ]
+    };
+    let response;
+    if (this.supportsJsonSchema) {
+      try {
+        response = await this.chat({
+          ...base,
+          response_format: {
+            type: "json_schema",
+            json_schema: {
+              name: this.schemaName,
+              strict: true,
+              schema: toStrictSchema(req.schema)
+            }
+          }
+        });
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        if (!/response_format|json_schema|schema/i.test(message) && message !== "HTTP 400") {
+          throw e;
+        }
+        this.supportsJsonSchema = false;
+        response = await this.jsonObjectFallback(base, req);
+      }
+    } else {
+      response = await this.jsonObjectFallback(base, req);
+    }
+    const content = response.choices?.[0]?.message?.content;
+    if (!content) throw new Error("Empty completion response");
+    return {
+      json: stripNulls(extractJson(content)),
+      usage: response.usage?.prompt_tokens != null ? {
+        inputTokens: response.usage.prompt_tokens ?? 0,
+        outputTokens: response.usage.completion_tokens ?? 0
+      } : void 0
+    };
+  }
+  jsonObjectFallback(base, req) {
+    return this.chat({
+      ...base,
+      messages: [
+        {
+          role: "system",
+          content: `${req.system}
+
+Respond with ONLY a JSON object conforming to this JSON Schema:
+${JSON.stringify(req.schema)}`
+        },
+        { role: "user", content: req.user }
+      ],
+      response_format: { type: "json_object" }
+    });
+  }
+};
+
+// src/exec.ts
+import spawn from "cross-spawn";
+var realExec = (cmd, opts = {}) => {
+  const [bin, ...args] = cmd;
+  if (!bin) {
+    return Promise.resolve({
+      code: null,
+      stdout: "",
+      stderr: "",
+      timedOut: false,
+      spawnError: "Empty command"
+    });
+  }
+  return new Promise((resolvePromise) => {
+    const child = spawn(bin, args, {
+      cwd: opts.cwd,
+      env: { ...process.env, ...opts.env ?? {} },
+      stdio: [opts.input != null ? "pipe" : "ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+    const timeoutMs = opts.timeoutMs ?? 6e4;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill();
+      settle({ code: null, stdout, stderr, timedOut: true });
+    }, timeoutMs);
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolvePromise(result);
+    };
+    if (opts.input != null && child.stdin) {
+      child.stdin.on("error", () => {
+      });
+      child.stdin.end(opts.input);
+    }
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (d) => stdout += d);
+    child.stderr?.on("data", (d) => stderr += d);
+    child.on(
+      "error",
+      (e) => settle({ code: null, stdout, stderr, timedOut, spawnError: e.message })
+    );
+    child.on("close", (code) => settle({ code, stdout, stderr, timedOut }));
+  });
+};
+
+// src/providers/claude-cli.ts
+var ClaudeCliProvider = class {
+  constructor(model, command = "claude", exec = realExec, timeoutMs = 18e4) {
+    this.model = model;
+    this.command = command;
+    this.exec = exec;
+    this.timeoutMs = timeoutMs;
+  }
+  model;
+  command;
+  exec;
+  timeoutMs;
+  provider() {
+    return "claude-cli";
+  }
+  modelName() {
+    return this.model;
+  }
+  async completeJSON(req) {
+    const prompt = [
+      req.user,
+      "",
+      "Respond with ONLY a JSON object conforming to this JSON Schema \u2014 no",
+      "prose, no markdown fences:",
+      JSON.stringify(req.schema)
+    ].join("\n");
+    const result = await this.exec(
+      [
+        this.command,
+        "-p",
+        "--append-system-prompt",
+        req.system,
+        "--output-format",
+        "json",
+        "--model",
+        this.model
+      ],
+      { timeoutMs: this.timeoutMs, input: prompt }
+    );
+    if (result.spawnError) {
+      throw new Error(
+        `Failed to run ${this.command}: ${result.spawnError} (is the Claude CLI installed?)`
+      );
+    }
+    if (result.timedOut) throw new Error("Claude CLI timed out");
+    if (result.code !== 0) {
+      throw new Error(
+        `Claude CLI exited ${result.code}: ${result.stderr.trim().slice(-300)}`
+      );
+    }
+    const wrapper = JSON.parse(result.stdout);
+    if (typeof wrapper.result !== "string") {
+      throw new Error("Claude CLI returned no result field");
+    }
+    return { json: extractJson(wrapper.result) };
+  }
+};
+
+// src/providers/mock.ts
+var MockProvider = class {
+  constructor(responses, model = "mock-model") {
+    this.responses = responses;
+    this.model = model;
+    if (responses.length === 0) {
+      throw new Error("MockProvider needs at least one scripted response");
+    }
+  }
+  responses;
+  model;
+  calls = 0;
+  /** Every request seen, in order — assert against this in tests. */
+  requests = [];
+  provider() {
+    return "mock";
+  }
+  modelName() {
+    return this.model;
+  }
+  completeJSON(req) {
+    this.requests.push(req);
+    const response = this.responses[this.calls % this.responses.length];
+    this.calls += 1;
+    if ("error" in response) {
+      return Promise.reject(new Error(response.error));
+    }
+    return Promise.resolve({
+      json: response.json,
+      usage: response.usage ?? { inputTokens: 500, outputTokens: 100 }
+    });
+  }
+};
+function mockVerdict(match, confidence, overrides = {}) {
+  return {
+    json: {
+      claim: overrides.claim ?? "The assertion under test",
+      observed: overrides.observed ?? "Observed content",
+      match,
+      confidence,
+      reasoning: overrides.reasoning ?? "Scripted mock reasoning"
+    }
+  };
+}
+
+// src/providers/index.ts
+var DEFAULT_MODELS = {
+  anthropic: "claude-sonnet-4-5",
+  openai: "gpt-4o-mini",
+  "claude-cli": "claude-sonnet-4-5",
+  mock: "mock-model"
+};
+var DEFAULT_API_KEY_ENV = {
+  anthropic: "ANTHROPIC_API_KEY",
+  openai: "OPENAI_API_KEY"
+};
+var DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1";
+function resolveProviderIdentity(spec) {
+  return {
+    provider: spec.provider,
+    model: spec.model ?? DEFAULT_MODELS[spec.provider] ?? "unknown"
+  };
+}
+function makeProvider(spec) {
+  const { model } = resolveProviderIdentity(spec);
+  switch (spec.provider) {
+    case "anthropic":
+      return new AnthropicProvider(
+        model,
+        spec.apiKeyEnv ?? DEFAULT_API_KEY_ENV["anthropic"],
+        spec.anthropic ?? {}
+      );
+    case "openai":
+      return new OpenAICompatProvider(
+        spec.baseUrl ?? DEFAULT_OPENAI_BASE_URL,
+        model,
+        spec.apiKeyEnv ?? DEFAULT_API_KEY_ENV["openai"],
+        void 0,
+        spec.openai ?? {}
+      );
+    case "claude-cli":
+      return new ClaudeCliProvider(
+        model,
+        spec.command ?? "claude",
+        spec.exec,
+        spec.timeoutMs
+      );
+    case "mock":
+      return new MockProvider(spec.mockResponses ?? [{ json: {} }], model);
+    default:
+      throw new InferenceError(
+        `Unknown provider "${String(spec.provider)}". Available: ${Object.keys(
+          DEFAULT_MODELS
+        ).join(", ")}.`
+      );
+  }
+}
+
+// src/complete.ts
+import { Ajv2020 } from "ajv/dist/2020.js";
+var validatorCache = /* @__PURE__ */ new WeakMap();
+function validatorFor(schema) {
+  const cached = validatorCache.get(schema);
+  if (cached) return cached;
+  const compiled = new Ajv2020({ allErrors: true }).compile(schema);
+  validatorCache.set(schema, compiled);
+  return compiled;
+}
+async function completeValidatedJSON(options) {
+  const {
+    provider,
+    system,
+    user,
+    schema,
+    temperature = 0,
+    attempts = 2
+  } = options;
+  const validate = options.validate ?? validatorFor(schema);
+  const start = Date.now();
+  const base = {
+    provider: provider.provider(),
+    model: provider.modelName(),
+    cached: false
+  };
+  let lastError = "unknown error";
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try {
+      const response = await provider.completeJSON({
+        system,
+        user,
+        schema,
+        temperature
+      });
+      if (validate(response.json)) {
+        return {
+          ...base,
+          result: response.json,
+          usage: response.usage,
+          durationMs: Date.now() - start
+        };
+      }
+      lastError = `Response failed schema validation: ${(validate.errors ?? []).map((e) => `${e.instancePath} ${e.message}`).join("; ")}`;
+    } catch (e) {
+      lastError = e instanceof Error ? e.message : String(e);
+    }
+  }
+  return { ...base, error: lastError, durationMs: Date.now() - start };
+}
+
+// src/cache.ts
+import { createHash } from "crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+function sha256(text) {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+function buildCacheKey(parts) {
+  return sha256(parts.map((p) => `${p.length}:${p}`).join("|"));
+}
+var JsonCache = class {
+  constructor(dir, enabled = true, label = "inference") {
+    this.dir = dir;
+    this.enabled = enabled;
+    this.label = label;
+  }
+  dir;
+  enabled;
+  label;
+  /** Cache-write failures warn once per process, not once per entry. */
+  warned = false;
+  get(key) {
+    if (!this.enabled) return void 0;
+    const path = join(this.dir, `${key}.json`);
+    if (!existsSync(path)) return void 0;
+    try {
+      return JSON.parse(readFileSync(path, "utf8"));
+    } catch {
+      return void 0;
+    }
+  }
+  set(key, value) {
+    if (!this.enabled) return;
+    try {
+      mkdirSync(this.dir, { recursive: true });
+      writeFileSync(
+        join(this.dir, `${key}.json`),
+        JSON.stringify(value, null, 2)
+      );
+    } catch (e) {
+      if (!this.warned) {
+        this.warned = true;
+        console.warn(
+          `${this.label}: could not write the cache at ${this.dir} (${e instanceof Error ? e.message : String(e)}). Continuing without caching.`
+        );
+      }
+    }
+  }
+};
+
+// src/cost.ts
+var PRICE_TABLE = {
+  "claude-sonnet-4-5": { inputPerMTok: 3, outputPerMTok: 15 },
+  "claude-sonnet-4-6": { inputPerMTok: 3, outputPerMTok: 15 },
+  "claude-haiku-4-5": { inputPerMTok: 1, outputPerMTok: 5 },
+  "claude-opus-4-8": { inputPerMTok: 15, outputPerMTok: 75 },
+  "gpt-4o-mini": { inputPerMTok: 0.15, outputPerMTok: 0.6 },
+  "gpt-4o": { inputPerMTok: 2.5, outputPerMTok: 10 }
+};
+function pricingFor(model, override) {
+  if (override) return override;
+  if (PRICE_TABLE[model]) return PRICE_TABLE[model];
+  const base = Object.keys(PRICE_TABLE).filter((k) => model.startsWith(k)).sort((a, b) => b.length - a.length)[0];
+  return base ? PRICE_TABLE[base] : void 0;
+}
+function costOfUsage(usage, pricing) {
+  if (!usage || !pricing) return 0;
+  return usage.inputTokens / 1e6 * pricing.inputPerMTok + usage.outputTokens / 1e6 * pricing.outputPerMTok;
+}
+function costOfRuns(runs, pricing) {
+  if (!pricing) return 0;
+  let usd = 0;
+  for (const run of runs) {
+    if (!run.usage || run.cached) continue;
+    usd += costOfUsage(run.usage, pricing);
+  }
+  return usd;
+}
+
+// src/judge/verdict-schema.json
+var verdict_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "inference:verdict:0.1",
+  title: "LLM-as-judge verdict",
+  type: "object",
+  required: ["claim", "observed", "match", "confidence", "reasoning"],
+  properties: {
+    claim: {
+      type: "string",
+      description: "The specific assertion under evaluation."
+    },
+    observed: {
+      type: "string",
+      description: "What was actually observed in the subject under evaluation, quoting evidence where possible."
+    },
+    match: {
+      enum: ["pass", "fail", "partial"],
+      description: "pass only if the assertion is fully satisfied; partial for partial compliance."
+    },
+    confidence: {
+      type: "number",
+      minimum: 0,
+      maximum: 1,
+      description: "Self-reported confidence in this verdict."
+    },
+    reasoning: {
+      type: "string",
+      description: "Why this conclusion was reached."
+    }
+  },
+  additionalProperties: false
+};
+
+// src/judge/types.ts
+var VERDICT_SCHEMA = verdict_schema_default;
+
+// src/judge/consensus.ts
+function computeConsensus(runs) {
+  const votes = { pass: 0, fail: 0, partial: 0, error: 0 };
+  let confidenceSum = 0;
+  let confidenceCount = 0;
+  for (const run of runs) {
+    if (!run.verdict) {
+      votes.error += 1;
+      continue;
+    }
+    votes[run.verdict.match] += 1;
+    confidenceSum += run.verdict.confidence;
+    confidenceCount += 1;
+  }
+  const passVotes = votes.pass;
+  const failVotes = votes.fail + votes.partial;
+  const verdict = passVotes > failVotes ? "pass" : "fail";
+  const graded = passVotes + failVotes;
+  const agreement = graded > 0 ? Math.max(passVotes, failVotes) / graded : 0;
+  const meanConfidence = confidenceCount > 0 ? confidenceSum / confidenceCount : 0;
+  return { runs, votes, verdict, agreement, meanConfidence };
+}
+
+// src/judge/zones.ts
+var DEFAULT_ZONES = { autoPass: 0.8, autoFail: 0.8 };
+function zoneFor(consensus, thresholds = DEFAULT_ZONES) {
+  const { votes, meanConfidence } = consensus;
+  const unanimousPass = votes.pass > 0 && votes.fail === 0 && votes.partial === 0 && votes.error === 0;
+  const unanimousFail = votes.pass === 0 && votes.error === 0 && votes.fail + votes.partial > 0;
+  if (unanimousPass && meanConfidence >= thresholds.autoPass) return "auto-pass";
+  if (unanimousFail && meanConfidence >= thresholds.autoFail) return "auto-fail";
+  return "human-review";
+}
+
+// src/judge/ensemble.ts
+var warnedTemperature = false;
+async function runEnsemble(options) {
+  const {
+    provider,
+    system,
+    user,
+    runs: runCount = 3,
+    temperature = 0,
+    schema = VERDICT_SCHEMA,
+    cache,
+    cacheKey,
+    label = "inference"
+  } = options;
+  if (temperature > 0 && !warnedTemperature) {
+    warnedTemperature = true;
+    console.warn(
+      `${label}: judge temperature is ${temperature} \u2014 nonzero temperature adds noise to verdicts; 0 is strongly recommended.`
+    );
+  }
+  if (cache && cacheKey) {
+    const hit = cache.get(cacheKey);
+    if (Array.isArray(hit)) return hit.map((r) => ({ ...r, cached: true }));
+  }
+  const validate = validatorFor(schema);
+  const results = [];
+  for (let i = 0; i < runCount; i++) {
+    const run = await completeValidatedJSON({
+      provider,
+      system,
+      user,
+      schema,
+      temperature,
+      validate
+    });
+    const { result, ...rest } = run;
+    results.push(result === void 0 ? rest : { ...rest, verdict: result });
+  }
+  if (cache && cacheKey) cache.set(cacheKey, results);
+  return results;
+}
+async function judge(options) {
+  const runs = await runEnsemble(options);
+  const base = computeConsensus(runs);
+  return { ...base, zone: zoneFor(base, options.zones ?? DEFAULT_ZONES) };
+}
+function resetTemperatureWarning() {
+  warnedTemperature = false;
+}
+export {
+  AnthropicProvider,
+  ClaudeCliProvider,
+  DEFAULT_MODELS,
+  DEFAULT_OPENAI_BASE_URL,
+  DEFAULT_ZONES,
+  InferenceError,
+  JsonCache,
+  MockProvider,
+  OpenAICompatProvider,
+  PRICE_TABLE,
+  VERDICT_SCHEMA,
+  buildCacheKey,
+  completeValidatedJSON,
+  computeConsensus,
+  costOfRuns,
+  costOfUsage,
+  extractJson,
+  judge,
+  makeProvider,
+  mockVerdict,
+  pricingFor,
+  realExec,
+  resetTemperatureWarning,
+  resolveProviderIdentity,
+  runEnsemble,
+  sha256,
+  stripNulls,
+  toStrictSchema,
+  validatorFor,
+  zoneFor
+};
+//# sourceMappingURL=index.js.map