Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
5.9 KB
Raw Blame
/**
 * Per-item validation of a decision-model reply.
 *
 * A reply is validated item by item: an item that fails is marked
 * `valid: false` and every use treats it as absent, while the rest of the
 * batch stands. Nothing here throws on a bad item; only a reply whose
 * overall shape is unusable is rejected by the adapter.
 *
 * Shared by every adapter that returns the `systemone` answer shape, so
 * the rules cannot drift between routes.
 */

import type { DecisionAnswer, DecisionQuestion } from "./contract.ts";

/** How far a probability distribution may sum from 1 and still count. */
export const PROBABILITY_SUM_TOLERANCE = 0.02;

/** Client-side limits the wire format declares. */
export const CHOICE_MIN_OPTIONS = 1;
export const CHOICE_MAX_OPTIONS = 255;
export const SCORE_MIN_LEVELS = 2;
export const SCORE_MAX_LEVELS = 10;

function isRecord(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === "object" && !Array.isArray(value);
}

function isProbability(value: unknown): value is number {
  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
}

function invalid(type: DecisionQuestion["type"]): DecisionAnswer {
  return Object.freeze({ type, value: Number.NaN, valid: false });
}

/**
 * Confidence from a distribution over `n` outcomes when the provider did
 * not report one: `(n * p_max - 1) / (n - 1)`, 0 for a uniform
 * distribution and 1 for a certain one. Confidences from different
 * providers are not comparable, so this is only a stand-in.
 */
export function recomputeConfidence(probabilities: ReadonlyArray<number>, n: number): number {
  if (n < 2) return 1;
  const pMax = Math.max(...probabilities, 0);
  const c = (n * pMax - 1) / (n - 1);
  return Math.min(1, Math.max(0, c));
}

/**
 * Read a probability map whose keys must all be in `allowed`. Returns null
 * when any key is unknown, any value is not a probability, or the sum is
 * off by more than {@link PROBABILITY_SUM_TOLERANCE}. Missing keys count
 * as 0.
 */
function readDistribution(
  raw: unknown,
  allowed: ReadonlyArray<string>,
): Record<string, number> | null {
  if (!isRecord(raw)) return null;
  const allowedSet = new Set(allowed);
  const out: Record<string, number> = {};
  for (const key of allowed) out[key] = 0;
  let sum = 0;
  for (const [key, value] of Object.entries(raw)) {
    if (!allowedSet.has(key) || !isProbability(value)) return null;
    out[key] = value;
    sum += value;
  }
  if (Math.abs(sum - 1) > PROBABILITY_SUM_TOLERANCE) return null;
  return out;
}

function readConfidence(raw: unknown, fallback: number): number {
  return isProbability(raw) ? raw : fallback;
}

/** Validate one reply item against the question it answers. */
export function validateAnswer(question: DecisionQuestion, raw: unknown): DecisionAnswer {
  if (!isRecord(raw)) return invalid(question.type);
  if (raw["type"] !== undefined && raw["type"] !== question.type) return invalid(question.type);

  if (question.type === "noul") {
    const p = raw["noul"];
    if (!isProbability(p)) return invalid("noul");
    return Object.freeze({ type: "noul", value: p, valid: true });
  }

  if (question.type === "choice") {
    const options = Object.keys(question.criteria);
    const choice = raw["choice"];
    if (typeof choice !== "string" || !options.includes(choice)) return invalid("choice");
    const probabilities = readDistribution(raw["probabilities"], options);
    if (probabilities === null) return invalid("choice");
    const pMax = Math.max(...Object.values(probabilities));
    // The reported choice must be the argmax (ties allowed): a reply
    // whose label and distribution disagree says nothing reliable.
    if (probabilities[choice]! + 1e-9 < pMax) return invalid("choice");
    const confidence = readConfidence(
      raw["confidence"],
      recomputeConfidence(Object.values(probabilities), options.length),
    );
    return Object.freeze({
      type: "choice",
      value: choice,
      probabilities: Object.freeze(probabilities),
      confidence,
      valid: true,
    });
  }

  const levels = question.criteria.length;
  const keys = Array.from({ length: levels }, (_, i) => String(i));
  const probabilities = readDistribution(raw["probabilities"], keys);
  if (probabilities === null) return invalid("score");
  const expected = keys.reduce((acc, key, i) => acc + i * probabilities[key]!, 0);
  const reported = raw["score"];
  const value =
    typeof reported === "number" &&
    Number.isFinite(reported) &&
    reported >= 0 &&
    reported <= levels - 1
      ? reported
      : expected;
  const confidence = readConfidence(
    raw["confidence"],
    recomputeConfidence(Object.values(probabilities), levels),
  );
  return Object.freeze({
    type: "score",
    value,
    probabilities: Object.freeze(probabilities),
    confidence,
    valid: true,
  });
}

/**
 * Client-side limits, checked before anything is sent. Returns the first
 * violation as a sentence, or null when every question is within limits.
 * `maxChoiceOptions` is the route's own limit (52 for OpenJev, for
 * example), never above the wire maximum.
 */
export function questionLimitViolation(
  questions: Readonly<Record<string, DecisionQuestion>>,
  maxChoiceOptions: number = CHOICE_MAX_OPTIONS,
): string | null {
  const maxOptions = Math.min(CHOICE_MAX_OPTIONS, Math.max(CHOICE_MIN_OPTIONS, maxChoiceOptions));
  for (const [id, q] of Object.entries(questions)) {
    if (q.type === "choice") {
      const n = Object.keys(q.criteria).length;
      if (n < CHOICE_MIN_OPTIONS || n > maxOptions) {
        return `question '${id}': a choice needs ${CHOICE_MIN_OPTIONS}-${maxOptions} options on this route, got ${n}`;
      }
    } else if (q.type === "score") {
      const n = q.criteria.length;
      if (n < SCORE_MIN_LEVELS || n > SCORE_MAX_LEVELS) {
        return `question '${id}': a score needs ${SCORE_MIN_LEVELS}-${SCORE_MAX_LEVELS} levels, got ${n}`;
      }
    }
  }
  return null;
}