Connected Knowledge Model And Refs

knowledgeModel(), KnowledgeModel, KnowledgeRef, KnowledgeRefKind, and reference codecs.

import { z } from "zod";
import {
  decodeKnowledgeRef,
  encodeKnowledgeRef,
  isKnowledgeRef,
  isKnowledgeRefKind,
  knowledgeModel,
} from "@use-crux/core/knowledge";
import type {
  KnowledgeContentPart,
  KnowledgeModality,
  KnowledgeModel,
  KnowledgeModelConfig,
  KnowledgeRef,
  KnowledgeRefKind,
} from "@use-crux/core/knowledge";
import type { StoredAsset } from "@use-crux/core/storage";

Overview

knowledgeModel() binds a retrieval model to stable identity before it is used by persisted connected-knowledge configuration. KnowledgeRef is the closed reference union used by relations, assertions, communities, recipe steps, and record-key codecs.

`knowledgeModel(config)`

Creates a frozen named model binding.

function knowledgeModel(config: KnowledgeModelConfig): KnowledgeModel;

Parameters

type KnowledgeModelConfig = RetrievalModel & {
  readonly name: string;
  readonly modalities?: readonly KnowledgeModality[];
  readonly generateObjectFromParts?: <T>(args: {
    readonly system: string;
    readonly parts: readonly KnowledgeContentPart[];
    readonly schema: z.ZodType<T>;
  }) => Promise<{ object: T }>;
} & (
  | { readonly fingerprint: string; readonly version?: string | number }
  | { readonly version: string | number; readonly fingerprint?: string }
);

Option	Type	Default	Constraints
`name`	`string`	Required	Must be non-empty after trimming.
`generateText`	`RetrievalModel["generateText"]`	Required	Forwarded unchanged.
`generateObject`	`RetrievalModel["generateObject"]`	Required	Forwarded unchanged.
`modalities`	`readonly KnowledgeModality[]`	`["text"]`	Supported evidence modalities: `"text"`, `"image"`, `"audio"`, or `"video"`. Non-text declarations require `generateObjectFromParts`.
`generateObjectFromParts`	Function	Optional	Required when `modalities` includes image, audio, or video. Receives text plus hydrated media evidence parts.
`fingerprint`	`string`	Stable hash of `{ name, version }` when omitted	Must be non-empty after trimming.
`version`	`string \| number`	Required when `fingerprint` is omitted	String versions must be non-empty. Number versions are accepted as provided.

Returns

interface KnowledgeModel extends RetrievalModel {
  readonly name: string;
  readonly fingerprint: string;
  readonly modalities?: readonly KnowledgeModality[];
  generateObjectFromParts?<T>(args: {
    readonly system: string;
    readonly parts: readonly KnowledgeContentPart[];
    readonly schema: z.ZodType<T>;
  }): Promise<{ object: T }>;
}

The returned object forwards generateText(args) and generateObject(args) to the configured functions. When media-only evidence is uncovered and the model declares the matching modality, Connected Knowledge calls generateObjectFromParts() instead.

type KnowledgeModality = "text" | "image" | "audio" | "video";

type KnowledgeContentPart =
  | { readonly kind: "text"; readonly text: string }
  | {
      readonly kind: "media";
      readonly mediaType: string;
      readonly bytesRef: StoredAsset;
    };

bytesRef is the hydrated StoredAsset returned by the configured AssetStore.get(source.assetRef). The media part keeps the indexing source fact vocabulary: mediaType from CruxSourceFacts and a store-owned asset reference resolved through storage.assets.

The effective modalities and the presence of generateObjectFromParts participate in the model fingerprint whenever they differ from the default text-only capability.

Failures

Condition	Error
Empty `name`	`Error("Knowledge model name must be non-empty.")`
Missing `version` and `fingerprint`	`Error("Knowledge model requires a version or fingerprint.")`
Empty string `version`	`Error("Knowledge model version must be non-empty.")`
Empty resolved `fingerprint`	`Error("Knowledge model fingerprint must be non-empty.")`
Non-text `modalities` without `generateObjectFromParts`	`Error("Knowledge model declaring image, audio, or video modalities requires generateObjectFromParts.")`

Example

import { knowledgeModel } from "@use-crux/core/knowledge";

const extractor = knowledgeModel({
  name: "extractor",
  version: "2026-07-31",
  generateText,
  generateObject,
});

`KnowledgeRefKind`

type KnowledgeRefKind =
  | "document"
  | "parent"
  | "chunk"
  | "entity";

`KnowledgeRef`

type KnowledgeRef =
  | { readonly kind: "document"; readonly sourceId: string }
  | { readonly kind: "parent"; readonly sourceId: string; readonly parentId: string }
  | { readonly kind: "chunk"; readonly sourceId: string; readonly chunkId: string }
  | { readonly kind: "entity"; readonly entityId: string };

Runtime validation only checks object shape, kind, and string fields. It does not reject empty string ids.

`isKnowledgeRefKind(value)`

function isKnowledgeRefKind(value: unknown): value is KnowledgeRefKind;

Returns true for "document", "parent", "chunk", or "entity".

Example

if (isKnowledgeRefKind(value)) {
  console.log(value);
}

`isKnowledgeRef(value)`

function isKnowledgeRef(value: unknown): value is KnowledgeRef;

Returns true when value is a non-array object with a supported kind and the required string fields for that kind.

Example

const ref = JSON.parse(input);

if (isKnowledgeRef(ref)) {
  console.log(encodeKnowledgeRef(ref));
}

`encodeKnowledgeRef(ref)`

function encodeKnowledgeRef(ref: KnowledgeRef): string;

Encodes refs into canonical record-key segments:

Ref kind	Encoded form
`document`	`document:<sourceId>`
`parent`	`parent:<sourceId>:<parentId>`
`chunk`	`chunk:<sourceId>:<chunkId>`
`entity`	`entity:<entityId>`

Segments escape % as %25 and : as %3A.

Example

const key = encodeKnowledgeRef({
  kind: "chunk",
  sourceId: "guide:v1",
  chunkId: "intro%1",
});

console.log(key);

`decodeKnowledgeRef(value)`

function decodeKnowledgeRef(value: string): KnowledgeRef | null;

Decodes the canonical representation. Returns null when the kind is unknown, the segment count is wrong, or a percent escape is not %25 or %3A.

Example

const ref = decodeKnowledgeRef("chunk:guide%3Av1:intro%251");

if (ref?.kind === "chunk") {
  console.log(ref.sourceId, ref.chunkId);
}

Reference: Connected Knowledge relations
Reference: Connected Knowledge assertions
Reference: Connected Knowledge communities

Connected Knowledge Model And Refs

On this page