@tangle-network/agent-knowledge 3.2.1 → 4.0.0

package/dist/types-BFRyr390.d.ts

@@ -1,319 +0,0 @@
-import { S as SourceRecord } from './types-6x0OpfW6.js';
-import { OffPolicyTrajectory } from '@tangle-network/agent-eval/rl';
-
-interface RetrievalHoldoutConfig {
-    /** Per-session probability that one eligible watchlist item is suppressed. 0 logs the full schema without ever dropping. */
-    epsilon: number;
-    /** Item ids eligible for suppression. Empty or absent means no item can ever be dropped. */
-    watchlist?: string[];
-    /** Ties every event to the exact epsilon/watchlist in force, for audit and replay. */
-    configVersion?: string;
-    /** Copied onto every event so multi-adapter logs stay attributable. */
-    adapterId?: string;
-    /** Corpus/store version stamp; an edited item under the same id is a different treatment. */
-    corpusVersion?: string;
-    /**
-     * Emit plaintext sessionId and scope on events. Default false: events carry only
-     * sessionIdHash/scopeHash, so PII-bearing identifiers (tenantId/userId/tags) never reach a
-     * consumer-controlled sink unless the consumer explicitly owns that decision. Note that
-     * replaying assignment draws from logs alone needs the plaintext sessionId, so
-     * privacy-default logs require the consumer's own sessionId mapping for replay audits.
-     */
-    includePlaintextIdentifiers?: boolean;
-    /**
-     * Cap on tracked sessions per experiment config in the sticky wrapper's registry.
-     * Exists so tests can exercise eviction; production should keep the default (10,000).
-     */
-    maxTrackedSessions?: number;
-    /**
-     * Uniform-[0,1) generator keyed by a string. Defaults to a sha256-derived deterministic
-     * generator so every assignment is replayable from the logged keys alone (design rule D5).
-     */
-    rng?: (key: string) => number;
-    /** Receives one event per retrieval call, INCLUDING no-drop calls: control-arm membership is half the data. */
-    onEvent: (event: RetrievalHoldoutEvent) => void;
-}
-interface RetrievalHoldoutEligibleItem {
-    id: string;
-    /** 1-based position in the post-filter hit list. */
-    rank: number;
-    score?: number;
-    kind: string;
-    /** sha256(hit.text) prefix; effects are estimated per (id, contentHash) pair. */
-    contentHash: string;
-}
-interface RetrievalHoldoutEvent {
-    v: 1;
-    eventId: string;
-    ts: string;
-    adapterId?: string;
-    /** Plaintext session id — emitted ONLY when config.includePlaintextIdentifiers is true. */
-    sessionId?: string;
-    /** Consumer-supplied experiment/outcome join id (scope.tags.taskId); deliberately plaintext. */
-    taskId?: string;
-    /** 1-based call counter within the session; 0 when the call is outside session randomization. */
-    callIndex: number;
-    /**
-     * sha256(sessionId) prefix — the default privacy-preserving session join key AND the seed-key
-     * reference for the assignment draws (previously named rngKey; identical derivation, deduped).
-     */
-    sessionIdHash?: string;
-    queryHash?: string;
-    /** Verbatim scope — emitted ONLY when config.includePlaintextIdentifiers is true (PII risk). */
-    scope?: AgentMemoryScope;
-    /** sha256 prefix of the canonical-JSON scope (keys sorted, undefined stripped). */
-    scopeHash?: string;
-    config: {
-        epsilon: number;
-        watchlist: string[];
-        configVersion?: string;
-    };
-    /**
-     * Value-hash of the experiment-defining knobs, sha256({epsilon, sorted watchlist}) prefix.
-     * The estimator groups events by it; the sticky-session registry is keyed by it.
-     */
-    configHash: string;
-    /**
-     * False when no sessionId is available or the adapter answered without retrieval
-     * (see bypassReason), so the fraction-under-experiment denominator stays honest.
-     */
-    holdoutEligible: boolean;
-    /** Present only on adapter paths that bypassed retrieval, where no suppression could apply. */
-    bypassReason?: RetrievalHoldoutBypassReason;
-    /** The full post-filter eligibility set E, logged on every call (control arm + interference probes). */
-    eligible: RetrievalHoldoutEligibleItem[];
-    /** Ids in watchlist ∩ E, in eligibility order. */
-    watchlistEligible: string[];
-    sessionHoldout: boolean;
-    /** The session's sticky drop target once drawn; distinguishes "target absent from E" from "not yet drawn". */
-    sessionTargetId: string | null;
-    /** The item suppressed in THIS call, or null. */
-    droppedId: string | null;
-    /** 1/|watchlist ∩ E| recorded at draw time; the exact inverse-propensity weight input. */
-    pickPropensity: number | null;
-    /** epsilon * pickPropensity, recorded at draw time so analysis never re-derives assignment probabilities. */
-    dropPropensity: number | null;
-    deliveredIds: string[];
-    corpusVersion?: string;
-}
-interface RetrievalHoldoutSessionState {
-    sessionId: string;
-    /** Calls observed so far in this session. */
-    callCount: number;
-    sessionHoldout: boolean;
-    /** Sticky drop target; drawn once at the first call whose eligibility set intersects the watchlist. */
-    targetId: string | null;
-    pickPropensity: number | null;
-}
-interface RetrievalHoldoutCallContext {
-    sessionId?: string;
-    taskId?: string;
-    /** Raw query; only its sha256 prefix is logged. */
-    query?: string;
-    scope?: AgentMemoryScope;
-    /** State returned by the previous call of this session; threading it is what makes suppression sticky. */
-    session?: RetrievalHoldoutSessionState;
-}
-interface RetrievalHoldoutResult {
-    delivered: AgentMemoryHit[];
-    event: RetrievalHoldoutEvent;
-    session?: RetrievalHoldoutSessionState;
-}
-/** Adapter context paths that answer without retrieval, so no holdout draw can happen. */
-type RetrievalHoldoutBypassReason = 'short-term-context' | 'raw-string-context';
-/**
- * Deterministic uniform [0,1) for assignment draws. The sha256 key derivation is ours — it makes
- * every draw replayable from the logged keys alone (design rule D5) — while the generator core is
- * the substrate's `mulberry32` (@tangle-network/agent-eval statistics vocabulary), seeded with the
- * top 32 bits of the digest, so the statistical machinery is reused rather than forked.
- */
-declare function deterministicRng(key: string): number;
-/**
- * Value-hash of the knobs that DEFINE the experiment (epsilon + watchlist, order-independent).
- * Everything else on the config (callbacks, attribution stamps, privacy flags) does not change
- * which assignments are drawn, so it stays out of the hash.
- */
-declare function retrievalHoldoutConfigHash(config: Pick<RetrievalHoldoutConfig, 'epsilon' | 'watchlist'>): string;
-/**
- * Pure per-call holdout: takes post-filter hits, returns delivered hits plus the log event
- * and the next session state. Suppression only removes items (no backfill), and it happens
- * before rendering so a drop session's context is byte-identical to a natural smaller retrieval.
- */
-declare function applyRetrievalHoldout(hits: AgentMemoryHit[], config: RetrievalHoldoutConfig, ctx?: RetrievalHoldoutCallContext): RetrievalHoldoutResult;
-/**
- * Logs a holdout event for adapter context paths that answer WITHOUT going through the
- * search→render seam (Neo4j short-term conversation context, raw-string getContext results),
- * so a consumer with a holdout configured still sees every call and the fraction-under-experiment
- * denominator stays honest instead of silently losing these calls. No suppression is applied:
- * dropping is only meaningful for retrieved memory hits, never for conversation context.
- */
-declare function emitRetrievalHoldoutBypass(hits: AgentMemoryHit[], config: RetrievalHoldoutConfig, ctx: Omit<RetrievalHoldoutCallContext, 'session'>, bypassReason: RetrievalHoldoutBypassReason): RetrievalHoldoutEvent;
-/**
- * Clears all sticky-session state. For test isolation and experiment-epoch boundaries;
- * sessions in flight afterwards re-draw deterministically (same rng keys), so with the default
- * rng a reset is invisible in the logs unless eligibility sets changed in between.
- */
-declare function resetRetrievalHoldoutRegistry(): void;
-/**
- * Convenience wrapper that threads session state internally, keyed by the VALUE of the
- * experiment-defining knobs (configHash = epsilon + sorted watchlist) plus sessionId, so a fresh
- * config object per call — the natural pattern when options are built inline — keeps full
- * stickiness. Distinct experiments never share session state; two config objects with the same
- * epsilon/watchlist are the same experiment by definition.
- */
-declare function applySessionStickyRetrievalHoldout(hits: AgentMemoryHit[], config: RetrievalHoldoutConfig, ctx?: Omit<RetrievalHoldoutCallContext, 'session'>): RetrievalHoldoutResult;
-/** Aggregated view of one session's holdout exposure — the randomization unit of this design. */
-interface RetrievalHoldoutSessionSummary {
-    /** `${configHash}:${sessionIdHash}` — the trajectory's runId. */
-    runId: string;
-    configHash: string;
-    sessionIdHash: string;
-    sessionHoldout: boolean;
-    sessionTargetId: string | null;
-    /** Item actually suppressed in this session (equals sessionTargetId when a drop occurred). */
-    droppedId: string | null;
-    /** |watchlist ∩ E| at the session's first intersecting randomized call; 0 when never intersecting. */
-    firstCandidateCount: number;
-    /** Randomized retrieval calls observed for this session. */
-    callCount: number;
-    /** Adapter bypass calls observed for this session (logged, never randomized). */
-    bypassCallCount: number;
-    /** Session-level probability of the OBSERVED assignment under the behavior policy. */
-    behaviorProb: number;
-    /** True when the session's events disagree on arm or target (e.g. registry eviction re-draw). */
-    mixedExposure: boolean;
-    /** Present only on sessions surfaced in `excluded` rather than converted. */
-    exclusionReason?: 'mixed-exposure' | 'no-randomized-calls';
-}
-interface RetrievalHoldoutOffPolicyOptions {
-    /**
-     * Realized outcome PER SESSION, keyed by sessionIdHash — the session is the randomization
-     * unit, so rewards are per session, never per call. A missing entry for an included session
-     * throws: silently dropping unscored sessions would corrupt the estimator's denominator, so
-     * filter events to scored sessions upstream instead.
-     */
-    rewards: Record<string, number>;
-    /**
-     * Target-policy probability of the session's observed assignment. Default models the
-     * always-deliver-in-full policy: 1 for full-delivery sessions, 0 for drop sessions.
-     */
-    targetProb?: (session: RetrievalHoldoutSessionSummary) => number;
-    /** Per-session reward-model prediction enabling `doublyRobust`; when absent, qHat is null. */
-    qHat?: (session: RetrievalHoldoutSessionSummary) => number | null;
-}
-interface RetrievalHoldoutOffPolicyResult {
-    /** One trajectory per (configHash, sessionIdHash) — never per call. */
-    trajectories: OffPolicyTrajectory[];
-    /** 1:1 with `trajectories` (same order): the diagnostic view of each converted session. */
-    sessions: RetrievalHoldoutSessionSummary[];
-    /** Sessions surfaced but NOT converted (mixed exposure, bypass-only) — counted, never hidden. */
-    excluded: RetrievalHoldoutSessionSummary[];
-    /** Events with no sessionIdHash: outside session randomization, cannot join a reward. */
-    unattributableEvents: number;
-}
-/**
- * Maps holdout logs onto agent-eval's `OffPolicyTrajectory`, ONE TRAJECTORY PER SESSION, so
- * EXP-007's analysis consumes the substrate's `inverseProbabilityWeighting` /
- * `selfNormalizedImportanceWeighting` / `doublyRobust` estimators directly. This matches the
- * PREREG estimator (session-sticky self-normalized IPW): the design randomizes per SESSION —
- * the arm coin is flipped once (P(holdout) = epsilon) and the sticky target is drawn once,
- * uniformly over watchlist ∩ E at the session's first intersecting call.
- *
- * Session-level action space and behavior probabilities (they sum to 1 by construction):
- * - full delivery (control arm observed): `1 − epsilon`;
- * - drop candidate i of k = |watchlist ∩ E_first|: `epsilon / k` each (the draw event's logged
- *   `dropPropensity`);
- * - sessions whose eligibility sets never intersect the watchlist: probability 1 — full
- *   delivery was certain in either arm.
- *
- * Per-call events are repeated observations WITHIN one session-level randomization; per-call
- * IPW is statistically invalid for this design (per-call "propensities" imply an action
- * distribution summing to more than 1 and bias IPS downward). Calls where the sticky target is
- * absent from E, and adapter bypass calls, fold into the session summary (callCount /
- * bypassCallCount) instead of generating independent propensities.
- *
- * Join contract: `rewards` is keyed by `sessionIdHash` (sha256(sessionId) first 16 hex — compute
- * the same prefix over the outcome table's session ids, or log with
- * `includePlaintextIdentifiers: true` and join on raw ids upstream). Events are grouped per
- * (configHash, sessionIdHash) so different experiment configs are never pooled. Mixed-exposure
- * sessions (arm or target disagreement, e.g. after registry eviction) are excluded from the
- * trajectories and surfaced in `excluded` for the analysis to count.
- * Pre-registration for EXP-007 stays in the research repo by design; the manifest vocabulary for
- * it is agent-eval's `HypothesisManifest` / `signManifest` / `evaluateHypothesis` exports.
- */
-declare function toOffPolicyTrajectory(events: RetrievalHoldoutEvent[], options: RetrievalHoldoutOffPolicyOptions): RetrievalHoldoutOffPolicyResult;
-
-type AgentMemoryKind = 'message' | 'entity' | 'fact' | 'preference' | 'observation' | 'reasoning-trace';
-interface AgentMemoryScope {
-    tenantId?: string;
-    userId?: string;
-    sessionId?: string;
-    namespace?: string;
-    tags?: Record<string, string>;
-}
-interface AgentMemoryHit {
-    id: string;
-    uri: string;
-    kind: AgentMemoryKind;
-    text: string;
-    title?: string;
-    score?: number;
-    normalizedScore?: number;
-    confidence?: number;
-    createdAt?: string;
-    validUntil?: string;
-    lastVerifiedAt?: string;
-    metadata?: Record<string, unknown>;
-}
-interface AgentMemoryContext {
-    query: string;
-    text: string;
-    hits: AgentMemoryHit[];
-    sourceRecords: SourceRecord[];
-    metadata?: Record<string, unknown>;
-}
-interface AgentMemorySearchOptions {
-    scope?: AgentMemoryScope;
-    limit?: number;
-    minScore?: number;
-    kinds?: AgentMemoryKind[];
-    metadata?: Record<string, unknown>;
-    /**
-     * Opt-in randomized retrieval holdout (epsilon-dropout) for treatment-effect logging.
-     * Absent by default; when absent, retrieval behavior is unchanged. See ./holdout.
-     */
-    holdout?: RetrievalHoldoutConfig;
-}
-interface AgentMemoryWriteInput {
-    kind: AgentMemoryKind;
-    text: string;
-    id?: string;
-    title?: string;
-    role?: 'system' | 'user' | 'assistant' | 'tool';
-    entityName?: string;
-    entityType?: string;
-    category?: string;
-    predicate?: string;
-    subject?: string;
-    object?: string;
-    confidence?: number;
-    scope?: AgentMemoryScope;
-    metadata?: Record<string, unknown>;
-}
-interface AgentMemoryWriteResult {
-    accepted: boolean;
-    id: string;
-    uri: string;
-    kind: AgentMemoryKind;
-    sourceRecord?: SourceRecord;
-    metadata?: Record<string, unknown>;
-}
-interface AgentMemoryAdapter {
-    readonly id: string;
-    search(query: string, options?: AgentMemorySearchOptions): Promise<AgentMemoryHit[]>;
-    getContext(query: string, options?: AgentMemorySearchOptions): Promise<AgentMemoryContext>;
-    write(input: AgentMemoryWriteInput): Promise<AgentMemoryWriteResult>;
-    flush?(): Promise<void>;
-}
-
-export { type AgentMemoryAdapter as A, type RetrievalHoldoutBypassReason as R, type AgentMemoryScope as a, type AgentMemoryContext as b, type AgentMemoryHit as c, type AgentMemoryKind as d, type AgentMemorySearchOptions as e, type AgentMemoryWriteInput as f, type AgentMemoryWriteResult as g, type RetrievalHoldoutCallContext as h, type RetrievalHoldoutConfig as i, type RetrievalHoldoutEligibleItem as j, type RetrievalHoldoutEvent as k, type RetrievalHoldoutOffPolicyOptions as l, type RetrievalHoldoutOffPolicyResult as m, type RetrievalHoldoutResult as n, type RetrievalHoldoutSessionState as o, type RetrievalHoldoutSessionSummary as p, applyRetrievalHoldout as q, applySessionStickyRetrievalHoldout as r, deterministicRng as s, emitRetrievalHoldoutBypass as t, resetRetrievalHoldoutRegistry as u, retrievalHoldoutConfigHash as v, toOffPolicyTrajectory as w };