@objectstack/service-ai 4.0.0

package/src/objects/ai-message.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_messages — AI Message Object
+ *
+ * Stores individual messages within an AI conversation.
+ * Each message belongs to a conversation via `conversation_id` foreign key.
+ *
+ * @namespace ai
+ */
+export const AiMessageObject = ObjectSchema.create({
+  namespace: 'ai',
+  name: 'messages',
+  label: 'AI Message',
+  pluralLabel: 'AI Messages',
+  icon: 'message-circle',
+  isSystem: true,
+  description: 'Individual messages within AI conversations',
+
+  fields: {
+    id: Field.text({
+      label: 'Message ID',
+      required: true,
+      readonly: true,
+    }),
+
+    conversation_id: Field.text({
+      label: 'Conversation ID',
+      required: true,
+      description: 'Foreign key to ai_conversations',
+    }),
+
+    role: Field.select({
+      label: 'Role',
+      required: true,
+      options: [
+        { label: 'System', value: 'system' },
+        { label: 'User', value: 'user' },
+        { label: 'Assistant', value: 'assistant' },
+        { label: 'Tool', value: 'tool' },
+      ],
+    }),
+
+    content: Field.textarea({
+      label: 'Content',
+      required: true,
+      description: 'Message content',
+    }),
+
+    tool_calls: Field.textarea({
+      label: 'Tool Calls',
+      required: false,
+      description: 'JSON-serialized tool calls (when role=assistant)',
+    }),
+
+    tool_call_id: Field.text({
+      label: 'Tool Call ID',
+      required: false,
+      maxLength: 255,
+      description: 'ID of the tool call this message responds to (when role=tool)',
+    }),
+
+    created_at: Field.datetime({
+      label: 'Created At',
+      required: true,
+      defaultValue: 'NOW()',
+      readonly: true,
+    }),
+  },
+
+  indexes: [
+    { fields: ['conversation_id'] },
+    { fields: ['conversation_id', 'created_at'] },
+  ],
+
+  enable: {
+    trackHistory: false,
+    searchable: false,
+    apiEnabled: true,
+    apiMethods: ['get', 'list', 'create'],
+    trash: false,
+    mru: false,
+  },
+});

package/src/objects/index.ts

@@ -0,0 +1,10 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * AI Service — System Object Definitions (ai namespace)
+ *
+ * Canonical ObjectSchema definitions for AI conversation persistence.
+ */
+
+export { AiConversationObject } from './ai-conversation.object.js';
+export { AiMessageObject } from './ai-message.object.js';

package/src/plugin.ts

@@ -0,0 +1,184 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Plugin, PluginContext } from '@objectstack/core';
+import type { IAIService, IAIConversationService, IDataEngine, IMetadataService, LLMAdapter } from '@objectstack/spec/contracts';
+import { AIService } from './ai-service.js';
+import type { AIServiceConfig } from './ai-service.js';
+import { buildAIRoutes } from './routes/ai-routes.js';
+import { buildAgentRoutes } from './routes/agent-routes.js';
+import { ObjectQLConversationService } from './conversation/objectql-conversation-service.js';
+import { AiConversationObject, AiMessageObject } from './objects/index.js';
+import { registerDataTools } from './tools/data-tools.js';
+import { AgentRuntime } from './agent-runtime.js';
+import { DATA_CHAT_AGENT } from './agents/index.js';
+
+/**
+ * Configuration options for the AIServicePlugin.
+ */
+export interface AIServicePluginOptions {
+  /** LLM adapter to use (defaults to MemoryLLMAdapter). */
+  adapter?: LLMAdapter;
+  /** Enable debug logging. */
+  debug?: boolean;
+  /** Explicit conversation service override. When set, auto-detection is skipped. */
+  conversationService?: IAIConversationService;
+}
+
+/**
+ * AIServicePlugin — Kernel plugin for the unified AI capability service.
+ *
+ * Lifecycle:
+ * 1. **init** — Creates {@link AIService}, registers as `'ai'` service.
+ *    If an existing AI service is already registered, it is replaced.
+ * 2. **start** — Triggers `'ai:ready'` hook so other plugins can register
+ *    tools or extend the service.  Registers REST/SSE routes.
+ * 3. **destroy** — Cleans up references.
+ *
+ * @example
+ * ```ts
+ * import { LiteKernel } from '@objectstack/core';
+ * import { AIServicePlugin } from '@objectstack/service-ai';
+ *
+ * const kernel = new LiteKernel();
+ * kernel.use(new AIServicePlugin());
+ * await kernel.bootstrap();
+ *
+ * const ai = kernel.getService<IAIService>('ai');
+ * const result = await ai.chat([{ role: 'user', content: 'Hello' }]);
+ * ```
+ */
+export class AIServicePlugin implements Plugin {
+  name = 'com.objectstack.service-ai';
+  version = '1.0.0';
+  type = 'standard' as const;
+  dependencies: string[] = [];
+
+  private service?: AIService;
+  private readonly options: AIServicePluginOptions;
+
+  constructor(options: AIServicePluginOptions = {}) {
+    this.options = options;
+  }
+
+  async init(ctx: PluginContext): Promise<void> {
+    // Check if there is an existing AI service (e.g. from dev-plugin)
+    let hasExisting = false;
+    try {
+      const existing = ctx.getService<IAIService>('ai');
+      if (existing && typeof existing.chat === 'function') {
+        hasExisting = true;
+        ctx.logger.debug('[AI] Found existing AI service, replacing');
+      }
+    } catch {
+      // No existing service — that's fine
+    }
+
+    // Determine conversation service: explicit > auto-detect IDataEngine > InMemory fallback
+    let conversationService: IAIConversationService | undefined = this.options.conversationService;
+    if (!conversationService) {
+      try {
+        const engine = ctx.getService<IDataEngine>('data');
+        if (engine && typeof engine.find === 'function') {
+          conversationService = new ObjectQLConversationService(engine);
+          ctx.logger.info('[AI] Using ObjectQLConversationService (IDataEngine detected)');
+        }
+      } catch {
+        // No data engine — fall back to InMemory
+      }
+    }
+
+    const config: AIServiceConfig = {
+      adapter: this.options.adapter,
+      logger: ctx.logger,
+      conversationService,
+    };
+
+    this.service = new AIService(config);
+
+    // Register or replace the AI service
+    if (hasExisting) {
+      ctx.replaceService('ai', this.service);
+    } else {
+      ctx.registerService('ai', this.service);
+    }
+
+    // Register AI system objects so ObjectQLPlugin auto-discovers them
+    ctx.registerService('app.com.objectstack.service-ai', {
+      id: 'com.objectstack.service-ai',
+      name: 'AI Service',
+      version: '1.0.0',
+      type: 'plugin',
+      namespace: 'ai',
+      objects: [AiConversationObject, AiMessageObject],
+    });
+
+    if (this.options.debug) {
+      ctx.hook('ai:beforeChat', async (messages: unknown) => {
+        ctx.logger.debug('[AI] Before chat', { messages });
+      });
+    }
+
+    ctx.logger.info('[AI] Service initialized');
+  }
+
+  async start(ctx: PluginContext): Promise<void> {
+    if (!this.service) return;
+
+    // ── Auto-register built-in data tools if data engine + metadata are available ──
+    try {
+      const dataEngine = ctx.getService<IDataEngine>('data');
+      const metadataService = ctx.getService<IMetadataService>('metadata');
+      if (dataEngine && metadataService) {
+        registerDataTools(this.service.toolRegistry, { dataEngine, metadataService });
+        ctx.logger.info('[AI] Built-in data tools registered');
+
+        // Register the built-in data_chat agent only if it does not already exist
+        const agentExists =
+          typeof metadataService.exists === 'function'
+            ? await metadataService.exists('agent', DATA_CHAT_AGENT.name)
+            : false;
+
+        if (!agentExists) {
+          await metadataService.register('agent', DATA_CHAT_AGENT.name, DATA_CHAT_AGENT);
+          ctx.logger.info('[AI] data_chat agent registered');
+        } else {
+          ctx.logger.debug('[AI] data_chat agent already exists, skipping auto-registration');
+        }
+      }
+    } catch {
+      // Data engine or metadata service not available — skip data tools
+      ctx.logger.debug('[AI] Data engine or metadata service not available, skipping data tools');
+    }
+
+    // Trigger hook to notify AI service is ready — other plugins can register tools
+    await ctx.trigger('ai:ready', this.service);
+
+    // Build and expose route definitions
+    const routes = buildAIRoutes(this.service, this.service.conversationService, ctx.logger);
+
+    // Build agent routes if metadata service is available
+    try {
+      const metadataService = ctx.getService<IMetadataService>('metadata');
+      if (metadataService) {
+        const agentRuntime = new AgentRuntime(metadataService);
+        const agentRoutes = buildAgentRoutes(this.service, agentRuntime, ctx.logger);
+        routes.push(...agentRoutes);
+      }
+    } catch {
+      ctx.logger.debug('[AI] Metadata service not available, skipping agent routes');
+    }
+
+    // Trigger hook so HTTP server plugins can mount these routes
+    await ctx.trigger('ai:routes', routes);
+
+    ctx.logger.info(
+      `[AI] Service started — adapter="${this.service.adapterName}", ` +
+      `tools=${this.service.toolRegistry.size}, ` +
+      `routes=${routes.length}`,
+    );
+  }
+
+  async destroy(): Promise<void> {
+    this.service = undefined;
+  }
+}

package/src/routes/agent-routes.ts

@@ -0,0 +1,132 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { AIMessage } from '@objectstack/spec/contracts';
+import type { Logger } from '@objectstack/spec/contracts';
+import type { AIService } from '../ai-service.js';
+import type { AgentRuntime, AgentChatContext } from '../agent-runtime.js';
+import type { RouteDefinition } from './ai-routes.js';
+
+/**
+ * Allowed message roles for the agent chat endpoint.
+ *
+ * Only `user` and `assistant` are accepted from clients.
+ * `system` messages are injected server-side from agent instructions,
+ * and `tool` messages are produced by the tool-call loop — accepting
+ * either from the client would allow callers to override agent
+ * guardrails or inject fabricated tool results.
+ */
+const ALLOWED_AGENT_ROLES = new Set<string>(['user', 'assistant']);
+
+function validateAgentMessage(raw: unknown): string | null {
+  if (typeof raw !== 'object' || raw === null) {
+    return 'each message must be an object';
+  }
+  const msg = raw as Record<string, unknown>;
+  if (typeof msg.role !== 'string' || !ALLOWED_AGENT_ROLES.has(msg.role)) {
+    return `message.role must be one of ${[...ALLOWED_AGENT_ROLES].map(r => `"${r}"`).join(', ')} for agent chat`;
+  }
+  if (typeof msg.content !== 'string') {
+    return 'message.content must be a string';
+  }
+  return null;
+}
+
+/**
+ * Build agent-specific REST routes.
+ *
+ * | Method | Path | Description |
+ * |:---|:---|:---|
+ * | POST | /api/v1/ai/agents/:agentName/chat | Chat with a specific agent |
+ */
+export function buildAgentRoutes(
+  aiService: AIService,
+  agentRuntime: AgentRuntime,
+  logger: Logger,
+): RouteDefinition[] {
+  return [
+    {
+      method: 'POST',
+      path: '/api/v1/ai/agents/:agentName/chat',
+      description: 'Chat with a specific AI agent',
+      handler: async (req) => {
+        const agentName = req.params?.agentName;
+        if (!agentName) {
+          return { status: 400, body: { error: 'agentName parameter is required' } };
+        }
+
+        // Parse request body
+        const {
+          messages: rawMessages,
+          context: chatContext,
+          options: extraOptions,
+        } = (req.body ?? {}) as {
+          messages?: unknown[];
+          context?: AgentChatContext;
+          options?: Record<string, unknown>;
+        };
+
+        if (!Array.isArray(rawMessages) || rawMessages.length === 0) {
+          return { status: 400, body: { error: 'messages array is required' } };
+        }
+
+        for (const msg of rawMessages) {
+          const err = validateAgentMessage(msg);
+          if (err) return { status: 400, body: { error: err } };
+        }
+
+        // Load agent definition
+        const agent = await agentRuntime.loadAgent(agentName);
+        if (!agent) {
+          return { status: 404, body: { error: `Agent "${agentName}" not found` } };
+        }
+        if (!agent.active) {
+          return { status: 403, body: { error: `Agent "${agentName}" is not active` } };
+        }
+
+        try {
+          // Build system messages from agent instructions + UI context
+          const systemMessages = agentRuntime.buildSystemMessages(agent, chatContext);
+
+          // Resolve agent model/tools → request options
+          const agentOptions = agentRuntime.buildRequestOptions(
+            agent,
+            aiService.toolRegistry.getAll(),
+          );
+
+          // Whitelist only safe caller overrides — block tools/toolChoice/model
+          // to prevent tool-definition injection or DoS via unregistered tools.
+          const safeOverrides: Record<string, unknown> = {};
+          if (extraOptions) {
+            const ALLOWED_KEYS = new Set(['temperature', 'maxTokens', 'stop']);
+            for (const key of Object.keys(extraOptions)) {
+              if (ALLOWED_KEYS.has(key)) {
+                safeOverrides[key] = extraOptions[key];
+              }
+            }
+          }
+          const mergedOptions = { ...agentOptions, ...safeOverrides };
+
+          // Prepend system messages then user conversation
+          const fullMessages: AIMessage[] = [
+            ...systemMessages,
+            ...(rawMessages as AIMessage[]),
+          ];
+
+          // Use chatWithTools for automatic tool resolution
+          const result = await aiService.chatWithTools(fullMessages, {
+            ...mergedOptions,
+            maxIterations: agent.planning?.maxIterations,
+          });
+
+          return { status: 200, body: result };
+        } catch (err) {
+          logger.error(
+            '[AI Route] /agents/:agentName/chat error',
+            err instanceof Error ? err : undefined,
+          );
+          return { status: 500, body: { error: 'Internal AI service error' } };
+        }
+      },
+    },
+  ];
+}

package/src/routes/ai-routes.ts

@@ -0,0 +1,286 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { IAIService, IAIConversationService, AIMessage } from '@objectstack/spec/contracts';
+import type { Logger } from '@objectstack/spec/contracts';
+
+/**
+ * Minimal HTTP handler abstraction so routes stay framework-agnostic.
+ *
+ * Consumers wire these handlers to their HTTP server of choice
+ * (Hono, Express, Fastify, etc.) via the kernel's HTTP server service.
+ */
+export interface RouteDefinition {
+  /** HTTP method */
+  method: 'GET' | 'POST' | 'DELETE';
+  /** Path pattern (e.g. '/api/v1/ai/chat') */
+  path: string;
+  /** Human-readable description */
+  description: string;
+  /**
+   * Handler receives a plain request-like object and returns a response-like
+   * object.  SSE responses set `stream: true` and provide an async iterable.
+   */
+  handler: (req: RouteRequest) => Promise<RouteResponse>;
+}
+
+export interface RouteRequest {
+  /** Parsed JSON body (for POST requests) */
+  body?: unknown;
+  /** Route/query parameters */
+  params?: Record<string, string>;
+  /** Query string parameters */
+  query?: Record<string, string>;
+}
+
+export interface RouteResponse {
+  /** HTTP status code */
+  status: number;
+  /** JSON-serializable body (for non-streaming responses) */
+  body?: unknown;
+  /** If true, `stream` provides SSE events */
+  stream?: boolean;
+  /** Async iterable of SSE events (when stream=true) */
+  events?: AsyncIterable<unknown>;
+}
+
+/** Valid message roles accepted by the AI routes. */
+const VALID_ROLES = new Set<string>(['system', 'user', 'assistant', 'tool']);
+
+/**
+ * Validate that `raw` is a well-formed AIMessage.
+ * Returns null on success, or an error string on failure.
+ */
+function validateMessage(raw: unknown): string | null {
+  if (typeof raw !== 'object' || raw === null) {
+    return 'each message must be an object';
+  }
+  const msg = raw as Record<string, unknown>;
+  if (typeof msg.role !== 'string' || !VALID_ROLES.has(msg.role)) {
+    return `message.role must be one of ${[...VALID_ROLES].map(r => `"${r}"`).join(', ')}`;
+  }
+  if (typeof msg.content !== 'string') {
+    return 'message.content must be a string';
+  }
+  return null;
+}
+
+/**
+ * Build the standard AI REST/SSE routes.
+ *
+ * Depends on contracts ({@link IAIService} + {@link IAIConversationService})
+ * rather than concrete implementations, so any compliant service pair can
+ * be wired in.
+ *
+ * Routes:
+ * | Method | Path | Description |
+ * |:---|:---|:---|
+ * | POST | /api/v1/ai/chat | Synchronous chat completion |
+ * | POST | /api/v1/ai/chat/stream | SSE streaming chat completion |
+ * | POST | /api/v1/ai/complete | Text completion |
+ * | GET  | /api/v1/ai/models | List available models |
+ * | POST | /api/v1/ai/conversations | Create a conversation |
+ * | GET  | /api/v1/ai/conversations | List conversations |
+ * | POST | /api/v1/ai/conversations/:id/messages | Add message to conversation |
+ * | DELETE | /api/v1/ai/conversations/:id | Delete conversation |
+ */
+export function buildAIRoutes(
+  aiService: IAIService,
+  conversationService: IAIConversationService,
+  logger: Logger,
+): RouteDefinition[] {
+  return [
+    // ── Chat ────────────────────────────────────────────────────
+    {
+      method: 'POST',
+      path: '/api/v1/ai/chat',
+      description: 'Synchronous chat completion',
+      handler: async (req) => {
+        const { messages, options } = (req.body ?? {}) as {
+          messages?: unknown[];
+          options?: Record<string, unknown>;
+        };
+
+        if (!Array.isArray(messages) || messages.length === 0) {
+          return { status: 400, body: { error: 'messages array is required' } };
+        }
+
+        for (const msg of messages) {
+          const err = validateMessage(msg);
+          if (err) return { status: 400, body: { error: err } };
+        }
+
+        try {
+          const result = await aiService.chat(messages as AIMessage[], options as any);
+          return { status: 200, body: result };
+        } catch (err) {
+          logger.error('[AI Route] /chat error', err instanceof Error ? err : undefined);
+          return { status: 500, body: { error: 'Internal AI service error' } };
+        }
+      },
+    },
+
+    // ── Stream Chat (SSE) ──────────────────────────────────────
+    {
+      method: 'POST',
+      path: '/api/v1/ai/chat/stream',
+      description: 'SSE streaming chat completion',
+      handler: async (req) => {
+        const { messages, options } = (req.body ?? {}) as {
+          messages?: unknown[];
+          options?: Record<string, unknown>;
+        };
+
+        if (!Array.isArray(messages) || messages.length === 0) {
+          return { status: 400, body: { error: 'messages array is required' } };
+        }
+
+        for (const msg of messages) {
+          const err = validateMessage(msg);
+          if (err) return { status: 400, body: { error: err } };
+        }
+
+        try {
+          if (!aiService.streamChat) {
+            return { status: 501, body: { error: 'Streaming is not supported by the configured AI service' } };
+          }
+          const events = aiService.streamChat(messages as AIMessage[], options as any);
+          return { status: 200, stream: true, events };
+        } catch (err) {
+          logger.error('[AI Route] /chat/stream error', err instanceof Error ? err : undefined);
+          return { status: 500, body: { error: 'Internal AI service error' } };
+        }
+      },
+    },
+
+    // ── Complete ────────────────────────────────────────────────
+    {
+      method: 'POST',
+      path: '/api/v1/ai/complete',
+      description: 'Text completion',
+      handler: async (req) => {
+        const { prompt, options } = (req.body ?? {}) as {
+          prompt?: string;
+          options?: Record<string, unknown>;
+        };
+
+        if (!prompt || typeof prompt !== 'string') {
+          return { status: 400, body: { error: 'prompt string is required' } };
+        }
+
+        try {
+          const result = await aiService.complete(prompt, options as any);
+          return { status: 200, body: result };
+        } catch (err) {
+          logger.error('[AI Route] /complete error', err instanceof Error ? err : undefined);
+          return { status: 500, body: { error: 'Internal AI service error' } };
+        }
+      },
+    },
+
+    // ── Models ──────────────────────────────────────────────────
+    {
+      method: 'GET',
+      path: '/api/v1/ai/models',
+      description: 'List available models',
+      handler: async () => {
+        try {
+          const models = aiService.listModels ? await aiService.listModels() : [];
+          return { status: 200, body: { models } };
+        } catch (err) {
+          logger.error('[AI Route] /models error', err instanceof Error ? err : undefined);
+          return { status: 500, body: { error: 'Internal AI service error' } };
+        }
+      },
+    },
+
+    // ── Conversations ──────────────────────────────────────────
+    {
+      method: 'POST',
+      path: '/api/v1/ai/conversations',
+      description: 'Create a conversation',
+      handler: async (req) => {
+        try {
+          const options = (req.body ?? {}) as Record<string, unknown>;
+          const conversation = await conversationService.create(options as any);
+          return { status: 201, body: conversation };
+        } catch (err) {
+          logger.error('[AI Route] POST /conversations error', err instanceof Error ? err : undefined);
+          return { status: 500, body: { error: 'Internal AI service error' } };
+        }
+      },
+    },
+    {
+      method: 'GET',
+      path: '/api/v1/ai/conversations',
+      description: 'List conversations',
+      handler: async (req) => {
+        try {
+          const rawQuery = req.query ?? {};
+          const options: Record<string, unknown> = { ...rawQuery };
+
+          if (typeof rawQuery.limit === 'string') {
+            const parsedLimit = Number(rawQuery.limit);
+            if (!Number.isFinite(parsedLimit) || parsedLimit <= 0 || !Number.isInteger(parsedLimit)) {
+              return { status: 400, body: { error: 'Invalid limit parameter' } };
+            }
+            options.limit = parsedLimit;
+          }
+
+          const conversations = await conversationService.list(options as any);
+          return { status: 200, body: { conversations } };
+        } catch (err) {
+          logger.error('[AI Route] GET /conversations error', err instanceof Error ? err : undefined);
+          return { status: 500, body: { error: 'Internal AI service error' } };
+        }
+      },
+    },
+    {
+      method: 'POST',
+      path: '/api/v1/ai/conversations/:id/messages',
+      description: 'Add message to a conversation',
+      handler: async (req) => {
+        const id = req.params?.id;
+        if (!id) {
+          return { status: 400, body: { error: 'conversation id is required' } };
+        }
+
+        const message = req.body;
+        const validationError = validateMessage(message);
+        if (validationError) {
+          return { status: 400, body: { error: validationError } };
+        }
+
+        try {
+          const conversation = await conversationService.addMessage(id, message as AIMessage);
+          return { status: 200, body: conversation };
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          if (msg.includes('not found')) {
+            return { status: 404, body: { error: msg } };
+          }
+          logger.error('[AI Route] POST /conversations/:id/messages error', err instanceof Error ? err : undefined);
+          return { status: 500, body: { error: 'Internal AI service error' } };
+        }
+      },
+    },
+    {
+      method: 'DELETE',
+      path: '/api/v1/ai/conversations/:id',
+      description: 'Delete a conversation',
+      handler: async (req) => {
+        const id = req.params?.id;
+        if (!id) {
+          return { status: 400, body: { error: 'conversation id is required' } };
+        }
+
+        try {
+          await conversationService.delete(id);
+          return { status: 204 };
+        } catch (err) {
+          logger.error('[AI Route] DELETE /conversations/:id error', err instanceof Error ? err : undefined);
+          return { status: 500, body: { error: 'Internal AI service error' } };
+        }
+      },
+    },
+  ];
+}