ai.matey.types 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/LICENSE +21 -0
  2. package/dist/cjs/adapters.js +16 -0
  3. package/dist/cjs/adapters.js.map +1 -0
  4. package/dist/cjs/bridge.js +32 -0
  5. package/dist/cjs/bridge.js.map +1 -0
  6. package/dist/cjs/errors.js +121 -0
  7. package/dist/cjs/errors.js.map +1 -0
  8. package/dist/cjs/index.js +44 -0
  9. package/dist/cjs/index.js.map +1 -0
  10. package/dist/cjs/ir.js +17 -0
  11. package/dist/cjs/ir.js.map +1 -0
  12. package/dist/cjs/middleware.js +11 -0
  13. package/dist/cjs/middleware.js.map +1 -0
  14. package/dist/cjs/model-runner.js +11 -0
  15. package/dist/cjs/model-runner.js.map +1 -0
  16. package/dist/cjs/model-translation.js +10 -0
  17. package/dist/cjs/model-translation.js.map +1 -0
  18. package/dist/cjs/models.js +11 -0
  19. package/dist/cjs/models.js.map +1 -0
  20. package/dist/cjs/router.js +93 -0
  21. package/dist/cjs/router.js.map +1 -0
  22. package/dist/cjs/streaming.js +28 -0
  23. package/dist/cjs/streaming.js.map +1 -0
  24. package/dist/esm/adapters.js +15 -0
  25. package/dist/esm/adapters.js.map +1 -0
  26. package/dist/esm/bridge.js +29 -0
  27. package/dist/esm/bridge.js.map +1 -0
  28. package/dist/esm/errors.js +118 -0
  29. package/dist/esm/errors.js.map +1 -0
  30. package/dist/esm/index.js +28 -0
  31. package/dist/esm/index.js.map +1 -0
  32. package/dist/esm/ir.js +16 -0
  33. package/dist/esm/ir.js.map +1 -0
  34. package/dist/esm/middleware.js +10 -0
  35. package/dist/esm/middleware.js.map +1 -0
  36. package/dist/esm/model-runner.js +10 -0
  37. package/dist/esm/model-runner.js.map +1 -0
  38. package/dist/esm/model-translation.js +9 -0
  39. package/dist/esm/model-translation.js.map +1 -0
  40. package/dist/esm/models.js +10 -0
  41. package/dist/esm/models.js.map +1 -0
  42. package/dist/esm/router.js +90 -0
  43. package/dist/esm/router.js.map +1 -0
  44. package/dist/esm/streaming.js +25 -0
  45. package/dist/esm/streaming.js.map +1 -0
  46. package/dist/types/adapters.d.ts +377 -0
  47. package/dist/types/adapters.d.ts.map +1 -0
  48. package/dist/types/bridge.d.ts +290 -0
  49. package/dist/types/bridge.d.ts.map +1 -0
  50. package/dist/types/errors.d.ts +380 -0
  51. package/dist/types/errors.d.ts.map +1 -0
  52. package/dist/types/index.d.ts +18 -0
  53. package/dist/types/index.d.ts.map +1 -0
  54. package/dist/types/ir.d.ts +820 -0
  55. package/dist/types/ir.d.ts.map +1 -0
  56. package/dist/types/middleware.d.ts +256 -0
  57. package/dist/types/middleware.d.ts.map +1 -0
  58. package/dist/types/model-runner.d.ts +344 -0
  59. package/dist/types/model-runner.d.ts.map +1 -0
  60. package/dist/types/model-translation.d.ts +76 -0
  61. package/dist/types/model-translation.d.ts.map +1 -0
  62. package/dist/types/models.d.ts +160 -0
  63. package/dist/types/models.d.ts.map +1 -0
  64. package/dist/types/router.d.ts +526 -0
  65. package/dist/types/router.d.ts.map +1 -0
  66. package/dist/types/streaming.d.ts +96 -0
  67. package/dist/types/streaming.d.ts.map +1 -0
  68. package/package.json +64 -0
  69. package/readme.md +84 -0
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Type Definitions
3
+ *
4
+ * All type definitions for the Universal AI Adapter System.
5
+ *
6
+ * @module
7
+ */
8
+ // IR (Intermediate Representation) types
9
+ export * from './ir.js';
10
+ // Adapter interfaces
11
+ export * from './adapters.js';
12
+ // Model types
13
+ export * from './models.js';
14
+ // Error types (type definitions only, implementations in errors/)
15
+ export * from './errors.js';
16
+ // Bridge types
17
+ export * from './bridge.js';
18
+ // Router types
19
+ export * from './router.js';
20
+ // Middleware types
21
+ export * from './middleware.js';
22
+ // Model runner types
23
+ export * from './model-runner.js';
24
+ // Model translation types
25
+ export * from './model-translation.js';
26
+ // Streaming types
27
+ export * from './streaming.js';
28
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,yCAAyC;AACzC,cAAc,SAAS,CAAC;AAExB,qBAAqB;AACrB,cAAc,eAAe,CAAC;AAE9B,cAAc;AACd,cAAc,aAAa,CAAC;AAE5B,kEAAkE;AAClE,cAAc,aAAa,CAAC;AAE5B,eAAe;AACf,cAAc,aAAa,CAAC;AAE5B,eAAe;AACf,cAAc,aAAa,CAAC;AAE5B,mBAAmB;AACnB,cAAc,iBAAiB,CAAC;AAEhC,qBAAqB;AACrB,cAAc,mBAAmB,CAAC;AAElC,0BAA0B;AAC1B,cAAc,wBAAwB,CAAC;AAEvC,kBAAkB;AAClB,cAAc,gBAAgB,CAAC"}
package/dist/esm/ir.js ADDED
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Intermediate Representation (IR) Types
3
+ *
4
+ * The IR is the universal format that sits between frontend and backend adapters.
5
+ * It represents chat requests, responses, and streams in a normalized, provider-agnostic way.
6
+ *
7
+ * Design principles:
8
+ * - Provider-agnostic: No provider-specific fields in core types
9
+ * - Extensible: Support for metadata and custom fields
10
+ * - Type-safe: Use discriminated unions for runtime type checking
11
+ * - Stream-friendly: First-class support for streaming responses
12
+ *
13
+ * @module
14
+ */
15
+ export {};
16
+ //# sourceMappingURL=ir.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ir.js","sourceRoot":"","sources":["../../src/ir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Middleware Function Signatures
3
+ *
4
+ * Middleware provides composable transformation layers for cross-cutting concerns
5
+ * like logging, caching, telemetry, prompt rewriting, and error handling.
6
+ *
7
+ * @module
8
+ */
9
+ export {};
10
+ //# sourceMappingURL=middleware.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Model Runner Backend Types
3
+ *
4
+ * Type definitions for backends that run models locally via subprocess/binary execution.
5
+ * Supports stdio and HTTP communication patterns.
6
+ *
7
+ * @module
8
+ */
9
+ export {};
10
+ //# sourceMappingURL=model-runner.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"model-runner.js","sourceRoot":"","sources":["../../src/model-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Model Translation Types
3
+ *
4
+ * Type definitions for model name translation between AI providers.
5
+ *
6
+ * @module
7
+ */
8
+ export {};
9
+ //# sourceMappingURL=model-translation.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"model-translation.js","sourceRoot":"","sources":["../../src/model-translation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Model Types
3
+ *
4
+ * Types for representing AI models and model listing functionality.
5
+ * Backend adapters can expose available models through the listModels() method.
6
+ *
7
+ * @module
8
+ */
9
+ export {};
10
+ //# sourceMappingURL=models.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"models.js","sourceRoot":"","sources":["../../src/models.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}
@@ -0,0 +1,90 @@
1
+ /**
2
+ * Router Types and Interfaces
3
+ *
4
+ * The Router manages multiple backend adapters and provides intelligent routing,
5
+ * fallback strategies, and parallel dispatch capabilities.
6
+ *
7
+ * @module
8
+ */
9
+ // ============================================================================
10
+ // Router Configuration
11
+ // ============================================================================
12
+ /**
13
+ * Fallback strategies for handling backend failures.
14
+ */
15
+ export const FallbackStrategy = {
16
+ /**
17
+ * No fallback - fail immediately if primary backend fails.
18
+ */
19
+ NONE: 'none',
20
+ /**
21
+ * Try backends sequentially in order until one succeeds.
22
+ */
23
+ SEQUENTIAL: 'sequential',
24
+ /**
25
+ * Try all backends in parallel, return first success.
26
+ */
27
+ PARALLEL: 'parallel',
28
+ /**
29
+ * Use custom fallback logic.
30
+ */
31
+ CUSTOM: 'custom',
32
+ };
33
+ /**
34
+ * Routing strategies for selecting backends.
35
+ */
36
+ export const RoutingStrategy = {
37
+ /**
38
+ * Use backend specified in request options.
39
+ */
40
+ EXPLICIT: 'explicit',
41
+ /**
42
+ * Route based on model name.
43
+ */
44
+ MODEL_BASED: 'model-based',
45
+ /**
46
+ * Route to least-cost backend.
47
+ */
48
+ COST_OPTIMIZED: 'cost-optimized',
49
+ /**
50
+ * Route to fastest backend (lowest latency).
51
+ */
52
+ LATENCY_OPTIMIZED: 'latency-optimized',
53
+ /**
54
+ * Round-robin load balancing.
55
+ */
56
+ ROUND_ROBIN: 'round-robin',
57
+ /**
58
+ * Random backend selection.
59
+ */
60
+ RANDOM: 'random',
61
+ /**
62
+ * Use custom routing logic.
63
+ */
64
+ CUSTOM: 'custom',
65
+ };
66
+ // ============================================================================
67
+ // Parallel Dispatch Options
68
+ // ============================================================================
69
+ /**
70
+ * Strategy for handling parallel dispatch results.
71
+ */
72
+ export const ParallelStrategy = {
73
+ /**
74
+ * Return first successful response, cancel others.
75
+ */
76
+ FIRST: 'first',
77
+ /**
78
+ * Wait for all responses, return array of results.
79
+ */
80
+ ALL: 'all',
81
+ /**
82
+ * Return fastest successful response (with timeout).
83
+ */
84
+ FASTEST: 'fastest',
85
+ /**
86
+ * Use custom aggregation logic.
87
+ */
88
+ CUSTOM: 'custom',
89
+ };
90
+ //# sourceMappingURL=router.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"router.js","sourceRoot":"","sources":["../../src/router.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B;;OAEG;IACH,IAAI,EAAE,MAAM;IAEZ;;OAEG;IACH,UAAU,EAAE,YAAY;IAExB;;OAEG;IACH,QAAQ,EAAE,UAAU;IAEpB;;OAEG;IACH,MAAM,EAAE,QAAQ;CACR,CAAC;AAIX;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B;;OAEG;IACH,QAAQ,EAAE,UAAU;IAEpB;;OAEG;IACH,WAAW,EAAE,aAAa;IAE1B;;OAEG;IACH,cAAc,EAAE,gBAAgB;IAEhC;;OAEG;IACH,iBAAiB,EAAE,mBAAmB;IAEtC;;OAEG;IACH,WAAW,EAAE,aAAa;IAE1B;;OAEG;IACH,MAAM,EAAE,QAAQ;IAEhB;;OAEG;IACH,MAAM,EAAE,QAAQ;CACR,CAAC;AA2SX,+EAA+E;AAC/E,4BAA4B;AAC5B,+EAA+E;AAE/E;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B;;OAEG;IACH,KAAK,EAAE,OAAO;IAEd;;OAEG;IACH,GAAG,EAAE,KAAK;IAEV;;OAEG;IACH,OAAO,EAAE,SAAS;IAElB;;OAEG;IACH,MAAM,EAAE,QAAQ;CACR,CAAC"}
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Streaming Configuration Types
3
+ *
4
+ * Defines how streaming responses should be delivered across the system.
5
+ * Supports flexible streaming modes with delta (incremental) and accumulated (full text) formats.
6
+ *
7
+ * @module
8
+ */
9
+ /**
10
+ * Default streaming configuration.
11
+ */
12
+ export const DEFAULT_STREAMING_CONFIG = {
13
+ mode: 'delta',
14
+ includeBoth: false,
15
+ bufferStrategy: 'memory',
16
+ };
17
+ /**
18
+ * Default conversion options.
19
+ */
20
+ export const DEFAULT_CONVERSION_OPTIONS = {
21
+ mode: 'delta',
22
+ preserveIfMatch: true,
23
+ validateSequence: false,
24
+ };
25
+ //# sourceMappingURL=streaming.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"streaming.js","sourceRoot":"","sources":["../../src/streaming.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA0FH;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAA8B;IACjE,IAAI,EAAE,OAAO;IACb,WAAW,EAAE,KAAK;IAClB,cAAc,EAAE,QAAQ;CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAyD;IAC9F,IAAI,EAAE,OAAO;IACb,eAAe,EAAE,IAAI;IACrB,gBAAgB,EAAE,KAAK;CACxB,CAAC"}
@@ -0,0 +1,377 @@
1
+ /**
2
+ * Frontend and Backend Adapter Interfaces
3
+ *
4
+ * Adapters are the core translation layer between provider-specific formats
5
+ * and the universal Intermediate Representation (IR).
6
+ *
7
+ * Architecture:
8
+ * - Frontend Adapters: Normalize provider-specific requests → IR
9
+ * - Backend Adapters: Transform IR → provider API calls → IR responses
10
+ * - Both implement common interface with metadata for router decisions
11
+ *
12
+ * @module
13
+ */
14
+ import type { IRChatRequest, IRChatResponse, IRChatStream, IRCapabilities } from './ir.js';
15
+ import type { AIModel, ListModelsOptions, ListModelsResult } from './models.js';
16
+ import type { StreamingConfig, StreamConversionOptions } from './streaming.js';
17
+ /**
18
+ * Adapter identification and capability metadata.
19
+ *
20
+ * Used by router for backend selection and compatibility checking.
21
+ */
22
+ export interface AdapterMetadata {
23
+ /**
24
+ * Unique adapter identifier (lowercase, no spaces).
25
+ * Used for routing and logging.
26
+ */
27
+ readonly name: string;
28
+ /**
29
+ * Semantic version of adapter implementation.
30
+ */
31
+ readonly version: string;
32
+ /**
33
+ * Human-readable provider name.
34
+ */
35
+ readonly provider: string;
36
+ /**
37
+ * Adapter capabilities for router decisions.
38
+ */
39
+ readonly capabilities: IRCapabilities;
40
+ /**
41
+ * Optional adapter-specific configuration.
42
+ */
43
+ readonly config?: Record<string, unknown>;
44
+ }
45
+ /**
46
+ * Frontend adapter interface.
47
+ *
48
+ * Frontend adapters represent how developers want to interact with AI APIs.
49
+ * They normalize provider-specific request formats into universal IR and
50
+ * denormalize IR responses back to provider-specific formats.
51
+ *
52
+ * @template TRequest Provider-specific request type
53
+ * @template TResponse Provider-specific response type
54
+ * @template TStreamChunk Provider-specific stream chunk type
55
+ */
56
+ export interface FrontendAdapter<TRequest = unknown, TResponse = unknown, TStreamChunk = unknown> {
57
+ /**
58
+ * Adapter metadata for identification and capabilities.
59
+ */
60
+ readonly metadata: AdapterMetadata;
61
+ /**
62
+ * Convert provider-specific request to universal IR.
63
+ *
64
+ * @param request Provider-specific request object
65
+ * @returns Universal IR request
66
+ * @throws {ValidationError} If request is invalid for this provider
67
+ * @throws {AdapterConversionError} If conversion fails
68
+ */
69
+ toIR(request: TRequest): Promise<IRChatRequest>;
70
+ /**
71
+ * Convert universal IR response to provider-specific format.
72
+ *
73
+ * @param response Universal IR response
74
+ * @returns Provider-specific response object
75
+ * @throws {AdapterConversionError} If conversion fails
76
+ */
77
+ fromIR(response: IRChatResponse): Promise<TResponse>;
78
+ /**
79
+ * Convert universal IR stream to provider-specific stream format.
80
+ *
81
+ * @param stream Universal IR stream
82
+ * @param options Optional stream conversion options (mode, transform, etc.)
83
+ * @returns Provider-specific stream of chunks
84
+ * @throws {StreamError} If stream processing fails
85
+ */
86
+ fromIRStream(stream: IRChatStream, options?: StreamConversionOptions): AsyncGenerator<TStreamChunk, void, undefined>;
87
+ /**
88
+ * Optional: Validate provider-specific request before conversion.
89
+ *
90
+ * @param request Provider-specific request
91
+ * @throws {ValidationError} If request is invalid
92
+ */
93
+ validate?(request: TRequest): Promise<void>;
94
+ }
95
+ /**
96
+ * Configuration options for backend adapters.
97
+ */
98
+ export interface BackendAdapterConfig {
99
+ /**
100
+ * API key for authentication.
101
+ * Should be injected from environment or secure config.
102
+ */
103
+ readonly apiKey: string;
104
+ /**
105
+ * Base URL for API endpoint.
106
+ * Useful for proxies or alternative endpoints.
107
+ */
108
+ readonly baseURL?: string;
109
+ /**
110
+ * Request timeout in milliseconds.
111
+ * @default 30000
112
+ */
113
+ readonly timeout?: number;
114
+ /**
115
+ * Maximum number of retries for transient failures.
116
+ * @default 0
117
+ */
118
+ readonly maxRetries?: number;
119
+ /**
120
+ * Enable debug logging.
121
+ * @default false
122
+ */
123
+ readonly debug?: boolean;
124
+ /**
125
+ * Custom HTTP headers to include in requests.
126
+ */
127
+ readonly headers?: Record<string, string>;
128
+ /**
129
+ * Provider-specific configuration options.
130
+ */
131
+ readonly custom?: Record<string, unknown>;
132
+ /**
133
+ * Enable browser-compatible mode.
134
+ *
135
+ * ⚠️ **SECURITY WARNING**: Enabling browser mode may expose API keys in client-side code.
136
+ * This option should ONLY be used for development and testing. Production applications
137
+ * should always use proxy servers to protect API keys.
138
+ *
139
+ * Each provider implements browser compatibility differently:
140
+ * - **Anthropic**: Adds `anthropic-dangerous-direct-browser-access: true` header
141
+ * - **Gemini**: Already browser-compatible (API key in URL), this flag has no effect
142
+ * - **OpenAI**: Already browser-compatible, this flag has no effect
143
+ * - **Other providers**: May have provider-specific implementations
144
+ *
145
+ * @default false
146
+ * @example
147
+ * ```typescript
148
+ * // Development only - DO NOT use in production!
149
+ * const backend = new AnthropicBackendAdapter({
150
+ * apiKey: process.env.ANTHROPIC_API_KEY,
151
+ * browserMode: true // ⚠️ Exposes API key in browser
152
+ * });
153
+ * ```
154
+ */
155
+ readonly browserMode?: boolean;
156
+ /**
157
+ * Default model to use when no model is specified in the request.
158
+ * This provides a fallback model for requests that don't specify one.
159
+ *
160
+ * @example 'gpt-4o' for OpenAI, 'claude-3-5-sonnet-20241022' for Anthropic
161
+ */
162
+ readonly defaultModel?: string;
163
+ /**
164
+ * Static model list (used when provider doesn't have listing endpoint
165
+ * or to override remote list).
166
+ *
167
+ * Can be either:
168
+ * - Array of model IDs (strings) - will be normalized to AIModel objects
169
+ * - Array of full AIModel objects with capabilities
170
+ */
171
+ readonly models?: readonly (string | AIModel)[];
172
+ /**
173
+ * URL endpoint for fetching models (overrides default).
174
+ * Used for custom model endpoints or proxies.
175
+ */
176
+ readonly modelsEndpoint?: string;
177
+ /**
178
+ * Enable model list caching.
179
+ * @default true
180
+ */
181
+ readonly cacheModels?: boolean;
182
+ /**
183
+ * Cache TTL in milliseconds.
184
+ * @default 3600000 (1 hour)
185
+ */
186
+ readonly modelsCacheTTL?: number;
187
+ /**
188
+ * Cache scope strategy.
189
+ * - 'global': Share cache across all adapter instances (default)
190
+ * - 'instance': Each adapter instance has its own cache
191
+ * @default 'global'
192
+ */
193
+ readonly modelsCacheScope?: 'global' | 'instance';
194
+ /**
195
+ * Streaming configuration for this backend.
196
+ *
197
+ * Controls how streaming responses are delivered:
198
+ * - mode: 'delta' (incremental only) or 'accumulated' (full text each chunk)
199
+ * - includeBoth: Whether to provide both delta and accumulated in chunks
200
+ * - bufferStrategy: How to buffer for accumulated mode
201
+ *
202
+ * @default { mode: 'delta', includeBoth: false, bufferStrategy: 'memory' }
203
+ */
204
+ readonly streaming?: StreamingConfig;
205
+ }
206
+ /**
207
+ * Backend adapter interface.
208
+ *
209
+ * Backend adapters handle actual API calls to AI providers. They transform
210
+ * universal IR into provider-specific API requests and normalize responses
211
+ * back to IR.
212
+ *
213
+ * @template TRequest Provider-specific request type
214
+ * @template TResponse Provider-specific response type
215
+ */
216
+ export interface BackendAdapter<TRequest = unknown, TResponse = unknown> {
217
+ /**
218
+ * Adapter metadata for identification and capabilities.
219
+ */
220
+ readonly metadata: AdapterMetadata;
221
+ /**
222
+ * Convert universal IR request to provider-specific format.
223
+ *
224
+ * Useful for:
225
+ * - Debugging: Inspect what will be sent to the provider
226
+ * - Testing: Test conversion logic without making API calls
227
+ * - Transparency: See provider-specific request structure
228
+ *
229
+ * @param request Universal IR request
230
+ * @returns Provider-specific request object
231
+ * @throws {ValidationError} If request is invalid for this provider
232
+ * @throws {AdapterConversionError} If conversion fails
233
+ */
234
+ fromIR(request: IRChatRequest): TRequest;
235
+ /**
236
+ * Convert provider-specific response to universal IR.
237
+ *
238
+ * Useful for:
239
+ * - Testing: Convert mock provider responses to IR
240
+ * - Debugging: Parse provider responses manually
241
+ * - Format conversion: Use backend as response converter
242
+ *
243
+ * @param response Provider-specific response object
244
+ * @param originalRequest Original IR request (for context)
245
+ * @param latencyMs Request latency in milliseconds
246
+ * @returns Universal IR response
247
+ * @throws {AdapterConversionError} If conversion fails
248
+ */
249
+ toIR(response: TResponse, originalRequest: IRChatRequest, latencyMs: number): IRChatResponse;
250
+ /**
251
+ * Execute non-streaming chat completion request.
252
+ *
253
+ * @param request Universal IR request
254
+ * @param signal Optional AbortSignal for cancellation
255
+ * @returns Universal IR response
256
+ * @throws {AuthenticationError} If API key is invalid
257
+ * @throws {ValidationError} If request is invalid for this provider
258
+ * @throws {ProviderError} If provider API returns error
259
+ * @throws {NetworkError} If network request fails
260
+ * @throws {AdapterConversionError} If response parsing fails
261
+ */
262
+ execute(request: IRChatRequest, signal?: AbortSignal): Promise<IRChatResponse>;
263
+ /**
264
+ * Execute streaming chat completion request.
265
+ *
266
+ * @param request Universal IR request
267
+ * @param signal Optional AbortSignal for cancellation
268
+ * @returns Universal IR stream of chunks
269
+ * @throws {AuthenticationError} If API key is invalid
270
+ * @throws {ValidationError} If request is invalid for this provider
271
+ * @throws {ProviderError} If provider API returns error
272
+ * @throws {NetworkError} If network request fails
273
+ * @throws {StreamError} If stream parsing or processing fails
274
+ */
275
+ executeStream(request: IRChatRequest, signal?: AbortSignal): IRChatStream;
276
+ /**
277
+ * Optional: Health check to verify backend is available.
278
+ *
279
+ * @returns true if backend is healthy and available
280
+ */
281
+ healthCheck?(): Promise<boolean>;
282
+ /**
283
+ * Optional: Estimate cost for a request.
284
+ *
285
+ * @param request IR request to estimate cost for
286
+ * @returns Estimated cost in USD (or null if unavailable)
287
+ */
288
+ estimateCost?(request: IRChatRequest): Promise<number | null>;
289
+ /**
290
+ * Optional: List available models from this backend.
291
+ *
292
+ * Behavior depends on provider:
293
+ * - Providers with API endpoints (OpenAI, Groq): Fetch from API with caching
294
+ * - Providers without endpoints (Anthropic): Return static list from config or defaults
295
+ * - Can be overridden via config.models or config.modelsEndpoint
296
+ *
297
+ * @param options Options for listing models (filtering, cache control)
298
+ * @returns List of available models with metadata
299
+ * @throws {ProviderError} If remote fetch fails
300
+ * @throws {NetworkError} If network request fails
301
+ */
302
+ listModels?(options?: ListModelsOptions): Promise<ListModelsResult>;
303
+ }
304
+ /**
305
+ * Registry for managing available adapters.
306
+ *
307
+ * Used internally by routers and bridges to discover and instantiate adapters.
308
+ */
309
+ export interface AdapterRegistry {
310
+ /**
311
+ * Register a frontend adapter type.
312
+ *
313
+ * @param name Unique adapter identifier
314
+ * @param adapterClass Frontend adapter constructor
315
+ */
316
+ registerFrontend<T extends FrontendAdapter>(name: string, adapterClass: new () => T): void;
317
+ /**
318
+ * Register a backend adapter type.
319
+ *
320
+ * @param name Unique adapter identifier
321
+ * @param adapterClass Backend adapter constructor
322
+ */
323
+ registerBackend<T extends BackendAdapter>(name: string, adapterClass: new (config: BackendAdapterConfig) => T): void;
324
+ /**
325
+ * Get frontend adapter instance by name.
326
+ *
327
+ * @param name Adapter identifier
328
+ * @returns Frontend adapter instance
329
+ * @throws {Error} If adapter not found
330
+ */
331
+ getFrontend(name: string): FrontendAdapter;
332
+ /**
333
+ * Get backend adapter instance by name.
334
+ *
335
+ * @param name Adapter identifier
336
+ * @param config Backend configuration
337
+ * @returns Backend adapter instance
338
+ * @throws {Error} If adapter not found
339
+ */
340
+ getBackend(name: string, config: BackendAdapterConfig): BackendAdapter;
341
+ /**
342
+ * List all registered frontend adapters.
343
+ */
344
+ listFrontends(): string[];
345
+ /**
346
+ * List all registered backend adapters.
347
+ */
348
+ listBackends(): string[];
349
+ /**
350
+ * Check if frontend adapter is registered.
351
+ */
352
+ hasFrontend(name: string): boolean;
353
+ /**
354
+ * Check if backend adapter is registered.
355
+ */
356
+ hasBackend(name: string): boolean;
357
+ }
358
+ /**
359
+ * Adapter pair for type-safe frontend/backend combinations.
360
+ */
361
+ export type AdapterPair<TFrontend extends FrontendAdapter = FrontendAdapter, TBackend extends BackendAdapter = BackendAdapter> = {
362
+ readonly frontend: TFrontend;
363
+ readonly backend: TBackend;
364
+ };
365
+ /**
366
+ * Infer provider request type from frontend adapter.
367
+ */
368
+ export type InferFrontendRequest<T extends FrontendAdapter> = T extends FrontendAdapter<infer TRequest, any, any> ? TRequest : never;
369
+ /**
370
+ * Infer provider response type from frontend adapter.
371
+ */
372
+ export type InferFrontendResponse<T extends FrontendAdapter> = T extends FrontendAdapter<any, infer TResponse, any> ? TResponse : never;
373
+ /**
374
+ * Infer provider stream chunk type from frontend adapter.
375
+ */
376
+ export type InferFrontendStreamChunk<T extends FrontendAdapter> = T extends FrontendAdapter<any, any, infer TStreamChunk> ? TStreamChunk : never;
377
+ //# sourceMappingURL=adapters.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../../src/adapters.ts"],"names":[],"mappings":"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"}