@mikesaintsg/core 0.0.1 → 0.0.2

package/dist/index.d.ts

@@ -3,43 +3,6 @@ export declare interface AbortableOptions {
     readonly signal?: AbortSignal;
 }
 
-/** Anthropic embedding adapter options */
-export declare interface AnthropicEmbeddingAdapterOptions {
-    readonly apiKey: string;
-    readonly model?: string;
-    readonly baseURL?: string;
-}
-
-/** Anthropic provider adapter options */
-export declare interface AnthropicProviderAdapterOptions {
-    readonly apiKey: string;
-    readonly model?: string;
-    readonly baseURL?: string;
-    readonly defaultOptions?: GenerationDefaults;
-}
-
-/** Anthropic tool schema format */
-export declare interface AnthropicTool {
-    readonly name: string;
-    readonly description: string;
-    readonly input_schema: unknown;
-}
-
-/** Anthropic tool format adapter options */
-export declare interface AnthropicToolFormatAdapterOptions {
-    readonly toolChoice?: 'auto' | 'any' | {
-        readonly name: string;
-    };
-}
-
-/** Anthropic tool use content block */
-export declare interface AnthropicToolUse {
-    readonly type: 'tool_use';
-    readonly id: string;
-    readonly name: string;
-    readonly input: Readonly<Record<string, unknown>>;
-}
-
 /** Batched embedding adapter interface - extends base with batching */
 export declare interface BatchedEmbeddingAdapterInterface extends EmbeddingAdapterInterface {
     queue(text: string, options?: AbortableOptions): Promise<Embedding>;
@@ -130,95 +93,9 @@ export declare class CoreError extends Error {
 /** Core package error codes */
 export declare type CoreErrorCode = 'ADAPTER_ERROR' | 'BRIDGE_ERROR' | 'VALIDATION_ERROR' | 'NOT_FOUND' | 'TIMEOUT' | 'ABORTED';
 
-/**
- * Create an Anthropic-compatible embedding adapter.
- *
- * Note: Anthropic recommends Voyage AI for embeddings, so this adapter
- * uses the Voyage AI API. The apiKey should be a Voyage AI API key.
- *
- * @param options - Adapter configuration
- * @returns An embedding adapter for Anthropic/Voyage
- *
- * @example
- * ```ts
- * const adapter = createAnthropicEmbeddingAdapter({
- *   apiKey: process.env.VOYAGE_API_KEY,
- *   model: 'voyage-2',
- * })
- *
- * const embeddings = await adapter.embed(['Hello, world!'])
- * ```
- */
-export declare function createAnthropicEmbeddingAdapter(options: AnthropicEmbeddingAdapterOptions): EmbeddingAdapterInterface;
-
-/**
- * Create an Anthropic tool format adapter.
- *
- * @param options - Adapter options
- * @returns A tool format adapter for Anthropic
- *
- * @example
- * ```ts
- * const adapter = createAnthropicToolFormatAdapter({
- *   toolChoice: 'auto',
- * })
- *
- * const formatted = adapter.formatSchemas(schemas)
- * const calls = adapter.parseToolCalls(response)
- * ```
- */
-export declare function createAnthropicToolFormatAdapter(_options?: AnthropicToolFormatAdapterOptions): ToolFormatAdapterInterface;
-
-/**
- * Create a batched embedding adapter that wraps any embedding adapter.
- *
- * @param adapter - The base embedding adapter to wrap
- * @param options - Batching configuration options
- * @returns A batched embedding adapter instance
- *
- * @example
- * ```ts
- * const baseAdapter = createOpenAIEmbeddingAdapter({ apiKey: '...' })
- * const cache = createEmbeddingCache({ maxEntries: 1000 })
- *
- * const batched = createBatchedEmbeddingAdapter(baseAdapter, {
- *   maxBatchSize: 100,
- *   flushDelayMs: 50,
- *   deduplicate: true,
- *   cache,
- * })
- *
- * // These will be batched together
- * const [e1, e2] = await Promise.all([
- *   batched.queue('text 1'),
- *   batched.queue('text 2'),
- * ])
- * ```
- */
-export declare function createBatchedEmbeddingAdapter(adapter: EmbeddingAdapterInterface, options?: EmbeddingBatchOptions): BatchedEmbeddingAdapterInterface;
-
 /** Factory function for creating embedding cache */
 export declare type CreateEmbeddingCache = (options?: EmbeddingCacheOptions) => EmbeddingCacheInterface;
 
-/**
- * Create an in-memory embedding cache with LRU eviction.
- *
- * @param options - Cache configuration options
- * @returns An embedding cache instance
- *
- * @example
- * ```ts
- * const cache = createEmbeddingCache({
- *   maxEntries: 1000,
- *   ttlMs: 60 * 60 * 1000, // 1 hour
- * })
- *
- * cache.set('hash123', embedding)
- * const cached = cache.get('hash123')
- * ```
- */
-export declare function createEmbeddingCache(options?: EmbeddingCacheOptions): EmbeddingCacheInterface;
-
 /**
  * Create a navigation guard that prevents leaving when form is dirty.
  *
@@ -245,102 +122,6 @@ export declare function createEmbeddingCache(options?: EmbeddingCacheOptions): E
  */
 export declare function createFormDirtyGuard<TFormData = unknown, TPage extends string = string>(options: FormDirtyGuardOptions<TFormData, TPage>): NavigationGuard<TPage>;
 
-/**
- * Create an HTTP persistence adapter for VectorStore.
- *
- * @param options - Adapter configuration
- * @returns A persistence adapter using HTTP
- *
- * @example
- * ```ts
- * const adapter = createHTTPVectorStorePersistence({
- *   baseURL: 'https://api.example.com/vectors',
- *   headers: { 'Authorization': 'Bearer token' },
- * })
- *
- * await adapter.save({ id: 'doc1', content: 'hello', embedding: new Float32Array([...]) })
- * ```
- */
-export declare function createHTTPVectorStorePersistence(options: HTTPPersistenceOptions): VectorStorePersistenceAdapterInterface;
-
-/**
- * Create an IndexedDB persistence adapter for VectorStore.
- *
- * @param options - Adapter configuration
- * @returns A persistence adapter using IndexedDB
- *
- * @example
- * ```ts
- * import { createDatabase } from '@mikesaintsg/indexeddb'
- *
- * const db = await createDatabase({ name: 'vectors' })
- * const adapter = createIndexedDBVectorStorePersistence({
- *   database: db,
- *   documentsStore: 'embeddings',
- * })
- *
- * await adapter.save({ id: 'doc1', content: 'hello', embedding: new Float32Array([...]) })
- * ```
- */
-export declare function createIndexedDBVectorStorePersistence(options: IndexedDBVectorStorePersistenceOptions): VectorStorePersistenceAdapterInterface;
-
-/**
- * Create an OpenAI embedding adapter.
- *
- * @param options - OpenAI adapter configuration
- * @returns An embedding adapter for OpenAI
- *
- * @example
- * ```ts
- * const adapter = createOpenAIEmbeddingAdapter({
- *   apiKey: process.env.OPENAI_API_KEY,
- *   model: 'text-embedding-3-small',
- * })
- *
- * const embeddings = await adapter.embed(['Hello, world!'])
- * ```
- */
-export declare function createOpenAIEmbeddingAdapter(options: OpenAIEmbeddingAdapterOptions): EmbeddingAdapterInterface;
-
-/**
- * Create an OpenAI tool format adapter.
- *
- * @param options - Adapter options
- * @returns A tool format adapter for OpenAI
- *
- * @example
- * ```ts
- * const adapter = createOpenAIToolFormatAdapter({
- *   toolChoice: 'auto',
- * })
- *
- * const formatted = adapter.formatSchemas(schemas)
- * const calls = adapter.parseToolCalls(response)
- * ```
- */
-export declare function createOpenAIToolFormatAdapter(_options?: OpenAIToolFormatAdapterOptions): ToolFormatAdapterInterface;
-
-/**
- * Create an OPFS persistence adapter for VectorStore.
- *
- * @param options - Adapter configuration
- * @returns A persistence adapter using OPFS
- *
- * @example
- * ```ts
- * import { createDirectory } from '@mikesaintsg/filesystem'
- *
- * const dir = await createDirectory({ name: 'vectors' })
- * const adapter = createOPFSVectorStorePersistence({
- *   directory: dir,
- *   chunkSize: 50,
- * })
- *
- * await adapter.save({ id: 'doc1', content: 'hello', embedding: new Float32Array([...]) })
- * ```
- */
-export declare function createOPFSVectorStorePersistence(options: OPFSVectorStorePersistenceOptions): VectorStorePersistenceAdapterInterface;
-
 /**
  * Create a retrieval tool for use with contextprotocol tool registry.
  *
@@ -432,38 +213,18 @@ export declare interface DeduplicationResult {
 }
 
 /**
- * Deserialize a stored document from JSON storage.
- * Converts array embeddings back to Float32Array.
- *
- * @param data - The plain object from JSON.parse
- * @returns A StoredDocument with proper Float32Array embedding
- *
- * @example
- * ```ts
- * const data = JSON.parse(json)
- * const doc = deserializeStoredDocument(data)
- * ```
+ * Base error class for all ecosystem errors.
+ * All package-specific errors should extend this class.
  */
-export declare function deserializeStoredDocument(data: Record<string, unknown>): StoredDocument;
-
-/** Base ecosystem error */
 export declare abstract class EcosystemError extends Error {
     abstract readonly code: string;
     readonly cause: Error | undefined;
+    constructor(message: string, cause?: Error);
 }
 
 /** Embedding vector */
 export declare type Embedding = Float32Array;
 
-/** Default flush delay in milliseconds for batched embeddings */
-export declare const EMBEDDING_BATCH_DEFAULT_FLUSH_DELAY_MS = 50;
-
-/** Default maximum batch size for embedding requests */
-export declare const EMBEDDING_BATCH_DEFAULT_MAX_SIZE = 100;
-
-/** Default maximum entries for embedding cache */
-export declare const EMBEDDING_CACHE_DEFAULT_MAX_ENTRIES = 1000;
-
 /** Embedding generation contract */
 export declare interface EmbeddingAdapterInterface {
     embed(texts: readonly string[], options?: AbortableOptions): Promise<readonly Embedding[]>;
@@ -545,14 +306,6 @@ export declare function err<E>(error: E): Err<E>;
 /** Extract error code type */
 export declare type ErrorCode<T extends EcosystemError> = T['code'];
 
-/**
- * Estimate the byte size of an embedding.
- *
- * @param embedding - The embedding to measure
- * @returns The byte length of the embedding
- */
-export declare function estimateEmbeddingBytes(embedding: Embedding): number;
-
 /** Default form dirty guard message */
 export declare const FORM_DIRTY_DEFAULT_MESSAGE = "You have unsaved changes. Are you sure you want to leave?";
 
@@ -601,15 +354,13 @@ export declare type FrameType = 'system' | 'instruction' | 'section' | 'file' |
 
 /** Generation defaults for provider adapters */
 export declare interface GenerationDefaults {
+    readonly model?: string;
     readonly temperature?: number;
     readonly maxTokens?: number;
     readonly topP?: number;
     readonly stop?: readonly string[];
 }
 
-/** Default timeout for HTTP persistence requests in milliseconds */
-export declare const HTTP_DEFAULT_TIMEOUT = 30000;
-
 /** HTTP persistence options */
 export declare interface HTTPPersistenceOptions {
     readonly baseURL: string;
@@ -617,12 +368,6 @@ export declare interface HTTPPersistenceOptions {
     readonly timeout?: number;
 }
 
-/** Default documents store name for IndexedDB persistence */
-export declare const INDEXEDDB_DEFAULT_DOCUMENTS_STORE = "documents";
-
-/** Default metadata store name for IndexedDB persistence */
-export declare const INDEXEDDB_DEFAULT_METADATA_STORE = "metadata";
-
 /** IndexedDB VectorStore persistence options */
 export declare interface IndexedDBVectorStorePersistenceOptions {
     readonly database: MinimalDatabaseAccess;
@@ -655,7 +400,23 @@ export declare interface InMemoryEmbeddingCacheOptions {
  */
 export declare function isCoreError(error: unknown): error is CoreError;
 
-/** Type guard for ecosystem errors */
+/**
+ * Type guard for ecosystem errors.
+ *
+ * @param error - The value to check
+ * @returns True if the error is an EcosystemError
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await someOperation()
+ * } catch (error) {
+ *   if (isEcosystemError(error)) {
+ *     console.log('Code:', error.code)
+ *   }
+ * }
+ * ```
+ */
 export declare function isEcosystemError(error: unknown): error is EcosystemError;
 
 /**
@@ -714,14 +475,6 @@ export declare interface JSONSchema7 {
     readonly definitions?: Readonly<Record<string, JSONSchema7>>;
 }
 
-/** Internal LRU cache entry with access tracking */
-export declare interface LRUCacheEntry {
-    readonly embedding: Embedding;
-    readonly createdAt: number;
-    hitCount: number;
-    lastAccess: number;
-}
-
 /**
  * Map a function over a success value.
  *
@@ -823,95 +576,6 @@ export declare interface Ok<T> {
  */
 export declare function ok<T>(value: T): Ok<T>;
 
-/** OpenAI API base URL */
-export declare const OPENAI_API_BASE_URL = "https://api.openai.com/v1";
-
-/** Default dimensions for OpenAI text-embedding-3-small */
-export declare const OPENAI_DEFAULT_EMBEDDING_DIMENSIONS = 1536;
-
-/** Default OpenAI embedding model */
-export declare const OPENAI_DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small";
-
-/** OpenAI embedding adapter options */
-export declare interface OpenAIEmbeddingAdapterOptions {
-    readonly apiKey: string;
-    readonly model?: string;
-    readonly baseURL?: string;
-    readonly dimensions?: number;
-}
-
-/** OpenAI embedding data item */
-export declare interface OpenAIEmbeddingData {
-    readonly object: 'embedding';
-    readonly index: number;
-    readonly embedding: readonly number[];
-}
-
-/** OpenAI embedding API response */
-export declare interface OpenAIEmbeddingResponse {
-    readonly object: 'list';
-    readonly data: readonly OpenAIEmbeddingData[];
-    readonly model: string;
-    readonly usage: OpenAIEmbeddingUsage;
-}
-
-/** OpenAI embedding usage stats */
-export declare interface OpenAIEmbeddingUsage {
-    readonly prompt_tokens: number;
-    readonly total_tokens: number;
-}
-
-/** OpenAI provider adapter options */
-export declare interface OpenAIProviderAdapterOptions {
-    readonly apiKey: string;
-    readonly model?: string;
-    readonly baseURL?: string;
-    readonly organization?: string;
-    readonly defaultOptions?: GenerationDefaults;
-}
-
-/** OpenAI tool schema format */
-export declare interface OpenAITool {
-    readonly type: 'function';
-    readonly function: OpenAIToolFunction;
-}
-
-/** OpenAI tool call from response */
-export declare interface OpenAIToolCall {
-    readonly id: string;
-    readonly type: 'function';
-    readonly function: OpenAIToolCallFunction;
-}
-
-/** OpenAI tool call function */
-export declare interface OpenAIToolCallFunction {
-    readonly name: string;
-    readonly arguments: string;
-}
-
-/** OpenAI tool format adapter options */
-export declare interface OpenAIToolFormatAdapterOptions {
-    readonly toolChoice?: 'auto' | 'none' | 'required' | {
-        readonly name: string;
-    };
-}
-
-/** OpenAI tool function definition */
-export declare interface OpenAIToolFunction {
-    readonly name: string;
-    readonly description: string;
-    readonly parameters: unknown;
-}
-
-/** Default chunk size for OPFS persistence */
-export declare const OPFS_DEFAULT_CHUNK_SIZE = 100;
-
-/** Documents file name prefix for OPFS persistence */
-export declare const OPFS_DOCUMENTS_PREFIX = "chunk_";
-
-/** Metadata file name for OPFS persistence */
-export declare const OPFS_METADATA_FILE = "_metadata.json";
-
 /** OPFS VectorStore persistence options */
 export declare interface OPFSVectorStorePersistenceOptions {
     readonly directory: MinimalDirectoryAccess;
@@ -935,25 +599,6 @@ export declare interface PackageErrorData<TCode extends string> {
     readonly cause?: Error;
 }
 
-/** Pending embedding request in batch queue */
-export declare interface PendingEmbeddingRequest {
-    readonly text: string;
-    readonly contentHash: ContentHash;
-    resolve: (embedding: Embedding) => void;
-    reject: (error: unknown) => void;
-}
-
-/**
- * Provider adapter interface for LLM providers.
- * Implemented by OpenAI, Anthropic, and other provider adapters.
- */
-export declare interface ProviderAdapterInterface {
-    getId(): string;
-    supportsTools(): boolean;
-    supportsStreaming(): boolean;
-    getCapabilities(): ProviderCapabilities;
-}
-
 /** Provider capabilities information */
 export declare interface ProviderCapabilities {
     readonly supportsTools: boolean;
@@ -1012,7 +657,7 @@ export declare interface ScoredResult {
  */
 export declare interface SerializableSession {
     getMessages(): readonly SerializedMessage[];
-    getMetadata(): SessionMetadata;
+    getMetadata(): SerializedSessionMetadata;
 }
 
 /** Serialized message for persistence */
@@ -1027,27 +672,12 @@ export declare interface SerializedMessage {
 export declare interface SerializedSession {
     readonly id: string;
     readonly messages: readonly SerializedMessage[];
-    readonly metadata: SessionMetadata;
+    readonly metadata: SerializedSessionMetadata;
     readonly updatedAt: number;
 }
 
-/**
- * Serialize a stored document for JSON storage.
- * Converts Float32Array embeddings to regular arrays.
- *
- * @param doc - The document to serialize
- * @returns A plain object suitable for JSON.stringify
- *
- * @example
- * ```ts
- * const serialized = serializeStoredDocument(doc)
- * const json = JSON.stringify(serialized)
- * ```
- */
-export declare function serializeStoredDocument(doc: StoredDocument): Record<string, unknown>;
-
-/** Session metadata for persistence */
-export declare interface SessionMetadata {
+/** Serialized session metadata for persistence */
+export declare interface SerializedSessionMetadata {
     readonly model: string;
     readonly provider: string;
     readonly createdAt: number;
@@ -1140,6 +770,7 @@ export declare interface ToolCallBridgeOptions {
 /**
  * Tool format adapter interface.
  * Converts between internal tool representations and provider-specific formats.
+ * Implemented in @mikesaintsg/adapters.
  */
 export declare interface ToolFormatAdapterInterface {
     formatSchemas(schemas: readonly ToolSchema[]): unknown;
@@ -1187,12 +818,6 @@ export declare type TruncationReason = 'budget_exceeded' | 'priority_too_low' |
 /** Truncation strategy */
 export declare type TruncationStrategy = 'priority' | 'fifo' | 'lifo' | 'score' | 'custom';
 
-/**
- * @mikesaintsg/core
- *
- * Type definitions for the core library.
- * All public types and interfaces are defined here as the SOURCE OF TRUTH.
- */
 /** Cleanup function returned by event subscriptions */
 export declare type Unsubscribe = () => void;
 
@@ -1226,9 +851,6 @@ export declare function unwrap<T, E>(result: Result<T, E>, defaultValue: T): T;
  */
 export declare function unwrapOrThrow<T, E>(result: Result<T, E>): T;
 
-/** Metadata key for VectorStore in persistence */
-export declare const VECTORSTORE_METADATA_KEY = "vectorstore_metadata";
-
 /** VectorStore metadata for persistence */
 export declare interface VectorStoreMetadata {
     readonly dimensions: number;
@@ -1267,33 +889,4 @@ export declare interface VectorStoreSearchOptions<TMetadata = unknown> {
     readonly filter?: TMetadata;
 }
 
-/** Voyage AI API base URL */
-export declare const VOYAGE_API_BASE_URL = "https://api.voyageai.com/v1";
-
-/** Default dimensions for Voyage AI voyage-2 */
-export declare const VOYAGE_DEFAULT_EMBEDDING_DIMENSIONS = 1024;
-
-/** Default Voyage AI embedding model (recommended by Anthropic) */
-export declare const VOYAGE_DEFAULT_EMBEDDING_MODEL = "voyage-2";
-
-/** Voyage AI embedding data item */
-export declare interface VoyageEmbeddingData {
-    readonly object: 'embedding';
-    readonly index: number;
-    readonly embedding: readonly number[];
-}
-
-/** Voyage AI embedding API response */
-export declare interface VoyageEmbeddingResponse {
-    readonly object: 'list';
-    readonly data: readonly VoyageEmbeddingData[];
-    readonly model: string;
-    readonly usage: VoyageEmbeddingUsage;
-}
-
-/** Voyage AI embedding usage stats */
-export declare interface VoyageEmbeddingUsage {
-    readonly total_tokens: number;
-}
-
 export { }