@mikesaintsg/core 0.0.1 → 0.0.2

package/README.md

@@ -1,365 +1,175 @@
-# @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.
+# @mikesaintsg/core
+
+> **Shared types, contracts, and bridge functions for the @mikesaintsg ecosystem.**
+
+[![npm version](https://img.shields.io/npm/v/@mikesaintsg/core.svg)](https://www.npmjs.com/package/@mikesaintsg/core)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@mikesaintsg/core)](https://bundlephobia.com/package/@mikesaintsg/core)
+[![license](https://img.shields.io/npm/l/@mikesaintsg/core.svg)](LICENSE)
+
+---
+
+## Features
+
+- ✅ **Shared Types** — Contracts used across multiple packages
+- ✅ **Result Pattern** — Functional error handling (`ok`, `err`, `map`, `chain`)
+- ✅ **Bridge Functions** — Connect packages without circular dependencies
+- ✅ **Interface Definitions** — Embedding, tool format, and persistence adapters
+- ✅ **Zero dependencies** — Built on native platform APIs
+- ✅ **TypeScript first** — Full type safety with generics
+- ✅ **Tree-shakeable** — ESM-only, import what you need
+
+---
+
+## Installation
+
+```bash
+npm install @mikesaintsg/core
+```
+
+---
+
+## Quick Start
+
+```ts
+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)
+```
+
+---
+
+## Documentation
+
+📚 **[Full API Guide](./guides/core.md)** — Comprehensive documentation with examples
+
+### Key Sections
+
+- [Introduction](./guides/core.md#introduction) — Value proposition and use cases
+- [Quick Start](./guides/core.md#quick-start) — Get started in minutes
+- [Core Concepts](./guides/core.md#core-concepts) — Understand the fundamentals
+- [Result Pattern](./guides/core.md#result-pattern) — Functional error handling
+- [Bridge Interfaces](./guides/core.md#bridge-interfaces) — Cross-package communication
+- [API Reference](./guides/core.md#api-reference) — Complete API documentation
+
+---
+
+## API Overview
+
+### Result Functions
+
+| 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       |
+| `map(result, fn)`         | Transform success value    |
+| `chain(result, fn)`       | Chain results (flatMap)    |
+
+### 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)` | Session storage adapter          |
+
+### Shared Types
+
+| Type                         | Description                     |
+|------------------------------|---------------------------------|
+| `Result<T, E>`               | Success or failure union        |
+| `Unsubscribe`                | Cleanup function type           |
+| `EmbeddingAdapterInterface`  | Embedding generation contract   |
+| `ToolFormatAdapterInterface` | Tool format conversion          |
+| `BuiltContext`               | Assembled context for inference |
+
+---
+
+## Examples
+
+### Result Pattern
+
+```ts
+import { ok, err, isOk, unwrap } from '@mikesaintsg/core'
+
+function divide(a: number, b: number) {
+  if (b === 0) return err('DIVISION_BY_ZERO')
+  return ok(a / b)
+}
+
+const result = divide(10, 2)
+const value = unwrap(result, 0) // 5
+```
+
+### Tool Call Bridge
+
+```ts
+import { createToolCallBridge } from '@mikesaintsg/core'
+
+const bridge = createToolCallBridge({
+  registry,
+  timeout: 30000,
+  onError: (error, toolCall) => console.error(error),
+})
+
+const result = await bridge.execute(toolCall)
+```
+
+### With TypeScript
+
+```ts
+import type { 
+  EmbeddingAdapterInterface, 
+  Result 
+} from '@mikesaintsg/core'
+
+// Type-safe adapter interface
+const adapter: EmbeddingAdapterInterface = createAdapter()
+
+// Inferred result types
+function safeParse(input: string): Result<number, 'PARSE_ERROR'> {
+  const n = parseInt(input, 10)
+  return isNaN(n) ? err('PARSE_ERROR') : ok(n)
+}
+```
+
+---
+
+## Ecosystem Integration
+
+| Package                        | Integration                                    |
+|--------------------------------|------------------------------------------------|
+| `@mikesaintsg/adapters`        | Provider and embedding adapter implementations |
+| `@mikesaintsg/inference`       | Uses shared types and bridge functions         |
+| `@mikesaintsg/vectorstore`     | Uses embedding and persistence interfaces      |
+| `@mikesaintsg/contextprotocol` | Uses tool types and registry interface         |
+
+See [Integration Patterns](./guides/core.md#integration-patterns) for details.
+
+---
+
+## License
+
+MIT © [mikesaintsg](https://github.com/mikesaintsg)