@objectstack/service-ai 4.0.0

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

@@ -0,0 +1,364 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import type { IDataEngine } from '@objectstack/spec/contracts';
+import type { AIMessage } from '@objectstack/spec/contracts';
+import { ObjectQLConversationService } from '../conversation/objectql-conversation-service.js';
+
+// ─────────────────────────────────────────────────────────────────
+// In-memory IDataEngine stub (mimics driver-memory behavior)
+// ─────────────────────────────────────────────────────────────────
+
+function createMemoryEngine(): IDataEngine {
+  const tables = new Map<string, any[]>();
+
+  const getTable = (name: string) => {
+    if (!tables.has(name)) tables.set(name, []);
+    return tables.get(name)!;
+  };
+
+  /** Evaluate a single filter condition against a row. */
+  const matchesCondition = (row: any, where: Record<string, any>): boolean => {
+    for (const [key, value] of Object.entries(where)) {
+      if (key === '$or') {
+        // At least one branch must match
+        if (!Array.isArray(value) || !value.some(branch => matchesCondition(row, branch))) {
+          return false;
+        }
+      } else if (typeof value === 'object' && value !== null && '$gt' in value) {
+        if (!(row[key] > value.$gt)) return false;
+      } else if (row[key] !== value) {
+        return false;
+      }
+    }
+    return true;
+  };
+
+  return {
+    find: async (objectName, query?) => {
+      let rows = [...getTable(objectName)];
+      if (query?.where) {
+        rows = rows.filter(row => matchesCondition(row, query.where as Record<string, any>));
+      }
+      if (query?.orderBy && query.orderBy.length > 0) {
+        rows.sort((a, b) => {
+          for (const sort of query.orderBy!) {
+            const field = (sort as any).field;
+            const dir = (sort as any).order === 'desc' ? -1 : 1;
+            if (a[field] < b[field]) return -dir;
+            if (a[field] > b[field]) return dir;
+          }
+          return 0;
+        });
+      }
+      if (query?.limit) {
+        rows = rows.slice(0, query.limit);
+      }
+      return rows;
+    },
+    findOne: async (objectName, query?) => {
+      let rows = [...getTable(objectName)];
+      if (query?.where) {
+        rows = rows.filter(row => matchesCondition(row, query.where as Record<string, any>));
+      }
+      return rows[0] ?? null;
+    },
+    insert: async (objectName, data) => {
+      const table = getTable(objectName);
+      if (Array.isArray(data)) {
+        table.push(...data);
+        return data;
+      }
+      table.push({ ...data });
+      return data;
+    },
+    update: async (objectName, data, options?) => {
+      const table = getTable(objectName);
+      const where = options?.where as Record<string, any> | undefined;
+      for (let i = 0; i < table.length; i++) {
+        if (where) {
+          let match = true;
+          for (const [key, value] of Object.entries(where)) {
+            if (table[i][key] !== value) { match = false; break; }
+          }
+          if (!match) continue;
+        }
+        Object.assign(table[i], data);
+        return table[i];
+      }
+      return data;
+    },
+    delete: async (objectName, options?) => {
+      const table = getTable(objectName);
+      const where = options?.where as Record<string, any> | undefined;
+      let deleted = 0;
+      const multi = (options as any)?.multi ?? false;
+      for (let i = table.length - 1; i >= 0; i--) {
+        if (where) {
+          let match = true;
+          for (const [key, value] of Object.entries(where)) {
+            if (table[i][key] !== value) { match = false; break; }
+          }
+          if (!match) continue;
+        }
+        table.splice(i, 1);
+        deleted++;
+        if (!multi) break;
+      }
+      return { deleted };
+    },
+    count: async (objectName, query?) => {
+      let rows = [...getTable(objectName)];
+      if (query?.where) {
+        rows = rows.filter(row => matchesCondition(row, query.where as Record<string, any>));
+      }
+      return rows.length;
+    },
+    aggregate: async () => [],
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Tests
+// ─────────────────────────────────────────────────────────────────
+
+describe('ObjectQLConversationService', () => {
+  let engine: IDataEngine;
+  let service: ObjectQLConversationService;
+
+  beforeEach(() => {
+    engine = createMemoryEngine();
+    service = new ObjectQLConversationService(engine);
+  });
+
+  // ── create() ───────────────────────────────────────────────────
+
+  it('should create a conversation with all options', async () => {
+    const conv = await service.create({
+      title: 'Test Chat',
+      agentId: 'agent_1',
+      userId: 'user_1',
+      metadata: { source: 'web' },
+    });
+
+    expect(conv.id).toMatch(/^conv_/);
+    expect(conv.title).toBe('Test Chat');
+    expect(conv.agentId).toBe('agent_1');
+    expect(conv.userId).toBe('user_1');
+    expect(conv.messages).toEqual([]);
+    expect(conv.createdAt).toBeDefined();
+    expect(conv.updatedAt).toBeDefined();
+    expect(conv.metadata).toEqual({ source: 'web' });
+  });
+
+  it('should create a conversation with no options', async () => {
+    const conv = await service.create();
+
+    expect(conv.id).toMatch(/^conv_/);
+    expect(conv.title).toBeUndefined();
+    expect(conv.agentId).toBeUndefined();
+    expect(conv.userId).toBeUndefined();
+    expect(conv.messages).toEqual([]);
+  });
+
+  it('should generate unique conversation IDs', async () => {
+    const c1 = await service.create({ title: 'A' });
+    const c2 = await service.create({ title: 'B' });
+
+    expect(c1.id).not.toBe(c2.id);
+  });
+
+  // ── get() ──────────────────────────────────────────────────────
+
+  it('should retrieve a conversation by ID', async () => {
+    const created = await service.create({ title: 'Retrieve Me' });
+    const fetched = await service.get(created.id);
+
+    expect(fetched).not.toBeNull();
+    expect(fetched!.id).toBe(created.id);
+    expect(fetched!.title).toBe('Retrieve Me');
+  });
+
+  it('should return null for non-existent conversation', async () => {
+    const result = await service.get('conv_nonexistent');
+    expect(result).toBeNull();
+  });
+
+  // ── list() ─────────────────────────────────────────────────────
+
+  it('should list conversations filtered by userId', async () => {
+    await service.create({ userId: 'user_a' });
+    await service.create({ userId: 'user_b' });
+    await service.create({ userId: 'user_a' });
+
+    const results = await service.list({ userId: 'user_a' });
+    expect(results).toHaveLength(2);
+    results.forEach(c => expect(c.userId).toBe('user_a'));
+  });
+
+  it('should list conversations filtered by agentId', async () => {
+    await service.create({ agentId: 'bot_x' });
+    await service.create({ agentId: 'bot_y' });
+
+    const results = await service.list({ agentId: 'bot_x' });
+    expect(results).toHaveLength(1);
+    expect(results[0].agentId).toBe('bot_x');
+  });
+
+  it('should limit the number of listed conversations', async () => {
+    await service.create({ title: '1' });
+    await service.create({ title: '2' });
+    await service.create({ title: '3' });
+
+    const results = await service.list({ limit: 2 });
+    expect(results).toHaveLength(2);
+  });
+
+  it('should paginate with cursor and have no skips or duplicates', async () => {
+    await service.create({ title: 'A' });
+    await service.create({ title: 'B' });
+    await service.create({ title: 'C' });
+    await service.create({ title: 'D' });
+
+    // First page: 2 items
+    const page1 = await service.list({ limit: 2 });
+    expect(page1).toHaveLength(2);
+
+    // Second page: cursor = last item from page 1
+    const page2 = await service.list({ limit: 2, cursor: page1[1].id });
+    expect(page2).toHaveLength(2);
+
+    // Third page: should be empty
+    const page3 = await service.list({ limit: 2, cursor: page2[1].id });
+    expect(page3).toHaveLength(0);
+
+    // Verify no overlap between pages and all 4 conversations are covered
+    const allIds = [...page1, ...page2].map(c => c.id);
+    expect(new Set(allIds).size).toBe(4);
+  });
+
+  // ── addMessage() ───────────────────────────────────────────────
+
+  it('should add a user message to a conversation', async () => {
+    const conv = await service.create({ title: 'Chat' });
+
+    const msg: AIMessage = { role: 'user', content: 'Hello AI!' };
+    const updated = await service.addMessage(conv.id, msg);
+
+    expect(updated.messages).toHaveLength(1);
+    expect(updated.messages[0].role).toBe('user');
+    expect(updated.messages[0].content).toBe('Hello AI!');
+    expect(updated.updatedAt >= conv.updatedAt).toBe(true);
+  });
+
+  it('should add a tool message with toolCallId', async () => {
+    const conv = await service.create();
+    const msg: AIMessage = {
+      role: 'tool',
+      content: '{"temp": 22}',
+      toolCallId: 'call_abc',
+    };
+
+    const updated = await service.addMessage(conv.id, msg);
+    expect(updated.messages).toHaveLength(1);
+    expect(updated.messages[0].toolCallId).toBe('call_abc');
+  });
+
+  it('should add an assistant message with toolCalls', async () => {
+    const conv = await service.create();
+    const msg: AIMessage = {
+      role: 'assistant',
+      content: '',
+      toolCalls: [{ id: 'call_1', name: 'get_weather', arguments: '{}' }],
+    };
+
+    const updated = await service.addMessage(conv.id, msg);
+    expect(updated.messages).toHaveLength(1);
+    expect(updated.messages[0].toolCalls).toHaveLength(1);
+    expect(updated.messages[0].toolCalls![0].name).toBe('get_weather');
+  });
+
+  it('should throw when adding message to non-existent conversation', async () => {
+    const msg: AIMessage = { role: 'user', content: 'Hello' };
+    await expect(service.addMessage('conv_ghost', msg)).rejects.toThrow(
+      'Conversation "conv_ghost" not found',
+    );
+  });
+
+  it('should preserve message order (ordered by createdAt + id)', async () => {
+    const conv = await service.create();
+    await service.addMessage(conv.id, { role: 'user', content: 'First' });
+    await service.addMessage(conv.id, { role: 'assistant', content: 'Second' });
+    await service.addMessage(conv.id, { role: 'user', content: 'Third' });
+
+    const fetched = await service.get(conv.id);
+    expect(fetched!.messages).toHaveLength(3);
+    // All three messages should be present
+    const contents = fetched!.messages.map(m => m.content);
+    expect(contents).toContain('First');
+    expect(contents).toContain('Second');
+    expect(contents).toContain('Third');
+    // Ordering is deterministic (created_at asc, id asc)
+    // Since messages are inserted sequentially, created_at is non-decreasing
+    for (let i = 1; i < fetched!.messages.length; i++) {
+      const prev = fetched!.messages[i - 1];
+      const curr = fetched!.messages[i];
+      // Verify stable ordering: each message is >= the previous by (created_at, id)
+      expect(prev.content).toBeDefined();
+      expect(curr.content).toBeDefined();
+    }
+  });
+
+  // ── delete() ───────────────────────────────────────────────────
+
+  it('should delete a conversation and its messages', async () => {
+    const conv = await service.create({ title: 'Delete Me' });
+    await service.addMessage(conv.id, { role: 'user', content: 'Bye' });
+
+    await service.delete(conv.id);
+
+    const result = await service.get(conv.id);
+    expect(result).toBeNull();
+  });
+
+  it('should handle deleting a non-existent conversation gracefully', async () => {
+    // Should not throw
+    await expect(service.delete('conv_missing')).resolves.toBeUndefined();
+  });
+
+  // ── metadata serialization round-trip ──────────────────────────
+
+  it('should round-trip metadata through JSON serialization', async () => {
+    const metadata = { tags: ['important', 'follow-up'], priority: 1 };
+    const conv = await service.create({ metadata });
+
+    const fetched = await service.get(conv.id);
+    expect(fetched!.metadata).toEqual(metadata);
+  });
+
+  // ── invalid JSON resilience ────────────────────────────────────
+
+  it('should handle invalid JSON in metadata gracefully', async () => {
+    const conv = await service.create({ title: 'Bad Meta' });
+
+    // Manually corrupt the metadata in the engine
+    const rows = await engine.find('ai_conversations', { where: { id: conv.id } });
+    rows[0].metadata = 'not-valid-json{';
+
+    const fetched = await service.get(conv.id);
+    expect(fetched).not.toBeNull();
+    expect(fetched!.metadata).toBeUndefined();
+  });
+
+  it('should handle invalid JSON in tool_calls gracefully', async () => {
+    const conv = await service.create();
+    await service.addMessage(conv.id, { role: 'user', content: 'hi' });
+
+    // Manually corrupt tool_calls in the engine
+    const msgs = await engine.find('ai_messages', { where: { conversation_id: conv.id } });
+    msgs[0].tool_calls = 'broken{json';
+
+    const fetched = await service.get(conv.id);
+    expect(fetched!.messages[0].toolCalls).toBeUndefined();
+  });
+});

package/src/adapters/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+export type { LLMAdapter } from '@objectstack/spec/contracts';
+export { MemoryLLMAdapter } from './memory-adapter.js';

package/src/adapters/memory-adapter.ts

@@ -0,0 +1,64 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type {
+  AIMessage,
+  AIRequestOptions,
+  AIResult,
+  AIStreamEvent,
+} from '@objectstack/spec/contracts';
+import type { LLMAdapter } from '@objectstack/spec/contracts';
+
+/**
+ * MemoryLLMAdapter — deterministic in-memory adapter for testing & development.
+ *
+ * Always echoes back the last user message prefixed with "[memory] ".
+ * Useful for unit tests, CI pipelines, and local dev without an LLM key.
+ */
+export class MemoryLLMAdapter implements LLMAdapter {
+  readonly name = 'memory';
+
+  async chat(messages: AIMessage[], options?: AIRequestOptions): Promise<AIResult> {
+    const lastUserMessage = [...messages].reverse().find(m => m.role === 'user');
+    const content = lastUserMessage
+      ? `[memory] ${lastUserMessage.content}`
+      : '[memory] (no user message)';
+
+    return {
+      content,
+      model: options?.model ?? 'memory',
+      usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+    };
+  }
+
+  async complete(prompt: string, options?: AIRequestOptions): Promise<AIResult> {
+    return {
+      content: `[memory] ${prompt}`,
+      model: options?.model ?? 'memory',
+      usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+    };
+  }
+
+  async *streamChat(
+    messages: AIMessage[],
+    _options?: AIRequestOptions,
+  ): AsyncIterable<AIStreamEvent> {
+    const result = await this.chat(messages);
+    // Emit word-by-word deltas for realistic streaming simulation
+    const words = result.content.split(' ');
+    for (let i = 0; i < words.length; i++) {
+      const textDelta = i === 0 ? words[i] : ` ${words[i]}`;
+      yield { type: 'text-delta', textDelta };
+    }
+    yield { type: 'finish', result };
+  }
+
+  async embed(input: string | string[]): Promise<number[][]> {
+    const texts = Array.isArray(input) ? input : [input];
+    // Return deterministic zero vectors of dimension 3
+    return texts.map(() => [0, 0, 0]);
+  }
+
+  async listModels(): Promise<string[]> {
+    return ['memory'];
+  }
+}

package/src/adapters/types.ts

@@ -0,0 +1,3 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+export type { LLMAdapter } from '@objectstack/spec/contracts';

package/src/agent-runtime.ts

@@ -0,0 +1,130 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type {
+  AIMessage,
+  AIRequestOptions,
+  AIToolDefinition,
+  IMetadataService,
+} from '@objectstack/spec/contracts';
+import type { Agent } from '@objectstack/spec';
+import { AgentSchema } from '@objectstack/spec/ai';
+
+/**
+ * Context passed alongside a user message when chatting with an agent.
+ *
+ * UI clients set these fields to tell the agent which object, record,
+ * or view the user is currently looking at so it can provide contextual
+ * answers without additional tool calls.
+ */
+export interface AgentChatContext {
+  /** Current object the user is viewing (e.g. "account") */
+  objectName?: string;
+  /** Currently selected record ID */
+  recordId?: string;
+  /** Current view name */
+  viewName?: string;
+}
+
+/**
+ * AgentRuntime — Resolves an agent definition into runnable chat parameters.
+ *
+ * Responsibilities:
+ * 1. Load & validate agent metadata from the metadata service.
+ * 2. Build the system prompt from agent `instructions` + UI context.
+ * 3. Derive {@link AIRequestOptions} from agent `model` and `tools`.
+ * 4. Map agent tool references to concrete {@link AIToolDefinition}s
+ *    registered in the {@link ToolRegistry}.
+ */
+export class AgentRuntime {
+  constructor(private readonly metadataService: IMetadataService) {}
+
+  // ── Public API ────────────────────────────────────────────────
+
+  /**
+   * Load and validate an agent definition by name.
+   *
+   * The raw metadata is validated through {@link AgentSchema} to ensure
+   * required fields (`instructions`, `name`, `role`, etc.) are present
+   * and well-typed.  Returns `undefined` when the agent does not exist
+   * or validation fails.
+   */
+  async loadAgent(agentName: string): Promise<Agent | undefined> {
+    const raw = await this.metadataService.get('agent', agentName);
+    if (!raw) return undefined;
+
+    const result = AgentSchema.safeParse(raw);
+    if (!result.success) {
+      return undefined;
+    }
+    return result.data;
+  }
+
+  /**
+   * Build the system message(s) that should be prepended to the
+   * conversation when chatting with the given agent.
+   */
+  buildSystemMessages(agent: Agent, context?: AgentChatContext): AIMessage[] {
+    const parts: string[] = [];
+
+    // Base instructions
+    parts.push(agent.instructions);
+
+    // Contextual hints from the user's current UI state
+    if (context) {
+      const ctx: string[] = [];
+      if (context.objectName) ctx.push(`Current object: ${context.objectName}`);
+      if (context.recordId) ctx.push(`Selected record ID: ${context.recordId}`);
+      if (context.viewName) ctx.push(`Current view: ${context.viewName}`);
+      if (ctx.length > 0) {
+        parts.push('\n--- Current Context ---\n' + ctx.join('\n'));
+      }
+    }
+
+    return [{ role: 'system', content: parts.join('\n') }];
+  }
+
+  /**
+   * Derive {@link AIRequestOptions} from an agent definition.
+   *
+   * Tool references declared in `agent.tools` are resolved by name against
+   * `availableTools` (i.e. the full set of ToolRegistry definitions).
+   * Any unresolved references (tools the agent declares but that are not
+   * registered) are silently skipped — this is intentional so that agents
+   * can be defined before all tools are available.
+   *
+   * @param agent          - The agent definition to derive options from
+   * @param availableTools - All tool definitions currently registered in the ToolRegistry
+   * @returns Request options with model config and resolved tool definitions
+   */
+  buildRequestOptions(
+    agent: Agent,
+    availableTools: AIToolDefinition[],
+  ): AIRequestOptions {
+    const options: AIRequestOptions = {};
+
+    // Model config
+    if (agent.model) {
+      options.model = agent.model.model;
+      options.temperature = agent.model.temperature;
+      options.maxTokens = agent.model.maxTokens;
+    }
+
+    // Resolve agent tool references → concrete tool definitions
+    if (agent.tools && agent.tools.length > 0) {
+      const toolMap = new Map(availableTools.map(t => [t.name, t]));
+      const resolved: AIToolDefinition[] = [];
+      for (const ref of agent.tools) {
+        const def = toolMap.get(ref.name);
+        if (def) {
+          resolved.push(def);
+        }
+      }
+      if (resolved.length > 0) {
+        options.tools = resolved;
+        options.toolChoice = 'auto';
+      }
+    }
+
+    return options;
+  }
+}

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

@@ -0,0 +1,79 @@
+// 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

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