@demlik/tea 0.13.0 → 0.15.0

package/dist/jev/index.js

@@ -0,0 +1,485 @@
+import { createBatchWindow, subscribeBatchWindow } from '../chunk-QPEVCJ5Q.js';
+import '../chunk-LFZUK6J2.js';
+import { createFanOut } from '../chunk-MYXFNWAJ.js';
+import '../chunk-TXN2KFHF.js';
+import { runCmdDef, createResilientCall, MsgType } from '../chunk-AYS5N6WY.js';
+export { mountResilientCall } from '../chunk-AYS5N6WY.js';
+import '../chunk-VBDU4JL6.js';
+import { initCache, has, set, evictExpired, cacheEvictionSub, cacheEvictionSubscribe, get } from '../chunk-22POWGFA.js';
+export { deadlineSub, subscribeDeadline } from '../chunk-22POWGFA.js';
+import { describeError } from '../chunk-G5E74IJB.js';
+import { liftSlice, readInOrder } from '../chunk-66PY5WYF.js';
+import { z } from 'zod';
+
+var jevQuestions = (questions) => questions;
+var JEV_ENDPOINT = "https://api.typesafe.ai/v1/systemone";
+var JEV_ERR_TAG_WITNESS = {
+  malformed_body: true,
+  missing_answer: true,
+  answer_type_mismatch: true,
+  off_criteria_choice: true,
+  off_criteria_probabilities: true,
+  malformed_answer: true
+};
+var JEV_ERR_TAGS = new Set(
+  Object.keys(JEV_ERR_TAG_WITNESS)
+);
+function isJevErr(value) {
+  if (!("_tag" in value)) return false;
+  const tag = value._tag;
+  const tags = JEV_ERR_TAGS;
+  return typeof tag === "string" && tags.has(tag);
+}
+var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var at = (value, key) => isObj(value) ? value[key] : void 0;
+var err = (error) => ({
+  ok: false,
+  error
+});
+var finite = z.number().finite();
+var answerSchema = (question) => {
+  switch (question.type) {
+    case "noul":
+      return z.object({ type: z.literal("noul"), noul: finite });
+    case "score":
+      return z.object({
+        type: z.literal("score"),
+        confidence: finite,
+        score: finite,
+        legend: z.record(z.string(), z.string()),
+        probabilities: z.record(z.string(), finite)
+      });
+    case "choice": {
+      const options = Object.keys(question.criteria);
+      return z.object({
+        type: z.literal("choice"),
+        choice: z.enum(options),
+        confidence: finite,
+        // `JevChoiceAnswer<K>` types `probabilities` as TOTAL over the criteria
+        // keys. A strict object whose shape is those keys IS that claim: a
+        // missing key fails the shape, an extra one is unrecognized.
+        probabilities: z.strictObject(
+          Object.fromEntries(options.map((k) => [k, finite]))
+        )
+      });
+    }
+  }
+};
+var jevAnswersSchema = (questions) => z.object(
+  Object.fromEntries(
+    Object.entries(questions).map(([id, question]) => [
+      id,
+      answerSchema(question)
+    ])
+  )
+);
+var responseSchema = (questions) => z.object({
+  model: z.string(),
+  usage: z.object({ input_tokens: finite, output_tokens: finite }),
+  answers: jevAnswersSchema(questions)
+});
+var ANSWER_FIELD_REASON = {
+  confidence: "`confidence` is not a number",
+  score: "`score` is not a number",
+  legend: "`legend` is not a map of strings",
+  probabilities: "`probabilities` is not a map of numbers",
+  choice: "`choice` is not a string",
+  noul: "`noul` is not a number"
+};
+var toJevErr = (questions, body, issue) => {
+  const [head, id, field] = issue?.path ?? [];
+  if (head === "model") {
+    return { _tag: "malformed_body", reason: "`model` is not a string" };
+  }
+  if (head === "usage") {
+    return {
+      _tag: "malformed_body",
+      reason: "`usage` is not `{ input_tokens, output_tokens }`"
+    };
+  }
+  if (head !== "answers") {
+    return { _tag: "malformed_body", reason: "body is not an object" };
+  }
+  const answers = at(body, "answers");
+  if (!isObj(answers) || typeof id !== "string") {
+    return { _tag: "malformed_body", reason: "`answers` is not an object" };
+  }
+  if (!Object.hasOwn(answers, id)) return { _tag: "missing_answer", id };
+  const answer = answers[id];
+  const question = questions[id];
+  if (question === void 0 || field === void 0) {
+    return { _tag: "malformed_answer", id, reason: "answer is not an object" };
+  }
+  if (field === "type") {
+    const received = at(answer, "type");
+    return typeof received === "string" ? { _tag: "answer_type_mismatch", id, expected: question.type, received } : { _tag: "malformed_answer", id, reason: "answer has no `type`" };
+  }
+  if (question.type === "choice") {
+    const options = Object.keys(question.criteria);
+    if (field === "choice") {
+      const choice = at(answer, "choice");
+      if (typeof choice === "string") {
+        return { _tag: "off_criteria_choice", id, choice, options };
+      }
+    }
+    if (field === "probabilities") {
+      const probabilities = at(answer, "probabilities");
+      const key = issue?.path[3];
+      const badValue = isObj(probabilities) && typeof key === "string" && Object.hasOwn(probabilities, key);
+      if (isObj(probabilities) && !badValue) {
+        return {
+          _tag: "off_criteria_probabilities",
+          id,
+          missing: options.filter((k) => !Object.hasOwn(probabilities, k)),
+          extra: Object.keys(probabilities).filter((k) => !options.includes(k)),
+          options
+        };
+      }
+    }
+  }
+  const named = typeof field === "string" ? ANSWER_FIELD_REASON[field] : void 0;
+  return {
+    _tag: "malformed_answer",
+    id,
+    reason: named ?? issue?.message ?? "answer is malformed"
+  };
+};
+var parseAnswers = (questions, body) => {
+  const parsed = responseSchema(questions).safeParse(body);
+  if (!parsed.success) {
+    return err(toJevErr(questions, body, parsed.error.issues[0]));
+  }
+  const { answers, model, usage } = parsed.data;
+  return { ok: true, answers, model, usage };
+};
+var classifyStatus = (status) => {
+  if (status >= 200 && status < 300) return "ok";
+  if (status === 429 || status === 529) return "retry";
+  return "terminal";
+};
+
+// src/internal/jev/ask/index.ts
+function isTransientJevAskErr(error) {
+  return error._tag === "http_retry" || error._tag === "port_threw";
+}
+var JevAskFailure = class extends Error {
+  constructor(jev) {
+    super(`jev ask: ${jev._tag}`);
+    this.jev = jev;
+    this.name = "JevAskFailure";
+  }
+  jev;
+};
+function toAskErr(error) {
+  if (error instanceof JevAskFailure) return error.jev;
+  return { _tag: "port_threw", reason: describeError(error) };
+}
+var DEFAULT_JEV_MODEL = "jev-latest";
+var NO_USAGE = { input_tokens: 0, output_tokens: 0 };
+function jevAskCmdDef() {
+  return runCmdDef();
+}
+function createJevAsk(config, rng = Math.random) {
+  const resilientConfig = {
+    ...config.retry === void 0 ? {} : { retry: config.retry }
+  };
+  const rc = createResilientCall(resilientConfig, rng);
+  const model = config.model ?? DEFAULT_JEV_MODEL;
+  function isErrDecision(decided) {
+    return isJevErr(decided);
+  }
+  function liveRequest(s, key) {
+    const call = s.calls[key];
+    if (call?.phase === "running" || call?.phase === "waiting_retry") {
+      return call.input;
+    }
+    return void 0;
+  }
+  function init() {
+    return rc.init();
+  }
+  function attempt(s, key, content, at2) {
+    const request = {
+      state: content,
+      model,
+      questions: config.questions
+    };
+    return rc.attempt(s, key, request, at2);
+  }
+  function succeed(s, key, msg) {
+    return rc.succeed(s, key, msg);
+  }
+  function settleFromFallback(s, key, request, fallback, at2) {
+    const decided = fallback(request);
+    if (isErrDecision(decided)) return rc.settleFailed(s, key, decided);
+    return rc.succeed(s, key, {
+      type: MsgType.ResilientOk,
+      key,
+      result: {
+        answers: decided,
+        model: request.model,
+        usage: NO_USAGE,
+        source: "fallback"
+      },
+      at: at2
+    });
+  }
+  function fail(s, key, msg) {
+    if (!isTransientJevAskErr(msg.error)) {
+      return rc.settleFailed(s, key, msg.error);
+    }
+    const request = liveRequest(s, key);
+    const settled = rc.fail(s, key, msg);
+    const backedOff = settled[0].calls[key]?.phase !== "failed";
+    if (backedOff || config.fallback === void 0 || request === void 0) {
+      return settled;
+    }
+    return settleFromFallback(s, key, request, config.fallback, msg.at);
+  }
+  function onTimer(s, msg) {
+    return rc.onTimer(s, msg);
+  }
+  function subs(s) {
+    return rc.subs(s);
+  }
+  async function ask(request, signal) {
+    if (config.port === void 0) {
+      if (config.fallback === void 0) {
+        throw new JevAskFailure({ _tag: "no_answer_path" });
+      }
+      const decided = config.fallback(request);
+      if (isErrDecision(decided)) throw new JevAskFailure(decided);
+      return {
+        answers: decided,
+        model: request.model,
+        usage: NO_USAGE,
+        source: "fallback"
+      };
+    }
+    const { status, body } = await config.port(request, signal);
+    const kind = classifyStatus(status);
+    if (kind === "retry")
+      throw new JevAskFailure({ _tag: "http_retry", status });
+    if (kind === "terminal") {
+      throw new JevAskFailure({ _tag: "http_terminal", status });
+    }
+    const parsed = parseAnswers(config.questions, body);
+    if (!parsed.ok) throw new JevAskFailure(parsed.error);
+    return {
+      answers: parsed.answers,
+      model: parsed.model,
+      usage: parsed.usage,
+      source: "port"
+    };
+  }
+  const resilientRunHandler = rc.handlers({
+    run: (request) => ask(request)
+  }).resilient_run;
+  async function settleOf(cmd) {
+    const settle = await resilientRunHandler(cmd, {});
+    if (settle.type === MsgType.ResilientOk) return settle;
+    return {
+      type: MsgType.ResilientErr,
+      key: settle.key,
+      error: toAskErr(settle.error),
+      at: settle.at
+    };
+  }
+  function handlers() {
+    return { resilient_run: (cmd) => settleOf(cmd) };
+  }
+  return {
+    name: rc.name,
+    init,
+    attempt,
+    succeed,
+    fail,
+    onTimer,
+    subs,
+    handlers,
+    ask
+  };
+}
+function liftJevAsk(state, result) {
+  return liftSlice("resilience", state, result);
+}
+
+// src/internal/jev/classify-batch/index.ts
+var DEFAULT_CLASSIFY_MAX_ITEMS = 25;
+function createClassifyBatch(config) {
+  const maxItems = config.maxItems ?? DEFAULT_CLASSIFY_MAX_ITEMS;
+  const askCmd = jevAskCmdDef();
+  const instructionsFor = config.instructions ?? ((key) => `Classify the element of \`state\` whose key is "${key}".`);
+  function idOfBatch(batch) {
+    return batch.id;
+  }
+  function questionsFor(items) {
+    const questions = {};
+    for (const item of items) {
+      const key = config.keyOf(item);
+      questions[key] = {
+        type: "choice",
+        instructions: instructionsFor(key, item),
+        criteria: config.criteria
+      };
+    }
+    return questions;
+  }
+  function requestFor(batch) {
+    return {
+      state: batch.items,
+      model: config.model ?? DEFAULT_JEV_MODEL,
+      questions: questionsFor(batch.items)
+    };
+  }
+  const fanOut = createFanOut({
+    concurrency: config.concurrency,
+    idOf: idOfBatch,
+    of: (batch) => askCmd({ key: batch.id, input: requestFor(batch) })
+  });
+  const window = createBatchWindow({
+    maxItems,
+    maxMs: config.maxMs,
+    flush: (items) => ({ type: "classify_batch_flush", items })
+  });
+  function init() {
+    return {
+      window: window.init(),
+      fanOut: fanOut.init(),
+      cache: initCache(),
+      failed: {}
+    };
+  }
+  function keysInFlight(state) {
+    const keys = /* @__PURE__ */ new Set();
+    for (const item of state.window.buffer) keys.add(config.keyOf(item));
+    for (const batch of state.fanOut.pending) {
+      for (const item of batch.items) keys.add(config.keyOf(item));
+    }
+    for (const batch of state.fanOut.running) {
+      for (const item of batch.items) keys.add(config.keyOf(item));
+    }
+    return keys;
+  }
+  function runningBatch(state, id) {
+    return state.fanOut.running.find((batch) => batch.id === id);
+  }
+  function scatter(state, flushed) {
+    if (flushed.length === 0) return [state, []];
+    const batches = flushed.map((cmd) => ({
+      id: cmd.items.map(config.keyOf).join("\0"),
+      items: cmd.items
+    }));
+    return liftSlice("fanOut", state, fanOut.scatter(state.fanOut, batches));
+  }
+  function add(state, item, at2) {
+    const key = config.keyOf(item);
+    if (has(state.cache, key, at2)) return [state, []];
+    if (keysInFlight(state).has(key)) return [state, []];
+    const failed = { ...state.failed };
+    delete failed[key];
+    const [buffered, flushed] = liftSlice(
+      "window",
+      { ...state, failed },
+      window.add(state.window, item, at2)
+    );
+    return scatter(buffered, flushed);
+  }
+  function onWindow(state, at2) {
+    const [closed, flushed] = liftSlice(
+      "window",
+      state,
+      window.onWindow(state.window, at2)
+    );
+    return scatter(closed, flushed);
+  }
+  function onBatchOk(state, msg) {
+    let cache = state.cache;
+    for (const [key, answer] of Object.entries(msg.result.answers)) {
+      cache = set(cache, key, answer, msg.at, config.ttlMs);
+    }
+    const failed = { ...state.failed };
+    for (const key of Object.keys(msg.result.answers)) delete failed[key];
+    return liftSlice(
+      "fanOut",
+      { ...state, cache, failed },
+      fanOut.itemOk(state.fanOut, msg.key, msg.result)
+    );
+  }
+  function onBatchErr(state, msg) {
+    const batch = runningBatch(state, msg.key);
+    const failed = { ...state.failed };
+    if (batch !== void 0) {
+      for (const item of batch.items) failed[config.keyOf(item)] = msg.error;
+    }
+    return liftSlice(
+      "fanOut",
+      { ...state, failed },
+      fanOut.itemErr(state.fanOut, msg.key, msg.error)
+    );
+  }
+  function onEvict(state, at2) {
+    return liftSlice("cache", state, [evictExpired(state.cache, at2), []]);
+  }
+  const ANSWER_ORDER = [
+    {
+      name: "cache",
+      read: ({ state, key, at: at2 }) => {
+        const answer = get(state.cache, key, at2);
+        return answer === void 0 ? void 0 : { status: "answered", answer };
+      }
+    },
+    {
+      name: "failed",
+      read: ({ state, key }) => {
+        const error = state.failed[key];
+        return error === void 0 ? void 0 : { status: "failed", error };
+      }
+    },
+    {
+      name: "inFlight",
+      read: ({ state, key }) => keysInFlight(state).has(key) ? { status: "pending" } : void 0
+    }
+  ];
+  function answerFor(state, key, at2) {
+    return readInOrder({ state, key, at: at2 }, ANSWER_ORDER, { status: "absent" });
+  }
+  function subs(state, id = "jev-classify-batch") {
+    const windowSubs = window.subs(state.window, id);
+    if (config.evictEveryMs === void 0) return windowSubs;
+    return [...windowSubs, cacheEvictionSub(id, config.evictEveryMs)];
+  }
+  function subscribers() {
+    return { deadline: subscribeBatchWindow, cache: cacheEvictionSubscribe };
+  }
+  function handlers() {
+    return {
+      resilient_run: (cmd) => {
+        const request = cmd.input;
+        const ask = createJevAsk({
+          questions: request.questions,
+          ...config.port === void 0 ? {} : { port: config.port },
+          ...config.fallback === void 0 ? {} : { fallback: config.fallback },
+          ...config.model === void 0 ? {} : { model: config.model }
+        });
+        return ask.handlers().resilient_run(cmd);
+      }
+    };
+  }
+  return {
+    init,
+    add,
+    onWindow,
+    onBatchOk,
+    onBatchErr,
+    onEvict,
+    answerFor,
+    subs,
+    subscribers,
+    handlers
+  };
+}
+
+export { DEFAULT_CLASSIFY_MAX_ITEMS, DEFAULT_JEV_MODEL, JEV_ENDPOINT, JevAskFailure, classifyStatus, createClassifyBatch, createJevAsk, isJevErr, isTransientJevAskErr, jevAskCmdDef, jevQuestions, liftJevAsk, parseAnswers };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map