@rizom/brain 0.2.0-alpha.47 → 0.2.0-alpha.49

package/dist/entities.d.ts

@@ -1,154 +1,521 @@
-import type { z } from "zod";
+import { z } from 'zod';
 
-export interface BaseEntity {
-  id: string;
-  entityType: string;
-  content: string;
-  created: string;
-  updated: string;
-  metadata: Record<string, unknown>;
-  contentHash?: string;
-}
-export type EntityInput<T extends BaseEntity = BaseEntity> = Omit<
-  T,
-  "created" | "updated" | "contentHash"
-> &
-  Partial<Pick<T, "created" | "updated" | "contentHash">>;
-export interface EntityMutationResult {
-  entityId: string;
-  jobId: string;
-}
-export interface CreateInput {
-  entityType: string;
-  title?: string;
-  content?: string;
-  prompt?: string;
-  url?: string;
-  [key: string]: unknown;
-}
-export interface CreateExecutionContext {
-  interfaceType?: string;
-  userId?: string;
-  channelId?: string;
-  [key: string]: unknown;
-}
-export interface CreateResult {
-  entityId: string;
-  jobId?: string;
-  entityType: string;
-}
-export type CreateInterceptionResult =
-  | { kind: "continue"; input: CreateInput }
-  | { kind: "handled"; result: CreateResult };
-export type CreateInterceptor = (
-  input: CreateInput,
-  context: CreateExecutionContext,
-) => Promise<CreateInterceptionResult> | CreateInterceptionResult;
-
-export interface EntityAdapter<TEntity extends BaseEntity = BaseEntity> {
-  entityType: string;
-  schema: z.ZodSchema<TEntity>;
-  frontmatterSchema?: z.ZodTypeAny;
-  toMarkdown(entity: TEntity): string;
-  fromMarkdown(markdown: string, id?: string): TEntity;
-}
-export interface EntityTypeConfig {
-  embeddable?: boolean;
-  weight?: number;
-  [key: string]: unknown;
-}
-export class BaseEntityAdapter<
-  TEntity extends BaseEntity = BaseEntity,
-> implements EntityAdapter<TEntity> {
-  readonly entityType: string;
-  readonly schema: z.ZodSchema<TEntity>;
-  readonly frontmatterSchema?: z.ZodTypeAny;
-  constructor(config: {
+/**
+ * Entity type for unstructured notes (the "base" entity type).
+ * Used as a sentinel for the default catch-all markdown file shape —
+ * no typed frontmatter schema required, content is the entire file body.
+ */
+declare const BASE_ENTITY_TYPE = "base";
+/**
+ * Options for entity mutation operations (create, update, upsert)
+ */
+interface EntityJobOptions {
+    priority?: number;
+    maxRetries?: number;
+}
+/**
+ * Options for entity creation (extends EntityJobOptions with deduplication)
+ */
+interface CreateEntityOptions extends EntityJobOptions {
+    deduplicateId?: boolean;
+}
+/**
+ * Result of an entity mutation that triggers an embedding job.
+ * When skipped is true, content was unchanged — no DB write, no event, no embedding job.
+ */
+interface EntityMutationResult {
+    entityId: string;
+    jobId: string;
+    skipped: boolean;
+}
+/**
+ * Input for adapter-validated direct creation from finalized markdown.
+ */
+interface CreateEntityFromMarkdownInput {
+    entityType: string;
+    id: string;
+    markdown: string;
+}
+/**
+ * Data for storing an embedding for an entity
+ */
+interface StoreEmbeddingData {
+    entityId: string;
+    entityType: string;
+    embedding: Float32Array;
+    contentHash: string;
+}
+/**
+ * Base entity schema that all entities must extend
+ */
+declare const baseEntitySchema: z.ZodObject<{
+    id: z.ZodString;
+    entityType: z.ZodString;
+    content: z.ZodString;
+    created: z.ZodString;
+    updated: z.ZodString;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    contentHash: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    entityType: string;
+    content: string;
+    created: string;
+    updated: string;
+    metadata: Record<string, unknown>;
+    contentHash: string;
+}, {
+    id: string;
+    entityType: string;
+    content: string;
+    created: string;
+    updated: string;
+    metadata: Record<string, unknown>;
+    contentHash: string;
+}>;
+/**
+ * Base entity type - generic to support typed metadata
+ * TMetadata defaults to Record<string, unknown> for backward compatibility
+ */
+interface BaseEntity<TMetadata = Record<string, unknown>> {
+    id: string;
+    entityType: string;
+    content: string;
+    created: string;
+    updated: string;
+    metadata: TMetadata;
+    /** SHA256 hash of content for change detection */
+    contentHash: string;
+}
+/**
+ * Entity input type for creation - allows partial entities with optional system fields
+ * contentHash is excluded because it's computed automatically by the entity service
+ */
+type EntityInput<T extends BaseEntity> = Omit<T, "id" | "created" | "updated" | "contentHash"> & {
+    id?: string;
+    created?: string;
+    updated?: string;
+};
+/**
+ * Search result type
+ */
+interface SearchResult<T extends BaseEntity = BaseEntity> {
+    entity: T;
+    score: number;
+    excerpt: string;
+}
+/**
+ * Normalized system_create input shape used by plugin create interceptors.
+ */
+interface CreateInput {
+    entityType: string;
+    prompt?: string;
+    title?: string;
+    content?: string;
+    url?: string;
+    targetEntityType?: string;
+    targetEntityId?: string;
+}
+/**
+ * Minimal caller context forwarded to plugin create interceptors.
+ */
+interface CreateExecutionContext {
+    interfaceType: string;
+    userId: string;
+    channelId?: string;
+    channelName?: string;
+}
+/**
+ * Result returned to system_create when a plugin fully handles creation.
+ */
+type CreateResult = {
+    success: true;
+    data: {
+        entityId?: string;
+        jobId?: string;
+        status: string;
+    };
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Plugin create interceptors can either fully handle creation,
+ * or continue with a rewritten normalized input.
+ */
+type CreateInterceptionResult = {
+    kind: "handled";
+    result: CreateResult;
+} | {
+    kind: "continue";
+    input: CreateInput;
+};
+type CreateInterceptor = (input: CreateInput, executionContext: CreateExecutionContext) => Promise<CreateInterceptionResult>;
+/**
+ * Interface for entity adapter - handles conversion between entities and markdown
+ * following the hybrid storage model
+ *
+ * @template TEntity - The full entity type
+ * @template TMetadata - The metadata type (defaults to Record<string, unknown>)
+ */
+interface EntityAdapter<TEntity extends BaseEntity<TMetadata>, TMetadata = Record<string, unknown>> {
     entityType: string;
     schema: z.ZodSchema<TEntity>;
-    frontmatterSchema?: z.ZodTypeAny;
-  });
-  toMarkdown(entity: TEntity): string;
-  fromMarkdown(markdown: string, id?: string): TEntity;
+    toMarkdown(entity: TEntity): string;
+    fromMarkdown(markdown: string): Partial<TEntity>;
+    extractMetadata(entity: TEntity): TMetadata;
+    parseFrontMatter<TFrontmatter>(markdown: string, schema: z.ZodSchema<TFrontmatter>): TFrontmatter;
+    generateFrontMatter(entity: TEntity): string;
+    /** Optional: Zod schema for frontmatter fields. Used by CMS config generation. */
+    frontmatterSchema?: z.ZodObject<z.ZodRawShape>;
+    /** Optional: Declares this entity type is a singleton (one file, e.g., identity/identity.md). Used by CMS to generate files collection. */
+    isSingleton?: boolean;
+    /** Optional: Whether this entity has a free-form markdown body below frontmatter. Defaults to true. When false, CMS omits the body widget. */
+    hasBody?: boolean;
+    /** Returns a markdown body template with section headings for this entity type. Empty string for free-form entities. */
+    getBodyTemplate(): string;
+    /** Optional: Declares that this entity type supports cover images via coverImageId in frontmatter */
+    supportsCoverImage?: boolean;
+    /** Optional: Extract coverImageId from entity content/frontmatter */
+    getCoverImageId?(entity: TEntity): string | undefined;
+}
+/**
+ * Sort field specification for multi-field sorting
+ */
+interface SortField {
+    /** Field to sort by - "created", "updated", or a metadata field name */
+    field: string;
+    /** Sort direction */
+    direction: "asc" | "desc";
+    /** Sort NULL values before non-NULL values (default: false / SQLite default) */
+    nullsFirst?: boolean;
+}
+/**
+ * List entities options
+ * Generic over metadata type for type-safe filtering
+ */
+interface ListOptions<TMetadata = Record<string, unknown>> {
+    limit?: number;
+    offset?: number;
+    /** Multi-field sorting - supports system fields (created, updated) and metadata fields */
+    sortFields?: SortField[];
+    filter?: {
+        metadata?: Partial<TMetadata>;
+    };
+    /** Filter to only entities with metadata.status = "published" */
+    publishedOnly?: boolean;
+}
+/**
+ * Search options
+ */
+interface SearchOptions {
+    limit?: number;
+    offset?: number;
+    types?: string[];
+    excludeTypes?: string[];
+    sortBy?: "relevance" | "created" | "updated";
+    sortDirection?: "asc" | "desc";
+    /** Score multipliers per entity type - applied after initial search */
+    weight?: Record<string, number>;
+}
+/**
+ * Configuration for entity type registration
+ */
+interface EntityTypeConfig {
+    /** Score multiplier for search results (default: 1.0) */
+    weight?: number;
+    /** Whether to generate embeddings for this entity type (default: true).
+     *  Set to false for entity types with non-textual content (e.g., images). */
+    embeddable?: boolean;
+}
+/**
+ * Core entity service interface for read-only operations
+ * Used by core plugins that need entity access but shouldn't modify entities
+ */
+interface ICoreEntityService {
+    getEntity<T extends BaseEntity>(entityType: string, id: string): Promise<T | null>;
+    /**
+     * Get entity without content resolution (raw)
+     * Used internally to avoid recursion when resolving image references
+     */
+    getEntityRaw<T extends BaseEntity>(entityType: string, id: string): Promise<T | null>;
+    listEntities<T extends BaseEntity>(type: string, options?: ListOptions): Promise<T[]>;
+    search<T extends BaseEntity = BaseEntity>(query: string, options?: SearchOptions): Promise<SearchResult<T>[]>;
+    getEntityTypes(): string[];
+    hasEntityType(type: string): boolean;
+    countEntities(entityType: string, options?: Pick<ListOptions, "publishedOnly" | "filter">): Promise<number>;
+    getEntityCounts(): Promise<Array<{
+        entityType: string;
+        count: number;
+    }>>;
+    /** Get weight map for all registered entity types with non-default weights */
+    getWeightMap(): Record<string, number>;
+}
+/**
+ * Entity service interface for managing brain entities
+ */
+interface EntityService extends ICoreEntityService {
+    createEntity<T extends BaseEntity>(entity: EntityInput<T>, options?: CreateEntityOptions): Promise<EntityMutationResult>;
+    createEntityFromMarkdown(input: CreateEntityFromMarkdownInput, options?: CreateEntityOptions): Promise<EntityMutationResult>;
+    updateEntity<T extends BaseEntity>(entity: T, options?: EntityJobOptions): Promise<EntityMutationResult>;
+    deleteEntity(entityType: string, id: string): Promise<boolean>;
+    upsertEntity<T extends BaseEntity>(entity: T, options?: EntityJobOptions): Promise<EntityMutationResult & {
+        created: boolean;
+    }>;
+    storeEmbedding(data: StoreEmbeddingData): Promise<void>;
+    serializeEntity(entity: BaseEntity): string;
+    deserializeEntity(markdown: string, entityType: string): Partial<BaseEntity>;
+    countEmbeddings(): Promise<number>;
+    searchWithDistances(query: string): Promise<Array<{
+        entityId: string;
+        entityType: string;
+        distance: number;
+    }>>;
+    initialize(): Promise<void>;
+    getAsyncJobStatus(jobId: string): Promise<{
+        status: "pending" | "processing" | "completed" | "failed";
+        error?: string;
+    } | null>;
 }
-export const baseEntitySchema: z.ZodSchema<BaseEntity>;
-export const BASE_ENTITY_TYPE: "base";
 
-export interface SearchResult<TEntity extends BaseEntity = BaseEntity> {
-  entity: TEntity;
-  score: number;
-  excerpt?: string;
+/** Interface for objects that can generate a body template. */
+interface BodyTemplateProvider {
+    generateBodyTemplate(): string;
 }
-export interface ListOptions {
-  limit?: number;
-  offset?: number;
-  publishedOnly?: boolean;
-  [key: string]: unknown;
+interface BaseEntityAdapterConfig<TEntity extends BaseEntity<TMetadata>, TMetadata extends object> {
+    entityType: string;
+    schema: z.ZodSchema<TEntity>;
+    frontmatterSchema: z.ZodObject<z.ZodRawShape>;
+    isSingleton?: boolean;
+    hasBody?: boolean;
+    supportsCoverImage?: boolean;
+    bodyFormatter?: BodyTemplateProvider;
 }
-export interface SearchOptions extends ListOptions {
-  entityType?: string;
+/**
+ * Abstract base class for entity adapters.
+ *
+ * Provides default implementations for the 3 boilerplate methods
+ * (extractMetadata, parseFrontMatter, generateFrontMatter) and
+ * protected helpers for common patterns in toMarkdown/fromMarkdown.
+ *
+ * Subclasses must implement toMarkdown() and fromMarkdown().
+ */
+declare abstract class BaseEntityAdapter<TEntity extends BaseEntity<TMetadata>, TMetadata extends object = Record<string, unknown>, TFrontmatter = TMetadata> implements EntityAdapter<TEntity, TMetadata> {
+    readonly entityType: string;
+    readonly schema: z.ZodSchema<TEntity>;
+    readonly frontmatterSchema: z.ZodObject<z.ZodRawShape>;
+    readonly isSingleton?: boolean;
+    readonly hasBody?: boolean;
+    readonly supportsCoverImage?: boolean;
+    private readonly fmSchema;
+    private readonly bodyFormatter;
+    constructor(config: BaseEntityAdapterConfig<TEntity, TMetadata>);
+    abstract fromMarkdown(markdown: string): Partial<TEntity>;
+    /**
+     * Serialize an entity to markdown.
+     *
+     * Rebuilds frontmatter from entity.metadata overlaid on any existing
+     * frontmatter parsed from entity.content. Body comes from renderBody,
+     * which defaults to the body portion of entity.content (frontmatter
+     * stripped).
+     *
+     * Adapters that want the body to reflect typed fields (e.g. a
+     * structured about/skills section) override renderBody. Adapters that
+     * need entirely custom serialization override toMarkdown.
+     */
+    toMarkdown(entity: TEntity): string;
+    /**
+     * Render the body section of the entity.
+     *
+     * Default returns the body portion of entity.content (frontmatter
+     * stripped). Override when the body should be rebuilt from typed
+     * fields on the entity.
+     */
+    protected renderBody(entity: TEntity): string;
+    private readExistingFrontmatter;
+    extractMetadata(entity: TEntity): TMetadata;
+    parseFrontMatter<T>(markdown: string, schema: z.ZodSchema<T>): T;
+    getBodyTemplate(): string;
+    generateFrontMatter(entity: TEntity): string;
+    /** Strip frontmatter and return the body content. */
+    protected extractBody(markdown: string): string;
+    /** Parse frontmatter using this adapter's frontmatter schema. */
+    protected parseFrontmatter(markdown: string): TFrontmatter;
+    /** Combine body and frontmatter into a markdown string. */
+    protected buildMarkdown(body: string, frontmatter: Record<string, unknown>): string;
 }
 
-export interface DataSourceCapabilities {
-  list?: boolean;
-  get?: boolean;
-  search?: boolean;
-  generate?: boolean;
-  transform?: boolean;
-}
-export interface BaseDataSourceContext {
-  entityService?: unknown;
-  [key: string]: unknown;
-}
-export interface DataSource<TQuery = unknown, TResult = unknown> {
-  id: string;
-  name?: string;
-  capabilities?: DataSourceCapabilities;
-  fetch(query?: TQuery, context?: BaseDataSourceContext): Promise<TResult>;
+/**
+ * Configuration for frontmatter handling
+ */
+interface FrontmatterConfig<T extends BaseEntity> {
+    /**
+     * Fields to explicitly include in frontmatter
+     * If not specified, includes all non-system fields
+     */
+    includeFields?: (keyof T)[];
+    /**
+     * Fields to exclude from frontmatter
+     * By default excludes: id, entityType, content, created, updated
+     */
+    excludeFields?: (keyof T)[];
+    /**
+     * Custom serializers for complex fields
+     */
+    customSerializers?: {
+        [K in keyof T]?: (value: T[K]) => unknown;
+    };
+    /**
+     * Custom deserializers for complex fields
+     */
+    customDeserializers?: {
+        [K in keyof T]?: (value: unknown) => T[K];
+    };
+}
+/**
+ * Generate markdown with frontmatter from content and metadata
+ */
+declare function generateMarkdownWithFrontmatter(content: string, metadata: Record<string, unknown>): string;
+/**
+ * Parse markdown with frontmatter into content and metadata
+ */
+declare function parseMarkdownWithFrontmatter<T>(markdown: string, schema: z.ZodSchema<T>): {
+    content: string;
+    metadata: T;
+};
+/**
+ * Generate frontmatter string from metadata
+ */
+declare function generateFrontmatter(metadata: Record<string, unknown>): string;
+
+/**
+ * Context passed to all DataSource operations
+ * Contains internal state that should not be mixed with user query parameters
+ */
+interface BaseDataSourceContext {
+    /**
+     * Whether to filter to only published/complete content
+     * Set by site-builder: true for production, false for preview
+     */
+    publishedOnly?: boolean;
+    /**
+     * Scoped entity service that auto-applies publishedOnly filter
+     * Datasources should use this instead of their injected entityService
+     * to ensure consistent filtering behavior across environments
+     */
+    entityService: EntityService;
+}
+/**
+ * DataSource Interface
+ *
+ * Provides data for templates through fetch, generate, or transform operations.
+ * DataSources are registered in the DataSourceRegistry and referenced by templates
+ * via their dataSourceId property.
+ */
+interface DataSource {
+    /**
+     * Unique identifier for this data source
+     */
+    id: string;
+    /**
+     * Human-readable name for this data source
+     */
+    name: string;
+    /**
+     * Optional description of what this data source provides
+     */
+    description?: string;
+    /**
+     * Optional: Fetch existing data
+     * Used by data sources that aggregate or retrieve data (e.g., dashboard stats, API data)
+     * DataSources validate output using the provided schema
+     * @param query - Query parameters for fetching data
+     * @param outputSchema - Schema for validating output data
+     * @param context - Context with environment
+     */
+    fetch?: <T>(query: unknown, outputSchema: z.ZodSchema<T>, context: BaseDataSourceContext) => Promise<T>;
+    /**
+     * Optional: Generate new content
+     * Used by data sources that create content (e.g., AI-generated content, reports)
+     */
+    generate?: <T>(request: unknown, schema: z.ZodSchema<T>) => Promise<T>;
+    /**
+     * Optional: Transform content between formats
+     * Used by data sources that convert content (e.g., markdown to HTML, data formatting)
+     */
+    transform?: <T>(content: unknown, format: string, schema: z.ZodSchema<T>) => Promise<T>;
+}
+/**
+ * DataSource capabilities for discovery and validation
+ */
+interface DataSourceCapabilities {
+    canFetch: boolean;
+    canGenerate: boolean;
+    canTransform: boolean;
 }
 
-export interface PaginationInfo {
-  page: number;
-  pageSize: number;
-  totalItems: number;
-  totalPages: number;
-  hasNext: boolean;
-  hasPrevious: boolean;
-}
-export interface PaginateOptions {
-  page?: number;
-  pageSize?: number;
-  limit?: number;
-  offset?: number;
-}
-export interface PaginateResult<T> {
-  items: T[];
-  pagination: PaginationInfo;
-}
-export const paginationInfoSchema: z.ZodSchema<PaginationInfo>;
-export function paginateItems<T>(
-  items: T[],
-  options?: PaginateOptions,
-): PaginateResult<T>;
-export function buildPaginationInfo(
-  totalItems: number,
-  options?: PaginateOptions,
-): PaginationInfo;
+/**
+ * Schema for pagination information
+ * Used by datasources that return paginated lists
+ */
+declare const paginationInfoSchema: z.ZodObject<{
+    currentPage: z.ZodNumber;
+    totalPages: z.ZodNumber;
+    totalItems: z.ZodNumber;
+    pageSize: z.ZodNumber;
+    hasNextPage: z.ZodBoolean;
+    hasPrevPage: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    currentPage: number;
+    totalPages: number;
+    totalItems: number;
+    pageSize: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+}, {
+    currentPage: number;
+    totalPages: number;
+    totalItems: number;
+    pageSize: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+}>;
+/**
+ * Pagination information type
+ */
+type PaginationInfo = z.infer<typeof paginationInfoSchema>;
+/**
+ * Build pagination info from total count and page parameters
+ * Used for database-level pagination where we have a separate count query
+ */
+declare function buildPaginationInfo(totalItems: number, page: number, pageSize: number): PaginationInfo;
+/**
+ * Options for paginating items
+ */
+interface PaginateOptions {
+    page?: number | undefined;
+    limit?: number | undefined;
+    pageSize?: number | undefined;
+}
+/**
+ * Result of paginating items
+ */
+interface PaginateResult<T> {
+    items: T[];
+    pagination: PaginationInfo | null;
+}
+/**
+ * Paginate a list of items
+ *
+ * When `page` is specified, returns paginated results with pagination info.
+ * When only `limit` is specified, returns first N items without pagination info.
+ * When neither is specified, returns all items without pagination info.
+ *
+ * @param items - The full list of items to paginate (should already be sorted)
+ * @param options - Pagination options
+ * @returns Paginated items and optional pagination info
+ */
+declare function paginateItems<T>(items: T[], options: PaginateOptions): PaginateResult<T>;
 
-export interface FrontmatterConfig {
-  includeFields?: string[];
-  excludeFields?: string[];
-}
-export function generateMarkdownWithFrontmatter(
-  content: string,
-  metadata?: Record<string, unknown>,
-  config?: FrontmatterConfig,
-): string;
-export function parseMarkdownWithFrontmatter(markdown: string): {
-  content: string;
-  metadata: Record<string, unknown>;
-};
-export function generateFrontmatter(
-  metadata: Record<string, unknown>,
-  config?: FrontmatterConfig,
-): string;
+export { BASE_ENTITY_TYPE, BaseEntityAdapter, baseEntitySchema, buildPaginationInfo, generateFrontmatter, generateMarkdownWithFrontmatter, paginateItems, paginationInfoSchema, parseMarkdownWithFrontmatter };
+export type { BaseDataSourceContext, BaseEntity, CreateExecutionContext, CreateInput, CreateInterceptionResult, CreateInterceptor, CreateResult, DataSource, DataSourceCapabilities, EntityAdapter, EntityInput, EntityMutationResult, EntityTypeConfig, FrontmatterConfig, ListOptions, PaginateOptions, PaginateResult, PaginationInfo, SearchOptions, SearchResult };