@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/services/graph/core/IGraphProvider.d.ts

@@ -0,0 +1,295 @@
+/**
+ * @fileoverview Interface for graph database providers, plus all core graph primitives.
+ * Defines the contract for vertex/edge CRUD, relationship management, traversal,
+ * and pathfinding that every provider backend must implement.
+ * @module src/services/graph/core/IGraphProvider
+ */
+import type { RequestContext } from '../../../utils/internal/requestContext.js';
+import type { GraphStats } from '../types.js';
+/**
+ * Direction of edge traversal relative to the starting vertex.
+ * - `'out'` — follow outgoing edges only (default)
+ * - `'in'`  — follow incoming edges only
+ * - `'both'` — follow edges in either direction
+ */
+export type TraversalDirection = 'out' | 'in' | 'both';
+/**
+ * Represents a vertex (node) in the graph.
+ *
+ * @example
+ * ```ts
+ * const vertex: Vertex = { id: 'user:alice', table: 'user', data: { name: 'Alice' } };
+ * ```
+ */
+export interface Vertex {
+    /** Arbitrary key-value payload stored on the vertex */
+    data: Record<string, unknown>;
+    /** Unique identifier, typically in `table:id` format (e.g. `"user:alice"`) */
+    id: string;
+    /** Table (collection/type) this vertex belongs to */
+    table: string;
+}
+/**
+ * Represents a directed edge (relationship) between two vertices in the graph.
+ *
+ * @example
+ * ```ts
+ * const edge: Edge = {
+ *   id: 'follows:1',
+ *   table: 'follows',
+ *   from: 'user:alice',
+ *   to: 'user:bob',
+ *   data: { since: '2025-01-01' },
+ * };
+ * ```
+ */
+export interface Edge {
+    /** Arbitrary key-value payload stored on the edge */
+    data: Record<string, unknown>;
+    /** ID of the source (tail) vertex */
+    from: string;
+    /** Unique identifier for this edge */
+    id: string;
+    /** Table (collection/type) this edge belongs to */
+    table: string;
+    /** ID of the target (head) vertex */
+    to: string;
+}
+/**
+ * Options controlling how a relationship edge is created.
+ */
+export interface RelateOptions {
+    /**
+     * When `true`, a new edge is created even if one already exists between
+     * the same pair of vertices with the same table. Defaults to `false`.
+     */
+    allowDuplicates?: boolean;
+    /** Arbitrary key-value payload to store on the created edge */
+    data?: Record<string, unknown>;
+}
+/**
+ * Options controlling how a graph traversal is executed.
+ */
+export interface TraversalOptions {
+    /** Edge direction to follow from each vertex. Defaults to `'out'`. */
+    direction?: TraversalDirection;
+    /** Restrict traversal to edges belonging to these tables. All edge types are followed when omitted. */
+    edgeTypes?: string[];
+    /** Maximum number of hops from the start vertex. Defaults to `1`. */
+    maxDepth?: number;
+    /** Restrict returned vertices to those belonging to these tables. All vertex types are returned when omitted. */
+    vertexTypes?: string[];
+    /** Provider-specific filter expression applied to vertices or edges during traversal */
+    where?: string;
+}
+/**
+ * Result returned by a graph traversal operation.
+ */
+export interface TraversalResult {
+    /** All paths discovered from the starting vertex, up to the configured depth */
+    paths: GraphPath[];
+    /** The resolved starting vertex that was used as the traversal root */
+    start: Vertex;
+}
+/**
+ * A single path through the graph, expressed as an ordered sequence of vertices
+ * and the edges that connect them.
+ */
+export interface GraphPath {
+    /** Edges traversed along the path, in traversal order */
+    edges: Edge[];
+    /** Vertices visited along the path, in traversal order */
+    vertices: Vertex[];
+    /** Cumulative cost of the path, present when a weight function was applied */
+    weight?: number;
+}
+/**
+ * Options for shortest-path and pathfinding queries.
+ */
+export interface PathOptions {
+    /**
+     * Graph search algorithm to apply.
+     * - `'dijkstra'` — weighted shortest path (requires `weightFn`)
+     * - `'bfs'` — unweighted shortest path by hop count (default)
+     * - `'dfs'` — depth-first, finds *a* path but not necessarily the shortest
+     */
+    algorithm?: 'dijkstra' | 'bfs' | 'dfs';
+    /** Maximum number of hops to consider. Unbounded when omitted. */
+    maxLength?: number;
+    /** Returns the numeric cost of traversing the given edge. Required when `algorithm` is `'dijkstra'`. */
+    weightFn?: (edge: Edge) => number;
+}
+/**
+ * Contract that every graph database provider must implement.
+ *
+ * @remarks
+ * Providers must implement relationship creation and deletion, directed edge
+ * queries, graph traversal, pathfinding, statistics, and a health check.
+ * The `GraphService` class delegates all operations to the active provider
+ * through this interface.
+ *
+ * @example
+ * ```ts
+ * class MyProvider implements IGraphProvider {
+ *   readonly name = 'my-provider';
+ *   async relate(from, edgeTable, to, context, options) { ... }
+ *   async unrelate(edgeId, context) { ... }
+ *   // ... remaining methods
+ * }
+ * ```
+ */
+export interface IGraphProvider {
+    /**
+     * Get all incoming edges directed at a vertex.
+     *
+     * @param vertexId - ID of the target vertex
+     * @param context - Request context used for correlated logging
+     * @param edgeTypes - When provided, only edges belonging to these tables are returned
+     * @returns Array of all incoming edges matching the filter, or an empty array if none
+     * @throws {Error} If the underlying provider encounters a storage or query error
+     *
+     * @example
+     * ```ts
+     * const incoming = await provider.getIncomingEdges('user:bob', context, ['follows']);
+     * ```
+     */
+    getIncomingEdges(vertexId: string, context: RequestContext, edgeTypes?: string[]): Promise<Edge[]>;
+    /**
+     * Get all outgoing edges originating from a vertex.
+     *
+     * @param vertexId - ID of the source vertex
+     * @param context - Request context used for correlated logging
+     * @param edgeTypes - When provided, only edges belonging to these tables are returned
+     * @returns Array of all outgoing edges matching the filter, or an empty array if none
+     * @throws {Error} If the underlying provider encounters a storage or query error
+     *
+     * @example
+     * ```ts
+     * const outgoing = await provider.getOutgoingEdges('user:alice', context, ['follows']);
+     * ```
+     */
+    getOutgoingEdges(vertexId: string, context: RequestContext, edgeTypes?: string[]): Promise<Edge[]>;
+    /**
+     * Compute aggregate statistics about the current graph.
+     *
+     * @param context - Request context used for correlated logging
+     * @returns Snapshot of vertex/edge counts and per-type breakdowns
+     * @throws {Error} If the underlying provider cannot compute statistics
+     *
+     * @example
+     * ```ts
+     * const stats = await provider.getStats(context);
+     * console.log(stats.vertexCount, stats.avgDegree);
+     * ```
+     */
+    getStats(context: RequestContext): Promise<GraphStats>;
+    /**
+     * Perform a liveness check on the provider connection.
+     *
+     * @returns `true` if the provider is reachable and operational, `false` otherwise
+     *
+     * @example
+     * ```ts
+     * if (!(await provider.healthCheck())) {
+     *   throw new Error('Graph provider is unhealthy');
+     * }
+     * ```
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * Human-readable identifier for this provider (e.g. `'mock'`, `'surrealdb'`).
+     * Used in logging and diagnostics.
+     */
+    readonly name: string;
+    /**
+     * Determine whether any path exists between two vertices without returning it.
+     * More efficient than `shortestPath` when only reachability is needed.
+     *
+     * @param from - ID of the source vertex
+     * @param to - ID of the target vertex
+     * @param context - Request context used for correlated logging
+     * @param maxDepth - Maximum hop count to search. Unbounded when omitted.
+     * @returns `true` if at least one path exists within the depth limit
+     * @throws {Error} If the underlying provider encounters a storage or query error
+     *
+     * @example
+     * ```ts
+     * const connected = await provider.pathExists('user:alice', 'user:charlie', context, 3);
+     * ```
+     */
+    pathExists(from: string, to: string, context: RequestContext, maxDepth?: number): Promise<boolean>;
+    /**
+     * Create a directed relationship edge between two vertices.
+     *
+     * @param from - ID of the source vertex
+     * @param edgeTable - Table (type) name for the edge (e.g. `'follows'`)
+     * @param to - ID of the target vertex
+     * @param context - Request context used for correlated logging
+     * @param options - Optional payload and duplicate-handling behaviour
+     * @returns The newly created edge
+     * @throws {Error} If either vertex does not exist, or a duplicate is rejected
+     *
+     * @example
+     * ```ts
+     * const edge = await provider.relate('user:alice', 'follows', 'user:bob', context, {
+     *   data: { since: '2025-01-01' },
+     * });
+     * ```
+     */
+    relate(from: string, edgeTable: string, to: string, context: RequestContext, options?: RelateOptions): Promise<Edge>;
+    /**
+     * Find the lowest-cost path between two vertices using the specified algorithm.
+     *
+     * @param from - ID of the source vertex
+     * @param to - ID of the target vertex
+     * @param context - Request context used for correlated logging
+     * @param options - Algorithm selection, depth limit, and optional weight function
+     * @returns The shortest path, or `null` if no path exists within the constraints
+     * @throws {Error} If the underlying provider encounters a storage or query error
+     *
+     * @example
+     * ```ts
+     * const path = await provider.shortestPath('user:alice', 'user:charlie', context, {
+     *   algorithm: 'bfs',
+     *   maxLength: 4,
+     * });
+     * if (path) console.log(`${path.vertices.length} hops`);
+     * ```
+     */
+    shortestPath(from: string, to: string, context: RequestContext, options?: PathOptions): Promise<GraphPath | null>;
+    /**
+     * Traverse the graph outward (or inward/both) from a starting vertex.
+     *
+     * @param startVertexId - ID of the vertex to begin traversal from
+     * @param context - Request context used for correlated logging
+     * @param options - Direction, depth limit, edge/vertex type filters, and WHERE expression
+     * @returns All discovered paths and the resolved start vertex
+     * @throws {Error} If the start vertex does not exist or the provider query fails
+     *
+     * @example
+     * ```ts
+     * const result = await provider.traverse('user:alice', context, {
+     *   maxDepth: 2,
+     *   edgeTypes: ['follows'],
+     *   direction: 'out',
+     * });
+     * console.log(`Found ${result.paths.length} paths`);
+     * ```
+     */
+    traverse(startVertexId: string, context: RequestContext, options?: TraversalOptions): Promise<TraversalResult>;
+    /**
+     * Delete a relationship edge by its ID.
+     *
+     * @param edgeId - ID of the edge to remove
+     * @param context - Request context used for correlated logging
+     * @returns `true` if the edge was found and deleted, `false` if it did not exist
+     * @throws {Error} If the underlying provider encounters a storage error
+     *
+     * @example
+     * ```ts
+     * const deleted = await provider.unrelate('follows:1', context);
+     * ```
+     */
+    unrelate(edgeId: string, context: RequestContext): Promise<boolean>;
+}
+//# sourceMappingURL=IGraphProvider.d.ts.map

package/dist/services/graph/core/IGraphProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IGraphProvider.d.ts","sourceRoot":"","sources":["../../../../src/services/graph/core/IGraphProvider.ts"],"names":[],"mappings":"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"}

package/dist/services/graph/core/IGraphProvider.js

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Interface for graph database providers, plus all core graph primitives.
+ * Defines the contract for vertex/edge CRUD, relationship management, traversal,
+ * and pathfinding that every provider backend must implement.
+ * @module src/services/graph/core/IGraphProvider
+ */
+export {};
+//# sourceMappingURL=IGraphProvider.js.map

package/dist/services/graph/core/IGraphProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IGraphProvider.js","sourceRoot":"","sources":["../../../../src/services/graph/core/IGraphProvider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/services/graph/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview Type definitions for the graph service layer.
+ * Re-exports core graph primitives from IGraphProvider and defines
+ * service-level configuration, statistics, and pattern-matching types.
+ * @module src/services/graph/types
+ */
+export type { Edge, GraphPath, PathOptions, RelateOptions, TraversalDirection, TraversalOptions, TraversalResult, Vertex, } from './core/IGraphProvider.js';
+/**
+ * Discriminated union of supported graph provider backends.
+ * Currently only `'mock'` is available; extend this union when adding real backends.
+ */
+export type GraphProviderType = 'mock';
+/**
+ * Configuration for instantiating the graph service.
+ *
+ * @example
+ * ```ts
+ * const config: GraphServiceConfig = {
+ *   provider: 'mock',
+ *   config: { seedData: true },
+ * };
+ * ```
+ */
+export interface GraphServiceConfig {
+    /** Additional provider-specific configuration passed through to the provider constructor */
+    config?: Record<string, unknown>;
+    /** Which graph provider backend to instantiate */
+    provider: GraphProviderType;
+}
+/**
+ * Aggregate statistics describing the current state of a graph.
+ *
+ * @example
+ * ```ts
+ * const stats: GraphStats = await graphService.getStats(context);
+ * console.log(`${stats.vertexCount} vertices, ${stats.edgeCount} edges`);
+ * console.log(`Avg degree: ${stats.avgDegree}`);
+ * ```
+ */
+export interface GraphStats {
+    /** Mean number of edges per vertex across the entire graph */
+    avgDegree: number;
+    /** Total number of edges (relationships) in the graph */
+    edgeCount: number;
+    /** Map of edge table name to count of edges of that type */
+    edgeTypes: Record<string, number>;
+    /** Total number of vertices (nodes) in the graph */
+    vertexCount: number;
+    /** Map of vertex table name to count of vertices of that type */
+    vertexTypes: Record<string, number>;
+}
+/**
+ * A declarative pattern used to query subgraphs by structural shape.
+ *
+ * @example
+ * ```ts
+ * const pattern: GraphPattern = {
+ *   pattern: '(person)-[knows]->(person)',
+ *   params: { minAge: 18 },
+ * };
+ * ```
+ */
+export interface GraphPattern {
+    /** Named parameters bound into the pattern at query time */
+    params?: Record<string, unknown>;
+    /**
+     * Pattern string describing the structural shape to match.
+     * Uses graph path notation, e.g. `"(person)-[knows]->(person)"`.
+     */
+    pattern: string;
+}
+/**
+ * Result returned by a graph pattern-matching query.
+ *
+ * @example
+ * ```ts
+ * const result: PatternMatchResult = await provider.matchPattern(pattern, context);
+ * console.log(`Found ${result.count} matching subgraphs`);
+ * for (const match of result.matches) {
+ *   console.log(match.vertices.map(v => v.id).join(' -> '));
+ * }
+ * ```
+ */
+export interface PatternMatchResult {
+    /** Total number of subgraph matches found */
+    count: number;
+    /** Each matched subgraph, containing the vertices and edges that satisfied the pattern */
+    matches: Array<{
+        /** Ordered vertices in the matched path */
+        vertices: Array<{
+            id: string;
+            table: string;
+            data: Record<string, unknown>;
+        }>;
+        /** Edges connecting the matched vertices */
+        edges: Array<{
+            id: string;
+            table: string;
+            from: string;
+            to: string;
+            data: Record<string, unknown>;
+        }>;
+        /** Cumulative path weight, if edge weights are defined */
+        weight?: number;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/graph/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/graph/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACV,IAAI,EACJ,SAAS,EACT,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,MAAM,GACP,MAAM,0BAA0B,CAAC;AAElC;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,kDAAkD;IAClD,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,OAAO,EAAE,KAAK,CAAC;QACb,2CAA2C;QAC3C,QAAQ,EAAE,KAAK,CAAC;YACd,EAAE,EAAE,MAAM,CAAC;YACX,KAAK,EAAE,MAAM,CAAC;YACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SAC/B,CAAC,CAAC;QACH,4CAA4C;QAC5C,KAAK,EAAE,KAAK,CAAC;YACX,EAAE,EAAE,MAAM,CAAC;YACX,KAAK,EAAE,MAAM,CAAC;YACd,IAAI,EAAE,MAAM,CAAC;YACb,EAAE,EAAE,MAAM,CAAC;YACX,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SAC/B,CAAC,CAAC;QACH,0DAA0D;QAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ"}

package/dist/services/graph/types.js

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Type definitions for the graph service layer.
+ * Re-exports core graph primitives from IGraphProvider and defines
+ * service-level configuration, statistics, and pattern-matching types.
+ * @module src/services/graph/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/graph/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/graph/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/services/llm/core/ILlmProvider.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview Defines the `ILlmProvider` interface — the contract all LLM provider
+ * implementations must satisfy. Also exports `OpenRouterChatParams`, the union type
+ * representing valid parameters for OpenRouter chat completion requests (both streaming
+ * and non-streaming), derived from the OpenAI SDK types since OpenRouter exposes an
+ * OpenAI-compatible API surface.
+ * @module src/services/llm/core/ILlmProvider
+ */
+import type { ChatCompletion, ChatCompletionChunk, ChatCompletionCreateParamsNonStreaming, ChatCompletionCreateParamsStreaming } from 'openai/resources/chat/completions';
+import type { Stream } from 'openai/streaming';
+import type { RequestContext } from '../../../utils/internal/requestContext.js';
+/**
+ * Union of the OpenAI SDK's non-streaming and streaming chat completion parameter
+ * shapes. OpenRouter accepts the same request structure, so this type covers all
+ * valid call forms. The `stream` discriminant field determines which branch applies
+ * at runtime.
+ *
+ * @example
+ * ```ts
+ * const params: OpenRouterChatParams = {
+ *   model: 'openai/gpt-4o',
+ *   messages: [{ role: 'user', content: 'Hello' }],
+ *   stream: false,
+ * };
+ * ```
+ */
+export type OpenRouterChatParams = ChatCompletionCreateParamsNonStreaming | ChatCompletionCreateParamsStreaming;
+/**
+ * Provider-agnostic interface for interacting with a Large Language Model.
+ * Implementations must support both one-shot and streaming chat completions.
+ * Coding against this interface (rather than a concrete provider) allows the
+ * application to swap providers without changing call sites.
+ */
+export interface ILlmProvider {
+    /**
+     * Sends a chat completion request. Supports both streaming and non-streaming
+     * modes determined by `params.stream`.
+     *
+     * @param params - Chat completion parameters. Set `params.stream = true` to
+     *   receive a `Stream<ChatCompletionChunk>` in return; omit or set `false` for
+     *   a resolved `ChatCompletion` object.
+     * @param context - Request context used for correlated logging and tracing.
+     * @returns A `ChatCompletion` for non-streaming calls, or a
+     *   `Stream<ChatCompletionChunk>` for streaming calls.
+     * @throws {McpError} `ServiceUnavailable` if the upstream provider is
+     *   unreachable, `ConfigurationError` if the client is misconfigured, or
+     *   `RateLimited` if the rate limit is exceeded.
+     *
+     * @example
+     * ```ts
+     * const completion = await provider.chatCompletion(
+     *   { model: 'openai/gpt-4o', messages: [{ role: 'user', content: 'Hi' }] },
+     *   ctx,
+     * ) as ChatCompletion;
+     * console.log(completion.choices[0].message.content);
+     * ```
+     */
+    chatCompletion(params: OpenRouterChatParams, context: RequestContext): Promise<ChatCompletion | Stream<ChatCompletionChunk>>;
+    /**
+     * Sends a streaming chat completion request and returns an async iterable of
+     * chunks. Internally forces `params.stream = true` and logs the full collected
+     * response after the stream is exhausted.
+     *
+     * @param params - Chat completion parameters. The `stream` flag is overridden
+     *   to `true` regardless of what is passed.
+     * @param context - Request context used for correlated logging and tracing.
+     * @returns An async iterable that yields `ChatCompletionChunk` objects as they
+     *   arrive from the provider.
+     * @throws {McpError} `ServiceUnavailable` if the upstream provider is
+     *   unreachable, `ConfigurationError` if the client is misconfigured, or
+     *   `RateLimited` if the rate limit is exceeded.
+     *
+     * @example
+     * ```ts
+     * const stream = await provider.chatCompletionStream(
+     *   { model: 'openai/gpt-4o', messages: [{ role: 'user', content: 'Hi' }] },
+     *   ctx,
+     * );
+     * for await (const chunk of stream) {
+     *   process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+     * }
+     * ```
+     */
+    chatCompletionStream(params: OpenRouterChatParams, context: RequestContext): Promise<AsyncIterable<ChatCompletionChunk>>;
+}
+//# sourceMappingURL=ILlmProvider.d.ts.map

package/dist/services/llm/core/ILlmProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ILlmProvider.d.ts","sourceRoot":"","sources":["../../../../src/services/llm/core/ILlmProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EACV,cAAc,EACd,mBAAmB,EACnB,sCAAsC,EACtC,mCAAmC,EACpC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,oBAAoB,GAC5B,sCAAsC,GACtC,mCAAmC,CAAC;AAExC;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,cAAc,CACZ,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,cAAc,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC,CAAC;IAEzD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,oBAAoB,CAClB,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,mBAAmB,CAAC,CAAC,CAAC;CAChD"}

package/dist/services/llm/core/ILlmProvider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ILlmProvider.js.map

package/dist/services/llm/core/ILlmProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ILlmProvider.js","sourceRoot":"","sources":["../../../../src/services/llm/core/ILlmProvider.ts"],"names":[],"mappings":""}