@api-client/core 0.19.1 → 0.19.2

package/src/modeling/ai/types.ts

@@ -0,0 +1,306 @@
+import type { IApiAssociationShape } from '../../amf/definitions/Shapes.js'
+import type { Exception } from '../../exceptions/exception.js'
+import type { AiSessionSchema } from '../../models/AiSession.js'
+import type { DomainPropertyType } from '../DataFormat.js'
+import type { OnDeleteRule } from '../index.js'
+import { SemanticType } from '../Semantics.js'
+import type { AssociationTarget, PropertySchema } from '../types.js'
+import type { AiMessageSchema, AiModelMessage } from '../../models/AiMessage.js'
+
+/**
+ * A copy of the `Type` enum from the `@google/genai` package.
+ * It's here so we don't need to import the nodejs only package.
+ */
+export enum Type {
+  /**
+   * Not specified, should not be used.
+   */
+  TYPE_UNSPECIFIED = 'TYPE_UNSPECIFIED',
+  /**
+   * OpenAPI string type
+   */
+  STRING = 'STRING',
+  /**
+   * OpenAPI number type
+   */
+  NUMBER = 'NUMBER',
+  /**
+   * OpenAPI integer type
+   */
+  INTEGER = 'INTEGER',
+  /**
+   * OpenAPI boolean type
+   */
+  BOOLEAN = 'BOOLEAN',
+  /**
+   * OpenAPI array type
+   */
+  ARRAY = 'ARRAY',
+  /**
+   * OpenAPI object type
+   */
+  OBJECT = 'OBJECT',
+  /**
+   * Null type
+   */
+  NULL = 'NULL',
+}
+
+/**
+ * A lightweight representation of the `DataDomain` used specifically for serializing
+ * the current domain state and sending it as context to the AI endpoint.
+ * It omits complex internal graph structures, including only essential keys, names,
+ * descriptions, and the hierarchical structure of models and entities.
+ */
+export interface AiDataDomainSchema {
+  key: string
+  name: string
+  models: AiDataModelSchema[]
+  entities: AiDomainEntitySchema[]
+}
+
+/**
+ * A stripped-down representation of a `DomainModel` sent to the AI as part of the
+ * domain context. It provides the AI with the existing model hierarchy and descriptions.
+ */
+export interface AiDataModelSchema {
+  key: string
+  name?: string
+  description?: string
+}
+
+/**
+ * Represents a semantic annotation applied to an entity, property, or association
+ * within the AI's understanding or response. It defines the "meaning" of a field
+ * (e.g., "Email", "Password", "Address").
+ */
+export interface AiDomainSemantic {
+  id: SemanticType
+  config?: Record<string, unknown>
+}
+
+/**
+ * Represents a full or partial entity schema as generated by the AI in its response delta.
+ * It defines a new entity or updates to an existing one, including its properties,
+ * associations, semantics, and tags. This is also used by the `get_entity_details` tool
+ * to send detailed serialized entity information back to the AI.
+ */
+export interface AiDomainEntityResponseSchema {
+  key: string
+  modelKey: string
+  name?: string
+  displayName?: string
+  description?: string
+  tags?: string[]
+  semantics?: AiDomainSemantic[]
+  properties?: AiDomainProperty[]
+  associations?: AiDomainAssociation[]
+}
+
+/**
+ * A minimal representation of an entity used purely for context-setting when
+ * sending the current domain structure to the AI. It excludes deeply nested
+ * properties and associations to save token space.
+ */
+export interface AiDomainEntitySchema {
+  key: string
+  modelKey: string
+  name?: string
+  description?: string
+}
+
+/**
+ * Represents a property definition generated by the AI. It maps the complex internal
+ * domain property structure into a simpler, flat structure that the AI generates,
+ * including data types, constraints, schema metadata, and semantics.
+ */
+export interface AiDomainProperty {
+  key?: string
+  name?: string
+  displayName?: string
+  description?: string
+  type: DomainPropertyType
+  constraints?: {
+    required?: boolean
+    unique?: boolean
+    index?: boolean
+    primary?: boolean
+    multiple?: boolean
+    readOnly?: boolean
+    writeOnly?: boolean
+  }
+  deprecated?: boolean
+  schema?: PropertySchema
+  semantics?: AiDomainSemantic[]
+  tags?: string[]
+}
+
+/**
+ * Represents an association definition generated by the AI, linking an entity
+ * to one or more target entities. It includes relationship rules (like onDelete)
+ * and semantic annotations.
+ */
+export interface AiDomainAssociation {
+  key: string
+  name?: string
+  displayName?: string
+  description?: string
+  targets: AssociationTarget[]
+  required?: boolean
+  multiple?: boolean
+  onDelete?: OnDeleteRule
+  semantics?: AiDomainSemantic[]
+  schema?: IApiAssociationShape
+}
+
+/**
+ * The core structure representing a set of modifications (a delta) proposed by the AI.
+ * It contains arrays of models and entities to add, delete, or modify. The application
+ * processes this delta to transition the data domain to the new requested state.
+ */
+export interface AiDomainDelta {
+  /**
+   * Models to add to the domain.
+   */
+  addedModels?: AiDataModelSchema[]
+  /**
+   * Keys of models to delete from the domain.
+   */
+  deletedModelKeys?: string[]
+  /**
+   * Models to modify in the domain.
+   */
+  modifiedModels?: AiDataModelSchema[]
+  /**
+   * Entities to add to the domain.
+   */
+  addedEntities?: AiDomainEntityResponseSchema[]
+  /**
+   * Keys of entities to delete from the domain.
+   */
+  deletedEntityKeys?: string[]
+  /**
+   * Entities to modify in the domain.
+   */
+  modifiedEntities?: AiDomainEntityDelta[]
+}
+
+/**
+ * The expected JSON schema structure returned by the AI endpoint when performing
+ * data domain manipulation. It includes the AI's step-by-step reasoning and the
+ * actionable delta to be applied.
+ */
+export interface AiDomainDeltaResponse {
+  /**
+   * The LLM reasoning.
+   */
+  reasoning: string
+  /**
+   * Domain changes delta
+   */
+  delta?: AiDomainDelta
+}
+
+/**
+ * Union type for progressive SSE stream chunks
+ * received from the AI generation endpoint.
+ */
+export type AiStreamEvent =
+  | { event: 'user-message'; data: AiMessageSchema }
+  | { event: 'agent-message'; data: AiMessageSchema }
+  | { event: 'thought-chunk'; data: string }
+  | { event: 'text-chunk'; data: string }
+  | { event: 'done'; data: AiMessageSchema }
+  | { event: 'error'; data: Exception }
+  | { event: 'session-updated'; data: AiSessionSchema }
+
+/**
+ * Represents a targeted modification to an existing entity generated by the AI.
+ * Instead of providing the full entity state, the AI provides explicit arrays
+ * of properties, associations, and semantics to add, modify, or delete, enabling
+ * precise, non-destructive updates.
+ */
+export interface AiDomainEntityDelta {
+  key: string
+  modelKey?: string // Provide to move the entity to a different model
+  name?: string
+  displayName?: string
+  description?: string
+  tags?: string[]
+  // Entity semantics delta
+  addedSemantics?: AiDomainSemantic[]
+  modifiedSemantics?: AiDomainSemantic[]
+  deletedSemanticIds?: SemanticType[]
+  // Explicit deltas so the LLM doesn't have to list untouched properties
+  addedProperties?: AiDomainProperty[]
+  modifiedProperties?: AiDomainPropertyDelta[]
+  deletedPropertyKeys?: string[]
+  addedAssociations?: AiDomainAssociation[]
+  modifiedAssociations?: AiDomainAssociationDelta[]
+  deletedAssociationKeys?: string[]
+}
+
+/**
+ * Represents a targeted modification to an existing property generated by the AI.
+ * It captures changes to superficial properties (name, description), type changes,
+ * constraint updates, and semantic alterations.
+ */
+export interface AiDomainPropertyDelta {
+  key: string
+  name?: string
+  displayName?: string
+  description?: string
+  type?: DomainPropertyType
+  constraints?: {
+    required?: boolean
+    unique?: boolean
+    index?: boolean
+    primary?: boolean
+    multiple?: boolean
+    readOnly?: boolean
+    writeOnly?: boolean
+  }
+  deprecated?: boolean
+  // Property semantics delta
+  addedSemantics?: AiDomainSemantic[]
+  modifiedSemantics?: AiDomainSemantic[]
+  deletedSemanticIds?: SemanticType[]
+  schema?: PropertySchema
+}
+
+/**
+ * Represents a targeted modification to an existing association generated by the AI.
+ * It captures updates to relationship cardinality, target entities, deletion rules,
+ * and applied semantics.
+ */
+export interface AiDomainAssociationDelta {
+  key: string
+  name?: string
+  displayName?: string
+  description?: string
+  targets?: AssociationTarget[]
+  required?: boolean
+  onDelete?: OnDeleteRule
+  // Association semantics delta
+  addedSemantics?: AiDomainSemantic[]
+  modifiedSemantics?: AiDomainSemantic[]
+  deletedSemanticIds?: SemanticType[]
+}
+
+/**
+ * An enriched, in-memory representation of a model's message that includes the globally
+ * parsed `AiDomainDelta` object.
+ * This is not stored directly in the datastore as-is; instead, the raw JSON text is stored,
+ * and this structure is assembled at runtime when the chat history is loaded into the UI.
+ */
+export interface AiModelMessageWithDelta extends AiModelMessage {
+  /**
+   * The delta of the message, if any.
+   */
+  delta?: AiDomainDelta
+  /**
+   * The reasoning of the delta.
+   * Format in markdown.
+   */
+  reasoning?: string
+}

package/src/models/AiMessage.ts

@@ -0,0 +1,335 @@
+import type { IDeletion } from './store/Deletion.js'
+import { AiMessageKind } from './kinds.js'
+import { nanoid } from '../nanoid.js'
+import type { AiDomainDelta } from '../modeling/ai/types.js'
+import { DataDomainDelta } from '../modeling/ai/DataDomainDelta.js'
+
+export type AiMessageRole = 'user' | 'model'
+export type AiMessageState = 'loading' | 'complete' | 'error' | 'terminated'
+
+/**
+ * The base interface representing a single message in the domain manipulation chat history.
+ * It tracks metadata like timestamps, the associated session, and the raw text content.
+ * See `AiUserMessage` and `AiModelMessage` for specific role implementations.
+ */
+export interface AiMessageSchemaBase {
+  readonly kind: typeof AiMessageKind
+  /**
+   * The datastore key of the message.
+   */
+  key: string
+  /**
+   * The role of the message.
+   */
+  role: AiMessageRole
+  /**
+   * The timestamp of when the message was created.
+   */
+  createdAt: number
+  /**
+   * The timestamp of when the message was last updated.
+   */
+  updatedAt: number
+  /**
+   * The datastore key of the session.
+   */
+  session: string
+  /**
+   * The text of the message.
+   */
+  text: string
+  /**
+   * Whether the message is deleted.
+   */
+  deleted?: boolean
+  /**
+   * The information about the delete information.
+   * Always set when the `deleted` is true.
+   */
+  deletedInfo?: IDeletion
+}
+
+/**
+ * The schema for a user message.
+ */
+export interface AiUserMessageSchema extends AiMessageSchemaBase {
+  /**
+   * The role of the message.
+   */
+  role: 'user'
+  /**
+   * The state of the user message.
+   * Can only be `complete`.
+   */
+  state: 'complete'
+  /**
+   * The user utterance.
+   * Note, the actual message sent to the LLM may be different from the utterance
+   * as it has additional instructions and the domain context. However, we are not storing
+   * the full message in the datastore, only the utterance.
+   */
+  text: string
+}
+
+/**
+ * The schema for a model message.
+ */
+export interface AiModelMessageSchema extends AiMessageSchemaBase {
+  /**
+   * The role of the message.
+   */
+  role: 'model'
+  /**
+   * The full text of the message returned by the LLM.
+   * It is most likely a structured message that needs to be parsed
+   * to the corresponding message object.
+   */
+  text: string
+  /**
+   * The state of the message.
+   * - loading: the message is being generated
+   * - complete: the message is complete
+   * - error: the message generation failed
+   * - terminated: the message generation was terminated by the user
+   */
+  state: AiMessageState
+  /**
+   * Whether the message has been applied.
+   */
+  applied?: boolean
+  /**
+   * The thoughts of the message.
+   */
+  thoughts?: string
+}
+
+/**
+ * A union type representing any valid chat message in the AI session history.
+ */
+export type AiMessageSchema = AiUserMessageSchema | AiModelMessageSchema
+
+/**
+ * The base class for all AI messages.
+ * It provides common functionality for all message types.
+ */
+export abstract class AiMessageBase<
+  T extends AiMessageSchemaBase = AiMessageSchemaBase,
+> implements AiMessageSchemaBase {
+  /**
+   * The kind of the schema.
+   */
+  static get Kind(): typeof AiMessageKind {
+    return AiMessageKind
+  }
+
+  /**
+   * The kind of the schema.
+   */
+  get kind(): typeof AiMessageKind {
+    return AiMessageKind
+  }
+
+  key: string
+  role: T['role']
+  createdAt: number
+  updatedAt: number
+  session: string
+  text: string
+  deleted: boolean
+  deletedInfo?: IDeletion
+
+  protected static createBaseSchema(input: Partial<AiMessageSchemaBase>): Omit<AiMessageSchemaBase, 'role'> {
+    const { key = nanoid(), session, text = '', createdAt = 0, updatedAt = 0 } = input
+    if (!session) {
+      throw new Error('Session is required to create an AiMessage.')
+    }
+    return {
+      key,
+      kind: AiMessageKind,
+      session,
+      text,
+      createdAt,
+      updatedAt,
+    }
+  }
+
+  constructor(input: Partial<T> = {}, role: T['role']) {
+    const base = AiMessageBase.createBaseSchema(input)
+    this.key = base.key
+    this.role = role
+    this.session = base.session
+    this.text = base.text
+    this.createdAt = base.createdAt
+    this.updatedAt = base.updatedAt
+    this.deleted = input.deleted || false
+    this.deletedInfo = input.deletedInfo
+  }
+
+  toJSON(): T {
+    const result = {
+      kind: this.kind,
+      key: this.key,
+      role: this.role,
+      session: this.session,
+      text: this.text,
+      createdAt: this.createdAt,
+      updatedAt: this.updatedAt,
+    }
+    if (this.deleted && this.deletedInfo) {
+      Object.assign(result, {
+        deleted: this.deleted,
+        deletedInfo: { ...this.deletedInfo },
+      })
+    }
+    return result as unknown as T
+  }
+}
+
+export class AiUserMessage extends AiMessageBase<AiUserMessageSchema> implements AiUserMessageSchema {
+  state: 'complete'
+
+  static createSchema(input: Partial<AiUserMessageSchema>): AiUserMessageSchema {
+    const base = AiMessageBase.createBaseSchema(input)
+    return {
+      ...base,
+      role: 'user',
+      state: 'complete',
+    }
+  }
+
+  constructor(input: Partial<AiUserMessageSchema> = {}) {
+    super(input, 'user')
+    this.state = 'complete'
+  }
+
+  override toJSON(): AiUserMessageSchema {
+    return {
+      ...super.toJSON(),
+      state: this.state,
+    }
+  }
+}
+
+export class AiModelMessage extends AiMessageBase<AiModelMessageSchema> implements AiModelMessageSchema {
+  state: AiMessageState
+  applied?: boolean
+  thoughts: string
+
+  /**
+   * The delta of the message, if any.
+   */
+  delta?: AiDomainDelta
+  /**
+   * The reasoning of the delta.
+   * Format in markdown.
+   */
+  reasoning?: string
+
+  static createSchema(input: Partial<AiModelMessageSchema>): AiModelMessageSchema {
+    const base = AiMessageBase.createBaseSchema(input)
+    return {
+      ...base,
+      role: 'model',
+      state: input.state || 'loading',
+      applied: input.applied,
+      thoughts: input.thoughts || '',
+    }
+  }
+
+  constructor(input: Partial<AiModelMessageSchema> = {}) {
+    super(input, 'model')
+    this.state = input.state || 'loading'
+    this.applied = input.applied
+    this.thoughts = input.thoughts || ''
+  }
+
+  override toJSON(): AiModelMessageSchema {
+    const result: AiModelMessageSchema = {
+      ...super.toJSON(),
+      state: this.state,
+      thoughts: this.thoughts,
+    }
+    if (this.applied !== undefined) {
+      result.applied = this.applied
+    }
+    return result
+  }
+
+  /**
+   * Adds a thought to the message. Useful when streaming.
+   * @param thought The thought to add.
+   */
+  addThought(thought?: string): void {
+    if (!thought) {
+      return
+    }
+    this.thoughts += thought
+  }
+
+  /**
+   * Adds a text chunk to the message. Useful when streaming.
+   * @param text The text chunk to add.
+   */
+  addText(text?: string): void {
+    if (!text) {
+      return
+    }
+    this.text += text
+  }
+
+  /**
+   * Processes the message.
+   * If the message is not valid JSON, it will throw an error.
+   * It sets the delta and reasoning fields, if found in the message.
+   */
+  processMessage(): void {
+    if (!this.text) {
+      return
+    }
+    const parsed = JSON.parse(this.text)
+    if (parsed.delta) {
+      this.delta = DataDomainDelta.normalize(parsed.delta)
+    }
+    if (parsed.reasoning) {
+      this.reasoning = parsed.reasoning
+    }
+  }
+
+  /**
+   * Processes the message safely.
+   * If the message is not valid JSON, it will be ignored.
+   */
+  processMessageSafe(): void {
+    try {
+      this.processMessage()
+    } catch {
+      // do nothing
+    }
+  }
+
+  /**
+   * Creates an empty model message. Useful when initializing LLM flow.
+   * @param session The session key.
+   * @returns An empty model message.
+   */
+  static createEmpty(session: string): AiModelMessage {
+    return new AiModelMessage({
+      session,
+      state: 'loading',
+    })
+  }
+}
+
+/**
+ * A union type representing any valid chat message in the AI session history.
+ */
+export type AiMessage = AiUserMessage | AiModelMessage
+
+export const AiMessageFactory = {
+  fromSchema(schema: Partial<AiMessageSchema>): AiMessage {
+    if (schema.role === 'model') {
+      return new AiModelMessage(schema as Partial<AiModelMessageSchema>)
+    }
+    return new AiUserMessage(schema as Partial<AiUserMessageSchema>)
+  },
+}