@indexnetwork/protocol 4.15.0-rc.357.1 → 4.16.1-rc.359.1

package/dist/shared/hyde/hyde.generator.js

@@ -7,17 +7,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-/**
- * HyDE Generator Agent: pure LLM agent for generating hypothetical documents
- * in the target corpus voice. Uses free-text lens labels instead of enum strategies.
- */
 import { HumanMessage, SystemMessage } from '@langchain/core/messages';
 import { z } from 'zod';
-import { HYDE_CORPUS_PROMPTS } from './hyde.strategies.js';
-import { Timed } from "../observability/performance.js";
-import { protocolLogger } from '../observability/protocol.logger.js';
 import { createStructuredModel } from "../agent/model.config.js";
 import { invokeWithAbortSignal } from "../agent/model-signal.js";
+import { protocolLogger } from '../observability/protocol.logger.js';
+import { Timed } from "../observability/performance.js";
+import { HYDE_CORPUS_PROMPTS } from './hyde.strategies.js';
 const logger = protocolLogger("HydeGenerator");
 const SYSTEM_PROMPT = `You are a Hypothetical Document Generator for semantic search.
 
@@ -33,35 +29,68 @@ const responseFormat = z.object({
         .string()
         .describe('The hypothetical document text in the target voice, suitable for embedding and retrieval'),
 });
-/**
- * Generates hypothetical documents in a target corpus voice for semantic search.
- * Uses free-text lens labels (from LensInferrer) instead of enum strategies.
- */
+function renderList(items) {
+    return items.length > 0 ? items.join('; ') : '(none)';
+}
+/** Build the frame-v1 generation prompt from sanitized source evidence. */
+export function buildFrameHydePrompt(input) {
+    const { sourceText, corpus, sourceFrame } = input;
+    const corpusInstruction = {
+        profiles: 'Write a first-person professional biography in the target profile voice.',
+        intents: 'Write a first-person goal or aspiration in the target intent voice.',
+        premises: 'Write a first-person stable identity, values, or worldview statement in the target premise voice.',
+    }[corpus];
+    return `${corpusInstruction}
+
+Source text: "${sourceText}"
+
+Sanitized source frame:
+- Source roles: ${renderList(sourceFrame.sourceRoles.map((item) => `${item.role} [evidence: "${item.evidence}"]`))}
+- Counterpart/complementary roles: ${renderList(sourceFrame.counterpartRoles.map((item) => `${item.role} [evidence: "${item.evidence}"]`))}
+- Explicit hard constraints: ${renderList(sourceFrame.hardConstraints.map((item) => `${item.type}: ${item.value} [evidence: "${item.evidence}"]`))}
+- Named entities: ${renderList(sourceFrame.namedEntities.map((item) => `${item.type}: ${item.name} [evidence: "${item.evidence}"]`))}
+- Domain vocabulary: ${renderList(sourceFrame.domainVocabulary.map((item) => `${item.term} [evidence: "${item.evidence}"]`))}
+
+Generation constraints:
+- You MAY elaborate generic roles and generic domain language.
+- You MAY use reciprocal/complementary inversion and write in the target voice.
+- You MUST NOT introduce any new proper noun or named entity.
+- You MUST NOT introduce any new hard location, time, numeric, credential, organization, or exclusivity constraint.
+- Preserve explicit source-frame constraints when they apply to the reciprocal target.
+- Output only a few sentences or one short paragraph.`;
+}
+/** Generates hypothetical documents in a target corpus voice for semantic search. */
 export class HydeGenerator {
-    constructor() {
-        this.model = createStructuredModel("hydeGenerator", responseFormat, {
+    constructor(model) {
+        // Preserve the legacy production model construction path; injected models
+        // keep prompt tests provider-free.
+        this.model = model ?? createStructuredModel("hydeGenerator", responseFormat, {
             name: "hyde_generator",
         });
     }
-    /**
-     * Generate a hypothetical document for the given source text and lens.
-     *
-     * @param input - Source text, lens label, and target corpus
-     * @returns Generated hypothetical document text
-     */
+    getModel() {
+        this.model ?? (this.model = createStructuredModel("hydeGenerator", responseFormat, {
+            name: "hyde_generator",
+        }));
+        return this.model;
+    }
+    /** Generate a hypothetical document for the given source text and lens. */
     async generate(input) {
-        const promptText = HYDE_CORPUS_PROMPTS[input.corpus](input.sourceText, input.lens);
+        const promptText = input.sourceFrame
+            ? buildFrameHydePrompt(input)
+            : HYDE_CORPUS_PROMPTS[input.corpus](input.sourceText, input.lens);
         const messages = [
             new SystemMessage(SYSTEM_PROMPT),
             new HumanMessage(promptText),
         ];
-        const result = await invokeWithAbortSignal(this.model, messages);
+        const result = await invokeWithAbortSignal(this.getModel(), messages);
         const parsed = responseFormat.parse(result);
         const text = parsed.hypotheticalDocument ?? '';
         logger.verbose('Generated HyDE document', {
             lens: input.lens,
             corpus: input.corpus,
             textLength: text.length,
+            frameConstrained: !!input.sourceFrame,
         });
         return { text };
     }

package/dist/shared/hyde/hyde.generator.js.map

@@ -1 +1 @@
-{"version":3,"file":"hyde.generator.js","sourceRoot":"/","sources":["shared/hyde/hyde.generator.ts"],"names":[],"mappings":";;;;;;;;;AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,MAAM,MAAM,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;AAE/C,MAAM,aAAa,GAAG;;;;;;;;yDAQmC,CAAC;AAE1D,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,oBAAoB,EAAE,CAAC;SACpB,MAAM,EAAE;SACR,QAAQ,CAAC,0FAA0F,CAAC;CACxG,CAAC,CAAC;AAeH;;;GAGG;AACH,MAAM,OAAO,aAAa;IAA1B;QACU,UAAK,GAAG,qBAAqB,CAAC,eAAe,EAAE,cAAc,EAAE;YACrE,IAAI,EAAE,gBAAgB;SACvB,CAAC,CAAC;IA6BL,CAAC;IA3BC;;;;;OAKG;IAEG,AAAN,KAAK,CAAC,QAAQ,CAAC,KAAwB;QACrC,MAAM,UAAU,GAAG,mBAAmB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAEnF,MAAM,QAAQ,GAAG;YACf,IAAI,aAAa,CAAC,aAAa,CAAC;YAChC,IAAI,YAAY,CAAC,UAAU,CAAC;SAC7B,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,qBAAqB,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACjE,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC5C,MAAM,IAAI,GAAG,MAAM,CAAC,oBAAoB,IAAI,EAAE,CAAC;QAE/C,MAAM,CAAC,OAAO,CAAC,yBAAyB,EAAE;YACxC,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,UAAU,EAAE,IAAI,CAAC,MAAM;SACxB,CAAC,CAAC;QAEH,OAAO,EAAE,IAAI,EAAE,CAAC;IAClB,CAAC;CACF;AApBO;IADL,KAAK,EAAE;;;;6CAoBP","sourcesContent":["/**\n * HyDE Generator Agent: pure LLM agent for generating hypothetical documents\n * in the target corpus voice. Uses free-text lens labels instead of enum strategies.\n */\nimport { HumanMessage, SystemMessage } from '@langchain/core/messages';\nimport { z } from 'zod';\nimport { HYDE_CORPUS_PROMPTS } from './hyde.strategies.js';\nimport type { HydeTargetCorpus } from './lens.inferrer.js';\nimport { Timed } from \"../observability/performance.js\";\nimport { protocolLogger } from '../observability/protocol.logger.js';\nimport { createStructuredModel } from \"../agent/model.config.js\";\nimport { invokeWithAbortSignal } from \"../agent/model-signal.js\";\n\nconst logger = protocolLogger(\"HydeGenerator\");\n\nconst SYSTEM_PROMPT = `You are a Hypothetical Document Generator for semantic search.\n\nYour task: Given a source statement (e.g. an intent or goal), write a short hypothetical document in the voice of the TARGET side—the kind of person or statement that would be an ideal match for that source.\n\nRules:\n- Write in first person as the target.\n- Be concrete and specific so the text is good for vector similarity search.\n- Output only the hypothetical document text, no meta-commentary.\n- Keep length to a few sentences or one short paragraph.`;\n\nconst responseFormat = z.object({\n  hypotheticalDocument: z\n    .string()\n    .describe('The hypothetical document text in the target voice, suitable for embedding and retrieval'),\n});\n\nexport interface HydeGeneratorOutput {\n  text: string;\n}\n\nexport interface HydeGenerateInput {\n  /** Original intent or query text. */\n  sourceText: string;\n  /** Free-text lens label from LensInferrer (e.g. \"crypto infra VC\"). */\n  lens: string;\n  /** Which corpus voice to generate in. */\n  corpus: HydeTargetCorpus;\n}\n\n/**\n * Generates hypothetical documents in a target corpus voice for semantic search.\n * Uses free-text lens labels (from LensInferrer) instead of enum strategies.\n */\nexport class HydeGenerator {\n  private model = createStructuredModel(\"hydeGenerator\", responseFormat, {\n    name: \"hyde_generator\",\n  });\n\n  /**\n   * Generate a hypothetical document for the given source text and lens.\n   *\n   * @param input - Source text, lens label, and target corpus\n   * @returns Generated hypothetical document text\n   */\n  @Timed()\n  async generate(input: HydeGenerateInput): Promise<HydeGeneratorOutput> {\n    const promptText = HYDE_CORPUS_PROMPTS[input.corpus](input.sourceText, input.lens);\n\n    const messages = [\n      new SystemMessage(SYSTEM_PROMPT),\n      new HumanMessage(promptText),\n    ];\n\n    const result = await invokeWithAbortSignal(this.model, messages);\n    const parsed = responseFormat.parse(result);\n    const text = parsed.hypotheticalDocument ?? '';\n\n    logger.verbose('Generated HyDE document', {\n      lens: input.lens,\n      corpus: input.corpus,\n      textLength: text.length,\n    });\n\n    return { text };\n  }\n}\n"]}
+{"version":3,"file":"hyde.generator.js","sourceRoot":"/","sources":["shared/hyde/hyde.generator.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * HyDE Generator Agent: pure LLM agent for generating hypothetical documents\n * in the target corpus voice. Uses free-text lens labels instead of enum strategies.\n */\nimport type { BaseLanguageModelInput } from '@langchain/core/language_models/base';\nimport { HumanMessage, SystemMessage } from '@langchain/core/messages';\nimport { z } from 'zod';\n\nimport { createStructuredModel } from \"../agent/model.config.js\";\nimport { invokeWithAbortSignal } from \"../agent/model-signal.js\";\nimport { protocolLogger } from '../observability/protocol.logger.js';\nimport { Timed } from \"../observability/performance.js\";\nimport type { HydeSourceFrame } from './hyde.frame.js';\nimport { HYDE_CORPUS_PROMPTS } from './hyde.strategies.js';\nimport type { HydeTargetCorpus } from './lens.inferrer.js';\n\nconst logger = protocolLogger(\"HydeGenerator\");\n\nconst SYSTEM_PROMPT = `You are a Hypothetical Document Generator for semantic search.\n\nYour task: Given a source statement (e.g. an intent or goal), write a short hypothetical document in the voice of the TARGET side—the kind of person or statement that would be an ideal match for that source.\n\nRules:\n- Write in first person as the target.\n- Be concrete and specific so the text is good for vector similarity search.\n- Output only the hypothetical document text, no meta-commentary.\n- Keep length to a few sentences or one short paragraph.`;\n\nconst responseFormat = z.object({\n  hypotheticalDocument: z\n    .string()\n    .describe('The hypothetical document text in the target voice, suitable for embedding and retrieval'),\n});\n\nexport interface HydeGeneratorOutput {\n  text: string;\n}\n\nexport interface HydeGenerateInput {\n  /** Original intent or query text. */\n  sourceText: string;\n  /** Free-text lens label from LensInferrer (e.g. \"crypto infra VC\"). */\n  lens: string;\n  /** Which corpus voice to generate in. */\n  corpus: HydeTargetCorpus;\n  /** Sanitized source-grounded frame. Absence preserves the exact legacy prompt. */\n  sourceFrame?: HydeSourceFrame;\n}\n\n/** Minimal structured model contract used for deterministic injection in tests. */\nexport interface HydeGeneratorStructuredModel {\n  invoke(input: BaseLanguageModelInput, config?: { signal?: AbortSignal }): Promise<unknown>;\n}\n\nfunction renderList(items: string[]): string {\n  return items.length > 0 ? items.join('; ') : '(none)';\n}\n\n/** Build the frame-v1 generation prompt from sanitized source evidence. */\nexport function buildFrameHydePrompt(input: HydeGenerateInput & { sourceFrame: HydeSourceFrame }): string {\n  const { sourceText, corpus, sourceFrame } = input;\n  const corpusInstruction = {\n    profiles: 'Write a first-person professional biography in the target profile voice.',\n    intents: 'Write a first-person goal or aspiration in the target intent voice.',\n    premises: 'Write a first-person stable identity, values, or worldview statement in the target premise voice.',\n  }[corpus];\n\n  return `${corpusInstruction}\n\nSource text: \"${sourceText}\"\n\nSanitized source frame:\n- Source roles: ${renderList(sourceFrame.sourceRoles.map((item) => `${item.role} [evidence: \"${item.evidence}\"]`))}\n- Counterpart/complementary roles: ${renderList(sourceFrame.counterpartRoles.map((item) => `${item.role} [evidence: \"${item.evidence}\"]`))}\n- Explicit hard constraints: ${renderList(sourceFrame.hardConstraints.map((item) => `${item.type}: ${item.value} [evidence: \"${item.evidence}\"]`))}\n- Named entities: ${renderList(sourceFrame.namedEntities.map((item) => `${item.type}: ${item.name} [evidence: \"${item.evidence}\"]`))}\n- Domain vocabulary: ${renderList(sourceFrame.domainVocabulary.map((item) => `${item.term} [evidence: \"${item.evidence}\"]`))}\n\nGeneration constraints:\n- You MAY elaborate generic roles and generic domain language.\n- You MAY use reciprocal/complementary inversion and write in the target voice.\n- You MUST NOT introduce any new proper noun or named entity.\n- You MUST NOT introduce any new hard location, time, numeric, credential, organization, or exclusivity constraint.\n- Preserve explicit source-frame constraints when they apply to the reciprocal target.\n- Output only a few sentences or one short paragraph.`;\n}\n\n/** Generates hypothetical documents in a target corpus voice for semantic search. */\nexport class HydeGenerator {\n  private model?: HydeGeneratorStructuredModel;\n\n  constructor(model?: HydeGeneratorStructuredModel) {\n    // Preserve the legacy production model construction path; injected models\n    // keep prompt tests provider-free.\n    this.model = model ?? createStructuredModel(\"hydeGenerator\", responseFormat, {\n      name: \"hyde_generator\",\n    });\n  }\n\n  private getModel(): HydeGeneratorStructuredModel {\n    this.model ??= createStructuredModel(\"hydeGenerator\", responseFormat, {\n      name: \"hyde_generator\",\n    });\n    return this.model;\n  }\n\n  /** Generate a hypothetical document for the given source text and lens. */\n  @Timed()\n  async generate(input: HydeGenerateInput): Promise<HydeGeneratorOutput> {\n    const promptText = input.sourceFrame\n      ? buildFrameHydePrompt(input as HydeGenerateInput & { sourceFrame: HydeSourceFrame })\n      : HYDE_CORPUS_PROMPTS[input.corpus](input.sourceText, input.lens);\n\n    const messages = [\n      new SystemMessage(SYSTEM_PROMPT),\n      new HumanMessage(promptText),\n    ];\n\n    const result = await invokeWithAbortSignal(this.getModel(), messages);\n    const parsed = responseFormat.parse(result);\n    const text = parsed.hypotheticalDocument ?? '';\n\n    logger.verbose('Generated HyDE document', {\n      lens: input.lens,\n      corpus: input.corpus,\n      textLength: text.length,\n      frameConstrained: !!input.sourceFrame,\n    });\n\n    return { text };\n  }\n}\n"]}

package/dist/shared/hyde/hyde.graph.d.ts

@@ -1,27 +1,39 @@
-/**
- * HyDE Graph: cache-aware hypothetical document generation with lens inference.
- *
- * Flow: infer_lenses → check_cache → (generate_missing if needed) → embed → cache_results.
- * Constructor injects Database, Embedder, Cache, LensInferrer, HydeGenerator.
- */
-import { type HydeDocumentState } from './hyde.state.js';
-import { LensInferrer } from './lens.inferrer.js';
-import { HydeGenerator } from './hyde.generator.js';
+import type { DebugMetaAgent } from '../../chat/chat-streaming.types.js';
+import type { HydeCache } from '../interfaces/cache.interface.js';
 import type { HydeGraphDatabase } from '../interfaces/database.interface.js';
 import type { EmbeddingGenerator } from '../interfaces/embedder.interface.js';
-import type { HydeCache } from '../interfaces/cache.interface.js';
-import type { DebugMetaAgent } from '../../chat/chat-streaming.types.js';
-/**
- * Factory for the HyDE generation graph.
- * Injects Database, Embedder, Cache, LensInferrer, and HydeGenerator.
- */
+import { type HydeGenerationMode } from './hyde.env.js';
+import { type HydeSourceFrame } from './hyde.frame.js';
+import type { HydeGenerateInput, HydeGeneratorOutput } from './hyde.generator.js';
+import { type HydeDocumentState } from './hyde.state.js';
+import type { LensInferenceInput, LensInferenceOutput } from './lens.inferrer.js';
+import { type HydeValidationInput, type HydeValidationOutput } from './hyde.validator.js';
+/** Narrow lens inferrer contract accepted by the graph. */
+export interface HydeLensInferrerLike {
+    infer(input: LensInferenceInput): Promise<LensInferenceOutput>;
+}
+/** Narrow document generator contract accepted by the graph. */
+export interface HydeGeneratorLike {
+    generate(input: HydeGenerateInput): Promise<HydeGeneratorOutput>;
+}
+/** Narrow batch validator contract accepted by the graph. */
+export interface HydeValidatorLike {
+    validate(input: HydeValidationInput): Promise<HydeValidationOutput>;
+}
+export interface HydeGraphOptions {
+    /** Test override. Production derives the mode from HYDE_FRAME_CONSTRAINTS_ENABLED. */
+    mode?: HydeGenerationMode;
+    validator?: HydeValidatorLike;
+}
+/** Factory for the HyDE generation graph. Existing five-argument calls remain valid. */
 export declare class HydeGraphFactory {
     private database;
     private embedder;
     private cache;
     private inferrer;
     private generator;
-    constructor(database: HydeGraphDatabase, embedder: EmbeddingGenerator, cache: HydeCache, inferrer: LensInferrer, generator: HydeGenerator);
+    private options;
+    constructor(database: HydeGraphDatabase, embedder: EmbeddingGenerator, cache: HydeCache, inferrer: HydeLensInferrerLike, generator: HydeGeneratorLike, options?: HydeGraphOptions);
     createGraph(): import("@langchain/langgraph").CompiledStateGraph<{
         sourceType: "intent" | "context" | "query";
         sourceId: import("../interfaces/database.interface.js").Id<"users"> | import("../interfaces/database.interface.js").Id<"intents"> | undefined;
@@ -30,6 +42,10 @@ export declare class HydeGraphFactory {
         maxLenses: number;
         forceRegenerate: boolean;
         lenses: import("./lens.inferrer.js").Lens[];
+        sourceFrame: HydeSourceFrame | undefined;
+        frameFingerprint: string | undefined;
+        sourceTextHash: string | undefined;
+        generatedAt: string | undefined;
         hydeDocuments: Record<string, HydeDocumentState>;
         hydeEmbeddings: Record<string, number[]>;
         error: string | undefined;
@@ -42,6 +58,10 @@ export declare class HydeGraphFactory {
         maxLenses?: number | import("@langchain/langgraph").OverwriteValue<number> | undefined;
         forceRegenerate?: boolean | import("@langchain/langgraph").OverwriteValue<boolean> | undefined;
         lenses?: import("./lens.inferrer.js").Lens[] | import("@langchain/langgraph").OverwriteValue<import("./lens.inferrer.js").Lens[]> | undefined;
+        sourceFrame?: HydeSourceFrame | import("@langchain/langgraph").OverwriteValue<HydeSourceFrame | undefined> | undefined;
+        frameFingerprint?: string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined;
+        sourceTextHash?: string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined;
+        generatedAt?: string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined;
         hydeDocuments?: Record<string, HydeDocumentState> | import("@langchain/langgraph").OverwriteValue<Record<string, HydeDocumentState>> | undefined;
         hydeEmbeddings?: Record<string, number[]> | import("@langchain/langgraph").OverwriteValue<Record<string, number[]>> | undefined;
         error?: string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined;
@@ -62,6 +82,10 @@ export declare class HydeGraphFactory {
         maxLenses: import("@langchain/langgraph").BaseChannel<number, number | import("@langchain/langgraph").OverwriteValue<number>, unknown>;
         forceRegenerate: import("@langchain/langgraph").BaseChannel<boolean, boolean | import("@langchain/langgraph").OverwriteValue<boolean>, unknown>;
         lenses: import("@langchain/langgraph").BaseChannel<import("./lens.inferrer.js").Lens[], import("./lens.inferrer.js").Lens[] | import("@langchain/langgraph").OverwriteValue<import("./lens.inferrer.js").Lens[]>, unknown>;
+        sourceFrame: import("@langchain/langgraph").BaseChannel<HydeSourceFrame | undefined, HydeSourceFrame | import("@langchain/langgraph").OverwriteValue<HydeSourceFrame | undefined> | undefined, unknown>;
+        frameFingerprint: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+        sourceTextHash: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+        generatedAt: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
         hydeDocuments: import("@langchain/langgraph").BaseChannel<Record<string, HydeDocumentState>, Record<string, HydeDocumentState> | import("@langchain/langgraph").OverwriteValue<Record<string, HydeDocumentState>>, unknown>;
         hydeEmbeddings: import("@langchain/langgraph").BaseChannel<Record<string, number[]>, Record<string, number[]> | import("@langchain/langgraph").OverwriteValue<Record<string, number[]>>, unknown>;
         error: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
@@ -82,17 +106,34 @@ export declare class HydeGraphFactory {
         maxLenses: import("@langchain/langgraph").BaseChannel<number, number | import("@langchain/langgraph").OverwriteValue<number>, unknown>;
         forceRegenerate: import("@langchain/langgraph").BaseChannel<boolean, boolean | import("@langchain/langgraph").OverwriteValue<boolean>, unknown>;
         lenses: import("@langchain/langgraph").BaseChannel<import("./lens.inferrer.js").Lens[], import("./lens.inferrer.js").Lens[] | import("@langchain/langgraph").OverwriteValue<import("./lens.inferrer.js").Lens[]>, unknown>;
+        sourceFrame: import("@langchain/langgraph").BaseChannel<HydeSourceFrame | undefined, HydeSourceFrame | import("@langchain/langgraph").OverwriteValue<HydeSourceFrame | undefined> | undefined, unknown>;
+        frameFingerprint: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+        sourceTextHash: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+        generatedAt: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
         hydeDocuments: import("@langchain/langgraph").BaseChannel<Record<string, HydeDocumentState>, Record<string, HydeDocumentState> | import("@langchain/langgraph").OverwriteValue<Record<string, HydeDocumentState>>, unknown>;
         hydeEmbeddings: import("@langchain/langgraph").BaseChannel<Record<string, number[]>, Record<string, number[]> | import("@langchain/langgraph").OverwriteValue<Record<string, number[]>>, unknown>;
         error: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
         agentTimings: import("@langchain/langgraph").BaseChannel<DebugMetaAgent[], DebugMetaAgent[] | import("@langchain/langgraph").OverwriteValue<DebugMetaAgent[]>, unknown>;
     }, import("@langchain/langgraph").StateDefinition, {
         infer_lenses: {
+            lenses: import("./lens.inferrer.js").Lens[];
+            sourceFrame: HydeSourceFrame;
+            frameFingerprint: string;
+            sourceTextHash: string;
+            generatedAt: string;
+            agentTimings: DebugMetaAgent[];
+        } | {
             lenses: import("./lens.inferrer.js").Lens[];
             agentTimings: DebugMetaAgent[];
+            sourceFrame?: undefined;
+            frameFingerprint?: undefined;
+            sourceTextHash?: undefined;
+            generatedAt?: undefined;
         };
         check_cache: {
-            hydeDocuments: Record<string, HydeDocumentState>;
+            hydeDocuments: {
+                [k: string]: HydeDocumentState;
+            };
         };
         generate_missing: {
             hydeDocuments: {

package/dist/shared/hyde/hyde.graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hyde.graph.d.ts","sourceRoot":"/","sources":["shared/hyde/hyde.graph.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAKlE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAyBzE;;;GAGG;AACH,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,SAAS;gBAJT,QAAQ,EAAE,iBAAiB,EAC3B,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,aAAa;IAGlC,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqOZ"}
+{"version":3,"file":"hyde.graph.d.ts","sourceRoot":"/","sources":["shared/hyde/hyde.graph.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAK9E,OAAO,EAAwD,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC9G,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAElF,OAAO,EAAiB,KAAK,mBAAmB,EAAE,KAAK,oBAAoB,EAA8B,MAAM,qBAAqB,CAAC;AAUrI,2DAA2D;AAC3D,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAChE;AAED,gEAAgE;AAChE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAClE;AAED,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CACrE;AAED,MAAM,WAAW,gBAAgB;IAC/B,sFAAsF;IACtF,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B;AAsID,wFAAwF;AACxF,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,OAAO;gBALP,QAAQ,EAAE,iBAAiB,EAC3B,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,oBAAoB,EAC9B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,GAAE,gBAAqB;IAGxC,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiZZ"}