Class: Retrievable

Defined in: lib/classes/retrievable.ts:134

An immutable, validated retrieved record (RAG content) held by the agent.

Remarks

Peer of @nhtio/adk!Memory / Message / Thought / ToolCall. Carries an explicit trustTier that LLM batteries branch on to choose the rendering envelope. The retrieval middleware that produced the record is the only party that knows its provenance — batteries MUST NOT auto-classify or infer the tier from source.

Constructors

Constructor

new Retrievable(raw: RawRetrievable): Retrievable;

Defined in: lib/classes/retrievable.ts:188

Parameters

Parameter	Type	Description
raw	RawRetrievable	The raw retrievable input validated against rawRetrievableSchema.

Returns

Retrievable

Throws

@nhtio/adk/exceptions!E_INVALID_INITIAL_RETRIEVABLE_VALUE when raw does not satisfy the schema.

Properties

Property	Modifier	Type	Default value	Description	Defined in
content	readonly	| Tokenizable | SpooledArtifact	undefined	The retrieved content: a @nhtio/adk!Tokenizable (inline text) or a @nhtio/adk!SpooledArtifact (reader-backed, large text living in a consumer store). Use Retrievable.estimateTokens for budgeting and Retrievable.contentString to materialise the body at render time.	lib/classes/retrievable.ts:161
createdAt	readonly	DateTime	undefined	When the source record was created.	lib/classes/retrievable.ts:171
id	readonly	string	undefined	Stable unique identifier for this retrieved record.	lib/classes/retrievable.ts:154
kind	readonly	string | undefined	undefined	Optional semantic label.	lib/classes/retrievable.ts:167
score	readonly	number | undefined	undefined	Optional relevance / similarity score in [0, 1].	lib/classes/retrievable.ts:169
source	readonly	string | undefined	undefined	Optional provenance string.	lib/classes/retrievable.ts:165
trustTier	readonly	RetrievableTrustTier	undefined	Trust tier declared by the retrieval middleware.	lib/classes/retrievable.ts:163
updatedAt	readonly	DateTime	undefined	When the source record was last modified.	lib/classes/retrievable.ts:173
schema	static	ObjectSchema<RawRetrievable>	rawRetrievableSchema	Validator schema that accepts a RawRetrievable object. Remarks Reusable fragment for any schema that needs to validate or nest a retrievable record.	lib/classes/retrievable.ts:141

Methods

contentString()

contentString(): Promise<string>;

Defined in: lib/classes/retrievable.ts:283

Returns the content body as a single string.

Returns

Promise<string>

The full content body as a string.

Remarks

For a @nhtio/adk!Tokenizable this is synchronous in effect (resolved immediately); for a @nhtio/adk!SpooledArtifact it reads the full body from the backing store via @nhtio/adk!SpooledArtifact.asString. Always returns a Promise so callers have one code path; render helpers await it at the point the trust-tier envelope is built.

---

estimateTokens()

estimateTokens(encoding:
  | "gpt2"
  | "r50k_base"
  | "p50k_base"
  | "p50k_edit"
  | "cl100k_base"
  | "o200k_base"
  | "gemini"
  | "llama2"
| "claude"): number | Promise<number>;

Defined in: lib/classes/retrievable.ts:268

Estimates the token count of the content under encoding.

Parameters

Parameter	Type	Description
encoding	| "gpt2" | "r50k_base" | "p50k_base" | "p50k_edit" | "cl100k_base" | "o200k_base" | "gemini" | "llama2" | "claude"	The encoding identifier to use for counting.

Returns

number | Promise<number>

The estimated token count.

Remarks

Delegates to the content's own estimateTokens: synchronous for a @nhtio/adk!Tokenizable (returns number), asynchronous for a @nhtio/adk!SpooledArtifact (returns Promise<number>, reading the bytes from the backing store on demand). Both shapes satisfy the adapter's token-budget path, which already awaits estimates.

Note: the SpooledArtifact branch materialises the full decoded string transiently to count tokens — reader-backing keeps the body off the permanent heap, but does not eliminate the transient allocation at budgeting time.

---

isRetrievable()

static isRetrievable(value: unknown): value is Retrievable;

Defined in: lib/classes/retrievable.ts:149

Returns true if value is a Retrievable instance.

Parameters

Parameter	Type
value	unknown

Returns

value is Retrievable

Remarks

Uses @nhtio/adk!isInstanceOf for cross-realm safety.