feat(spec): promote LLMAdapter interface to @objectstack/spec/contracts

Copilot · hotlong · web-flow · commit 2c7ad7d5a89a · 2026-03-31T07:13:20.000Z
- Created packages/spec/src/contracts/llm-adapter.ts with LLMAdapter interface - Added llm-adapter.test.ts with comprehensive type verification tests - Updated contracts/index.ts to export LLMAdapter - Updated service-ai to import LLMAdapter from @objectstack/spec/contracts - Re-export from service-ai for backward compatibility - Updated ROADMAP.md Contract Implementation Matrix - Updated CHANGELOG.md Agent-Logs-Url: https://github.com/objectstack-ai/spec/sessions/265b5e7d-7f35-4751-8340-67374fe4ee78 Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Promoted `LLMAdapter` interface to `@objectstack/spec/contracts`** — Moved the `LLMAdapter`
+  adapter contract from `@objectstack/service-ai` internal types to the canonical protocol layer
+  (`packages/spec/src/contracts/llm-adapter.ts`). Third-party adapter implementations (OpenAI,
+  Anthropic, Ollama, etc.) can now depend solely on `@objectstack/spec` for type alignment.
+  `service-ai` re-exports the interface for backward compatibility.
+
 ### Fixed
 - **ObjectQL build failure** — Fixed TypeScript TS2345 errors in `packages/objectql/src/protocol.ts`
   where `SchemaRegistry.registerItem()` calls failed type checking for the `keyField` parameter.
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -879,7 +879,7 @@ Final polish and advanced features.
 | 15 | Feed Service | `IFeedService` | ✅ | `@objectstack/service-feed` | In-memory feed/chatter (comments, reactions, subscriptions) |
 | 16 | Search Service | `ISearchService` | ❌ | `@objectstack/service-search` (planned) | Spec only |
 | 17 | Notification Service | `INotificationService` | ❌ | `@objectstack/service-notification` (planned) | Spec only |
-| 18 | AI Service | `IAIService` | ✅ | `@objectstack/service-ai` | LLM adapter layer, ToolRegistry, conversation management, REST/SSE routes (52 tests) |
+| 18 | AI Service | `IAIService` | ✅ | `@objectstack/service-ai` | LLM adapter layer (`LLMAdapter` contract in spec), ToolRegistry, conversation management, REST/SSE routes (52 tests) |
 | 19 | Automation Service | `IAutomationService` | ✅ | `@objectstack/service-automation` | DAG engine + HTTP API CRUD + Client SDK + typed returns (67 tests) |
 | 20 | Workflow Service | `IWorkflowService` | ❌ | `@objectstack/service-workflow` (planned) | Spec only |
 | 21 | GraphQL Service | `IGraphQLService` | ❌ | `@objectstack/service-graphql` (planned) | Spec only |
diff --git a/packages/services/service-ai/src/__tests__/ai-service.test.ts b/packages/services/service-ai/src/__tests__/ai-service.test.ts
@@ -8,7 +8,7 @@ import { ToolRegistry } from '../tools/tool-registry.js';
 import { InMemoryConversationService } from '../conversation/in-memory-conversation-service.js';
 import { buildAIRoutes } from '../routes/ai-routes.js';
 import { AIServicePlugin } from '../plugin.js';
-import type { LLMAdapter } from '../adapters/types.js';
+import type { LLMAdapter } from '@objectstack/spec/contracts';
 
 // Suppress logger output in tests
 const silentLogger = {
diff --git a/packages/services/service-ai/src/adapters/index.ts b/packages/services/service-ai/src/adapters/index.ts
@@ -1,4 +1,4 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-export type { LLMAdapter } from './types.js';
+export type { LLMAdapter } from '@objectstack/spec/contracts';
 export { MemoryLLMAdapter } from './memory-adapter.js';
diff --git a/packages/services/service-ai/src/adapters/memory-adapter.ts b/packages/services/service-ai/src/adapters/memory-adapter.ts
@@ -6,7 +6,7 @@ import type {
   AIResult,
   AIStreamEvent,
 } from '@objectstack/spec/contracts';
-import type { LLMAdapter } from './types.js';
+import type { LLMAdapter } from '@objectstack/spec/contracts';
 
 /**
  * MemoryLLMAdapter — deterministic in-memory adapter for testing & development.
diff --git a/packages/services/service-ai/src/adapters/types.ts b/packages/services/service-ai/src/adapters/types.ts
@@ -1,52 +1,3 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import type {
-  AIMessage,
-  AIRequestOptions,
-  AIResult,
-  AIStreamEvent,
-} from '@objectstack/spec/contracts';
-
-/**
- * LLM Provider Adapter Interface
- *
- * Adapters translate between the ObjectStack AI protocol and concrete
- * LLM provider SDKs (OpenAI, Anthropic, Ollama, etc.).
- *
- * Each adapter is a thin wrapper — all orchestration, conversation
- * management, and tool execution logic lives in the AI service layer.
- */
-export interface LLMAdapter {
-  /** Unique adapter identifier (e.g. 'openai', 'anthropic', 'memory') */
-  readonly name: string;
-
-  /**
-   * Generate a chat completion.
-   * @param messages - Conversation messages
-   * @param options  - Request configuration (includes tool definitions)
-   */
-  chat(messages: AIMessage[], options?: AIRequestOptions): Promise<AIResult>;
-
-  /**
-   * Generate a text completion from a single prompt.
-   * @param prompt  - Input prompt string
-   * @param options - Request configuration
-   */
-  complete(prompt: string, options?: AIRequestOptions): Promise<AIResult>;
-
-  /**
-   * Stream a chat completion as an async iterable of events.
-   * Implementations that do not support streaming may omit this method.
-   */
-  streamChat?(messages: AIMessage[], options?: AIRequestOptions): AsyncIterable<AIStreamEvent>;
-
-  /**
-   * Generate embedding vectors.
-   */
-  embed?(input: string | string[], model?: string): Promise<number[][]>;
-
-  /**
-   * List models available through this adapter.
-   */
-  listModels?(): Promise<string[]>;
-}
+export type { LLMAdapter } from '@objectstack/spec/contracts';
diff --git a/packages/services/service-ai/src/ai-service.ts b/packages/services/service-ai/src/ai-service.ts
@@ -7,10 +7,10 @@ import type {
   AIStreamEvent,
   IAIService,
   IAIConversationService,
+  LLMAdapter,
 } from '@objectstack/spec/contracts';
 import type { Logger } from '@objectstack/spec/contracts';
 import { createLogger } from '@objectstack/core';
-import type { LLMAdapter } from './adapters/types.js';
 import { MemoryLLMAdapter } from './adapters/memory-adapter.js';
 import { ToolRegistry } from './tools/tool-registry.js';
 import { InMemoryConversationService } from './conversation/in-memory-conversation-service.js';
diff --git a/packages/services/service-ai/src/index.ts b/packages/services/service-ai/src/index.ts
@@ -10,7 +10,7 @@ export type { AIServicePluginOptions } from './plugin.js';
 
 // Adapters
 export { MemoryLLMAdapter } from './adapters/memory-adapter.js';
-export type { LLMAdapter } from './adapters/types.js';
+export type { LLMAdapter } from '@objectstack/spec/contracts';
 
 // Conversation
 export { InMemoryConversationService } from './conversation/in-memory-conversation-service.js';
diff --git a/packages/services/service-ai/src/plugin.ts b/packages/services/service-ai/src/plugin.ts
@@ -1,10 +1,9 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import type { Plugin, PluginContext } from '@objectstack/core';
-import type { IAIService } from '@objectstack/spec/contracts';
+import type { IAIService, LLMAdapter } from '@objectstack/spec/contracts';
 import { AIService } from './ai-service.js';
 import type { AIServiceConfig } from './ai-service.js';
-import type { LLMAdapter } from './adapters/types.js';
 import { buildAIRoutes } from './routes/ai-routes.js';
 
 /**
diff --git a/packages/spec/src/contracts/index.ts b/packages/spec/src/contracts/index.ts
@@ -29,6 +29,7 @@ export * from './analytics-service.js';
 export * from './realtime-service.js';
 export * from './job-service.js';
 export * from './ai-service.js';
+export * from './llm-adapter.js';
 export * from './i18n-service.js';
 export * from './ui-service.js';
 export * from './workflow-service.js';
diff --git a/packages/spec/src/contracts/llm-adapter.test.ts b/packages/spec/src/contracts/llm-adapter.test.ts
@@ -0,0 +1,147 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import type {
+  LLMAdapter,
+} from './llm-adapter';
+import type {
+  AIMessage,
+  AIRequestOptions,
+  AIResult,
+  AIStreamEvent,
+} from './ai-service';
+
+describe('LLM Adapter Contract', () => {
+  it('should allow a minimal LLMAdapter implementation with required methods', () => {
+    const adapter: LLMAdapter = {
+      name: 'test',
+      chat: async (_messages: AIMessage[], _options?: AIRequestOptions): Promise<AIResult> => ({
+        content: 'hello',
+      }),
+      complete: async (_prompt: string, _options?: AIRequestOptions): Promise<AIResult> => ({
+        content: 'completed',
+      }),
+    };
+
+    expect(adapter.name).toBe('test');
+    expect(typeof adapter.chat).toBe('function');
+    expect(typeof adapter.complete).toBe('function');
+  });
+
+  it('should allow a full implementation with all optional methods', () => {
+    const adapter: LLMAdapter = {
+      name: 'full',
+      chat: async () => ({ content: '' }),
+      complete: async () => ({ content: '' }),
+      async *streamChat(_messages: AIMessage[], _options?: AIRequestOptions): AsyncIterable<AIStreamEvent> {
+        yield { type: 'text-delta', textDelta: 'hi' };
+        yield { type: 'finish', result: { content: 'hi' } };
+      },
+      embed: async (input: string | string[]) => {
+        const texts = Array.isArray(input) ? input : [input];
+        return texts.map(() => [0.1, 0.2, 0.3]);
+      },
+      listModels: async () => ['gpt-4', 'claude-3'],
+    };
+
+    expect(adapter.name).toBe('full');
+    expect(adapter.streamChat).toBeDefined();
+    expect(adapter.embed).toBeDefined();
+    expect(adapter.listModels).toBeDefined();
+  });
+
+  it('should generate a chat completion', async () => {
+    const adapter: LLMAdapter = {
+      name: 'echo',
+      chat: async (messages) => {
+        const last = messages[messages.length - 1];
+        return { content: `Echo: ${last.content}`, model: 'echo' };
+      },
+      complete: async () => ({ content: '' }),
+    };
+
+    const result = await adapter.chat([
+      { role: 'user', content: 'Hello' },
+    ]);
+
+    expect(result.content).toBe('Echo: Hello');
+    expect(result.model).toBe('echo');
+  });
+
+  it('should generate a text completion', async () => {
+    const adapter: LLMAdapter = {
+      name: 'completer',
+      chat: async () => ({ content: '' }),
+      complete: async (prompt) => ({ content: `Done: ${prompt}` }),
+    };
+
+    const result = await adapter.complete('Tell me');
+    expect(result.content).toBe('Done: Tell me');
+  });
+
+  it('should stream chat events', async () => {
+    const adapter: LLMAdapter = {
+      name: 'streamer',
+      chat: async () => ({ content: '' }),
+      complete: async () => ({ content: '' }),
+      async *streamChat() {
+        yield { type: 'text-delta' as const, textDelta: 'Hello' };
+        yield { type: 'text-delta' as const, textDelta: ' world' };
+        yield { type: 'finish' as const, result: { content: 'Hello world' } };
+      },
+    };
+
+    const events: AIStreamEvent[] = [];
+    for await (const event of adapter.streamChat!([], {})) {
+      events.push(event);
+    }
+
+    expect(events).toHaveLength(3);
+    expect(events[0].textDelta).toBe('Hello');
+    expect(events[2].type).toBe('finish');
+  });
+
+  it('should generate embeddings', async () => {
+    const adapter: LLMAdapter = {
+      name: 'embedder',
+      chat: async () => ({ content: '' }),
+      complete: async () => ({ content: '' }),
+      embed: async (input) => {
+        const texts = Array.isArray(input) ? input : [input];
+        return texts.map(() => [0.5, 0.5]);
+      },
+    };
+
+    const embeddings = await adapter.embed!('test');
+    expect(embeddings).toHaveLength(1);
+    expect(embeddings[0]).toEqual([0.5, 0.5]);
+
+    const batch = await adapter.embed!(['a', 'b']);
+    expect(batch).toHaveLength(2);
+  });
+
+  it('should list available models', async () => {
+    const adapter: LLMAdapter = {
+      name: 'lister',
+      chat: async () => ({ content: '' }),
+      complete: async () => ({ content: '' }),
+      listModels: async () => ['model-a', 'model-b'],
+    };
+
+    const models = await adapter.listModels!();
+    expect(models).toHaveLength(2);
+    expect(models).toContain('model-a');
+  });
+
+  it('should have readonly name property', () => {
+    const adapter: LLMAdapter = {
+      name: 'immutable',
+      chat: async () => ({ content: '' }),
+      complete: async () => ({ content: '' }),
+    };
+
+    // The name property is readonly — attempting to assign should fail at compile time
+    // This runtime check verifies the value is accessible
+    expect(adapter.name).toBe('immutable');
+  });
+});
diff --git a/packages/spec/src/contracts/llm-adapter.ts b/packages/spec/src/contracts/llm-adapter.ts
@@ -0,0 +1,58 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * LLMAdapter — LLM Provider Adapter Contract
+ *
+ * Adapters translate between the ObjectStack AI protocol and concrete
+ * LLM provider SDKs (OpenAI, Anthropic, Ollama, etc.).
+ *
+ * Each adapter is a thin wrapper — all orchestration, conversation
+ * management, and tool execution logic lives in the AI service layer.
+ *
+ * Follows Dependency Inversion Principle — third-party adapter packages
+ * depend only on `@objectstack/spec/contracts` for type alignment.
+ *
+ * Aligned with `IAIService` in `ai-service.ts`.
+ */
+
+import type {
+  AIMessage,
+  AIRequestOptions,
+  AIResult,
+  AIStreamEvent,
+} from './ai-service.js';
+
+export interface LLMAdapter {
+  /** Unique adapter identifier (e.g. 'openai', 'anthropic', 'memory') */
+  readonly name: string;
+
+  /**
+   * Generate a chat completion.
+   * @param messages - Conversation messages
+   * @param options  - Request configuration (includes tool definitions)
+   */
+  chat(messages: AIMessage[], options?: AIRequestOptions): Promise<AIResult>;
+
+  /**
+   * Generate a text completion from a single prompt.
+   * @param prompt  - Input prompt string
+   * @param options - Request configuration
+   */
+  complete(prompt: string, options?: AIRequestOptions): Promise<AIResult>;
+
+  /**
+   * Stream a chat completion as an async iterable of events.
+   * Implementations that do not support streaming may omit this method.
+   */
+  streamChat?(messages: AIMessage[], options?: AIRequestOptions): AsyncIterable<AIStreamEvent>;
+
+  /**
+   * Generate embedding vectors.
+   */
+  embed?(input: string | string[], model?: string): Promise<number[][]>;
+
+  /**
+   * List models available through this adapter.
+   */
+  listModels?(): Promise<string[]>;
+}
