@directive-run/ai 1.13.0 → 1.14.0

package/dist/predicate.d.cts

@@ -0,0 +1,371 @@
+import { FactPredicate, SchemaValidationError } from '@directive-run/core';
+import { c as AgentRunner, b as AgentLike } from './types-DJ09LjZX.cjs';
+
+/**
+ * predicateFromIntent — let an LLM emit a typed FactPredicate as JSON,
+ * structurally + semantically validated before it ever reaches your
+ * constraint engine.
+ *
+ * Pipeline per call attempt:
+ *
+ *   1. Output-size check (reject before JSON.parse for DoS guard)
+ *   2. JSON.parse via extractJsonFromOutput (handles surrounding prose)
+ *   3. validatePredicate (structural: closed operator set, depth, JSON safety)
+ *   4. Operator-count check
+ *   5. validatePredicateAgainstSchema (semantic: operator-on-kind matrix)
+ *
+ * On any failure: a structured error message — including the offending
+ * clause's path, the allowed operators for that fact's kind, and the
+ * original schema kinds — is fed back to the LLM in the next attempt.
+ *
+ * Returns the validated FactPredicate. Throws PredicateFromIntentError
+ * on retry exhaustion. NEVER returns a partial / unvalidated predicate.
+ */
+
+interface PredicateFromIntentOptions<_F = Record<string, unknown>> {
+    /** Natural-language intent (untrusted user input — sanitize via `redact`). */
+    intent: string;
+    /**
+     * Module schema (must expose builders with `_typeName` or `_kind`).
+     * Pass either `{ facts: {...} }` or a bare `Record<string, builder>`.
+     */
+    schema: unknown;
+    /** AgentRunner from `@directive-run/ai` adapters (createOpenAIRunner, etc.). */
+    runner: AgentRunner;
+    /**
+     * Optional agent override. Default is `{ name: "predicate-emitter" }`
+     * with our system prompt; pass `instructions` to append additional
+     * context.
+     */
+    agent?: AgentLike;
+    /**
+     * Optional dotted-path namespace; useful for cross-module systems
+     * where the LLM should emit a predicate over `auth.token` (default:
+     * the schema's root facts).
+     */
+    factPath?: string;
+    /** Max retries on validation failure. Default 3. */
+    maxRetries?: number;
+    /**
+     * Hard byte cap on the LLM's raw output, BEFORE JSON.parse. Defaults
+     * to 64 KiB. A larger predicate is rejected outright; protects
+     * against multi-MB-payload DoS where the predicate is technically
+     * structurally valid.
+     */
+    maxPredicateBytes?: number;
+    /**
+     * Hard cap on the number of operator clauses in the predicate.
+     * Defaults to 256. Protects against `{ $any: [{ x: 1 }, … x100,000 ] }`
+     * style operator-count exhaustion.
+     */
+    maxOperatorCount?: number;
+    /**
+     * Optional sanitizer applied to `intent` BEFORE it lands in the
+     * system prompt. Useful for stripping or redacting user-controlled
+     * content that looks like prompt-injection.
+     */
+    redact?: (intent: string) => string;
+    /**
+     * Hard cap on the length of each `$in` / `$nin` array operand the LLM
+     * may emit. Defaults to 1000. Forwarded to
+     * `validatePredicateAgainstSchema`'s `maxArrayOperandLength`.
+     */
+    maxArrayOperandLength?: number;
+    /**
+     * Optional `AbortSignal` for cooperative cancellation. (N6)
+     *
+     * The retry loop checks `signal.aborted` between attempts AND forwards
+     * the signal into the runner call itself (`runner(agent, input, { signal })`).
+     * Whether the in-flight LLM call honors the signal depends on the runner:
+     * fetch-based adapters (the bundled OpenAI / Anthropic / Ollama runners)
+     * thread it through to `fetch`, so the network call aborts mid-stream.
+     * A custom runner that ignores the signal still delivers cancellation
+     * at the next retry boundary.
+     *
+     * On abort: throws `Error("aborted")`.
+     *
+     * NOTE: `predicateFromIntent` does NOT limit in-flight calls — callers
+     * MUST wrap with a concurrency limiter (e.g. `p-limit`) to bound
+     * fan-out under load.
+     */
+    signal?: AbortSignal;
+    /**
+     * When `true`, the {@link PredicateFromIntentProvenance} returned by
+     * `predicateFromIntentWithProvenance` omits the raw `intent` string and
+     * stores only the SHA-256 `intentHash`. Use this in PII-sensitive
+     * contexts where the original intent must not be persisted. (M6)
+     *
+     * **Default `false` for back-compat.** For PII-sensitive deployments,
+     * ALWAYS set `redactIntent: true` — the raw intent may contain
+     * user-supplied content (names, emails, medical or financial details,
+     * customer messages) that becomes a permanent record in
+     * `provenance.intent`. The default is opt-in only because flipping it
+     * now would silently strip diagnostic data from existing callers; v2
+     * may flip this default (tracked in IDEAS.md).
+     *
+     * Pair with a `redact:` sanitizer when the intent itself must be
+     * scrubbed BEFORE it lands in the LLM prompt — `redactIntent` controls
+     * only what enters the provenance record, not what the LLM sees.
+     */
+    redactIntent?: boolean;
+}
+interface PredicateFromIntentDiagnostics<F = Record<string, unknown>> {
+    /** The validated predicate (`null` if all retries failed). */
+    predicate: FactPredicate<F> | null;
+    /** Number of LLM calls actually made. */
+    attempts: number;
+    /** Errors encountered across all attempts (most recent last). */
+    errors: ReadonlyArray<{
+        attempt: number;
+        reason: string;
+        details?: readonly SchemaValidationError[];
+    }>;
+    /** The raw LLM output from the final attempt — useful for debugging. */
+    lastRawOutput?: string;
+}
+/** Thrown by `predicateFromIntent` on retry exhaustion. `predicateFromIntentRaw` returns these as a diagnostics payload instead. */
+declare class PredicateFromIntentError extends Error {
+    readonly attempts: number;
+    readonly errors: ReadonlyArray<{
+        attempt: number;
+        reason: string;
+        details?: readonly SchemaValidationError[];
+    }>;
+    readonly lastRawOutput: string | undefined;
+    readonly name = "PredicateFromIntentError";
+    constructor(message: string, attempts: number, errors: ReadonlyArray<{
+        attempt: number;
+        reason: string;
+        details?: readonly SchemaValidationError[];
+    }>, lastRawOutput: string | undefined);
+}
+/**
+ * Ask an LLM to emit a FactPredicate matching the user's intent, then
+ * validate it structurally + semantically before returning. On validation
+ * failure, retries with structured error feedback in the next prompt.
+ *
+ * Throws {@link PredicateFromIntentError} on retry exhaustion. NEVER
+ * returns a partial / unvalidated predicate.
+ *
+ * **Rate limiting:** this function does NOT limit in-flight calls. Wrap
+ * with a concurrency limiter (e.g. `p-limit` / `Bottleneck`) before
+ * exposing it to user-driven traffic. Pass an `AbortSignal` via `opts.signal`
+ * for cooperative cancellation between retry attempts.
+ *
+ * @example
+ * ```ts
+ * import { createOpenAIRunner } from "@directive-run/ai/openai";
+ * import { predicateFromIntent } from "@directive-run/ai";
+ *
+ * const runner = createOpenAIRunner({ apiKey, model: "gpt-4o-mini" });
+ *
+ * const predicate = await predicateFromIntent({
+ *   intent: "checkout is unblocked when the cart total is at least 50",
+ *   schema: myModule.schema,
+ *   runner,
+ * });
+ * // → { cartTotal: { $gte: 50 } }
+ * ```
+ */
+declare function predicateFromIntent<F = Record<string, unknown>>(opts: PredicateFromIntentOptions<F>): Promise<FactPredicate<F>>;
+/**
+ * Lower-level variant — returns the validated predicate (or null) plus
+ * full diagnostics. Use when you want to surface validation telemetry,
+ * preview the LLM's last raw output, or display per-attempt errors in
+ * a UI.
+ */
+declare function predicateFromIntentRaw<F = Record<string, unknown>>(opts: PredicateFromIntentOptions<F>): Promise<PredicateFromIntentDiagnostics<F>>;
+interface PredicateToolSpecOptions {
+    /** Tool name. Default `"emit_predicate"`. */
+    name?: string;
+    /** Tool description. Default: a one-liner describing predicate emission. */
+    description?: string;
+    /** Optional dotted-path namespace to restrict the tool's scope. */
+    factPath?: string;
+}
+/**
+ * Anthropic Messages API tool shape. Drop into the `tools: [...]` array.
+ * Anthropic's API expects `input_schema` at the top level of the tool.
+ */
+interface PredicateToolSpecAnthropic {
+    name: string;
+    description: string;
+    input_schema: {
+        type: "object";
+        properties: {
+            predicate: {
+                type: "object";
+            };
+        };
+        required: ["predicate"];
+    };
+    /** Human-readable schema description — embed in your tool's "description" if your provider concatenates them. */
+    schemaSummary: string;
+}
+/**
+ * OpenAI Chat Completions / Responses API tool shape. Drop into the
+ * `tools: [...]` array. OpenAI nests the function payload under
+ * `function: { name, description, parameters }`.
+ */
+interface PredicateToolSpecOpenAI {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: "object";
+            properties: {
+                predicate: {
+                    type: "object";
+                };
+            };
+            required: ["predicate"];
+        };
+    };
+    /** Human-readable schema description — embed in your tool's "description" if your provider concatenates them. */
+    schemaSummary: string;
+}
+/**
+ * @deprecated Use {@link PredicateToolSpecAnthropic} (or
+ * {@link PredicateToolSpecOpenAI}) directly. Kept as an alias for the
+ * pre-split shape that v1.12.x callers depend on; identical to
+ * `PredicateToolSpecAnthropic`.
+ */
+type PredicateToolSpec = PredicateToolSpecAnthropic;
+/**
+ * OpenAI Chat Completions / Responses API tool spec for predicate
+ * emission. Drop the result into your `tools: [...]` array; the model
+ * will be told to emit a predicate matching this schema.
+ *
+ * @example
+ * ```ts
+ * const tool = predicateToolSpecOpenAI(myModule.schema, { name: "set_checkout_rule" });
+ *
+ * await openai.chat.completions.create({
+ *   model: "gpt-4o-mini",
+ *   tools: [tool],
+ *   messages: [...],
+ * });
+ * ```
+ */
+declare function predicateToolSpecOpenAI(schema: unknown, opts?: PredicateToolSpecOptions): PredicateToolSpecOpenAI;
+/**
+ * Anthropic Messages API tool spec for predicate emission. Drop the
+ * result into your `tools: [...]` array; the model will be told to emit
+ * a predicate matching this schema.
+ *
+ * @example
+ * ```ts
+ * const tool = predicateToolSpecAnthropic(myModule.schema, { name: "set_checkout_rule" });
+ *
+ * await anthropic.messages.create({
+ *   model: "claude-3-5-sonnet-latest",
+ *   tools: [tool],
+ *   messages: [...],
+ * });
+ * ```
+ */
+declare function predicateToolSpecAnthropic(schema: unknown, opts?: PredicateToolSpecOptions): PredicateToolSpecAnthropic;
+/**
+ * @deprecated Use {@link predicateToolSpecAnthropic} (or
+ * {@link predicateToolSpecOpenAI}) directly. Back-compat alias for
+ * v1.12.x callers — emits the Anthropic shape, unchanged.
+ */
+declare function predicateToolSpec(schema: unknown, opts?: PredicateToolSpecOptions): PredicateToolSpec;
+interface PredicateFromIntentProvenance {
+    /**
+     * Resolved model name when the caller passes `agent: { model }`,
+     * otherwise `"unknown"`.
+     *
+     * NOTE: most callers omit `agent` (the default `predicate-emitter`
+     * agent has no model field set), so `model` is `"unknown"` by default.
+     * v1 does NOT read provider-detected model strings from `RunResult` —
+     * that requires every adapter to surface `runResult.model`, which the
+     * current `AgentRunner` contract does not. Tracked for v2; callers who
+     * need provider attribution today should pass `agent: { name, model: "..." }`.
+     */
+    readonly model: string;
+    /**
+     * Sanitized intent string actually sent to the LLM (post-redact). When
+     * `redactIntent: true` was passed, this field is omitted entirely — only
+     * `intentHash` is populated.
+     */
+    readonly intent?: string;
+    /**
+     * SHA-256 hex hash of the sanitized intent string (or djb2 fallback
+     * when `crypto.subtle` is unavailable). Always present — even when
+     * `intent` is omitted via `redactIntent`. (M6)
+     */
+    readonly intentHash: string;
+    /** Number of LLM calls that ran before the final predicate was accepted. */
+    readonly attemptCount: number;
+    /** ISO timestamp when the predicate was returned. */
+    readonly emittedAt: string;
+    /**
+     * Hash of the VALIDATED predicate (canonicalized via stableStringify
+     * before hashing). Two semantically-identical predicates emitted with
+     * different whitespace or key order produce the SAME `predicateHash`.
+     * Sufficient as a tamper-evident pointer alongside the persisted
+     * predicate. (N3)
+     *
+     * Renamed from `rawOutputHash` in v1.13.x — the old name hashed the
+     * raw LLM output string, which made two whitespace-different responses
+     * for the same logical predicate hash differently. Callers persisting
+     * the old `rawOutputHash` value should re-derive it from the stored
+     * predicate using `hashObject(predicate)` from `@directive-run/core/internals`.
+     */
+    readonly predicateHash: string;
+}
+interface PredicateFromIntentWithProvenanceResult<F = Record<string, unknown>> {
+    readonly predicate: FactPredicate<F>;
+    readonly provenance: PredicateFromIntentProvenance;
+}
+/**
+ * Like {@link predicateFromIntent} but additionally returns a structured
+ * provenance record — the model name, sanitized intent (or its hash),
+ * attempt count, timestamp, and a canonical hash of the validated
+ * predicate.
+ *
+ * **Production deployments MUST persist the provenance record alongside
+ * the predicate.** Without it, auditing "where did this rule come from?"
+ * becomes guesswork.
+ *
+ * Throws {@link PredicateFromIntentError} on retry exhaustion — same
+ * semantics as the un-provenanced variant.
+ *
+ * **PII guidance (M6):** pass `redactIntent: true` to omit the raw
+ * intent from the provenance record and persist only the `intentHash`.
+ * Useful when the intent itself is sensitive (medical, financial,
+ * customer messages, etc.).
+ *
+ * **Hash semantics (N3):**
+ * - `predicateHash` hashes the VALIDATED predicate object via stable
+ *   stringification — two whitespace-different LLM outputs that parse to
+ *   the same predicate produce the same hash.
+ * - `intentHash` hashes the sanitized intent STRING (SHA-256 when
+ *   available, djb2 fallback).
+ *
+ * @example
+ * ```ts
+ * const { predicate, provenance } = await predicateFromIntentWithProvenance({
+ *   intent: "block checkout when cart > 10k",
+ *   schema: checkoutModule.schema,
+ *   runner,
+ *   agent: { name: "predicate-emitter", model: "gpt-4o-mini" },
+ *   redactIntent: false, // default: store both intent + intentHash
+ * });
+ *
+ * await db.predicates.insert({
+ *   predicate,
+ *   model: provenance.model,
+ *   intent: provenance.intent,            // omitted when redactIntent: true
+ *   intentHash: provenance.intentHash,
+ *   emittedAt: provenance.emittedAt,
+ *   predicateHash: provenance.predicateHash,
+ *   attempts: provenance.attemptCount,
+ * });
+ * ```
+ */
+declare function predicateFromIntentWithProvenance<F = Record<string, unknown>>(opts: PredicateFromIntentOptions<F>): Promise<PredicateFromIntentWithProvenanceResult<F>>;
+
+export { type PredicateFromIntentDiagnostics, PredicateFromIntentError, type PredicateFromIntentOptions, type PredicateFromIntentProvenance, type PredicateFromIntentWithProvenanceResult, type PredicateToolSpec, type PredicateToolSpecAnthropic, type PredicateToolSpecOpenAI, type PredicateToolSpecOptions, predicateFromIntent, predicateFromIntentRaw, predicateFromIntentWithProvenance, predicateToolSpec, predicateToolSpecAnthropic, predicateToolSpecOpenAI };