@aria-framework/ai 0.1.0

package/polish.js

@@ -0,0 +1,156 @@
+/**
+ * Polish — Fix, Tidy, Rephrase and Tone, over any text, as a proposal.
+ *
+ * IT PROPOSES; IT DOES NOT REPLACE. The caller gets a rewrite and decides — the difference between a
+ * tool people use and one they switch off after it eats a paragraph they liked.
+ *
+ * THE SAFETY PROPERTY IS ENFORCED HERE, not trusted to the prompt: a rewrite that lost a number, a
+ * date, a reference, an amount, a link or an address comes back `blocked`, with the values named.
+ * The prompt asks; facts.compare checks.
+ *
+ * FRAMING IS THE APP'S. This engine is generic; the one line that says what is being edited ("a
+ * reply to a customer", "a knowledge-base article") is passed in as `framing`. The modes, tones and
+ * rules below are audience-neutral defaults an app can use as-is or override.
+ */
+
+'use strict';
+
+const { AiError } = require('./error');
+const facts = require('./facts');
+
+const VERSION = 'polish.v1';
+
+/** The most text worth sending in one pass. */
+const MAX_INPUT_CHARS = 8000;
+
+/** What the author pressed. Each is a different promise about how much may change. */
+const MODES = {
+  fix: {
+    label: 'Fix',
+    instruction: 'Correct spelling, grammar, punctuation and capitalisation. Change nothing else — ' +
+      'not the wording, not the order, not the structure.'
+  },
+  tidy: {
+    label: 'Tidy',
+    instruction: 'Improve the structure: break walls of text into paragraphs, turn a sequence of ' +
+      'steps into a list, and put any action or next step where it can be seen. Fix spelling and ' +
+      'grammar while you are there. Keep the wording that already works.'
+  },
+  rephrase: {
+    label: 'Rephrase',
+    instruction: 'Say the same thing more clearly and more briefly. You may reword freely, but the ' +
+      'meaning, the commitments and the questions asked must all survive unchanged.'
+  }
+};
+
+/** Tone is a modifier on any mode, not a mode of its own. Audience-neutral so KB and replies share them. */
+const TONES = {
+  warmer:     'Make it warmer and more personable, without adding pleasantries that promise anything.',
+  formal:     'Make it more formal. Full sentences, no contractions, no slang.',
+  direct:     'Make it more direct. Lead with the point, cut hedging and filler.',
+  simpler:    'Make it simpler. Short sentences, plain words, no unexplained jargon.',
+  apologetic: 'Acknowledge the inconvenience once, plainly and without grovelling. Do not admit fault that is not already in the text.',
+  steps:      'Where the text describes a procedure, rewrite it as clear, numbered steps.'
+};
+
+const RULES = [
+  'NEVER change a number, an amount, a date, a reference, an order number, a link or an email address.',
+  'NEVER add information that is not in the text — no facts, no promises, no timeframes, no apologies for things not mentioned.',
+  'NEVER remove information. Every point the author made must still be there.',
+  'Do not add a greeting or a sign-off that was not already there, and do not remove one that was.',
+  'Keep the author\'s own voice. This is their text, edited — not your text.',
+  'Return the edited text only. No commentary, no preamble, no explanation inside the text itself.'
+];
+
+/** What must come back. Constrained by the provider, not requested in prose. */
+const SCHEMA = {
+  name: 'polish',
+  schema: {
+    type: 'object',
+    properties: {
+      rewritten: { type: 'string', description: 'The edited text, and nothing else.' },
+      changes: {
+        type: 'array',
+        maxItems: 4,
+        description: 'What you changed, one short phrase each, at most four.',
+        items: { type: 'string' }
+      }
+    },
+    required: ['rewritten', 'changes'],
+    additionalProperties: false
+  }
+};
+
+/** Build the system prompt from the app's framing plus the chosen mode/tone and optional examples. */
+function system(opts) {
+  const modes = opts.modes || MODES;
+  const tones = opts.tones || TONES;
+  const mode = modes[opts.mode] || MODES.fix;
+  const lines = [opts.framing || 'You are editing a piece of text.', '', 'Task: ' + mode.instruction];
+  if (opts.tone && tones[opts.tone]) lines.push('Tone: ' + tones[opts.tone]);
+  if (opts.houseVoice && opts.houseVoice.length) {
+    lines.push('', 'For the house style, here are examples to match:');
+    opts.houseVoice.forEach((ex, i) => lines.push(`--- example ${i + 1} ---`, ex));
+    lines.push('--- end of examples ---');
+  }
+  lines.push('', 'Rules:', ...RULES.map((r) => '- ' + r));
+  return lines.join('\n');
+}
+
+function normalise(s) { return String(s).replace(/\s+/g, ' ').trim(); }
+
+/**
+ * @param {(opts:object, cfg?:object) => Promise<object>} complete  the client's complete()
+ * @param {{text:string, mode:string, tone?:string, framing?:string, houseVoice?:string[],
+ *          modes?:object, tones?:object, maxInputChars?:number, ticketId?:*, signal?:AbortSignal}} opts
+ */
+async function polish(complete, opts) {
+  const text = String(opts.text == null ? '' : opts.text);
+  const maxChars = opts.maxInputChars || MAX_INPUT_CHARS;
+  const modes = opts.modes || MODES;
+  const tones = opts.tones || TONES;
+
+  if (!text.trim()) throw new AiError('refused', 'There is nothing to polish yet.');
+  if (text.length > maxChars) {
+    throw new AiError('refused',
+      `That is ${text.length.toLocaleString()} characters — too long to rewrite in one pass. Polish it a section at a time.`);
+  }
+  if (!modes[opts.mode]) throw new AiError('refused', `Unknown polish mode: ${opts.mode}`);
+  if (opts.tone && !tones[opts.tone]) throw new AiError('refused', `Unknown tone: ${opts.tone}`);
+
+  const result = await complete({
+    system: system({ framing: opts.framing, mode: opts.mode, tone: opts.tone, houseVoice: opts.houseVoice, modes, tones }),
+    messages: [{ role: 'user', content: text }],
+    // Room for the answer plus the thinking: a reasoning model spends tokens before it writes.
+    maxTokens: Math.min(4096, Math.max(1024, Math.ceil(text.length / 2) + 768)),
+    temperature: opts.mode === 'fix' ? 0 : 0.3,
+    schema: SCHEMA,
+    signal: opts.signal,
+    ticketId: opts.ticketId || null
+  });
+
+  const json = result.json || {};
+  const rewritten = String(json.rewritten || '').trim();
+  if (!rewritten) throw new AiError('bad_response', 'The model returned no rewritten text.');
+
+  // THE CONTROL. Everything above this line is persuasion.
+  const check = facts.compare(text, rewritten);
+
+  return {
+    rewritten,
+    changes: Array.isArray(json.changes) ? json.changes.slice(0, 4).map(String) : [],
+    blocked: !check.ok,
+    lost: check.lost,
+    blockedReason: check.ok ? null
+      : `This rewrite drops ${facts.describe(check.lost)}. Accepting it would change what the text ` +
+        'says, so it has to be edited by hand or tried again.',
+    unchanged: normalise(rewritten) === normalise(text),
+    model: result.model,
+    ms: result.ms,
+    usage: result.usage,
+    truncated: !!result.truncated,
+    promptVersion: VERSION
+  };
+}
+
+module.exports = { polish, MODES, TONES, RULES, SCHEMA, MAX_INPUT_CHARS, VERSION, system };

package/providers/anthropic.js

@@ -0,0 +1,192 @@
+/**
+ * Anthropic's Messages API — the reason this layer has adapters at all.
+ *
+ * FOUR THINGS DIFFER from the OpenAI shape, and every one of them would break a "just change the
+ * base URL" design:
+ *
+ *   1. the endpoint is /v1/messages, not /chat/completions;
+ *   2. auth is `x-api-key`, not `Authorization: Bearer`, and an `anthropic-version` header is
+ *      REQUIRED — omit it and the request is rejected outright;
+ *   3. the system prompt is a top-level `system` parameter, not a message with role 'system';
+ *   4. the answer arrives as `content: [{type:'text', text}]` — an array of blocks — rather than
+ *      `choices[0].message.content`, and usage is `input_tokens`/`output_tokens`.
+ *
+ * Structured output is `output_config`, which was behind a beta header when this was written. The
+ * header is a setting rather than a constant so it can be dropped when the feature goes GA without
+ * a code change — and `schemaBeta: ''` turns it off.
+ */
+
+'use strict';
+
+const { AiError, fromFetchFailure, redact } = require('../error');
+
+const API_VERSION = '2023-06-01';
+const DEFAULT_BASE = 'https://api.anthropic.com/v1';
+
+async function complete(cfg, opts) {
+  const label = cfg.label || 'Claude';
+  const url = String(cfg.baseUrl || DEFAULT_BASE).replace(/\/+$/, '') + '/messages';
+
+  if (!cfg.apiKey) {
+    throw new AiError('unconfigured', 'No API key is saved for Claude.');
+  }
+
+  const body = {
+    model: cfg.model,
+    max_tokens: opts.maxTokens || 1024,
+    temperature: opts.temperature == null ? 0.2 : opts.temperature,
+    // Difference 3: top-level, not a message.
+    ...(opts.system ? { system: opts.system } : {}),
+    messages: (opts.messages || []).map((m) => ({
+      // Anthropic has no 'system' role in the message list; anything that is not the assistant is
+      // the user. A caller that passes one gets it folded in rather than silently dropped.
+      role: m.role === 'assistant' ? 'assistant' : 'user',
+      content: m.content
+    }))
+  };
+
+  const headers = {
+    'Content-Type': 'application/json',
+    'x-api-key': cfg.apiKey,          // difference 2
+    'anthropic-version': API_VERSION
+  };
+
+  if (opts.schema) {
+    body.output_config = {
+      format: { type: 'json_schema', schema: opts.schema.schema || opts.schema }
+    };
+    // Beta at the time of writing. Configurable so GA needs a settings change, not a deploy.
+    const beta = cfg.schemaBeta == null ? 'structured-outputs-2025-11-13' : cfg.schemaBeta;
+    if (beta) headers['anthropic-beta'] = beta;
+  }
+
+  const started = Date.now();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), cfg.timeoutMs || 60000);
+  if (opts.signal) opts.signal.addEventListener('abort', () => controller.abort(), { once: true });
+
+  let res;
+  try {
+    res = await fetch(url, { method: 'POST', headers, body: JSON.stringify(body), signal: controller.signal });
+  } catch (err) {
+    clearTimeout(timer);
+    throw fromFetchFailure(err, { label, url });
+  }
+
+  // The timer stays armed until the body is read — see the long note on the same block in
+  // openai-compatible.js. Clearing it when headers arrive leaves a stalled body with no deadline,
+  // and an await that never settles wedges the runner's single-flight flag permanently.
+  let payload;
+  try {
+    if (!res.ok) throw await httpError(res, label, cfg.apiKey);
+    payload = await res.json();
+  } catch (err) {
+    // Abort BEFORE instanceof — httpError's swallowed-abort case builds a plausible AiError from a
+    // body it never got, and that must not outrank the deadline. Full reasoning on the same block
+    // in openai-compatible.js.
+    if (controller.signal.aborted || (err && err.name === 'AbortError')) {
+      // Stated as a timeout DIRECTLY, not routed through fromFetchFailure — that helper keys on
+      // err.name === 'AbortError', and the error in hand here is often httpError's AiError built
+      // from a swallowed abort, which it would misfile as 'unreachable'. The signal aborting IS
+      // the deadline; no inspection of the error object can outrank that fact.
+      throw new AiError('timeout', `${label} did not answer in time.`, { cause: err });
+    }
+    if (err instanceof AiError) throw err;
+    throw new AiError('bad_response', `${label} replied with something that is not JSON.`, { cause: err });
+  } finally {
+    clearTimeout(timer);
+  }
+
+  // Difference 4: blocks, not a single string. Concatenated so a model that splits its answer over
+  // two text blocks does not silently lose the second one.
+  // Thinking arrives as its own block TYPE here rather than a field, so filtering to 'text' already
+  // excludes it — which is why this adapter needs no tag stripping.
+  const text = (payload.content || [])
+    .filter((b) => b && b.type === 'text')
+    .map((b) => b.text)
+    .join('');
+  if (!text) {
+    const thought = (payload.content || []).some((b) => b && b.type === 'thinking');
+    throw new AiError('bad_response', thought
+      ? `${label} returned only its internal reasoning. Raise the reply limit and try again.`
+      : `${label} returned no text (stop reason: ${payload.stop_reason || 'none given'}).`);
+  }
+
+  let json = null;
+  if (opts.schema) {
+    try {
+      json = JSON.parse(text);
+    } catch (err) {
+      // Truncation named as truncation — same reasoning as the openai-compatible adapter.
+      if (payload.stop_reason === 'max_tokens') {
+        throw new AiError('bad_response',
+          `${label} ran out of room mid-answer — the structured reply was cut off before it was ` +
+          'finished. A Regenerate usually succeeds.', { cause: err });
+      }
+      throw new AiError('bad_response',
+        `${label} was asked for structured output and returned text that will not parse.`, { cause: err });
+    }
+  }
+
+  return {
+    text,
+    json,
+    model: payload.model || cfg.model,
+    usage: normaliseUsage(payload.usage),
+    ms: Date.now() - started,
+    finishReason: payload.stop_reason || null,
+    truncated: payload.stop_reason === 'max_tokens',
+    reasonedFor: 0
+  };
+}
+
+async function httpError(res, label, apiKey) {
+  let detail = '';
+  try {
+    const body = await res.json();
+    // Redacted here, not at each use: Anthropic's 400 and 500 bodies quote the offending key.
+    detail = redact((body && body.error && body.error.message) || '', apiKey);
+  } catch (_) { /* a non-JSON error body is not worth a second failure */ }
+
+  if (res.status === 401 || res.status === 403) {
+    return new AiError('auth', `${label} rejected the API key.`, { status: res.status });
+  }
+  if (res.status === 429) {
+    return new AiError('rate_limit', `${label} is rate limiting this app.`, { status: res.status });
+  }
+  if (res.status === 400 && /output_config|structured/i.test(detail)) {
+    // Worth its own message: it means the beta header moved, not that anything here is broken.
+    return new AiError('refused',
+      `${label} refused the structured-output request — the beta header may have changed. ${detail}`,
+      { status: res.status });
+  }
+  return new AiError('bad_response', `${label} returned ${res.status}. ${detail}`.trim(), { status: res.status });
+}
+
+function normaliseUsage(u) {
+  if (!u) return { prompt: 0, completion: 0, total: 0 };
+  const prompt = u.input_tokens || 0;      // named differently to the OpenAI shape
+  const completion = u.output_tokens || 0;
+  return { prompt, completion, total: prompt + completion };
+}
+
+/** No listing endpoint is used here — the model name is typed, and a wrong one fails loudly. */
+async function listModels() { return []; }
+
+/**
+ * Anthropic does not offer an embeddings API. This is not a gap in the adapter.
+ *
+ * SAID PLAINLY RATHER THAN FAKED. The obvious alternatives were both worse: returning an empty
+ * array would make the re-rank silently do nothing and look like a working feature, and quietly
+ * calling a third party (Anthropic's own guidance points at Voyage AI) would send customer text to
+ * a company the operator never chose. An operator who has picked Anthropic and wants embeddings has
+ * to point the embedding side at something that serves them, and this sentence is how they find
+ * that out.
+ */
+async function embed() {
+  throw new AiError('unsupported',
+    'Anthropic does not provide an embeddings API, so related-content re-ranking is unavailable ' +
+    'with this provider. Everything else works; results are ordered by text search alone.');
+}
+
+module.exports = { complete, listModels, embed, API_VERSION, DEFAULT_BASE };