llm-output-guard 0.2.0 → 0.3.0

package/dist/stream-4a1hXc1m.d.ts

@@ -0,0 +1,150 @@
+type ReasonCode = 'EMPTY' | 'TOO_SHORT' | 'REPETITION' | 'TAIL_LOOP' | 'LOW_ENTROPY' | 'TRUNCATED' | 'INVALID_JSON' | 'LANG_MISMATCH';
+interface Reason {
+    code: ReasonCode;
+    /** 0..1. Higher means more suspicious. */
+    score: number;
+    /** The threshold this score crossed. */
+    threshold: number;
+    /** Human-readable explanation, safe to log. */
+    message: string;
+}
+interface Verdict {
+    /** True when nothing crossed its threshold. */
+    ok: boolean;
+    /** Every failing signal, not just the first -- more useful when debugging. */
+    reasons: Reason[];
+    /** Every score computed, including passing ones. Feed these to your metrics. */
+    scores: Partial<Record<ReasonCode, number>>;
+    /** Parsed JSON payload when `json` was enabled and parsing succeeded. */
+    json?: unknown;
+}
+interface CheckOptions {
+    /** Minimum acceptable length in characters. Set 0 to disable. Default 1. */
+    minLength?: number;
+    /** Duplicate-n-gram threshold. Set null to disable. Default 0.35. */
+    maxRepetition?: number | null;
+    /** Tail-loop threshold. Set null to disable. Default 0.5. */
+    maxTailLoop?: number | null;
+    /** Compressibility threshold. Set null to disable. Default 0.75. */
+    maxCompressibility?: number | null;
+    /** Truncation threshold. Set null to disable. Default null. */
+    maxTruncation?: number | null;
+    /** Provider stop reason, used by the truncation detector when present. */
+    finishReason?: string;
+    /** Require a parseable JSON payload. Default false. */
+    expectJson?: boolean;
+    /** Allow the JSON payload to be wrapped in a fence. Default true. */
+    allowJsonFence?: boolean;
+    /** Top-level keys the JSON payload must contain. */
+    requiredKeys?: string[];
+    /** Expected language code ('id' | 'en' | 'es'). Off by default. */
+    expectLang?: string | null;
+    /** Language-mismatch threshold. Default 0.6. */
+    maxLangMismatch?: number;
+    /** N-gram size for the repetition detector. Default 3. */
+    ngram?: number;
+}
+
+interface StreamGuardOptions extends CheckOptions {
+    /**
+     * Characters of *new* text between checks. Default 400.
+     *
+     * Checking on every chunk would re-scan the buffer per token and turn a
+     * linear stream into quadratic work. Batching costs a little detection
+     * latency and buys a bounded cost per stream.
+     */
+    checkEvery?: number;
+    /**
+     * Characters that must arrive before any judgement. Default 240.
+     *
+     * A loop is not visible in the first sentence, and neither is its absence.
+     * Below this the guard abstains rather than guessing -- the same rule the
+     * detectors already follow for short samples.
+     */
+    warmup?: number;
+    /**
+     * Trailing characters each mid-stream check looks at. Default 2000.
+     *
+     * Two reasons, and the second matters more. Cost: without a window every
+     * check re-scans the whole buffer, so a stream costs quadratic work in its
+     * own length. Sensitivity: a model that produced four healthy paragraphs
+     * and then began looping is diluted to nothing when measured across all
+     * five, which is the same reasoning that makes `tailLoopScore` a separate
+     * detector from `repetitionScore`. Recent text is the text in question.
+     */
+    window?: number;
+}
+interface StreamGuard {
+    /**
+     * Feed the next chunk.
+     *
+     * Returns a verdict only on the chunks where a check actually ran, and
+     * `null` on the rest -- so `null` means "not judged yet", never "healthy".
+     * Read `.ok` on what you get back.
+     */
+    push(chunk: string): Verdict | null;
+    /**
+     * Full check on the complete text, including the detectors deferred above.
+     * Pass the provider's stop reason if you have it; truncation keys off it.
+     */
+    end(finishReason?: string): Verdict;
+    /** Everything pushed so far. */
+    readonly text: string;
+    /** How many mid-stream checks have run. Useful when tuning `checkEvery`. */
+    readonly checks: number;
+}
+/**
+ * Watches a response as it arrives and reports degeneration before it finishes.
+ *
+ * The reason to bother: a model that has started looping will keep looping
+ * until it hits `max_tokens`, and you pay for every one of those tokens plus
+ * the latency of waiting for them. Catching it at character 300 of a 4000
+ * character run and aborting turns a slow bad answer into a fast one.
+ *
+ * This never aborts anything itself -- it holds no controller and knows
+ * nothing about your provider. It tells you; you decide.
+ */
+declare function createStreamGuard(options?: StreamGuardOptions): StreamGuard;
+interface GuardStreamOptions extends StreamGuardOptions {
+    /**
+     * Called the first time a mid-stream check fails. Abort your request here.
+     *
+     * The guard deliberately does not own the AbortController: the thing that
+     * knows how to cancel a generation is the code that started it, and a
+     * detection library that reaches into your transport is a library you
+     * cannot use with the next transport.
+     */
+    onDegenerate?: (verdict: Verdict) => void;
+    /**
+     * Called once with the final verdict when the source ends normally. Skipped
+     * when the stream was cut short, because a verdict on a deliberately
+     * abandoned response would describe your own abort, not the model.
+     */
+    onEnd?: (verdict: Verdict) => void;
+    /**
+     * Stop yielding once degeneration is detected. Default true.
+     *
+     * Set false to keep passing chunks through while still being told -- useful
+     * for a logging-only rollout, where you want the signal without changing
+     * what the user sees.
+     */
+    stopOnDegenerate?: boolean;
+}
+/**
+ * Wraps a chunk stream and cuts it off when the model starts looping.
+ *
+ * ```ts
+ * const controller = new AbortController();
+ * const guarded = guardStream(model.textStream, {
+ *   ...presets.chat,
+ *   onDegenerate: () => controller.abort(),
+ * });
+ * for await (const chunk of guarded) process.stdout.write(chunk);
+ * ```
+ *
+ * Yields the source's chunks unchanged until then, so it drops into an
+ * existing loop without touching what you do with the text.
+ */
+declare function guardStream(source: AsyncIterable<string>, options?: GuardStreamOptions): AsyncGenerator<string, void, undefined>;
+
+export { type CheckOptions as C, type GuardStreamOptions as G, type Reason as R, type StreamGuardOptions as S, type Verdict as V, type ReasonCode as a, type StreamGuard as b, createStreamGuard as c, guardStream as g };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-output-guard",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Detect degenerate LLM output that arrives with a 200 OK. Zero dependencies, deterministic, composes with any retry or fallback layer.",
   "keywords": [
     "llm",
@@ -24,7 +24,13 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
-    }
+    },
+    "./ai-sdk": {
+      "types": "./dist/ai-sdk.d.ts",
+      "import": "./dist/ai-sdk.js",
+      "require": "./dist/ai-sdk.cjs"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist"
@@ -41,9 +47,18 @@
     "seed": "node scripts/seed-fixtures.mjs",
     "prepublishOnly": "npm run typecheck && npm run test && npm run build"
   },
+  "peerDependencies": {
+    "ai": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@changesets/cli": "^2.27.0",
     "@types/node": "^20.19.43",
+    "ai": "^7.0.62",
     "tsup": "^8.0.0",
     "tsx": "^4.7.0",
     "typescript": "^5.4.0",