defineRetrieval

KIT · function · Runtime value

Compile a retrieval runner from its declared ports and effects.

Rejected queries stay in the caller's seen set, so a retry is reported as a duplicate instead of silently repeating the adapter call; only successful results increment the query count.

Import

TypeScript

import { defineRetrieval } from '@jangts/agent-core/kits/retrieval';

JavaScript

import { defineRetrieval } from '@jangts/agent-core/kits/retrieval';

Other public entry points:@jangts/agent-core, @jangts/agent-core/types, @jangts/agent-core/kits/retrieval, @jangts/agent-core/kits.

Definition

Type parameters

Type parameter	Constraint	Default type
Query	—	—
Source	RetrievalSource	—
Result	RetrievalResult<Source>	—
App	—	—

Call

defineRetrieval<Query, Source extends RetrievalSource, Result extends RetrievalResult<Source>, App>(definition: RetrievalDefinition<Query, Source, Result, App>): RetrievalRunner<Query, Source, Result, import("../structs/common.js").OperationContext<App>>

Compile a retrieval runner from its declared ports and effects.

Rejected queries stay in the caller's seen set, so a retry is reported as a duplicate instead of silently repeating the adapter call; only successful results increment the query count.

Type parameter	Constraint	Default type
Query	—	—
Source	RetrievalSource	—
Result	RetrievalResult<Source>	—
App	—	—

Parameter	Type	Passing	Description
definition	RetrievalDefinition<Query, Source, Result, App>	Required	—

Fields of definition

Field	Type	Required	Description
id	string	Required	Read-only. See the type definition and usage context.
description	string	Required	Read-only. See the type definition and usage context.
tags	readonly string[] | undefined	Optional	Read-only. See the type definition and usage context.
prepare	((query: Query, context: OperationContext<App>) => Query) | undefined	Optional	Read-only. Normalizes the query before assertions run; must be synchronous.
assertInput	(query: Query, context: OperationContext<App>) => void	Required	Read-only. Rejects a malformed query; must be synchronous and return void.
state	(context: OperationContext<App>) => RetrievalState<Source>	Required	Read-only. Returns the request-owned state that holds counters and sources.
limit	(context: OperationContext<App>) => number	Required	Read-only. Maximum accepted queries for the current state.
key	((query: Query) => string) | undefined	Optional	Read-only. Deduplication key; defaults to a canonical serialization of the query.
errors	{ readonly duplicate?: RetrievalReason<Query, OperationContext<App>> | undefined; readonly budget?: RetrievalReason<Query, OperationContext<App>> | undefined; } | undefined	Optional	Read-only. See the type definition and usage context.
authorize	((query: Query, context: OperationContext<App>) => void) | undefined	Optional	Read-only. Resource authorization runs after duplicate/budget checks and before reserving a key.
execute	(query: Query, context: OperationContext<App>) => Result	Required	Read-only. Performs the actual read; must be synchronous. Throwing does not refund the query key.
assertResult	((result: Result, query: Query, context: OperationContext<App>) => void) | undefined	Optional	Read-only. Validates the adapter result; a throw leaves the query counted as seen but not successful.
sourceId	((source: Source, query: Query, sequence: number, context: OperationContext<App>) => string) | undefined	Optional	Read-only. Names a source; the assigned value replaces sourceId in the receipt result.
effects	readonly RetrievalEffect<Query, Source, Result, OperationContext<App>>[] | undefined	Optional	Read-only. See the type definition and usage context.
now	(() => number) | undefined	Optional	Read-only. Clock override for receipt timestamps; defaults to Date.now.

Returns: RetrievalRunner<Query, Source, Result, OperationContext<App>>.

Return value structure

Field	Type	Required	Description
id	string	Required	Read-only. See the type definition and usage context.
description	string	Required	Read-only. See the type definition and usage context.
effects	readonly RetrievalEffect<Query, Source, Result, OperationContext<App>>[]	Required	Read-only. Effects that run after every accepted query.
run	(input: Query, context: OperationContext<App>) => RetrievalReceipt<Query, Source, Result>	Required	Executes one query in the fixed lifecycle order and returns its receipt.

Examples

• Retrieval: a synchronous retrieval lifecycle with quota: Keep normalization, validation, deduplication, authorization, reading, and follow-up effects on one deterministic call path.

Configure one read for the same product material

Beginner · Node.js

TypeScript

import { Retrieval } from '@jangts/agent-core/kits/retrieval';
type Source = { sourceId: string; text: string };
const state = { queryCount: 0, seen: new Set<string>(), sources: [] as Source[] };
const documents = [{ sourceId: 'manual', text: 'Agent Core 使用指南' }];
const retrieval = Retrieval.defineRetrieval({
  id: 'manual-search', description: '读取已确认的本地演示资料',
  assertInput(query: string) { if (!query.trim()) throw new Error('查询为空'); },
  state: () => state, limit: () => 2,
  execute: (query: string) => ({ sources: documents.filter(item => item.text.includes(query)) }),
});
console.log(retrieval.run('Agent', { app: {}, signal: new AbortController().signal }).result);

JavaScript

import { Retrieval } from '@jangts/agent-core/kits/retrieval';
const state = { queryCount: 0, seen: new Set(), sources: [] };
const documents = [{ sourceId: 'manual', text: 'Agent Core 使用指南' }];
const retrieval = Retrieval.defineRetrieval({
    id: 'manual-search', description: '读取已确认的本地演示资料',
    assertInput(query) { if (!query.trim())
        throw new Error('查询为空'); },
    state: () => state, limit: () => 2,
    execute: (query) => ({ sources: documents.filter(item => item.text.includes(query)) }),
});
console.log(retrieval.run('Agent', { app: {}, signal: new AbortController().signal }).result);

Add normalization, authorization, and receipt effects to the same run

Configuration · Node.js

TypeScript

import { Retrieval } from '@jangts/agent-core/kits/retrieval';
type Source = { sourceId: string; text: string };
const state = { queryCount: 0, seen: new Set<string>(), sources: [] as Source[] };
const retrieval = Retrieval.defineRetrieval<string, Source, { sources: Source[] }, { canRead: boolean }>({
  id: 'manual-search', description: '按当前服务端权限读取资料',
  prepare: query => query.trim(),
  assertInput(query) { if (!query) throw new Error('查询为空'); },
  state: () => state, limit: () => 2,
  authorize(_query, { app }) { if (!app.canRead) throw new Error('没有资料读取权限'); },
  execute: query => ({ sources: [{ sourceId: 'manual', text: 'Agent Core 使用指南' }].filter(item => item.text.includes(query)) }),
  effects: [{ id: 'source-count', description: '给真实回执附加来源数量', handle(receipt) { receipt.extensions.sourceCount = receipt.result.sources.length; } }],
});
const receipt = retrieval.run(' Agent ', { app: { canRead: true }, signal: new AbortController().signal });
console.log(receipt.sequence, receipt.extensions);

JavaScript

import { Retrieval } from '@jangts/agent-core/kits/retrieval';
const state = { queryCount: 0, seen: new Set(), sources: [] };
const retrieval = Retrieval.defineRetrieval({
    id: 'manual-search', description: '按当前服务端权限读取资料',
    prepare: query => query.trim(),
    assertInput(query) { if (!query)
        throw new Error('查询为空'); },
    state: () => state, limit: () => 2,
    authorize(_query, { app }) { if (!app.canRead)
        throw new Error('没有资料读取权限'); },
    execute: query => ({ sources: [{ sourceId: 'manual', text: 'Agent Core 使用指南' }].filter(item => item.text.includes(query)) }),
    effects: [{ id: 'source-count', description: '给真实回执附加来源数量', handle(receipt) { receipt.extensions.sourceCount = receipt.result.sources.length; } }],
});
const receipt = retrieval.run(' Agent ', { app: { canRead: true }, signal: new AbortController().signal });
console.log(receipt.sequence, receipt.extensions);

Related policy source

• Deduplication, reservation, reading, counting, and effect order
• Default query key

Related definitions

• OperationContext
• RetrievalDefinition
• RetrievalResult
• RetrievalRunner
• RetrievalSource