@objectstack/service-ai 4.0.3 → 4.0.5

package/src/agents/data-chat-agent.ts

@@ -1,79 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { Agent } from '@objectstack/spec';
-
-/**
- * Built-in `data_chat` agent definition.
- *
- * This agent powers the Airtable-style data conversation Chatbot.
- * It is registered automatically by the AI service plugin when a
- * data engine is available.
- *
- * @example
- * ```
- * POST /api/v1/ai/agents/data_chat/chat
- * {
- *   "messages": [{ "role": "user", "content": "Show me all active accounts" }],
- *   "context": { "objectName": "account" }
- * }
- * ```
- */
-export const DATA_CHAT_AGENT: Agent = {
-  name: 'data_chat',
-  label: 'Data Assistant',
-  role: 'Business Data Analyst',
-  instructions: `You are a helpful data assistant that helps users explore and understand their business data through natural language.
-
-Capabilities:
-- List available data objects (tables) and their schemas
-- Query records with filters, sorting, and pagination
-- Look up individual records by ID
-- Perform aggregations and statistical analysis (count, sum, avg, min, max)
-
-Guidelines:
-1. Always use the describe_object tool first to understand a table's structure before querying it.
-2. Respect the user's current context — if they are viewing a specific object or record, use that as the default scope.
-3. When presenting data, format it in a clear and readable way using markdown tables or bullet lists.
-4. For large result sets, summarize the data and mention the total count.
-5. When performing aggregations, explain the results in plain language.
-6. If a query returns no results, suggest possible reasons and alternative queries.
-7. Never expose internal IDs unless the user explicitly asks for them.
-8. Always answer in the same language the user is using.`,
-
-  model: {
-    provider: 'openai',
-    model: 'gpt-4',
-    temperature: 0.3,
-    maxTokens: 4096,
-  },
-
-  tools: [
-    { type: 'query', name: 'list_objects', description: 'List all available data objects' },
-    { type: 'query', name: 'describe_object', description: 'Get schema/fields of a data object' },
-    { type: 'query', name: 'query_records', description: 'Query records with filters and pagination' },
-    { type: 'query', name: 'get_record', description: 'Get a single record by ID' },
-    { type: 'query', name: 'aggregate_data', description: 'Aggregate/statistics on data' },
-  ],
-
-  active: true,
-  visibility: 'global',
-
-  guardrails: {
-    maxTokensPerInvocation: 8192,
-    maxExecutionTimeSec: 30,
-    blockedTopics: ['delete_records', 'drop_table', 'alter_schema'],
-  },
-
-  planning: {
-    strategy: 'react',
-    maxIterations: 5,
-    allowReplan: false,
-  },
-
-  memory: {
-    shortTerm: {
-      maxMessages: 20,
-      maxTokens: 4096,
-    },
-  },
-};

package/src/agents/index.ts

@@ -1,4 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-export { DATA_CHAT_AGENT } from './data-chat-agent.js';
-export { METADATA_ASSISTANT_AGENT } from './metadata-assistant-agent.js';

package/src/agents/metadata-assistant-agent.ts

@@ -1,87 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { Agent } from '@objectstack/spec';
-
-/**
- * Built-in `metadata_assistant` agent definition.
- *
- * This agent powers AI-driven metadata management — users can create objects,
- * add/modify/delete fields, and inspect schema definitions through natural
- * language conversation.
- *
- * It is registered automatically by the AI service plugin alongside the
- * `data_chat` agent when the metadata service is available.
- *
- * @example
- * ```
- * POST /api/v1/ai/agents/metadata_assistant/chat
- * {
- *   "messages": [{ "role": "user", "content": "Create a contracts table with name, value, and status fields" }],
- *   "context": {}
- * }
- * ```
- */
-export const METADATA_ASSISTANT_AGENT: Agent = {
-  name: 'metadata_assistant',
-  label: 'Metadata Assistant',
-  role: 'Schema Architect',
-  instructions: `You are an expert metadata architect that helps users design and manage their data models through natural language.
-
-Capabilities:
-- Create new data objects (tables) with fields
-- Add fields (columns) to existing objects
-- Modify field properties (label, type, required, default value)
-- Delete fields from objects
-- List all registered metadata objects and their schemas
-- Describe the full schema of a specific object
-
-Guidelines:
-1. Before creating a new object, use list_objects to check if a similar one already exists.
-2. Before modifying or deleting fields, use describe_object to understand the current schema.
-3. Always use snake_case for object names and field names (e.g. project_task, due_date).
-4. Suggest meaningful field types based on the user's description (e.g. "deadline" → date, "active" → boolean).
-5. When creating objects, propose a reasonable set of initial fields based on the entity type.
-6. Explain what changes you are about to make before executing them.
-7. After making changes, confirm the result by describing the updated schema.
-8. For destructive operations (deleting fields), always warn the user about potential data loss.
-9. Always answer in the same language the user is using.
-10. If the user's request is ambiguous, ask clarifying questions before proceeding.`,
-
-  model: {
-    provider: 'openai',
-    model: 'gpt-4',
-    temperature: 0.2,
-    maxTokens: 4096,
-  },
-
-  tools: [
-    { type: 'action', name: 'create_object', description: 'Create a new data object (table)' },
-    { type: 'action', name: 'add_field', description: 'Add a field to an existing object' },
-    { type: 'action', name: 'modify_field', description: 'Modify an existing field definition' },
-    { type: 'action', name: 'delete_field', description: 'Delete a field from an object' },
-    { type: 'query', name: 'list_objects', description: 'List all data objects' },
-    { type: 'query', name: 'describe_object', description: 'Describe an object schema' },
-  ],
-
-  active: true,
-  visibility: 'global',
-
-  guardrails: {
-    maxTokensPerInvocation: 8192,
-    maxExecutionTimeSec: 60,
-    blockedTopics: ['drop_database', 'raw_sql', 'system_tables'],
-  },
-
-  planning: {
-    strategy: 'react',
-    maxIterations: 10,
-    allowReplan: true,
-  },
-
-  memory: {
-    shortTerm: {
-      maxMessages: 30,
-      maxTokens: 8192,
-    },
-  },
-};

package/src/ai-service.ts

@@ -1,364 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type {
-  ModelMessage,
-  ToolCallPart,
-  TextStreamPart,
-  ToolSet,
-  AIRequestOptions,
-  AIResult,
-  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 type { ToolExecutionResult } from './tools/tool-registry.js';
-import { InMemoryConversationService } from './conversation/in-memory-conversation-service.js';
-
-// ── Stream event helpers ──────────────────────────────────────────
-// These helpers construct properly-typed Vercel AI SDK stream parts
-// to avoid repeated `as unknown as TextStreamPart<ToolSet>` casts.
-
-/** Create a text-delta stream part. */
-function textDeltaPart(id: string, text: string): TextStreamPart<ToolSet> {
-  return { type: 'text-delta', id, text } as TextStreamPart<ToolSet>;
-}
-
-/** Create a finish stream part from an AIResult. */
-function finishPart(result?: AIResult): TextStreamPart<ToolSet> {
-  return {
-    type: 'finish',
-    finishReason: 'stop',
-    totalUsage: result?.usage ?? { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
-    rawFinishReason: 'stop',
-  } as unknown as TextStreamPart<ToolSet>;
-}
-
-/**
- * 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: ModelMessage[], 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: ModelMessage[],
-    options?: AIRequestOptions,
-  ): AsyncIterable<TextStreamPart<ToolSet>> {
-    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 textDeltaPart('fallback', result.content);
-      yield finishPart(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;
-
-  /** Extract the text value from a ToolExecutionResult's output. */
-  private static extractOutputText(tr: ToolExecutionResult): string {
-    return tr.output && typeof tr.output === 'object' && 'value' in tr.output
-      ? String(tr.output.value) : 'unknown error';
-  }
-
-  /**
-   * 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: ModelMessage[],
-    options?: ChatWithToolsOptions,
-  ): Promise<AIResult> {
-    // Destructure loop-specific options so they are never forwarded to the adapter
-    const { maxIterations: maxIter, onToolError, ...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];
-
-    // Track errors across iterations for diagnostics
-    const toolErrors: Array<{ iteration: number; toolName: string; error: string }> = [];
-
-    this.logger.debug('[AI] chatWithTools start', {
-      messageCount: conversation.length,
-      toolCount: mergedTools.length,
-      maxIterations,
-    });
-
-    let abortedByCallback = false;
-
-    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.toolName),
-      });
-
-      // Append the assistant's response (with tool call metadata) to the conversation
-      const assistantContent: Array<{ type: 'text'; text: string } | ToolCallPart> = [];
-      if (result.content) assistantContent.push({ type: 'text', text: result.content });
-      assistantContent.push(...result.toolCalls);
-      conversation.push({
-        role: 'assistant',
-        content: assistantContent,
-      } as ModelMessage);
-
-      // Execute all tool calls in parallel
-      const toolResults: ToolExecutionResult[] = await this.toolRegistry.executeAll(result.toolCalls);
-
-      // Process results: track errors and honour onToolError callback
-      for (const tr of toolResults) {
-        if (tr.isError) {
-          // Match tool call by toolCallId for robust attribution
-          const matchedCall = result.toolCalls!.find(tc => tc.toolCallId === tr.toolCallId);
-          const toolName = matchedCall?.toolName ?? 'unknown';
-          const errorText = AIService.extractOutputText(tr);
-          const errorEntry = { iteration, toolName, error: errorText };
-          toolErrors.push(errorEntry);
-          this.logger.warn('[AI] chatWithTools tool error', errorEntry);
-
-          if (onToolError && matchedCall) {
-            const action = onToolError(matchedCall, errorText);
-            if (action === 'abort') {
-              abortedByCallback = true;
-            }
-          }
-        }
-
-        // Append each tool result as a `role: 'tool'` message
-        conversation.push({
-          role: 'tool',
-          content: [tr],
-        } as ModelMessage);
-      }
-
-      if (abortedByCallback) {
-        break;
-      }
-    }
-
-    // Distinguish user-driven abort from max-iterations exhaustion in logs
-    if (abortedByCallback) {
-      this.logger.warn('[AI] chatWithTools aborted by onToolError callback', { toolErrors });
-    } else {
-      this.logger.warn('[AI] chatWithTools max iterations reached, forcing final response', {
-        toolErrors: toolErrors.length > 0 ? toolErrors : undefined,
-      });
-    }
-
-    // Make one last call *without* tools so the model is forced to produce text.
-    const finalResult = await this.adapter.chat(conversation, {
-      ...chatOptions,
-      tools: undefined,
-      toolChoice: undefined,
-    });
-    return finalResult;
-  }
-
-  /**
-   * Stream chat with automatic tool call resolution.
-   *
-   * Works like {@link chatWithTools} but yields SSE events.  When the model
-   * requests tool calls during streaming, they are executed and the results
-   * fed back until a final text stream is produced.
-   */
-  async *streamChatWithTools(
-    messages: ModelMessage[],
-    options?: ChatWithToolsOptions,
-  ): AsyncIterable<TextStreamPart<ToolSet>> {
-    const { maxIterations: maxIter, onToolError, ...restOptions } = options ?? {};
-    const maxIterations = maxIter ?? AIService.DEFAULT_MAX_ITERATIONS;
-    const registeredTools = this.toolRegistry.getAll();
-
-    const mergedTools = [
-      ...registeredTools,
-      ...(restOptions.tools ?? []),
-    ];
-
-    const chatOptions: AIRequestOptions = {
-      ...restOptions,
-      tools: mergedTools.length > 0 ? mergedTools : undefined,
-      toolChoice: mergedTools.length > 0 ? (restOptions.toolChoice ?? 'auto') : undefined,
-    };
-
-    const conversation = [...messages];
-    let abortedByCallback = false;
-
-    for (let iteration = 0; iteration < maxIterations; iteration++) {
-      // Use non-streaming chat for intermediate tool-call rounds
-      const result = await this.adapter.chat(conversation, chatOptions);
-
-      if (!result.toolCalls || result.toolCalls.length === 0) {
-        // Final round — return the probed result without an extra model call
-        yield textDeltaPart('stream', result.content);
-        yield finishPart(result);
-        return;
-      }
-
-      // Emit tool-call events so the client can see tool execution progress
-      for (const tc of result.toolCalls) {
-        yield { type: 'tool-call', toolCallId: tc.toolCallId, toolName: tc.toolName, input: tc.input } as TextStreamPart<ToolSet>;
-      }
-
-      const assistantContent: Array<{ type: 'text'; text: string } | ToolCallPart> = [];
-      if (result.content) assistantContent.push({ type: 'text', text: result.content });
-      assistantContent.push(...result.toolCalls);
-      conversation.push({
-        role: 'assistant',
-        content: assistantContent,
-      } as ModelMessage);
-
-      const toolResults: ToolExecutionResult[] = await this.toolRegistry.executeAll(result.toolCalls);
-
-      for (const tr of toolResults) {
-        if (tr.isError && onToolError) {
-          const matchedCall = result.toolCalls!.find(tc => tc.toolCallId === tr.toolCallId);
-          if (matchedCall) {
-            const errorText = AIService.extractOutputText(tr);
-            const action = onToolError(matchedCall, errorText);
-            if (action === 'abort') {
-              abortedByCallback = true;
-            }
-          }
-        }
-        // Emit tool-result so the client can see tool output via SSE
-        yield {
-          type: 'tool-result',
-          toolCallId: tr.toolCallId,
-          toolName: tr.toolName,
-          output: tr.output,
-        } as TextStreamPart<ToolSet>;
-        conversation.push({
-          role: 'tool',
-          content: [tr],
-        } as ModelMessage);
-      }
-
-      if (abortedByCallback) {
-        break;
-      }
-    }
-
-    // Forced final response (no tools) — either aborted or max iterations
-    if (abortedByCallback) {
-      this.logger.warn('[AI] streamChatWithTools aborted by onToolError callback');
-    } else {
-      this.logger.warn('[AI] streamChatWithTools max iterations reached');
-    }
-    const finalOptions = { ...chatOptions, tools: undefined, toolChoice: undefined };
-    const result = await this.adapter.chat(conversation, finalOptions);
-    yield textDeltaPart('stream', result.content);
-    yield finishPart(result);
-  }
-}

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

@@ -1,103 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type {
-  AIConversation,
-  ModelMessage,
-  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: ModelMessage): 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

@@ -1,4 +0,0 @@
-// 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';