@api-client/core 0.19.1 → 0.19.3

package/src/modeling/ai/DomainSerialization.ts

@@ -0,0 +1,199 @@
+import type { DataDomain } from '../DataDomain.js'
+import type { DomainNamespace } from '../DomainNamespace.js'
+import type {
+  AiDataDomainSchema,
+  AiDomainAssociation,
+  AiDomainEntityResponseSchema,
+  AiDomainEntitySchema,
+  AiDomainProperty,
+  AiDomainSemantic,
+} from './types.js'
+import type { DomainAssociation, DomainEntity, DomainProperty } from '../index.js'
+
+function serializeProperty(prop: DomainProperty): AiDomainProperty {
+  const result: AiDomainProperty = {
+    key: prop.key,
+    type: prop.type,
+  }
+  if (prop.info.name) {
+    result.name = prop.info.name
+  }
+  if (prop.info.displayName) {
+    result.displayName = prop.info.displayName
+  }
+  if (prop.info.description) {
+    result.description = prop.info.description
+  }
+  if (Array.isArray(prop.semantics) && prop.semantics.length > 0) {
+    result.semantics = prop.semantics.map((s) => {
+      const res: AiDomainSemantic = { id: s.id }
+      if (s.config) res.config = { ...s.config }
+      return res
+    })
+  }
+  result.constraints = {}
+  if (typeof prop.required === 'boolean') {
+    result.constraints.required = prop.required
+  }
+  if (typeof prop.unique === 'boolean') {
+    result.constraints.unique = prop.unique
+  }
+  if (typeof prop.index === 'boolean') {
+    result.constraints.index = prop.index
+  }
+  if (typeof prop.primary === 'boolean') {
+    result.constraints.primary = prop.primary
+  }
+  if (typeof prop.multiple === 'boolean') {
+    result.constraints.multiple = prop.multiple
+  }
+  if (typeof prop.readOnly === 'boolean') {
+    result.constraints.readOnly = prop.readOnly
+  }
+  if (typeof prop.writeOnly === 'boolean') {
+    result.constraints.writeOnly = prop.writeOnly
+  }
+  if (typeof prop.deprecated === 'boolean') {
+    result.deprecated = prop.deprecated
+  }
+  if (prop.schema) {
+    result.schema = { ...prop.schema }
+  }
+  return result
+}
+
+function serializeAssociation(assoc: DomainAssociation): AiDomainAssociation {
+  const result: AiDomainAssociation = {
+    key: assoc.key,
+    targets: [],
+  }
+  if (assoc.info.name) {
+    result.name = assoc.info.name
+  }
+  if (assoc.info.displayName) {
+    result.displayName = assoc.info.displayName
+  }
+  if (assoc.info.description) {
+    result.description = assoc.info.description
+  }
+  if (Array.isArray(assoc.semantics) && assoc.semantics.length > 0) {
+    result.semantics = assoc.semantics.map((s) => {
+      const res: AiDomainSemantic = { id: s.id }
+      if (s.config) res.config = { ...s.config }
+      return res
+    })
+  }
+  if (typeof assoc.required === 'boolean') {
+    result.required = assoc.required
+  }
+  if (typeof assoc.onDelete === 'string') {
+    result.onDelete = assoc.onDelete
+  }
+  if (assoc.schema) {
+    result.schema = { ...assoc.schema }
+  }
+  return result
+}
+
+/**
+ * Serializes an entity to an AI domain entity response schema.
+ * It is used by the `get_entity_details` tool to send a serialized entity information to the AI.
+ *
+ * @param entity The entity to serialize.
+ * @param modelKey The key of the model the entity belongs to.
+ * @returns The AI domain entity response schema.
+ */
+export function serializeEntity(entity: DomainEntity, modelKey: string): AiDomainEntityResponseSchema {
+  const result: AiDomainEntityResponseSchema = {
+    key: entity.key,
+    modelKey,
+  }
+  if (entity.info.name) {
+    result.name = entity.info.name
+  }
+  if (entity.info.displayName) {
+    result.displayName = entity.info.displayName
+  }
+  if (entity.info.description) {
+    result.description = entity.info.description
+  }
+  if (Array.isArray(entity.tags) && entity.tags.length > 0) {
+    result.tags = [...entity.tags]
+  }
+  if (Array.isArray(entity.semantics) && entity.semantics.length > 0) {
+    result.semantics = entity.semantics.map((s) => {
+      const res: AiDomainSemantic = { id: s.id }
+      if (s.config) res.config = { ...s.config }
+      return res
+    })
+  }
+  result.properties = []
+  for (const prop of entity.listProperties()) {
+    result.properties.push(serializeProperty(prop))
+  }
+  result.associations = []
+  for (const assoc of entity.listAssociations()) {
+    result.associations.push(serializeAssociation(assoc))
+  }
+  return result
+}
+
+/**
+ * Serializes an entity to a minimal AI domain entity schema.
+ *
+ * @param entity The entity to serialize.
+ * @param modelKey The key of the model the entity belongs to.
+ * @returns The AI domain entity schema.
+ */
+function serializeEntityMinimal(entity: DomainEntity, modelKey: string): AiDomainEntitySchema {
+  const result: AiDomainEntitySchema = {
+    key: entity.key,
+    modelKey,
+  }
+  if (entity.info.name) {
+    result.name = entity.info.name
+  }
+  if (entity.info.description) {
+    result.description = entity.info.description
+  }
+  return result
+}
+
+/**
+ * Processes a namespace and serializes its models and entities to the schema sent to the AI endpoint.
+ * @param ns The namespace to process.
+ * @param result The result schema to add the models and entities to.
+ */
+function processNamespace(ns: DomainNamespace | DataDomain, result: AiDataDomainSchema): void {
+  for (const childNs of ns.listNamespaces()) {
+    processNamespace(childNs, result)
+  }
+  for (const model of ns.listModels()) {
+    result.models.push({
+      key: model.key,
+      name: model.info.name || model.info.displayName || model.key,
+      description: model.info.description,
+    })
+    for (const entity of model.listEntities()) {
+      result.entities.push(serializeEntityMinimal(entity, model.key))
+    }
+  }
+}
+
+/**
+ * Serializes a data domain to a minimal AI domain schema.
+ * It is used to serialize the domain to send it to the AI endpoint.
+ * @param domain The data domain to serialize.
+ * @returns The AI domain schema.
+ */
+export function serializeDomainForAi(domain: DataDomain): AiDataDomainSchema {
+  const result: AiDataDomainSchema = {
+    key: domain.key,
+    name: domain.info.name || domain.info.displayName || 'Unnamed Domain',
+    models: [],
+    entities: [],
+  }
+
+  processNamespace(domain, result)
+  return result
+}

package/src/modeling/ai/domain_response_schema.ts

@@ -0,0 +1,301 @@
+import { Type } from './types.js'
+
+const SemanticSchema = {
+  type: Type.OBJECT,
+  properties: {
+    id: { type: Type.STRING },
+    config: { type: Type.OBJECT },
+  },
+  required: ['id'],
+}
+
+const SchemaDefaultValue = {
+  type: Type.OBJECT,
+  properties: {
+    type: {
+      type: Type.STRING,
+      description: 'Enum: literal, function',
+    },
+    value: {
+      type: Type.STRING,
+      description: 'The default value of the property',
+    },
+  },
+  required: ['type'],
+}
+
+const PropertySchemaShape = {
+  type: Type.OBJECT,
+  properties: {
+    minimum: { type: Type.NUMBER },
+    maximum: { type: Type.NUMBER },
+    exclusiveMinimum: { type: Type.BOOLEAN },
+    exclusiveMaximum: { type: Type.BOOLEAN },
+    multipleOf: { type: Type.NUMBER },
+    enum: { type: Type.ARRAY, items: { type: Type.STRING } },
+    examples: { type: Type.ARRAY, items: { type: Type.STRING } },
+    defaultValue: SchemaDefaultValue,
+    pattern: { type: Type.STRING },
+  },
+}
+
+const PropertyConstraintsSchema = {
+  type: Type.OBJECT,
+  properties: {
+    required: { type: Type.BOOLEAN },
+    unique: { type: Type.BOOLEAN },
+    index: { type: Type.BOOLEAN },
+    primary: { type: Type.BOOLEAN },
+    multiple: { type: Type.BOOLEAN },
+    readOnly: { type: Type.BOOLEAN },
+    writeOnly: { type: Type.BOOLEAN },
+  },
+}
+
+/**
+ * Must comply with the `AiDomainProperty` type.
+ */
+const PropertySchema = {
+  type: Type.OBJECT,
+  properties: {
+    key: { type: Type.STRING },
+    name: { type: Type.STRING },
+    displayName: { type: Type.STRING },
+    description: { type: Type.STRING },
+    type: {
+      type: Type.STRING,
+      description: 'Enum: string, number, boolean, date, datetime, time, binary',
+    },
+    constraints: PropertyConstraintsSchema,
+    deprecated: { type: Type.BOOLEAN },
+    schema: PropertySchemaShape,
+    semantics: {
+      type: Type.ARRAY,
+      items: SemanticSchema,
+      description: "List of semantics applied to this property. Note: ONLY use semantics with scope='property'.",
+    },
+    tags: { type: Type.ARRAY, items: { type: Type.STRING } },
+  },
+  required: ['key', 'name', 'type', 'displayName', 'description'],
+}
+
+const AssociationSchemaShape = {
+  type: Type.OBJECT,
+  properties: {
+    linked: { type: Type.BOOLEAN },
+    unionType: { type: Type.STRING, description: 'Enum: allOf, anyOf, oneOf, not' },
+  },
+}
+
+/**
+ * Must comply with the `AiDomainAssociation` type.
+ */
+const AssociationSchema = {
+  type: Type.OBJECT,
+  properties: {
+    key: { type: Type.STRING },
+    name: { type: Type.STRING },
+    displayName: { type: Type.STRING },
+    description: { type: Type.STRING },
+    targets: { type: Type.ARRAY, items: { type: Type.STRING }, description: 'List of target entity keys' },
+    required: { type: Type.BOOLEAN },
+    multiple: {
+      type: Type.BOOLEAN,
+      description: 'Whether the association can have multiple targets (like User has multiple addresses)',
+    },
+    onDelete: { type: Type.STRING, description: 'Enum: restrict, cascade, setNull, doNothing' },
+    semantics: {
+      type: Type.ARRAY,
+      items: SemanticSchema,
+      description: "List of semantics applied to this association. Note: ONLY use semantics with scope='association'.",
+    },
+    schema: AssociationSchemaShape,
+  },
+  required: ['key', 'name', 'targets', 'displayName', 'description'],
+}
+
+/**
+ * Must comply with the `AiDataModel` type.
+ */
+const ModelSchema = {
+  type: Type.OBJECT,
+  properties: {
+    key: { type: Type.STRING },
+    name: { type: Type.STRING },
+    description: { type: Type.STRING },
+  },
+  required: ['key', 'name'],
+}
+
+/**
+ * Must comply with the `AiDomainEntityResponseSchema` type.
+ */
+const EntitySchema = {
+  type: Type.OBJECT,
+  properties: {
+    key: { type: Type.STRING },
+    modelKey: { type: Type.STRING, description: 'The Domain Model this entity belongs to (e.g. "users", "shipping")' },
+    name: { type: Type.STRING },
+    displayName: { type: Type.STRING },
+    description: { type: Type.STRING },
+    tags: { type: Type.ARRAY, items: { type: Type.STRING } },
+    semantics: {
+      type: Type.ARRAY,
+      items: SemanticSchema,
+      description: "List of semantics applied to this entity. Note: ONLY use semantics with scope='entity'.",
+    },
+    properties: { type: Type.ARRAY, items: PropertySchema },
+    associations: { type: Type.ARRAY, items: AssociationSchema },
+  },
+  required: ['key', 'name', 'modelKey', 'displayName', 'description'],
+}
+
+const PropertyDeltaSchema = {
+  type: Type.OBJECT,
+  properties: {
+    key: { type: Type.STRING },
+    name: { type: Type.STRING },
+    displayName: { type: Type.STRING },
+    description: { type: Type.STRING },
+    type: {
+      type: Type.STRING,
+      description: 'Enum: string, number, boolean, date, datetime, time, binary',
+    },
+    constraints: PropertyConstraintsSchema,
+    deprecated: { type: Type.BOOLEAN },
+    schema: PropertySchemaShape,
+    addedSemantics: {
+      type: Type.ARRAY,
+      items: SemanticSchema,
+      description: "Semantics to add. Note: ONLY use semantics with scope='property'.",
+    },
+    modifiedSemantics: { type: Type.ARRAY, items: SemanticSchema },
+    deletedSemanticIds: { type: Type.ARRAY, items: { type: Type.STRING } },
+  },
+  required: ['key'],
+}
+
+const AssociationDeltaSchema = {
+  type: Type.OBJECT,
+  properties: {
+    key: { type: Type.STRING },
+    name: { type: Type.STRING },
+    displayName: { type: Type.STRING },
+    description: { type: Type.STRING },
+    targets: { type: Type.ARRAY, items: { type: Type.STRING } },
+    required: { type: Type.BOOLEAN },
+    multiple: {
+      type: Type.BOOLEAN,
+      description: 'Whether the association can have multiple targets (like User has multiple addresses)',
+    },
+    onDelete: { type: Type.STRING, description: 'Enum: restrict, cascade, setNull, doNothing' },
+    addedSemantics: {
+      type: Type.ARRAY,
+      items: SemanticSchema,
+      description: "Semantics to add. Note: ONLY use semantics with scope='association'.",
+    },
+    modifiedSemantics: { type: Type.ARRAY, items: SemanticSchema },
+    deletedSemanticIds: { type: Type.ARRAY, items: { type: Type.STRING } },
+  },
+  required: ['key'],
+}
+
+/**
+ * Must comply with the `AiDomainDeltaResponse` type.
+ */
+export const DOMAIN_SCHEMA = {
+  type: Type.OBJECT,
+  properties: {
+    sessionTitle: {
+      type: Type.STRING,
+      description: 'A short, 3-to-5 word descriptive title for this data modeling session.',
+    },
+    reasoning: {
+      type: Type.STRING,
+      description: 'Conversational response analyzing the request or explaining changes, in markdown format',
+    },
+    delta: {
+      type: Type.OBJECT,
+      properties: {
+        addedModels: {
+          type: Type.ARRAY,
+          items: ModelSchema,
+          description: 'Brand new models to create',
+        },
+        deletedModelKeys: {
+          type: Type.ARRAY,
+          items: { type: Type.STRING },
+          description:
+            'Keys of completely removed models. This also removes all entities and associations in the model.',
+        },
+        modifiedModels: {
+          type: Type.ARRAY,
+          items: ModelSchema,
+          description: 'Models to modify in the domain',
+        },
+        addedEntities: {
+          type: Type.ARRAY,
+          items: EntitySchema,
+          description: 'Brand new entities to create',
+        },
+        deletedEntityKeys: {
+          type: Type.ARRAY,
+          items: { type: Type.STRING },
+          description: 'Keys of completely removed entities',
+        },
+        modifiedEntities: {
+          type: Type.ARRAY,
+          items: {
+            type: Type.OBJECT,
+            properties: {
+              key: { type: Type.STRING, description: 'The original key of the existing entity being modified' },
+              modelKey: {
+                type: Type.STRING,
+                description: 'Change this to migrate the entity to a different model (boundary)',
+              },
+              name: { type: Type.STRING },
+              displayName: { type: Type.STRING },
+              description: { type: Type.STRING },
+              tags: { type: Type.ARRAY, items: { type: Type.STRING } },
+              addedSemantics: {
+                type: Type.ARRAY,
+                items: SemanticSchema,
+                description: "Semantics to add. Note: ONLY use semantics with scope='entity'.",
+              },
+              modifiedSemantics: { type: Type.ARRAY, items: SemanticSchema },
+              deletedSemanticIds: { type: Type.ARRAY, items: { type: Type.STRING } },
+              addedProperties: { type: Type.ARRAY, items: PropertySchema },
+              modifiedProperties: { type: Type.ARRAY, items: PropertyDeltaSchema },
+              deletedPropertyKeys: { type: Type.ARRAY, items: { type: Type.STRING } },
+              addedAssociations: { type: Type.ARRAY, items: AssociationSchema },
+              modifiedAssociations: { type: Type.ARRAY, items: AssociationDeltaSchema },
+              deletedAssociationKeys: { type: Type.ARRAY, items: { type: Type.STRING } },
+            },
+            required: [
+              'key',
+              // 'addedSemantics',
+              // 'modifiedSemantics',
+              // 'deletedSemanticIds',
+              // 'addedProperties',
+              // 'modifiedProperties',
+              // 'deletedPropertyKeys',
+              // 'addedAssociations',
+              // 'modifiedAssociations',
+              // 'deletedAssociationKeys',
+            ],
+          },
+          description: 'Modifications to existing entities like adding, removing, or changing properties/associations',
+        },
+      },
+      required: [
+        'addedModels',
+        'deletedModelKeys',
+        'modifiedModels',
+        'addedEntities',
+        'deletedEntityKeys',
+        'modifiedEntities',
+      ],
+    },
+  },
+  required: ['reasoning', 'delta'],
+}

package/src/modeling/ai/domain_tools.ts

@@ -0,0 +1,76 @@
+import { Type } from './types.js'
+import { get_semantic_details, list_semantics } from './tools/Semantic.tools.js'
+import { explain_schema, get_entity_details } from './tools/DataDomain.tools.js'
+import { ToolConfig } from './tools/config.js'
+
+/**
+ * All tools available for the AI to use when modeling a domain.
+ */
+export const tools = [
+  {
+    functionDeclarations: [
+      {
+        name: 'list_semantics',
+        description: 'List all available data semantics, their scopes, and whether they have configuration options.',
+        parametersJsonSchema: {
+          type: Type.OBJECT,
+          properties: {},
+          required: [],
+        },
+      },
+      {
+        name: 'get_semantic_details',
+        description:
+          'Get detailed information about a specific data semantic, notably its JSON ' +
+          'configuration schema properties, to determine what additional config you might want to provide.',
+        parametersJsonSchema: {
+          type: Type.OBJECT,
+          properties: {
+            semanticId: {
+              type: Type.STRING,
+              description: 'The exact ID of the semantic (e.g. Semantic#Password, Semantic#Tags)',
+            },
+          },
+          required: ['semanticId'],
+        },
+      },
+      {
+        name: 'get_entity_details',
+        description: 'Get the full details of an entity given its key, including properties, associations, and tags.',
+        parametersJsonSchema: {
+          type: Type.OBJECT,
+          properties: {
+            entityKey: {
+              type: Type.STRING,
+              description: 'The exact key/ID of the entity to fetch details for.',
+            },
+          },
+          required: ['entityKey'],
+        },
+      },
+      {
+        name: 'explain_schema',
+        description: 'Explains the schema of a data type.',
+        parametersJsonSchema: {
+          type: Type.OBJECT,
+          properties: {
+            dataType: {
+              type: Type.STRING,
+              description: 'The data type (e.g. string, number, boolean, date, datetime, time, binary)',
+            },
+          },
+          required: ['dataType'],
+        },
+      },
+    ],
+  },
+]
+
+export type ToolFunction = (config: ToolConfig, args: Record<string, unknown>) => unknown | Promise<unknown>
+
+export const functions: Record<string, ToolFunction> = {
+  list_semantics,
+  get_semantic_details,
+  explain_schema,
+  get_entity_details,
+}

package/src/modeling/ai/message_parser.ts

@@ -0,0 +1,101 @@
+import type { AiModelMessageWithDelta } from './types.js'
+import type { AiMessageSchema, AiUserMessage } from '../../models/AiMessage.js'
+import { DataDomainDelta } from './DataDomainDelta.js'
+
+/**
+ * Parses an incoming `AiMessage` and maps it directly into its runtime
+ * representations `AiUserMessage` or `AiModelMessageWithDelta`.
+ *
+ * If the message is a model message, it attempts to parse the structured JSON
+ * contents in `msg.text` and sets the `delta` field accordingly. The `text` field
+ * is replaced with the reasoning text, or remains original if parsing fails/is omitted.
+ *
+ * @param msg The generic AI chat message.
+ * @returns The parsed in-memory wrapper context message.
+ */
+export function parseAiChatMessage(msg: AiMessageSchema): AiUserMessage | AiModelMessageWithDelta {
+  if (msg.role === 'user') {
+    return msg as AiUserMessage
+  }
+
+  const modelMsg = { ...msg } as AiModelMessageWithDelta
+
+  // Try to parse the delta structure
+  if (modelMsg.state === 'complete' && modelMsg.text) {
+    try {
+      const parsedJSON = JSON.parse(modelMsg.text)
+      modelMsg.delta = parsedJSON.delta ? DataDomainDelta.normalize(parsedJSON.delta) : undefined
+      modelMsg.text = parsedJSON.reasoning || modelMsg.text
+    } catch {
+      // It might legitimately not be valid JSON yet if it crashed mid-stream,
+      // fallback to retaining original shape.
+    }
+  }
+
+  return modelMsg
+}
+
+/**
+ * When a model response is generated it may contain the `reasoning` property. But because
+ * that property might still be generated it might not be a valid JSON. This function checks
+ * if the text contains reasoning and returns it if it does.
+ * @param text The text to check.
+ * @returns The reasoning string if it exists, otherwise undefined.
+ */
+export function detectReasoning(text: string): string | undefined {
+  try {
+    const parsedJSON = JSON.parse(text)
+    return parsedJSON.reasoning
+  } catch {
+    // Continue below
+  }
+
+  const searchStr = '"reasoning"'
+  const keyIndex = text.indexOf(searchStr)
+  if (keyIndex === -1) {
+    return undefined
+  }
+
+  const afterKey = text.substring(keyIndex + searchStr.length)
+  const colonIndex = afterKey.indexOf(':')
+  if (colonIndex === -1) {
+    return undefined
+  }
+
+  const afterColon = afterKey.substring(colonIndex + 1)
+  const quoteIndex = afterColon.indexOf('"')
+  if (quoteIndex === -1) {
+    return undefined
+  }
+
+  const valueStr = afterColon.substring(quoteIndex + 1)
+  let isEscaped = false
+  let endIndex = -1
+
+  for (let i = 0; i < valueStr.length; i++) {
+    const char = valueStr[i]
+    if (char === '\\' && !isEscaped) {
+      isEscaped = true
+    } else if (char === '"' && !isEscaped) {
+      endIndex = i
+      break
+    } else {
+      isEscaped = false
+    }
+  }
+
+  const extracted = endIndex !== -1 ? valueStr.substring(0, endIndex) : valueStr
+
+  try {
+    // Try to safely parse the literal string value.
+    return JSON.parse('"' + extracted + '"')
+  } catch {
+    // string replace fallback
+    return extracted
+      .replace(/\\n/g, '\n')
+      .replace(/\\r/g, '\r')
+      .replace(/\\t/g, '\t')
+      .replace(/\\"/g, '"')
+      .replace(/\\\\/g, '\\')
+  }
+}