@objectstack/service-ai 4.0.0

package/src/ai-service.ts

@@ -0,0 +1,205 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type {
+  AIMessage,
+  AIRequestOptions,
+  AIResult,
+  AIStreamEvent,
+  IAIService,
+  IAIConversationService,
+  ChatWithToolsOptions,
+  LLMAdapter,
+} from '@objectstack/spec/contracts';
+import type { Logger } from '@objectstack/spec/contracts';
+import { createLogger } from '@objectstack/core';
+import { MemoryLLMAdapter } from './adapters/memory-adapter.js';
+import { ToolRegistry } from './tools/tool-registry.js';
+import { InMemoryConversationService } from './conversation/in-memory-conversation-service.js';
+
+/**
+ * Configuration for AIService.
+ */
+export interface AIServiceConfig {
+  /** LLM adapter to delegate calls to (defaults to MemoryLLMAdapter). */
+  adapter?: LLMAdapter;
+  /** Logger instance. */
+  logger?: Logger;
+  /** Pre-registered tools. */
+  toolRegistry?: ToolRegistry;
+  /** Conversation service (defaults to InMemoryConversationService). */
+  conversationService?: IAIConversationService;
+}
+
+/**
+ * AIService — Unified AI capability service.
+ *
+ * Implements {@link IAIService} by delegating to a pluggable {@link LLMAdapter}
+ * and managing tools and conversations through dedicated sub-components:
+ *
+ * | Component | Responsibility |
+ * |:---|:---|
+ * | {@link LLMAdapter} | LLM provider abstraction (chat, complete, stream, embed) |
+ * | {@link ToolRegistry} | Tool definition storage & execution |
+ * | {@link IAIConversationService} | Conversation CRUD & message persistence |
+ *
+ * The service is registered as `'ai'` in the kernel service registry by
+ * the {@link AIServicePlugin}.
+ */
+export class AIService implements IAIService {
+  private readonly adapter: LLMAdapter;
+  private readonly logger: Logger;
+  readonly toolRegistry: ToolRegistry;
+  readonly conversationService: IAIConversationService;
+
+  constructor(config: AIServiceConfig = {}) {
+    this.adapter = config.adapter ?? new MemoryLLMAdapter();
+    this.logger = config.logger ?? createLogger({ level: 'info', format: 'pretty' });
+    this.toolRegistry = config.toolRegistry ?? new ToolRegistry();
+    this.conversationService = config.conversationService ?? new InMemoryConversationService();
+
+    this.logger.info(
+      `[AI] Service initialized with adapter="${this.adapter.name}", ` +
+      `tools=${this.toolRegistry.size}`,
+    );
+  }
+
+  /** The name of the active LLM adapter. */
+  get adapterName(): string {
+    return this.adapter.name;
+  }
+
+  // ── IAIService implementation ──────────────────────────────────
+
+  async chat(messages: AIMessage[], options?: AIRequestOptions): Promise<AIResult> {
+    this.logger.debug('[AI] chat', { messageCount: messages.length, model: options?.model });
+    return this.adapter.chat(messages, options);
+  }
+
+  async complete(prompt: string, options?: AIRequestOptions): Promise<AIResult> {
+    this.logger.debug('[AI] complete', { promptLength: prompt.length, model: options?.model });
+    return this.adapter.complete(prompt, options);
+  }
+
+  async *streamChat(
+    messages: AIMessage[],
+    options?: AIRequestOptions,
+  ): AsyncIterable<AIStreamEvent> {
+    this.logger.debug('[AI] streamChat', { messageCount: messages.length, model: options?.model });
+
+    if (!this.adapter.streamChat) {
+      // Fallback: emit the entire response as a single text-delta + finish
+      const result = await this.adapter.chat(messages, options);
+      yield { type: 'text-delta', textDelta: result.content };
+      yield { type: 'finish', result };
+      return;
+    }
+
+    yield* this.adapter.streamChat(messages, options);
+  }
+
+  async embed(input: string | string[], model?: string): Promise<number[][]> {
+    if (!this.adapter.embed) {
+      throw new Error(`[AI] Adapter "${this.adapter.name}" does not support embeddings`);
+    }
+    return this.adapter.embed(input, model);
+  }
+
+  async listModels(): Promise<string[]> {
+    if (!this.adapter.listModels) {
+      return [];
+    }
+    return this.adapter.listModels();
+  }
+
+  // ── Tool Call Loop ────────────────────────────────────────────
+
+  /** Default maximum iterations for the tool call loop. */
+  static readonly DEFAULT_MAX_ITERATIONS = 10;
+
+  /**
+   * Chat with automatic tool call resolution.
+   *
+   * 1. Merges registered tool definitions into `options.tools`.
+   * 2. Calls the LLM adapter.
+   * 3. If the response contains `toolCalls`, executes them via the
+   *    {@link ToolRegistry}, appends tool results as `role: 'tool'`
+   *    messages, and loops back to step 2.
+   * 4. Repeats until the model produces a final text response or the
+   *    maximum number of iterations (`maxIterations`) is reached.
+   */
+  async chatWithTools(
+    messages: AIMessage[],
+    options?: ChatWithToolsOptions,
+  ): Promise<AIResult> {
+    // Destructure maxIterations out so it is never forwarded to the adapter
+    const { maxIterations: maxIter, ...restOptions } = options ?? {};
+    const maxIterations = maxIter ?? AIService.DEFAULT_MAX_ITERATIONS;
+    const registeredTools = this.toolRegistry.getAll();
+
+    // Merge registered tools with any explicitly provided tools
+    const mergedTools = [
+      ...registeredTools,
+      ...(restOptions.tools ?? []),
+    ];
+
+    // Build the options that will be sent to every LLM call in the loop
+    const chatOptions: AIRequestOptions = {
+      ...restOptions,
+      tools: mergedTools.length > 0 ? mergedTools : undefined,
+      toolChoice: mergedTools.length > 0 ? (restOptions.toolChoice ?? 'auto') : undefined,
+    };
+
+    // Working copy of the conversation
+    const conversation = [...messages];
+
+    this.logger.debug('[AI] chatWithTools start', {
+      messageCount: conversation.length,
+      toolCount: mergedTools.length,
+      maxIterations,
+    });
+
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+      const result = await this.adapter.chat(conversation, chatOptions);
+
+      // If the model did not request any tool calls we're done
+      if (!result.toolCalls || result.toolCalls.length === 0) {
+        this.logger.debug('[AI] chatWithTools finished', { iteration, content: result.content.slice(0, 80) });
+        return result;
+      }
+
+      this.logger.debug('[AI] chatWithTools tool calls', {
+        iteration,
+        calls: result.toolCalls.map(tc => tc.name),
+      });
+
+      // Append the assistant's response (with tool call metadata) to the conversation
+      conversation.push({
+        role: 'assistant',
+        content: result.content ?? '',
+        toolCalls: result.toolCalls,
+      });
+
+      // Execute all tool calls in parallel
+      const toolResults = await this.toolRegistry.executeAll(result.toolCalls);
+
+      // Append each tool result as a `role: 'tool'` message
+      for (const tr of toolResults) {
+        conversation.push({
+          role: 'tool',
+          content: tr.content,
+          toolCallId: tr.toolCallId,
+        });
+      }
+    }
+
+    // If we exhausted the loop without a final response, make one last
+    // call *without* tools so the model is forced to produce text.
+    this.logger.warn('[AI] chatWithTools max iterations reached, forcing final response');
+    const finalResult = await this.adapter.chat(conversation, {
+      ...chatOptions,
+      tools: undefined,
+      toolChoice: undefined,
+    });
+    return finalResult;
+  }
+}

package/src/conversation/in-memory-conversation-service.ts

@@ -0,0 +1,103 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type {
+  AIConversation,
+  AIMessage,
+  IAIConversationService,
+} from '@objectstack/spec/contracts';
+
+/**
+ * InMemoryConversationService — Reference implementation of IAIConversationService.
+ *
+ * Stores conversations in a simple Map.  Suitable for development, testing,
+ * and single-process deployments.  Production environments should replace
+ * this with a persistent implementation (e.g., backed by ObjectQL/SQL).
+ */
+export class InMemoryConversationService implements IAIConversationService {
+  private readonly store = new Map<string, AIConversation>();
+  private counter = 0;
+
+  async create(options: {
+    title?: string;
+    agentId?: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+  } = {}): Promise<AIConversation> {
+    const now = new Date().toISOString();
+    const id = `conv_${++this.counter}`;
+
+    const conversation: AIConversation = {
+      id,
+      title: options.title,
+      agentId: options.agentId,
+      userId: options.userId,
+      messages: [],
+      createdAt: now,
+      updatedAt: now,
+      metadata: options.metadata,
+    };
+
+    this.store.set(id, conversation);
+    return conversation;
+  }
+
+  async get(conversationId: string): Promise<AIConversation | null> {
+    return this.store.get(conversationId) ?? null;
+  }
+
+  async list(options: {
+    userId?: string;
+    agentId?: string;
+    limit?: number;
+    cursor?: string;
+  } = {}): Promise<AIConversation[]> {
+    let results = Array.from(this.store.values());
+
+    if (options.userId) {
+      results = results.filter(c => c.userId === options.userId);
+    }
+    if (options.agentId) {
+      results = results.filter(c => c.agentId === options.agentId);
+    }
+
+    // Simple cursor-based pagination: cursor = conversation ID
+    if (options.cursor) {
+      const idx = results.findIndex(c => c.id === options.cursor);
+      if (idx >= 0) {
+        results = results.slice(idx + 1);
+      }
+    }
+
+    if (options.limit && options.limit > 0) {
+      results = results.slice(0, options.limit);
+    }
+
+    return results;
+  }
+
+  async addMessage(conversationId: string, message: AIMessage): Promise<AIConversation> {
+    const conversation = this.store.get(conversationId);
+    if (!conversation) {
+      throw new Error(`Conversation "${conversationId}" not found`);
+    }
+
+    conversation.messages.push(message);
+    conversation.updatedAt = new Date().toISOString();
+    return conversation;
+  }
+
+  async delete(conversationId: string): Promise<void> {
+    this.store.delete(conversationId);
+  }
+
+  /** Total number of stored conversations. */
+  get size(): number {
+    return this.store.size;
+  }
+
+  /** Clear all conversations. */
+  clear(): void {
+    this.store.clear();
+    this.counter = 0;
+  }
+}

package/src/conversation/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+export { InMemoryConversationService } from './in-memory-conversation-service.js';
+export { ObjectQLConversationService } from './objectql-conversation-service.js';

package/src/conversation/objectql-conversation-service.ts

@@ -0,0 +1,252 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { randomUUID } from 'node:crypto';
+import type {
+  AIConversation,
+  AIMessage,
+  IAIConversationService,
+  IDataEngine,
+} from '@objectstack/spec/contracts';
+
+/** Object names used for persistence. */
+const CONVERSATIONS_OBJECT = 'ai_conversations';
+const MESSAGES_OBJECT = 'ai_messages';
+
+/** Database row shape for ai_conversations. */
+interface DbConversationRow {
+  id: string;
+  title: string | null;
+  agent_id: string | null;
+  user_id: string | null;
+  metadata: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+/** Database row shape for ai_messages. */
+interface DbMessageRow {
+  id: string;
+  conversation_id: string;
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string;
+  tool_calls: string | null;
+  tool_call_id: string | null;
+  created_at: string;
+}
+
+/** Deterministic ordering for conversations (total order). */
+const CONVERSATION_ORDER = [
+  { field: 'created_at', order: 'asc' as const },
+  { field: 'id', order: 'asc' as const },
+];
+
+/** Deterministic ordering for messages within a conversation. */
+const MESSAGE_ORDER = [
+  { field: 'created_at', order: 'asc' as const },
+  { field: 'id', order: 'asc' as const },
+];
+
+/**
+ * ObjectQLConversationService — Persistent implementation of IAIConversationService.
+ *
+ * Delegates all storage to an {@link IDataEngine} instance, using the
+ * `ai_conversations` and `ai_messages` objects. This decouples the service
+ * from any specific database driver (Turso, Postgres, SQLite, etc.).
+ *
+ * Production environments should use this implementation to ensure
+ * conversation history survives service restarts.
+ */
+export class ObjectQLConversationService implements IAIConversationService {
+  private readonly engine: IDataEngine;
+
+  constructor(engine: IDataEngine) {
+    this.engine = engine;
+  }
+
+  async create(options: {
+    title?: string;
+    agentId?: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+  } = {}): Promise<AIConversation> {
+    const now = new Date().toISOString();
+    const id = `conv_${randomUUID()}`;
+
+    const record = {
+      id,
+      title: options.title ?? null,
+      agent_id: options.agentId ?? null,
+      user_id: options.userId ?? null,
+      metadata: options.metadata ? JSON.stringify(options.metadata) : null,
+      created_at: now,
+      updated_at: now,
+    };
+
+    await this.engine.insert(CONVERSATIONS_OBJECT, record);
+
+    return {
+      id,
+      title: options.title,
+      agentId: options.agentId,
+      userId: options.userId,
+      messages: [],
+      createdAt: now,
+      updatedAt: now,
+      metadata: options.metadata,
+    };
+  }
+
+  async get(conversationId: string): Promise<AIConversation | null> {
+    const row: DbConversationRow | null = await this.engine.findOne(CONVERSATIONS_OBJECT, {
+      where: { id: conversationId },
+    });
+
+    if (!row) return null;
+
+    const messages: DbMessageRow[] = await this.engine.find(MESSAGES_OBJECT, {
+      where: { conversation_id: conversationId },
+      orderBy: MESSAGE_ORDER,
+    });
+
+    return this.toConversation(row, messages);
+  }
+
+  async list(options: {
+    userId?: string;
+    agentId?: string;
+    limit?: number;
+    cursor?: string;
+  } = {}): Promise<AIConversation[]> {
+    const where: Record<string, unknown> = {};
+    if (options.userId) where.user_id = options.userId;
+    if (options.agentId) where.agent_id = options.agentId;
+
+    // Stable cursor-based pagination using composite (created_at, id) order.
+    // This avoids skips/duplicates when multiple conversations share a timestamp.
+    if (options.cursor) {
+      const cursorRow = await this.engine.findOne(CONVERSATIONS_OBJECT, {
+        where: { id: options.cursor },
+        fields: ['created_at', 'id'],
+      });
+      if (cursorRow) {
+        where.$or = [
+          { created_at: { $gt: cursorRow.created_at } },
+          { created_at: cursorRow.created_at, id: { $gt: cursorRow.id } },
+        ];
+      }
+    }
+
+    const rows: DbConversationRow[] = await this.engine.find(CONVERSATIONS_OBJECT, {
+      where: Object.keys(where).length > 0 ? where : undefined,
+      orderBy: CONVERSATION_ORDER,
+      limit: options.limit && options.limit > 0 ? options.limit : undefined,
+    });
+
+    // Load messages per conversation in parallel.
+    // N+1 is bounded by the pagination limit; driver-agnostic $in is not guaranteed.
+    const conversations: AIConversation[] = await Promise.all(
+      rows.map(async (row) => {
+        const messages: DbMessageRow[] = await this.engine.find(MESSAGES_OBJECT, {
+          where: { conversation_id: row.id },
+          orderBy: MESSAGE_ORDER,
+        });
+        return this.toConversation(row, messages);
+      }),
+    );
+
+    return conversations;
+  }
+
+  async addMessage(conversationId: string, message: AIMessage): Promise<AIConversation> {
+    // Verify conversation exists
+    const row: DbConversationRow | null = await this.engine.findOne(CONVERSATIONS_OBJECT, {
+      where: { id: conversationId },
+    });
+    if (!row) {
+      throw new Error(`Conversation "${conversationId}" not found`);
+    }
+
+    const now = new Date().toISOString();
+    const msgId = `msg_${randomUUID()}`;
+
+    // Insert the message
+    await this.engine.insert(MESSAGES_OBJECT, {
+      id: msgId,
+      conversation_id: conversationId,
+      role: message.role,
+      content: message.content,
+      tool_calls: message.toolCalls ? JSON.stringify(message.toolCalls) : null,
+      tool_call_id: message.toolCallId ?? null,
+      created_at: now,
+    });
+
+    // Update conversation timestamp
+    await this.engine.update(CONVERSATIONS_OBJECT, { id: conversationId, updated_at: now }, {
+      where: { id: conversationId },
+    });
+
+    // Return the full updated conversation
+    return (await this.get(conversationId))!;
+  }
+
+  async delete(conversationId: string): Promise<void> {
+    // Delete messages first (child records)
+    await this.engine.delete(MESSAGES_OBJECT, {
+      where: { conversation_id: conversationId },
+      multi: true,
+    });
+
+    // Delete the conversation
+    await this.engine.delete(CONVERSATIONS_OBJECT, {
+      where: { id: conversationId },
+    });
+  }
+
+  // ── Private helpers ──────────────────────────────────────────────
+
+  /**
+   * Safely parse a JSON string, returning `undefined` on failure.
+   */
+  private safeParse<T>(value: string | null, fallback?: T): T | undefined {
+    if (!value) return undefined;
+    try {
+      return JSON.parse(value) as T;
+    } catch {
+      return fallback;
+    }
+  }
+
+  /**
+   * Map a database row + message rows to an AIConversation.
+   */
+  private toConversation(row: DbConversationRow, messageRows: DbMessageRow[]): AIConversation {
+    return {
+      id: row.id,
+      title: row.title ?? undefined,
+      agentId: row.agent_id ?? undefined,
+      userId: row.user_id ?? undefined,
+      messages: messageRows.map(m => this.toMessage(m)),
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+      metadata: this.safeParse<Record<string, unknown>>(row.metadata),
+    };
+  }
+
+  /**
+   * Map a database row to an AIMessage.
+   */
+  private toMessage(row: DbMessageRow): AIMessage {
+    const msg: AIMessage = {
+      role: row.role,
+      content: row.content,
+    };
+    const toolCalls = this.safeParse<any[]>(row.tool_calls);
+    if (toolCalls) {
+      msg.toolCalls = toolCalls;
+    }
+    if (row.tool_call_id) {
+      msg.toolCallId = row.tool_call_id;
+    }
+    return msg;
+  }
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+// Core service
+export { AIService } from './ai-service.js';
+export type { AIServiceConfig } from './ai-service.js';
+
+// Kernel plugin
+export { AIServicePlugin } from './plugin.js';
+export type { AIServicePluginOptions } from './plugin.js';
+
+// Adapters
+export { MemoryLLMAdapter } from './adapters/memory-adapter.js';
+export type { LLMAdapter } from '@objectstack/spec/contracts';
+
+// Conversation
+export { InMemoryConversationService } from './conversation/in-memory-conversation-service.js';
+export { ObjectQLConversationService } from './conversation/objectql-conversation-service.js';
+
+// Tool registry
+export { ToolRegistry } from './tools/tool-registry.js';
+export type { ToolHandler } from './tools/tool-registry.js';
+
+// Data tools
+export { registerDataTools, DATA_TOOL_DEFINITIONS } from './tools/data-tools.js';
+export type { DataToolContext } from './tools/data-tools.js';
+
+// Agent runtime
+export { AgentRuntime } from './agent-runtime.js';
+export type { AgentChatContext } from './agent-runtime.js';
+
+// Built-in agents
+export { DATA_CHAT_AGENT } from './agents/index.js';
+
+// Object definitions
+export { AiConversationObject, AiMessageObject } from './objects/index.js';
+
+// Routes
+export { buildAIRoutes } from './routes/ai-routes.js';
+export { buildAgentRoutes } from './routes/agent-routes.js';
+export type { RouteDefinition, RouteRequest, RouteResponse } from './routes/ai-routes.js';

package/src/objects/ai-conversation.object.ts

@@ -0,0 +1,86 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { ObjectSchema, Field } from '@objectstack/spec/data';
+
+/**
+ * ai_conversations — AI Conversation Object
+ *
+ * Stores conversation metadata for persistent AI conversation management.
+ * Messages are stored separately in `ai_messages` to support efficient
+ * querying and pagination.
+ *
+ * @namespace ai
+ */
+export const AiConversationObject = ObjectSchema.create({
+  namespace: 'ai',
+  name: 'conversations',
+  label: 'AI Conversation',
+  pluralLabel: 'AI Conversations',
+  icon: 'message-square',
+  isSystem: true,
+  description: 'Persistent AI conversation metadata',
+
+  fields: {
+    id: Field.text({
+      label: 'Conversation ID',
+      required: true,
+      readonly: true,
+    }),
+
+    title: Field.text({
+      label: 'Title',
+      required: false,
+      maxLength: 500,
+      description: 'Conversation title or summary',
+    }),
+
+    agent_id: Field.text({
+      label: 'Agent ID',
+      required: false,
+      maxLength: 255,
+      description: 'Associated AI agent identifier',
+    }),
+
+    user_id: Field.text({
+      label: 'User ID',
+      required: false,
+      maxLength: 255,
+      description: 'User who owns the conversation',
+    }),
+
+    metadata: Field.textarea({
+      label: 'Metadata',
+      required: false,
+      description: 'JSON-serialized conversation metadata',
+    }),
+
+    created_at: Field.datetime({
+      label: 'Created At',
+      required: true,
+      defaultValue: 'NOW()',
+      readonly: true,
+    }),
+
+    updated_at: Field.datetime({
+      label: 'Updated At',
+      required: true,
+      defaultValue: 'NOW()',
+      readonly: true,
+    }),
+  },
+
+  indexes: [
+    { fields: ['user_id'] },
+    { fields: ['agent_id'] },
+    { fields: ['created_at'] },
+  ],
+
+  enable: {
+    trackHistory: false,
+    searchable: false,
+    apiEnabled: true,
+    apiMethods: ['get', 'list', 'create', 'update', 'delete'],
+    trash: false,
+    mru: false,
+  },
+});