@api-client/core 0.19.7 → 0.19.9

package/data/models/example-generator-api.json

@@ -42810,7 +42810,7 @@
 "@id": "#219"
 },
 {
-"@id": "#210"
+"@id": "#219"
 },
 {
 "@id": "#213"
@@ -42819,7 +42819,7 @@
 "@id": "#216"
 },
 {
-"@id": "#219"
+"@id": "#210"
 }
 ],
 "doc:root": false,
@@ -44232,7 +44232,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '22'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)22 000000'\n",
+"doc:raw": "type: \"GENERAL\"\nvalue: \"www.company.be\"\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -44295,7 +44295,7 @@
 "doc:ExternalDomainElement",
 "doc:DomainElement"
 ],
-"doc:raw": "type: \"GENERAL\"\nvalue: \"www.company.be\"\n",
+"doc:raw": "type: 'GENERAL'\ncountryDialCode : '+32'\nareaCode : '22'\nsubscriberNumber: '12.87.00'\nformatted: '+32-(0)22 000000'\n",
 "core:mediaType": "application/yaml",
 "sourcemaps:sources": [
 {
@@ -45116,7 +45116,7 @@
 {
 "@id": "#212/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#212",
-"sourcemaps:value": "[(1,0)-(6,0)]"
+"sourcemaps:value": "[(1,0)-(3,0)]"
 },
 {
 "@id": "#215/source-map/lexical/element_0",
@@ -45131,7 +45131,7 @@
 {
 "@id": "#221/source-map/lexical/element_0",
 "sourcemaps:element": "amf://id#221",
-"sourcemaps:value": "[(1,0)-(3,0)]"
+"sourcemaps:value": "[(1,0)-(6,0)]"
 },
 {
 "@id": "#338/source-map/synthesized-field/element_1",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-client/core",
   "description": "The API Client's core client library. Works in NodeJS and in a ES enabled browser.",
-  "version": "0.19.7",
+  "version": "0.19.9",
   "license": "Apache-2.0",
   "exports": {
     "./browser.js": {

package/src/modeling/ai/message_parser.ts

@@ -12,6 +12,7 @@ import { DataDomainDelta } from './DataDomainDelta.js'
  *
  * @param msg The generic AI chat message.
  * @returns The parsed in-memory wrapper context message.
+ * @deprecated Use `AiModelMessage.processMessageSafe` instead.
  */
 export function parseAiChatMessage(msg: AiMessageSchema): AiUserMessage | AiModelMessageWithDelta {
   if (msg.role === 'user') {

package/src/modeling/ai/types.ts

@@ -5,7 +5,7 @@ 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'
+import type { AiModelMessageSchema, AiModelMessage, AiUserMessageSchema } from '../../models/AiMessage.js'
 
 /**
  * A copy of the `Type` enum from the `@google/genai` package.
@@ -206,11 +206,11 @@ export interface AiDomainDeltaResponse {
  * received from the AI generation endpoint.
  */
 export type AiStreamEvent =
-  | { event: 'user-message'; data: AiMessageSchema }
-  | { event: 'agent-message'; data: AiMessageSchema }
+  | { event: 'user-message'; data: AiUserMessageSchema }
+  | { event: 'agent-message'; data: AiModelMessageSchema }
   | { event: 'thought-chunk'; data: string }
   | { event: 'text-chunk'; data: string }
-  | { event: 'done'; data: AiMessageSchema }
+  | { event: 'done'; data: AiModelMessageSchema }
   | { event: 'error'; data: Exception }
   | { event: 'session-updated'; data: AiSessionSchema }
 

package/src/models/AiMessage.ts

@@ -3,6 +3,7 @@ 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'
+import { detectReasoning } from '../modeling/ai/message_parser.js'
 
 export type AiMessageRole = 'user' | 'model'
 export type AiMessageState = 'loading' | 'complete' | 'error' | 'terminated'
@@ -210,21 +211,39 @@ export class AiUserMessage extends AiMessageBase<AiUserMessageSchema> implements
   }
 }
 
-export class AiModelMessage extends AiMessageBase<AiModelMessageSchema> implements AiModelMessageSchema {
+/**
+ * Model messages have the `text` that most likely is a structured JSON
+ * with the `delta` and `reasoning` properties. When an `AiModelMessage` is instantiated,
+ * it will try to parse the `text` into the `delta` and `reasoning` properties, leaving the
+ * `text` property unchanged.
+ *
+ * The delta object will be different for different models and different use cases.
+ * It is up to the model to define the delta object. However, the delta object should
+ * be normalized by each child class.
+ *
+ * @template D The type of the delta.
+ */
+export abstract class AiModelMessage<D = unknown>
+  extends AiMessageBase<AiModelMessageSchema>
+  implements AiModelMessageSchema
+{
   state: AiMessageState
   applied?: boolean
   thoughts: string
 
   /**
-   * The delta of the message, if any.
+   * The extracted delta from the message.
    */
-  delta?: AiDomainDelta
+  delta?: D
+
   /**
-   * The reasoning of the delta.
+   * The extracted reasoning from the message.
    * Format in markdown.
    */
   reasoning?: string
 
+  #reasoningEnded = false
+
   static createSchema(input: Partial<AiModelMessageSchema>): AiModelMessageSchema {
     const base = AiMessageBase.createBaseSchema(input)
     return {
@@ -241,6 +260,7 @@ export class AiModelMessage extends AiMessageBase<AiModelMessageSchema> implemen
     this.state = input.state || 'loading'
     this.applied = input.applied
     this.thoughts = input.thoughts || ''
+    this.processMessageSafe()
   }
 
   override toJSON(): AiModelMessageSchema {
@@ -268,6 +288,8 @@ export class AiModelMessage extends AiMessageBase<AiModelMessageSchema> implemen
 
   /**
    * Adds a text chunk to the message. Useful when streaming.
+   *
+   * Note, this function progressively detects the reasoning on each chunk.
    * @param text The text chunk to add.
    */
   addText(text?: string): void {
@@ -275,6 +297,15 @@ export class AiModelMessage extends AiMessageBase<AiModelMessageSchema> implemen
       return
     }
     this.text += text
+    if (this.#reasoningEnded) {
+      return
+    }
+    const before = this.reasoning
+    const after = detectReasoning(this.text)
+    if (after && after === before) {
+      this.#reasoningEnded = true
+    }
+    this.reasoning = after
   }
 
   /**
@@ -283,12 +314,13 @@ export class AiModelMessage extends AiMessageBase<AiModelMessageSchema> implemen
    * It sets the delta and reasoning fields, if found in the message.
    */
   processMessage(): void {
-    if (!this.text) {
+    const { text } = this
+    if (!text) {
       return
     }
-    const parsed = JSON.parse(this.text)
+    const parsed = JSON.parse(text)
     if (parsed.delta) {
-      this.delta = DataDomainDelta.normalize(parsed.delta)
+      this.delta = this.normalizeDelta(parsed.delta)
     }
     if (parsed.reasoning) {
       this.reasoning = parsed.reasoning
@@ -307,29 +339,44 @@ export class AiModelMessage extends AiMessageBase<AiModelMessageSchema> implemen
     }
   }
 
+  /**
+   * Normalizes the delta to the final shape required by the system.
+   *
+   * Probabilistic models can produce deltas that are not always what the author expected.
+   * For example, the DataDomain delta has `modifiedEntities` property that sometimes is
+   * populated multiple times by the same entity. This should be normalized to a single
+   * operation so that the UI can correctly render the changes, without an expensive lookup
+   * operations. The author of the message model should predict these situations and handle
+   * them accordingly.
+   *
+   * @param delta The delta to normalize.
+   * @returns The normalized delta.
+   */
+  abstract normalizeDelta(delta: D): D
+}
+
+/**
+ * A model message that contains a delta of type `AiDomainDelta`.
+ */
+export class AiModelDataDomainMessage extends AiModelMessage<AiDomainDelta> {
   /**
    * 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({
+  static createEmpty(session: string): AiModelDataDomainMessage {
+    return new AiModelDataDomainMessage({
       session,
       state: 'loading',
     })
   }
+
+  override normalizeDelta(delta: AiDomainDelta): AiDomainDelta {
+    return DataDomainDelta.normalize(delta)
+  }
 }
 
 /**
  * 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>)
-  },
-}
+export type AiMessage = AiUserMessage | AiModelMessage | AiModelDataDomainMessage

package/src/sdk/AiSdk.ts

@@ -1,7 +1,7 @@
 import type { ContextListOptions, ContextListResult } from '../events/BaseEvents.js'
 import { Exception } from '../exceptions/exception.js'
 import type { AiStreamEvent } from '../modeling/ai/types.js'
-import type { AiMessage, AiMessageSchema } from '../models/AiMessage.js'
+import type { AiMessageSchema, AiModelMessageSchema, AiUserMessageSchema } from '../models/AiMessage.js'
 import type { AiSessionApp, AiSessionSchema } from '../models/AiSession.js'
 import { AiMessageKind, AiSessionKind } from '../models/kinds.js'
 import { RouteBuilder } from './RouteBuilder.js'
@@ -95,9 +95,10 @@ export class AiSdk extends SdkBase {
 
         switch (eventName) {
           case 'user-message':
+            yield { event: eventName, data: eventData as AiUserMessageSchema }
+            break
           case 'agent-message':
-            // Assume the data is a full AiMessage
-            yield { event: eventName, data: eventData as AiMessage }
+            yield { event: eventName, data: eventData as AiModelMessageSchema }
             break
           case 'thought-chunk':
           case 'text-chunk':
@@ -105,7 +106,7 @@ export class AiSdk extends SdkBase {
             yield { event: eventName, data: eventData as string }
             break
           case 'done':
-            yield { event: eventName, data: eventData as AiMessage }
+            yield { event: eventName, data: eventData as AiModelMessageSchema }
             return
           case 'error':
             yield { event: eventName, data: Exception.fromRawException(eventData, 'Failed to generate results') }

package/tests/unit/models/AiMessage.spec.ts

@@ -1,5 +1,5 @@
 import { test } from '@japa/runner'
-import { AiUserMessage, AiModelMessage, AiMessageFactory } from '../../../src/models/AiMessage.js'
+import { AiUserMessage, AiModelDataDomainMessage } from '../../../src/models/AiMessage.js'
 import { AiMessageKind } from '../../../src/models/kinds.js'
 
 test.group('AiMessage | AiUserMessage', () => {
@@ -72,13 +72,13 @@ test.group('AiMessage | AiUserMessage', () => {
   })
 })
 
-test.group('AiMessage | AiModelMessage', () => {
+test.group('AiMessage | AiModelDataDomainMessage', () => {
   test('createSchema validates required session', ({ assert }) => {
-    assert.throws(() => AiModelMessage.createSchema({}), 'Session is required to create an AiMessage.')
+    assert.throws(() => AiModelDataDomainMessage.createSchema({}), 'Session is required to create an AiMessage.')
   })
 
   test('createSchema builds valid model schema', ({ assert }) => {
-    const schema = AiModelMessage.createSchema({ session: 'session1', text: 'Response' })
+    const schema = AiModelDataDomainMessage.createSchema({ session: 'session1', text: 'Response' })
     assert.isString(schema.key)
     assert.isNotEmpty(schema.key)
     assert.equal(schema.kind, AiMessageKind)
@@ -93,7 +93,7 @@ test.group('AiMessage | AiModelMessage', () => {
   })
 
   test('constructor builds AiModelMessage instance', ({ assert }) => {
-    const msg = new AiModelMessage({
+    const msg = new AiModelDataDomainMessage({
       key: 'msg1',
       session: 'sess1',
       text: 'Model utterance',
@@ -117,7 +117,7 @@ test.group('AiMessage | AiModelMessage', () => {
   })
 
   test('toJSON correctly serializes an AiModelMessage', ({ assert }) => {
-    const msg = new AiModelMessage({
+    const msg = new AiModelDataDomainMessage({
       key: 'msg1',
       session: 'sess1',
       text: 'Message Data',
@@ -148,7 +148,7 @@ test.group('AiMessage | AiModelMessage', () => {
   })
 
   test('addThought safely appends thoughts', ({ assert }) => {
-    const msg = new AiModelMessage({ session: 's1' })
+    const msg = new AiModelDataDomainMessage({ session: 's1' })
     msg.addThought('Hello ')
     msg.addThought('World!')
     msg.addThought()
@@ -156,20 +156,40 @@ test.group('AiMessage | AiModelMessage', () => {
   })
 
   test('addText safely appends text', ({ assert }) => {
-    const msg = new AiModelMessage({ session: 's1' })
+    const msg = new AiModelDataDomainMessage({ session: 's1' })
     msg.addText('Hello ')
     msg.addText('World!')
     msg.addText()
     assert.equal(msg.text, 'Hello World!')
   })
 
+  test('addText progressively detects reasoning and stops when reasoning ends', ({ assert }) => {
+    const msg = new AiModelDataDomainMessage({ session: 's1' })
+
+    msg.addText('{"reason')
+    assert.isUndefined(msg.reasoning)
+
+    msg.addText('ing": "I ')
+    assert.equal(msg.reasoning, 'I ')
+
+    msg.addText('think')
+    assert.equal(msg.reasoning, 'I think')
+
+    msg.addText(' therefore "')
+    assert.equal(msg.reasoning, 'I think therefore ')
+
+    // This triggers after === before, freezing reasoning detection.
+    msg.addText(', "delta": {')
+    assert.equal(msg.reasoning, 'I think therefore ')
+  })
+
   test('processMessage throws on invalid JSON', ({ assert }) => {
-    const msg = new AiModelMessage({ session: 's1', text: 'NOT JSON' })
+    const msg = new AiModelDataDomainMessage({ session: 's1', text: 'NOT JSON' })
     assert.throws(() => msg.processMessage(), SyntaxError)
   })
 
   test('processMessage parses delta and reasoning', ({ assert }) => {
-    const msg = new AiModelMessage({
+    const msg = new AiModelDataDomainMessage({
       session: 's1',
       text: JSON.stringify({
         reasoning: 'I need to make models',
@@ -183,34 +203,16 @@ test.group('AiMessage | AiModelMessage', () => {
   })
 
   test('processMessageSafe swallows errors', ({ assert }) => {
-    const msg = new AiModelMessage({ session: 's1', text: 'NOT JSON' })
+    const msg = new AiModelDataDomainMessage({ session: 's1', text: 'NOT JSON' })
     msg.processMessageSafe() // should not throw
     assert.isUndefined(msg.delta)
     assert.isUndefined(msg.reasoning)
   })
 
   test('createEmpty generates loading stub', ({ assert }) => {
-    const msg = AiModelMessage.createEmpty('sess1')
+    const msg = AiModelDataDomainMessage.createEmpty('sess1')
     assert.equal(msg.session, 'sess1')
     assert.equal(msg.state, 'loading')
     assert.equal(msg.role, 'model')
   })
 })
-
-test.group('AiMessage | AiMessageFactory', () => {
-  test('fromSchema generates AiUserMessage when role=user', ({ assert }) => {
-    const schema = AiUserMessage.createSchema({ session: 'sess', text: 'Hello User' })
-    const msg = AiMessageFactory.fromSchema(schema)
-    assert.instanceOf(msg, AiUserMessage)
-    assert.equal(msg.role, 'user')
-    assert.equal(msg.text, 'Hello User')
-  })
-
-  test('fromSchema generates AiModelMessage when role=model', ({ assert }) => {
-    const schema = AiModelMessage.createSchema({ session: 'sess', text: 'Hello Model' })
-    const msg = AiMessageFactory.fromSchema(schema)
-    assert.instanceOf(msg, AiModelMessage)
-    assert.equal(msg.role, 'model')
-    assert.equal(msg.text, 'Hello Model')
-  })
-})