--- url: 'https://adk.nht.io/api/@nhtio/adk/common/classes/Retrievable.md' description: 'An immutable, validated retrieved record (RAG content) held by the agent.' --- # Class: Retrievable Defined in: [lib/classes/retrievable.ts:134](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/retrievable.ts#L134) An immutable, validated retrieved record (RAG content) held by the agent. ## Remarks Peer of [@nhtio/adk!Memory](Memory.md) / `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 ```ts new Retrievable(raw: RawRetrievable): Retrievable; ``` Defined in: [lib/classes/retrievable.ts:188](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/retrievable.ts#L188) #### Parameters | Parameter | Type | Description | | --------- | --------------------------------------------------- | ------------------------------------------------------------------- | | `raw` | [`RawRetrievable`](../interfaces/RawRetrievable.md) | The raw retrievable input validated against `rawRetrievableSchema`. | #### Returns `Retrievable` #### Throws [@nhtio/adk/exceptions!E\_INVALID\_INITIAL\_RETRIEVABLE\_VALUE](../../exceptions/variables/E_INVALID_INITIAL_RETRIEVABLE_VALUE.md) when `raw` does not satisfy the schema. ## Properties | Property | Modifier | Type | Default value | Description | Defined in | | ------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | | `content` | `readonly` | | [`Tokenizable`](Tokenizable.md) | [`SpooledArtifact`](../../spooled_artifact/classes/SpooledArtifact.md) | `undefined` | The retrieved content: a [@nhtio/adk!Tokenizable](Tokenizable.md) (inline text) or a [@nhtio/adk!SpooledArtifact](../../spooled_artifact/classes/SpooledArtifact.md) (reader-backed, large text living in a consumer store). Use [Retrievable.estimateTokens](#estimatetokens) for budgeting and [Retrievable.contentString](#contentstring) to materialise the body at render time. | [lib/classes/retrievable.ts:161](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/retrievable.ts#L161) | | `createdAt` | `readonly` | `DateTime` | `undefined` | When the source record was created. | [lib/classes/retrievable.ts:171](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/retrievable.ts#L171) | | `id` | `readonly` | `string` | `undefined` | Stable unique identifier for this retrieved record. | [lib/classes/retrievable.ts:154](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/retrievable.ts#L154) | | `kind` | `readonly` | `string` | `undefined` | `undefined` | Optional semantic label. | [lib/classes/retrievable.ts:167](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/retrievable.ts#L167) | | `score` | `readonly` | `number` | `undefined` | `undefined` | Optional relevance / similarity score in `[0, 1]`. | [lib/classes/retrievable.ts:169](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/retrievable.ts#L169) | | `source` | `readonly` | `string` | `undefined` | `undefined` | Optional provenance string. | [lib/classes/retrievable.ts:165](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/retrievable.ts#L165) | | `trustTier` | `readonly` | [`RetrievableTrustTier`](../type-aliases/RetrievableTrustTier.md) | `undefined` | Trust tier declared by the retrieval middleware. | [lib/classes/retrievable.ts:163](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/retrievable.ts#L163) | | `updatedAt` | `readonly` | `DateTime` | `undefined` | When the source record was last modified. | [lib/classes/retrievable.ts:173](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/retrievable.ts#L173) | | `schema` | `static` | `ObjectSchema`<[`RawRetrievable`](../interfaces/RawRetrievable.md)> | `rawRetrievableSchema` | Validator schema that accepts a [RawRetrievable](../interfaces/RawRetrievable.md) object. **Remarks** Reusable fragment for any schema that needs to validate or nest a retrievable record. | [lib/classes/retrievable.ts:141](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/retrievable.ts#L141) | ## Methods ### contentString() ```ts contentString(): Promise; ``` Defined in: [lib/classes/retrievable.ts:283](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/retrievable.ts#L283) Returns the content body as a single string. #### Returns `Promise`<`string`> The full content body as a string. #### Remarks For a [@nhtio/adk!Tokenizable](Tokenizable.md) this is synchronous in effect (resolved immediately); for a [@nhtio/adk!SpooledArtifact](../../spooled_artifact/classes/SpooledArtifact.md) it reads the full body from the backing store via [@nhtio/adk!SpooledArtifact.asString](../../spooled_artifact/classes/SpooledArtifact.md#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() ```ts estimateTokens(encoding: | "gpt2" | "r50k_base" | "p50k_base" | "p50k_edit" | "cl100k_base" | "o200k_base" | "gemini" | "llama2" | "claude"): number | Promise; ``` Defined in: [lib/classes/retrievable.ts:268](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/retrievable.ts#L268) 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](Tokenizable.md) (returns `number`), asynchronous for a [@nhtio/adk!SpooledArtifact](../../spooled_artifact/classes/SpooledArtifact.md) (returns `Promise`, 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() ```ts static isRetrievable(value: unknown): value is Retrievable; ``` Defined in: [lib/classes/retrievable.ts:149](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/classes/retrievable.ts#L149) Returns `true` if `value` is a Retrievable instance. #### Parameters | Parameter | Type | | --------- | --------- | | `value` | `unknown` | #### Returns `value is Retrievable` #### Remarks Uses [@nhtio/adk!isInstanceOf](../../guards/functions/isInstanceOf.md) for cross-realm safety.