@maximem/synap-js-sdk 0.3.0 → 0.4.1

package/dist/anticipation-cache-BMVF5sXb.d.cts

@@ -0,0 +1,190 @@
+/**
+ * In-memory TTL cache for context bundles pushed over gRPC.
+ *
+ * Port of `maximem_synap/cache/anticipation_cache.py`.
+ *
+ * ## Why this is a faithful port and not a simplification
+ *
+ * `@maximem/synap-vercel-adk` already contains a native TS anticipation cache,
+ * and it is a simplification: a hardcoded 30-minute TTL, a plain BM25 threshold
+ * with no per-query derivation, and none of the gates below. Shipping that as
+ * the SDK's cache would mean two retrieval behaviors under one brand, which is
+ * gotcha G-C. Every gate here exists because a specific eval failed without it:
+ *
+ *  - **Recall bypass** runs BEFORE scoring. The measured false hit scored 2.86
+ *    at coverage 1.00, so no score-side gate could ever have caught it.
+ *  - **The novel-term gate** is suppressed below a 200-stem corpus, because at
+ *    cold start ordinary English trips it on nearly every query.
+ *  - **The per-query threshold** scales down for short queries, which otherwise
+ *    cannot reach the nominal score at all.
+ *  - **The coverage gate** catches a bundle that clears BM25 on one shared
+ *    token ("account") while lacking the asked-for fact.
+ *
+ * All thresholds come from the shared behavior contract.
+ */
+/** Sentinel scope that matches any requester. */
+declare const ANY_SCOPE = "_any";
+interface BundleItem {
+    item_id?: string;
+    content?: string;
+    [key: string]: unknown;
+}
+interface ContextBundle {
+    bundleId: string;
+    entityId?: string | null;
+    conversationId?: string | null;
+    itemsByType: Record<string, BundleItem[]>;
+    /** Server hint; may only SHORTEN the global TTL, never extend it. */
+    ttlHintSeconds?: number | null;
+    /** Which anticipation pattern produced this bundle. Diagnostics only. */
+    bundleType?: string | null;
+    /** The queries the server anticipated. Diagnostics only. */
+    searchQueries?: readonly string[] | null;
+}
+interface LookupResult {
+    itemsByType: Record<string, BundleItem[]>;
+    bundleIds: string[];
+    score: number;
+    coverage: number;
+}
+interface LookupParams {
+    searchQuery?: readonly string[] | null;
+    entityId?: string | null;
+    customerId?: string | null;
+    clientId?: string | null;
+    conversationId?: string | null;
+    maxItems?: number;
+}
+type ExitReason = 'empty' | 'recall_bypass' | 'no_query_tokens' | 'novel_term_gate' | 'empty_corpus' | 'no_items_above_threshold' | 'coverage_gate' | 'hit';
+interface LookupTelemetry {
+    searchQuery: string[];
+    entityId: string | null;
+    customerId: string | null;
+    clientId: string | null;
+    conversationId: string | null;
+    scopeFilterAccepted: string[];
+    novelTermRatio: number | null;
+    bm25Threshold: number | null;
+    bm25QueryTokens: string[];
+    itemsPicked: unknown[];
+    itemsRejected: unknown[];
+    coverage: number | null;
+    hit: boolean;
+    exitReason: ExitReason;
+}
+interface SnapshotItemPreview {
+    type: string;
+    scope: string | null;
+    content: string;
+}
+interface SnapshotItemRecord {
+    bundle_id: string;
+    item_type: string;
+    tokens: string[];
+    content: string;
+}
+interface SnapshotBundle {
+    bundle_id: string;
+    entity_id: string;
+    conversation_id: string | null;
+    bundle_type: string | null;
+    search_queries: string[];
+    scope_counts: Record<string, number>;
+    total_items: number;
+    items: SnapshotItemPreview[];
+}
+interface AnticipationCacheSnapshot {
+    total_entries: number;
+    total_item_records: number;
+    scope_breakdown_overall: Record<string, number>;
+    corpus_vocab_size: number;
+    corpus_vocab_sample: string[];
+    item_records: SnapshotItemRecord[];
+    bundles: SnapshotBundle[];
+}
+interface AnticipationCacheOptions {
+    ttlSeconds?: number;
+    maxBundles?: number;
+    /** Injected in tests. Defaults to a monotonic clock. */
+    now?: () => number;
+    onLookup?: (telemetry: LookupTelemetry) => void;
+}
+declare class AnticipationCache {
+    #private;
+    private readonly ttlSeconds;
+    private readonly maxBundles;
+    private readonly now;
+    private readonly onLookup;
+    private entries;
+    private items;
+    private corpusVocab;
+    private bm25;
+    private bm25Dirty;
+    constructor(options?: AnticipationCacheOptions);
+    get size(): number;
+    get itemCount(): number;
+    store(bundle: ContextBundle): void;
+    lookup(params: LookupParams): LookupResult | null;
+    /**
+     * Drop this entity's bundles after a write, so the cache stops serving a
+     * pre-write view. Gated on the flag: this is the write-path hook.
+     */
+    invalidateEntity(entityId: string): number;
+    /**
+     * Unconditionally drop this entity's bundles. Backs `cache.clear_user` and
+     * `cache.clear_customer`, which are explicit user requests and so are not
+     * gated on the invalidate-on-write flag.
+     */
+    dropEntity(entityId: string): number;
+    /**
+     * A read-only diagnostic projection of the cache.
+     *
+     * Backs `client.anticipation_cache_snapshot()` and mirrors Python's shape
+     * key for key, including snake_case keys: this output gets logged, diffed
+     * and pasted into issues across both SDKs, so it is a wire format.
+     *
+     * Note the 140-character content previews. That is Python's literal, and it
+     * is deliberately NOT the 120 of `telemetry.content_preview_chars` from the
+     * contract, which caps lookup telemetry rather than this snapshot.
+     */
+    snapshot(): AnticipationCacheSnapshot;
+    /**
+     * The freshest `user_summary` bundle for this entity, or null.
+     *
+     * `entityId` is REQUIRED, and a missing one refuses the lookup rather than
+     * falling back to the freshest summary across all users. Python hardened this
+     * for exactly that reason: the permissive version could splice user A's
+     * summary into user B's response on the conversation-scope path.
+     */
+    lookupUserSummary(entityId: string | null | undefined): Record<string, unknown> | null;
+    /**
+     * Drop every bundle belonging to one conversation.
+     *
+     * Backs the `compaction_update` signal on the Listen stream: a compaction
+     * rewrites the conversation's summary, so any bundle built from the previous
+     * state is stale and must not keep serving for the rest of its TTL.
+     *
+     * Unlike `dropEntity`, client-scope bundles are NOT spared: a bundle is only
+     * dropped here if it is bound to this specific conversation, and a shared
+     * client-scope bundle has no conversation id to match.
+     */
+    dropConversation(conversationId: string): number;
+    clear(): void;
+    private miss;
+    private fire;
+    private freshnessLookup;
+    /**
+     * The widened scope-match set for a request.
+     *
+     * A narrower-scope request also matches broader-scope bundles for the same
+     * customer or client. Falsy ids are dropped so an empty customer_id cannot
+     * accidentally match bundles keyed at "".
+     */
+    private buildAcceptedScope;
+    private getValidBundleIds;
+    private effectiveTtl;
+    private evictExpired;
+    private dropBundle;
+}
+
+export { AnticipationCache as A, type BundleItem as B, type ContextBundle as C, type ExitReason as E, type LookupParams as L, type SnapshotBundle as S, type AnticipationCacheSnapshot as a, ANY_SCOPE as b, type AnticipationCacheOptions as c, type LookupResult as d, type LookupTelemetry as e, type SnapshotItemPreview as f, type SnapshotItemRecord as g };

package/dist/anticipation-cache-BMVF5sXb.d.ts

@@ -0,0 +1,190 @@
+/**
+ * In-memory TTL cache for context bundles pushed over gRPC.
+ *
+ * Port of `maximem_synap/cache/anticipation_cache.py`.
+ *
+ * ## Why this is a faithful port and not a simplification
+ *
+ * `@maximem/synap-vercel-adk` already contains a native TS anticipation cache,
+ * and it is a simplification: a hardcoded 30-minute TTL, a plain BM25 threshold
+ * with no per-query derivation, and none of the gates below. Shipping that as
+ * the SDK's cache would mean two retrieval behaviors under one brand, which is
+ * gotcha G-C. Every gate here exists because a specific eval failed without it:
+ *
+ *  - **Recall bypass** runs BEFORE scoring. The measured false hit scored 2.86
+ *    at coverage 1.00, so no score-side gate could ever have caught it.
+ *  - **The novel-term gate** is suppressed below a 200-stem corpus, because at
+ *    cold start ordinary English trips it on nearly every query.
+ *  - **The per-query threshold** scales down for short queries, which otherwise
+ *    cannot reach the nominal score at all.
+ *  - **The coverage gate** catches a bundle that clears BM25 on one shared
+ *    token ("account") while lacking the asked-for fact.
+ *
+ * All thresholds come from the shared behavior contract.
+ */
+/** Sentinel scope that matches any requester. */
+declare const ANY_SCOPE = "_any";
+interface BundleItem {
+    item_id?: string;
+    content?: string;
+    [key: string]: unknown;
+}
+interface ContextBundle {
+    bundleId: string;
+    entityId?: string | null;
+    conversationId?: string | null;
+    itemsByType: Record<string, BundleItem[]>;
+    /** Server hint; may only SHORTEN the global TTL, never extend it. */
+    ttlHintSeconds?: number | null;
+    /** Which anticipation pattern produced this bundle. Diagnostics only. */
+    bundleType?: string | null;
+    /** The queries the server anticipated. Diagnostics only. */
+    searchQueries?: readonly string[] | null;
+}
+interface LookupResult {
+    itemsByType: Record<string, BundleItem[]>;
+    bundleIds: string[];
+    score: number;
+    coverage: number;
+}
+interface LookupParams {
+    searchQuery?: readonly string[] | null;
+    entityId?: string | null;
+    customerId?: string | null;
+    clientId?: string | null;
+    conversationId?: string | null;
+    maxItems?: number;
+}
+type ExitReason = 'empty' | 'recall_bypass' | 'no_query_tokens' | 'novel_term_gate' | 'empty_corpus' | 'no_items_above_threshold' | 'coverage_gate' | 'hit';
+interface LookupTelemetry {
+    searchQuery: string[];
+    entityId: string | null;
+    customerId: string | null;
+    clientId: string | null;
+    conversationId: string | null;
+    scopeFilterAccepted: string[];
+    novelTermRatio: number | null;
+    bm25Threshold: number | null;
+    bm25QueryTokens: string[];
+    itemsPicked: unknown[];
+    itemsRejected: unknown[];
+    coverage: number | null;
+    hit: boolean;
+    exitReason: ExitReason;
+}
+interface SnapshotItemPreview {
+    type: string;
+    scope: string | null;
+    content: string;
+}
+interface SnapshotItemRecord {
+    bundle_id: string;
+    item_type: string;
+    tokens: string[];
+    content: string;
+}
+interface SnapshotBundle {
+    bundle_id: string;
+    entity_id: string;
+    conversation_id: string | null;
+    bundle_type: string | null;
+    search_queries: string[];
+    scope_counts: Record<string, number>;
+    total_items: number;
+    items: SnapshotItemPreview[];
+}
+interface AnticipationCacheSnapshot {
+    total_entries: number;
+    total_item_records: number;
+    scope_breakdown_overall: Record<string, number>;
+    corpus_vocab_size: number;
+    corpus_vocab_sample: string[];
+    item_records: SnapshotItemRecord[];
+    bundles: SnapshotBundle[];
+}
+interface AnticipationCacheOptions {
+    ttlSeconds?: number;
+    maxBundles?: number;
+    /** Injected in tests. Defaults to a monotonic clock. */
+    now?: () => number;
+    onLookup?: (telemetry: LookupTelemetry) => void;
+}
+declare class AnticipationCache {
+    #private;
+    private readonly ttlSeconds;
+    private readonly maxBundles;
+    private readonly now;
+    private readonly onLookup;
+    private entries;
+    private items;
+    private corpusVocab;
+    private bm25;
+    private bm25Dirty;
+    constructor(options?: AnticipationCacheOptions);
+    get size(): number;
+    get itemCount(): number;
+    store(bundle: ContextBundle): void;
+    lookup(params: LookupParams): LookupResult | null;
+    /**
+     * Drop this entity's bundles after a write, so the cache stops serving a
+     * pre-write view. Gated on the flag: this is the write-path hook.
+     */
+    invalidateEntity(entityId: string): number;
+    /**
+     * Unconditionally drop this entity's bundles. Backs `cache.clear_user` and
+     * `cache.clear_customer`, which are explicit user requests and so are not
+     * gated on the invalidate-on-write flag.
+     */
+    dropEntity(entityId: string): number;
+    /**
+     * A read-only diagnostic projection of the cache.
+     *
+     * Backs `client.anticipation_cache_snapshot()` and mirrors Python's shape
+     * key for key, including snake_case keys: this output gets logged, diffed
+     * and pasted into issues across both SDKs, so it is a wire format.
+     *
+     * Note the 140-character content previews. That is Python's literal, and it
+     * is deliberately NOT the 120 of `telemetry.content_preview_chars` from the
+     * contract, which caps lookup telemetry rather than this snapshot.
+     */
+    snapshot(): AnticipationCacheSnapshot;
+    /**
+     * The freshest `user_summary` bundle for this entity, or null.
+     *
+     * `entityId` is REQUIRED, and a missing one refuses the lookup rather than
+     * falling back to the freshest summary across all users. Python hardened this
+     * for exactly that reason: the permissive version could splice user A's
+     * summary into user B's response on the conversation-scope path.
+     */
+    lookupUserSummary(entityId: string | null | undefined): Record<string, unknown> | null;
+    /**
+     * Drop every bundle belonging to one conversation.
+     *
+     * Backs the `compaction_update` signal on the Listen stream: a compaction
+     * rewrites the conversation's summary, so any bundle built from the previous
+     * state is stale and must not keep serving for the rest of its TTL.
+     *
+     * Unlike `dropEntity`, client-scope bundles are NOT spared: a bundle is only
+     * dropped here if it is bound to this specific conversation, and a shared
+     * client-scope bundle has no conversation id to match.
+     */
+    dropConversation(conversationId: string): number;
+    clear(): void;
+    private miss;
+    private fire;
+    private freshnessLookup;
+    /**
+     * The widened scope-match set for a request.
+     *
+     * A narrower-scope request also matches broader-scope bundles for the same
+     * customer or client. Falsy ids are dropped so an empty customer_id cannot
+     * accidentally match bundles keyed at "".
+     */
+    private buildAcceptedScope;
+    private getValidBundleIds;
+    private effectiveTtl;
+    private evictExpired;
+    private dropBundle;
+}
+
+export { AnticipationCache as A, type BundleItem as B, type ContextBundle as C, type ExitReason as E, type LookupParams as L, type SnapshotBundle as S, type AnticipationCacheSnapshot as a, ANY_SCOPE as b, type AnticipationCacheOptions as c, type LookupResult as d, type LookupTelemetry as e, type SnapshotItemPreview as f, type SnapshotItemRecord as g };

package/dist/anticipation-cache-H7HEVWQC.js

@@ -0,0 +1,10 @@
+import {
+  ANY_SCOPE,
+  AnticipationCache
+} from "./chunk-6LDUDKHS.js";
+import "./chunk-QBCVMPGK.js";
+export {
+  ANY_SCOPE,
+  AnticipationCache
+};
+//# sourceMappingURL=anticipation-cache-H7HEVWQC.js.map

package/dist/anticipation-cache-H7HEVWQC.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}