@mikesaintsg/core 0.0.1

package/README.md

@@ -0,0 +1,365 @@
+# @mikesaintsg/core
+
+> Shared types, contracts, bridge functions, and adapters for the @mikesaintsg ecosystem.
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Overview
+
+`@mikesaintsg/core` provides the integration layer for the @mikesaintsg ecosystem, including:
+
+- **Shared Types** — Contracts used across multiple packages
+- **Result Pattern** — Functional error handling helpers
+- **Embedding Adapters** — OpenAI, Anthropic (Voyage AI), batched, cached
+- **Tool Format Adapters** — Convert between internal and provider formats
+- **Persistence Adapters** — IndexedDB, OPFS, HTTP for VectorStore
+- **Bridge Functions** — Connect packages without circular dependencies
+
+## Installation
+
+```bash
+npm install @mikesaintsg/core
+```
+
+## Quick Start
+
+### Result Pattern
+
+Handle errors functionally without try/catch:
+
+```typescript
+import { ok, err, isOk, map, chain } from '@mikesaintsg/core'
+import type { Result } from '@mikesaintsg/core'
+
+// Create results
+const success = ok(42)
+const failure = err('NOT_FOUND')
+
+// Check and unwrap
+if (isOk(success)) {
+  console.log(success.value) // 42
+}
+
+// Transform values
+const doubled = map(ok(5), x => x * 2) // ok(10)
+
+// Chain operations
+function parse(s: string): Result<number, string> {
+  const n = parseInt(s, 10)
+  return isNaN(n) ? err('PARSE_ERROR') : ok(n)
+}
+
+const result = chain(ok('42'), parse) // ok(42)
+```
+
+### Tool Call Bridge
+
+Connect LLM tool calls to a tool registry:
+
+```typescript
+import { createToolCallBridge } from '@mikesaintsg/core'
+import type { ToolRegistryMinimal, ToolCall } from '@mikesaintsg/core'
+
+// Create a minimal registry (from contextprotocol or custom)
+const registry: ToolRegistryMinimal = {
+  has: (name) => name === 'get_weather',
+  execute: async (name, args) => {
+    if (name === 'get_weather') {
+      return { temperature: 72, conditions: 'sunny' }
+    }
+    throw new Error('Unknown tool')
+  }
+}
+
+// Create bridge
+const bridge = createToolCallBridge({
+  registry,
+  timeout: 30000,
+  onError: (error, toolCall) => console.error(`Tool ${toolCall.name} failed:`, error),
+})
+
+// Execute tool calls from LLM
+const toolCall: ToolCall = {
+  id: 'call-1',
+  name: 'get_weather',
+  arguments: { location: 'Seattle' },
+}
+
+const result = await bridge.execute(toolCall)
+// { callId: 'call-1', name: 'get_weather', success: true, value: { temperature: 72, conditions: 'sunny' } }
+```
+
+### Retrieval Tool Factory
+
+Create vectorstore-backed tools for RAG:
+
+```typescript
+import { createRetrievalTool } from '@mikesaintsg/core'
+import type { VectorStoreMinimal } from '@mikesaintsg/core'
+
+// Your vectorstore implementation
+const vectorStore: VectorStoreMinimal = {
+  search: async (query, options) => {
+    // Return scored results from your vector database
+    return [
+      { id: '1', content: 'Relevant document', score: 0.95 },
+    ]
+  }
+}
+
+// Create retrieval tool
+const { schema, handler } = createRetrievalTool({
+  vectorStore,
+  name: 'search_knowledge',
+  description: 'Search the knowledge base for relevant information',
+  defaultLimit: 5,
+  scoreThreshold: 0.7,
+})
+
+// Register with your tool registry
+registry.register(schema.name, handler)
+```
+
+### Form Dirty Guard
+
+Prevent navigation when forms have unsaved changes:
+
+```typescript
+import { createFormDirtyGuard } from '@mikesaintsg/core'
+import type { FormMinimal } from '@mikesaintsg/core'
+
+const form: FormMinimal = {
+  isDirty: () => formState.hasUnsavedChanges,
+}
+
+const guard = createFormDirtyGuard({
+  form,
+  confirmFn: (message) => window.confirm(message),
+  message: 'You have unsaved changes. Are you sure you want to leave?',
+  excludePages: ['logout', 'help'],
+})
+
+// Use with your router
+router.beforeNavigate(guard)
+```
+
+### Session Persistence
+
+Persist inference sessions to IndexedDB:
+
+```typescript
+import { createSessionPersistence } from '@mikesaintsg/core'
+import type { MinimalDatabaseAccess } from '@mikesaintsg/core'
+
+// Your database implementation (from @mikesaintsg/indexeddb)
+const database: MinimalDatabaseAccess = createDatabase({ name: 'sessions' })
+
+const persistence = createSessionPersistence({
+  database,
+  storeName: 'chat_sessions',
+  autoprune: 7 * 24 * 60 * 60 * 1000, // 7 days
+})
+
+// Save session
+await persistence.save('session-1', session)
+
+// Load session
+const saved = await persistence.load('session-1')
+
+// List all sessions
+const sessionIds = await persistence.list()
+
+// Prune old sessions
+const prunedCount = await persistence.prune(24 * 60 * 60 * 1000)
+```
+
+### Embedding Adapters
+
+Generate embeddings with OpenAI or Anthropic:
+
+```typescript
+import { 
+  createOpenAIEmbeddingAdapter,
+  createAnthropicEmbeddingAdapter,
+  createBatchedEmbeddingAdapter,
+  createEmbeddingCache,
+} from '@mikesaintsg/core'
+
+// OpenAI adapter
+const openai = createOpenAIEmbeddingAdapter({
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'text-embedding-3-small',
+})
+
+// Anthropic adapter (uses Voyage AI)
+const anthropic = createAnthropicEmbeddingAdapter({
+  apiKey: process.env.VOYAGE_API_KEY,
+  model: 'voyage-2',
+})
+
+// Add batching and caching
+const cache = createEmbeddingCache({ maxEntries: 1000, ttlMs: 3600000 })
+const batched = createBatchedEmbeddingAdapter(openai, {
+  maxBatchSize: 100,
+  flushDelayMs: 50,
+  deduplicate: true,
+  cache,
+})
+
+// Generate embeddings
+const embeddings = await batched.queueBatch([
+  'Hello, world!',
+  'How are you?',
+])
+```
+
+### Tool Format Adapters
+
+Convert tool schemas between formats:
+
+```typescript
+import { 
+  createOpenAIToolFormatAdapter,
+  createAnthropicToolFormatAdapter,
+} from '@mikesaintsg/core'
+import type { ToolSchema } from '@mikesaintsg/core'
+
+const schema: ToolSchema = {
+  name: 'get_weather',
+  description: 'Get the current weather',
+  parameters: {
+    type: 'object',
+    properties: {
+      location: { type: 'string', description: 'City name' },
+    },
+    required: ['location'],
+  },
+}
+
+// OpenAI format
+const openaiAdapter = createOpenAIToolFormatAdapter()
+const openaiTools = openaiAdapter.formatSchemas([schema])
+
+// Anthropic format
+const anthropicAdapter = createAnthropicToolFormatAdapter()
+const anthropicTools = anthropicAdapter.formatSchemas([schema])
+```
+
+### Persistence Adapters
+
+Store VectorStore data in different backends:
+
+```typescript
+import {
+  createIndexedDBVectorStorePersistence,
+  createOPFSVectorStorePersistence,
+  createHTTPVectorStorePersistence,
+} from '@mikesaintsg/core'
+
+// IndexedDB
+const idbPersistence = createIndexedDBVectorStorePersistence({
+  database,
+  documentsStore: 'embeddings',
+})
+
+// OPFS (Origin Private File System)
+const opfsPersistence = createOPFSVectorStorePersistence({
+  directory,
+  chunkSize: 100,
+})
+
+// HTTP (remote storage)
+const httpPersistence = createHTTPVectorStorePersistence({
+  baseURL: 'https://api.example.com/vectors',
+  headers: { Authorization: 'Bearer token' },
+  timeout: 30000,
+})
+```
+
+## API Reference
+
+### Result Pattern
+
+| Function | Description |
+|----------|-------------|
+| `ok(value)` | Create a success result |
+| `err(error)` | Create a failure result |
+| `isOk(result)` | Check if result is success |
+| `isErr(result)` | Check if result is failure |
+| `unwrap(result, default)` | Get value or default |
+| `unwrapOrThrow(result)` | Get value or throw |
+| `map(result, fn)` | Transform success value |
+| `mapErr(result, fn)` | Transform error value |
+| `chain(result, fn)` | Sequence operations |
+
+### Bridge Functions
+
+| Function | Description |
+|----------|-------------|
+| `createToolCallBridge(options)` | Connect tool calls to registry |
+| `createRetrievalTool(options)` | Create vectorstore search tool |
+| `createFormDirtyGuard(options)` | Navigation guard for dirty forms |
+| `createSessionPersistence(options)` | Persist sessions to IndexedDB |
+
+### Embedding Adapters
+
+| Function | Description |
+|----------|-------------|
+| `createOpenAIEmbeddingAdapter(options)` | OpenAI embeddings API |
+| `createAnthropicEmbeddingAdapter(options)` | Voyage AI embeddings |
+| `createBatchedEmbeddingAdapter(adapter, options)` | Batching wrapper |
+| `createEmbeddingCache(options)` | LRU cache with TTL |
+
+### Tool Format Adapters
+
+| Function | Description |
+|----------|-------------|
+| `createOpenAIToolFormatAdapter(options)` | OpenAI tool format |
+| `createAnthropicToolFormatAdapter(options)` | Anthropic tool format |
+
+### Persistence Adapters
+
+| Function | Description |
+|----------|-------------|
+| `createIndexedDBVectorStorePersistence(options)` | IndexedDB storage |
+| `createOPFSVectorStorePersistence(options)` | OPFS storage |
+| `createHTTPVectorStorePersistence(options)` | HTTP storage |
+
+## Types
+
+All types are exported from the main entry point:
+
+```typescript
+import type {
+  // Result pattern
+  Result, Ok, Err,
+  
+  // Embedding types
+  Embedding, EmbeddingAdapterInterface, EmbeddingModelMetadata,
+  
+  // Tool types
+  ToolCall, ToolResult, ToolSchema, JSONSchema7,
+  
+  // Bridge types
+  ToolCallBridgeInterface, ToolRegistryMinimal,
+  RetrievalToolOptions, VectorStoreMinimal,
+  FormDirtyGuardOptions, NavigationGuard,
+  SessionPersistenceInterface, SerializedSession,
+  
+  // Persistence types
+  VectorStorePersistenceAdapterInterface, StoredDocument,
+  
+  // Minimal cross-package interfaces
+  MinimalDatabaseAccess, MinimalStoreAccess,
+  MinimalDirectoryAccess, MinimalFileAccess,
+} from '@mikesaintsg/core'
+```
+
+## License
+
+MIT © mikesaintsg
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.