@drkmttr/adhere 0.14.0 → 0.17.5

package/src/providers/cloudflare.ts

@@ -0,0 +1,84 @@
+/**
+ * Cloudflare's Clef on Workers AI. Clef follows System One, so adhere's
+ * questions go as Jev's provider sends them, but for three differences: at
+ * most 64 questions to a request, ids of letters, digits, `_`, `.` and `-`
+ * where adhere's hold `/` and `:`, and no `choice` of one option. So the
+ * questions go in chunks of 64, each under its place in its chunk, and a
+ * choice of one option is answered by it, unasked.
+ *
+ * Clef cuts a state too long for it short rather than refuse it, and says so
+ * only by the tokens it read: on 2026-10-10, clef read at most 64,000 and
+ * clef-flash 24,000, well under the 65,536 their pages give. A request that
+ * reads that many, or that Workers AI refuses as too large with a 413, is
+ * over the model's context, and skips the file.
+ */
+import { decoded, failed, post } from "#providers/post.ts";
+import { ContextOverflow, type Provider, withoutSingleChoices } from "#providers/provider.ts";
+import { answersOf, requestOf, SystemOneAnswered } from "#providers/systemOne.ts";
+import { Schema } from "effect";
+
+const QUESTIONS_PER_REQUEST = 64;
+const MOST_TOKENS = { clef: 64_000, "clef-flash": 24_000 } as const;
+
+/** Workers AI's envelope around Clef's answers. */
+const Ran = Schema.fromJsonString(Schema.Struct({ result: SystemOneAnswered }));
+
+export interface CloudflareOptions {
+  /** The Cloudflare account that runs the model. */
+  readonly accountId: string;
+  /** A Cloudflare API token that can run Workers AI models. */
+  readonly apiToken: string;
+  /** The model to ask. Defaults to "clef". */
+  readonly model?: "clef" | "clef-flash";
+  /** What sends the requests. Defaults to `fetch`. */
+  readonly fetch?: typeof globalThis.fetch;
+}
+
+export const cloudflare = ({
+  accountId,
+  apiToken,
+  model = "clef",
+  fetch,
+}: CloudflareOptions): Provider => ({
+  model,
+  ask: async (state, questions, { signal }) => {
+    const { answers, asked } = withoutSingleChoices(questions);
+    const chunks = Array.from({ length: Math.ceil(asked.length / QUESTIONS_PER_REQUEST) }, (_, n) =>
+      asked.slice(n * QUESTIONS_PER_REQUEST, (n + 1) * QUESTIONS_PER_REQUEST),
+    );
+    const ran = await Promise.all(
+      chunks.map(async (chunk) => {
+        const { response, text } = await post(
+          "Cloudflare",
+          `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/run/@cf/cloudflare/${model}`,
+          { Authorization: `Bearer ${apiToken}` },
+          requestOf(
+            model,
+            state,
+            chunk.map((question, place) => ({ ...question, id: `q${place}` })),
+          ),
+          signal,
+          fetch,
+        );
+        const overflow = () => new ContextOverflow(`The request is over ${model}'s context`);
+        if (response.status === 413) throw overflow();
+        if (!response.ok) throw failed("Cloudflare", response, text);
+        const { result } = decoded("Cloudflare", Ran, text);
+        if ((result.usage?.input_tokens ?? 0) >= MOST_TOKENS[model]) throw overflow();
+        return { chunk, result };
+      }),
+    );
+    for (const { chunk, result } of ran) {
+      const answered = answersOf(result.answers);
+      chunk.forEach((question, place) => {
+        const answer = answered[`q${place}`];
+        if (answer !== undefined) answers[question.id] = answer;
+      });
+    }
+    return {
+      answers,
+      inputTokens: ran.reduce((sum, { result }) => sum + (result.usage?.input_tokens ?? 0), 0),
+      model,
+    };
+  },
+});

package/src/providers/jev.ts

@@ -0,0 +1,66 @@
+/**
+ * TypeSafe's Jev, adhere's default provider: adhere's questions as System One
+ * requests to TypeSafe's API, as adhere built them. With no provider in the
+ * config, adhere asks this one with the key `adhere login` saved, or
+ * `TYPESAFE_API_KEY`; a config names it to ask with another key or model.
+ */
+import { decoded, failed, post } from "#providers/post.ts";
+import { ContextOverflow, type Provider, RequestBlocked } from "#providers/provider.ts";
+import { answersOf, requestOf, SystemOneAnswered } from "#providers/systemOne.ts";
+import { Option, Schema } from "effect";
+
+const SYSTEM_ONE = "https://api.typesafe.ai/v1/systemone";
+
+const Answer = Schema.fromJsonString(SystemOneAnswered);
+
+/** What Jev answers, with a 400, to a request over its context. */
+const Overflowed = Schema.fromJsonString(
+  Schema.Struct({ detail: Schema.Struct({ error_type: Schema.Literal("max_tokens_exceeded") }) }),
+);
+
+export interface JevOptions {
+  /** A TypeSafe AI API key. Defaults to `TYPESAFE_API_KEY`, or the key `adhere login` saved. */
+  readonly apiKey?: string;
+  /** The model to ask. Defaults to "jev-latest". */
+  readonly model?: string;
+  /** What sends the requests. Defaults to `fetch`. */
+  readonly fetch?: typeof globalThis.fetch;
+}
+
+export const jev = ({ apiKey, model = "jev-latest", fetch }: JevOptions = {}): Provider => ({
+  model,
+  ...(apiKey === undefined ? { savedKey: "typesafe" as const } : {}),
+  ask: async (state, questions, { apiKey: saved, signal }) => {
+    const key = apiKey ?? saved;
+    if (key === undefined) throw new Error("No TypeSafe AI API key to ask Jev with");
+    const { response, text } = await post(
+      "Jev",
+      SYSTEM_ONE,
+      { Authorization: `Bearer ${key}` },
+      requestOf(model, state, questions),
+      signal,
+      fetch,
+    );
+    if (response.ok) {
+      const answered = decoded("Jev", Answer, text);
+      return {
+        answers: answersOf(answered.answers),
+        inputTokens: answered.usage?.input_tokens,
+        model: answered.model,
+      };
+    }
+    // Over Jev's context, a 400 that skips the file. The firewall in front of
+    // TypeSafe's API answers a 403 with an HTML page, where Jev answers JSON:
+    // a block, with the Ray ID TypeSafe can look it up by.
+    if (response.status === 400 && Option.isSome(Schema.decodeUnknownOption(Overflowed)(text))) {
+      throw new ContextOverflow("The request is over Jev's context");
+    }
+    const html =
+      (response.headers.get("content-type") ?? "").includes("text/html") ||
+      text.trimStart().startsWith("<");
+    if (response.status === 403 && html) {
+      throw new RequestBlocked(response.headers.get("cf-ray") ?? "none given");
+    }
+    throw failed("Jev", response, text);
+  },
+});

package/src/providers/openai.ts

@@ -0,0 +1,89 @@
+/**
+ * OpenAI's Decisions API: each of adhere's questions as a decision question,
+ * a `noul` as a `predicate` and a `choice` as a `choice`. A decision
+ * question's instructions are one string, so they hold the question as
+ * System One asks it, in JSON: the question beside the fields it names, and
+ * what yes and no mean. On the providers study's four repos, gpt-6-luna
+ * ranked findings better and located them more often than with the same parts
+ * in prose. The state is the input, in JSON. A question OpenAI refuses goes
+ * unanswered.
+ */
+import { decoded, failed, post } from "#providers/post.ts";
+import { type Provider, type Question, withoutSingleChoices } from "#providers/provider.ts";
+import { systemOneQuestionOf } from "#providers/systemOne.ts";
+import { Schema } from "effect";
+
+const DECISIONS = "https://api.openai.com/v1/decisions";
+
+/** A decision's answers, in question order: a predicate's probability, a choice's value, or a refusal, which has neither. */
+const Decided = Schema.fromJsonString(
+  Schema.Struct({
+    answers: Schema.Array(
+      Schema.Struct({
+        name: Schema.NullOr(Schema.String),
+        probability: Schema.optionalKey(Schema.Finite),
+        choice: Schema.optionalKey(Schema.Union([Schema.String, Schema.Boolean])),
+      }),
+    ),
+    model: Schema.optionalKey(Schema.String),
+    usage: Schema.optionalKey(Schema.Struct({ input_tokens: Schema.Finite })),
+  }),
+);
+
+/** System One's question without its type, in JSON, or its instructions alone when it says nothing of what yes and no mean. */
+const instructionsOf = (question: Question): string => {
+  const { type, ...asked } = systemOneQuestionOf(question);
+  if (type === "noul" && asked.criteria !== undefined) return JSON.stringify(asked);
+  return typeof asked.instructions === "string"
+    ? asked.instructions
+    : JSON.stringify(asked.instructions);
+};
+
+const decisionOf = (question: Question) =>
+  question.type === "noul"
+    ? { type: "predicate", name: question.id, instructions: instructionsOf(question) }
+    : {
+        type: "choice",
+        name: question.id,
+        instructions: instructionsOf(question),
+        choices: Object.entries(question.options).map(([value, description]) =>
+          description === null ? { value } : { value, description },
+        ),
+      };
+
+export interface OpenAIOptions {
+  /** An OpenAI API key. Defaults to `OPENAI_API_KEY`, or the key `adhere login --openai` saved. */
+  readonly apiKey?: string;
+  /** The model to ask. Defaults to "gpt-6-luna", the only one the Decisions API takes. */
+  readonly model?: string;
+  /** What sends the requests. Defaults to `fetch`. */
+  readonly fetch?: typeof globalThis.fetch;
+}
+
+export const openai = ({ apiKey, model = "gpt-6-luna", fetch }: OpenAIOptions = {}): Provider => ({
+  model,
+  ...(apiKey === undefined ? { savedKey: "openai" as const } : {}),
+  ask: async (state, questions, { apiKey: saved, signal }) => {
+    const key = apiKey ?? saved;
+    if (key === undefined) throw new Error("No OpenAI API key to ask gpt-6-luna with");
+    // OpenAI takes no choice of one option.
+    const { answers, asked } = withoutSingleChoices(questions);
+    if (asked.length === 0) return { answers };
+    const { response, text } = await post(
+      "OpenAI",
+      DECISIONS,
+      { Authorization: `Bearer ${key}` },
+      { model, input: JSON.stringify(state), questions: asked.map(decisionOf) },
+      signal,
+      fetch,
+    );
+    if (!response.ok) throw failed("OpenAI", response, text);
+    const decided = decoded("OpenAI", Decided, text);
+    for (const { name, probability, choice } of decided.answers) {
+      if (name === null) continue;
+      if (probability !== undefined) answers[name] = probability;
+      else if (choice !== undefined) answers[name] = String(choice);
+    }
+    return { answers, inputTokens: decided.usage?.input_tokens, model: decided.model };
+  },
+});

package/src/providers/post.ts

@@ -0,0 +1,53 @@
+/** How each built-in provider sends a request and reads what comes back. */
+import { RequestFailed } from "#providers/provider.ts";
+import { Schema } from "effect";
+
+const messageOf = (cause: unknown) => (cause instanceof Error ? cause.message : String(cause));
+
+/**
+ * POSTs `body` as JSON, once: adhere tries again. A request that gets no
+ * answer, or whose answer breaks off, throws a `RequestFailed` with status 0.
+ */
+export const post = async (
+  name: string,
+  url: string,
+  headers: Readonly<Record<string, string>>,
+  body: unknown,
+  signal: AbortSignal,
+  fetch: typeof globalThis.fetch = globalThis.fetch,
+): Promise<{ readonly response: Response; readonly text: string }> => {
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...headers },
+      body: JSON.stringify(body),
+      signal,
+    });
+    return { response, text: await response.text() };
+  } catch (cause) {
+    throw new RequestFailed(`${name} did not answer: ${messageOf(cause)}`, 0);
+  }
+};
+
+/**
+ * A response that is not ok, as the `RequestFailed` to throw: its status, the
+ * Ray ID of the Cloudflare edge in front of the API when there is one, and
+ * its body on one line and cut short.
+ */
+export const failed = (name: string, response: Response, text: string): RequestFailed => {
+  const ray = response.headers.get("cf-ray");
+  const detail = text.trim().replace(/\s+/g, " ").slice(0, 300);
+  return new RequestFailed(
+    `${name} answered HTTP ${response.status}${ray === null ? "" : `, Ray ID ${ray}`}${detail === "" ? "" : `: ${detail}`}`,
+    response.status,
+  );
+};
+
+/** An ok response's body, decoded by `schema`. One that does not decode throws, naming who sent it. */
+export const decoded = <A>(name: string, schema: Schema.Codec<A, string>, text: string): A => {
+  try {
+    return Schema.decodeUnknownSync(schema)(text);
+  } catch (cause) {
+    throw new Error(`${name}'s answer did not decode: ${messageOf(cause)}`);
+  }
+};

package/src/providers/provider.ts

@@ -0,0 +1,131 @@
+/**
+ * What adhere asks a decision model, and what it takes back. A provider puts
+ * adhere's questions to its model in whatever form the model takes; adhere
+ * builds the questions, splits them into requests, paces and retries them,
+ * and reads the answers. Jev's provider is the default.
+ */
+import { Schema } from "effect";
+
+/**
+ * What the questions ask about: the file's code by section under `code`,
+ * beside what adhere read for it; comparing rules, the rules under `rules`.
+ */
+export type State = Readonly<Record<string, unknown>>;
+
+/**
+ * One of adhere's questions, as adhere phrases it. `question` names what it
+ * asks about in backticks: keys of the state, such as `code`, and of
+ * `fields`, such as `rule`, `must`, `never`, or `matcher`, which hold the
+ * rule it asks about and its examples. A `noul` asks whether something holds,
+ * `yes` and `no` saying what each answer means when adhere says. A `choice`
+ * asks for the key of one of its `options`, each beside what it means when
+ * its key does not say; it can have a single option.
+ */
+export type Question =
+  | {
+      readonly id: string;
+      readonly type: "noul";
+      readonly question: string;
+      readonly fields: Readonly<Record<string, unknown>>;
+      readonly yes?: string;
+      readonly no?: string;
+    }
+  | {
+      readonly id: string;
+      readonly type: "choice";
+      readonly question: string;
+      readonly fields: Readonly<Record<string, unknown>>;
+      readonly options: Readonly<Record<string, string | null>>;
+    };
+
+/**
+ * A provider's answers by question id: a `noul`'s probability that it holds,
+ * from 0 to 1, or the key of a `choice`'s option. An id left out goes
+ * unanswered: its rule is asked again on the next run, or its finding not
+ * located. `inputTokens` and `model`, what the model read and which version
+ * answered, are for the record, such as the eval's costs.
+ */
+export const Answered = Schema.Struct({
+  answers: Schema.Record(Schema.String, Schema.Union([Schema.Finite, Schema.String])),
+  inputTokens: Schema.optional(Schema.Finite),
+  model: Schema.optional(Schema.String),
+});
+export interface Answered extends Schema.Schema.Type<typeof Answered> {}
+
+/** The keys `adhere login` saves: TypeSafe AI's, for Jev, and with `--openai`, OpenAI's. */
+export const SAVED_KEYS = ["typesafe", "openai"] as const;
+export type SavedKey = (typeof SAVED_KEYS)[number];
+
+/**
+ * What adhere passes each call of `ask`: the key, when the provider names a
+ * `savedKey`, and the signal that aborts the call when adhere gives up on it.
+ */
+export interface AskOptions {
+  readonly apiKey?: string;
+  readonly signal: AbortSignal;
+}
+
+/**
+ * Where adhere's questions go. `ask` answers one request's questions. Its
+ * rejection stops the run, as Jev being down does, but for three:
+ * `ContextOverflow` skips the file, `RequestBlocked` reports it blocked, and
+ * `RequestFailed` is tried again when its status says it may pass. adhere
+ * paces each call with `--rpm`, and gives up on one after 30 seconds. `model`
+ * names what it asks: adhere's cache keeps answers by it, so a new model is
+ * asked again. A provider that names a `savedKey` gets that key as `apiKey`:
+ * its environment variable when set, otherwise the one `adhere login` saved.
+ * adhere calls `ask` on the provider, so a class can implement it.
+ */
+export interface Provider {
+  readonly model: string;
+  readonly savedKey?: SavedKey;
+  ask(state: State, questions: ReadonlyArray<Question>, options: AskOptions): Promise<Answered>;
+}
+
+/**
+ * Splits off the choices of a single option, which some APIs refuse to be
+ * asked: each is answered by its option, and the rest are left to ask.
+ */
+export const withoutSingleChoices = (questions: ReadonlyArray<Question>) => {
+  const answers: Record<string, number | string> = {};
+  const asked = questions.filter((question) => {
+    const [only, ...others] = question.type === "choice" ? Object.keys(question.options) : [];
+    if (only === undefined || others.length > 0) return true;
+    answers[question.id] = only;
+    return false;
+  });
+  return { answers, asked };
+};
+
+/** Thrown from `ask` when the request is longer than the model takes: adhere skips the file. */
+export class ContextOverflow extends Error {
+  readonly _tag = "ContextOverflow";
+}
+
+/**
+ * Thrown from `ask` when something in front of the model refused the request
+ * for what it holds: adhere reports the file blocked, with `reference` to look
+ * the block up by, and goes on.
+ */
+export class RequestBlocked extends Error {
+  readonly _tag = "RequestBlocked";
+  constructor(readonly reference: string) {
+    super(`blocked, reference ${reference}`);
+  }
+}
+
+/**
+ * Thrown from `ask` when the request failed: `status` is the HTTP status it
+ * got, or 0 when it got no answer. adhere tries one with no answer, a 408, a
+ * 429, or a 5xx again, up to three times, after half a second, one, and two;
+ * any other stops the run with its message.
+ */
+export class RequestFailed extends Error {
+  readonly _tag = "RequestFailed";
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+  }
+}