Class: Retrievable

Defined in: src/lib/classes/retrievable.ts:136

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: src/lib/classes/retrievable.ts:190

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.	src/lib/classes/retrievable.ts:163
createdAt	readonly	DateTime	undefined	When the source record was created.	src/lib/classes/retrievable.ts:173
id	readonly	string	undefined	Stable unique identifier for this retrieved record.	src/lib/classes/retrievable.ts:156
kind	readonly	string | undefined	undefined	Optional semantic label.	src/lib/classes/retrievable.ts:169
score	readonly	number | undefined	undefined	Optional relevance / similarity score in [0, 1].	src/lib/classes/retrievable.ts:171
source	readonly	string | undefined	undefined	Optional provenance string.	src/lib/classes/retrievable.ts:167
trustTier	readonly	RetrievableTrustTier	undefined	Trust tier declared by the retrieval middleware.	src/lib/classes/retrievable.ts:165
updatedAt	readonly	DateTime	undefined	When the source record was last modified.	src/lib/classes/retrievable.ts:175
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.	src/lib/classes/retrievable.ts:143

Methods

[ENCODE_METHOD]()

ENCODE_METHOD: unknown;

Defined in: src/lib/classes/retrievable.ts:302

Serialise this Retrievable into an @nhtio/encoder snapshot.

Returns

unknown

A RawRetrievable-shaped snapshot.

Remarks

Emits a RawRetrievable-shaped object; content is the live @nhtio/adk!Tokenizable or @nhtio/adk!SpooledArtifact (the encoder recurses — a reader-backed artifact round-trips as a handle, throwing @nhtio/adk!E_READER_NOT_DESCRIBABLE if its reader cannot describe itself). Round-trips via Retrievable.[DECODE_METHOD], which re-validates through the constructor.

---

contentString()

contentString(): Promise<string>;

Defined in: src/lib/classes/retrievable.ts:285

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"
  | "gemma"
  | "llama2"
| "claude"): number | Promise<number>;

Defined in: src/lib/classes/retrievable.ts:270

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" | "gemma" | "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.

---

[DECODE_METHOD]()

static DECODE_METHOD: Retrievable;

Defined in: src/lib/classes/retrievable.ts:321

Reconstruct a Retrievable from a Retrievable.[ENCODE_METHOD] snapshot.

Parameters

Parameter	Type	Description
data	unknown	The snapshot produced by Retrievable.[ENCODE_METHOD].

Returns

Retrievable

A fully-validated Retrievable.

---

isRetrievable()

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

Defined in: src/lib/classes/retrievable.ts:151

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.