@seizn/summer 0.1.0

package/README.md

@@ -0,0 +1,278 @@
+# @seizn/summer
+
+RAG Infrastructure SDK for AI Applications. Build production-ready retrieval-augmented generation systems with vector search, hybrid search, and answer generation.
+
+## Installation
+
+```bash
+npm install @seizn/summer
+# or
+yarn add @seizn/summer
+# or
+pnpm add @seizn/summer
+```
+
+## Quick Start
+
+```typescript
+import { SummerClient } from '@seizn/summer';
+
+const summer = new SummerClient({
+  apiKey: process.env.SEIZN_API_KEY!,
+});
+
+// Create a collection
+const collection = await summer.createCollection({
+  name: 'my-docs',
+  description: 'My document collection',
+});
+
+// Index documents
+await summer.index({
+  collectionId: collection.id,
+  content: 'Your document content here...',
+  metadata: { source: 'my-app' },
+});
+
+// Search
+const results = await summer.search({
+  collectionId: collection.id,
+  query: 'What is machine learning?',
+  mode: 'hybrid',
+  rerank: true,
+});
+
+// RAG query
+const answer = await summer.ask(collection.id, 'Explain machine learning');
+console.log(answer.answer);
+```
+
+## Features
+
+- **Document Indexing**: Automatic chunking and embedding with configurable strategies
+- **Hybrid Search**: Combine vector similarity and keyword search
+- **Reranking**: Cross-encoder reranking for improved relevance
+- **Federated Search**: Search across multiple collections and sources
+- **RAG Query**: Generate answers with citations from your documents
+- **Analytics**: Track search performance and usage
+
+## API Reference
+
+### Configuration
+
+```typescript
+const summer = new SummerClient({
+  apiKey: 'szn_...',           // Required: Your Seizn API key
+  baseUrl: 'https://seizn.com/api/summer',  // Optional: API base URL
+  timeout: 60000,              // Optional: Request timeout (ms)
+  retries: 3,                  // Optional: Max retry attempts
+  onError: (error) => {},      // Optional: Error callback
+});
+```
+
+### Collection Management
+
+```typescript
+// Create collection
+const collection = await summer.createCollection({
+  name: 'my-collection',
+  description: 'Optional description',
+  embeddingModel: 'voyage-3', // or 'voyage-3-lite'
+});
+
+// List collections
+const collections = await summer.listCollections();
+
+// Get collection
+const collection = await summer.getCollection('col_123');
+
+// Delete collection
+await summer.deleteCollection('col_123');
+
+// Get statistics
+const stats = await summer.getCollectionStats('col_123');
+```
+
+### Document Indexing
+
+```typescript
+// Index single document
+const result = await summer.index({
+  collectionId: 'col_123',
+  content: 'Document text...',
+  title: 'Document Title',
+  externalId: 'doc-001',
+  metadata: { source: 'api', category: 'tech' },
+  chunkingStrategy: 'semantic', // 'fixed' | 'semantic' | 'paragraph'
+  chunkSize: 512,
+  chunkOverlap: 50,
+});
+
+// Bulk index
+const result = await summer.bulkIndex({
+  collectionId: 'col_123',
+  documents: [
+    { content: 'Doc 1...', title: 'Title 1' },
+    { content: 'Doc 2...', title: 'Title 2' },
+  ],
+});
+
+// Get document
+const doc = await summer.getDocument('doc_123');
+
+// Delete document
+await summer.deleteDocument('doc_123');
+```
+
+### Search
+
+```typescript
+// Full search options
+const results = await summer.search({
+  collectionId: 'col_123',
+  query: 'machine learning applications',
+  topK: 10,
+  threshold: 0.7,
+  mode: 'hybrid',      // 'vector' | 'keyword' | 'hybrid'
+  rerank: true,
+  rerankTopN: 5,
+  filter: { category: 'tech' },
+  includeMetadata: true,
+});
+
+// Quick search shorthand
+const results = await summer.query('col_123', 'my query', {
+  topK: 10,
+  mode: 'hybrid',
+  rerank: true,
+});
+
+// Access results
+results.results.forEach((r) => {
+  console.log(`${r.title}: ${r.similarity}`);
+});
+
+// Timings
+console.log(`Search took ${results.timings.totalMs}ms`);
+```
+
+### Federated Search
+
+```typescript
+const results = await summer.federatedSearch({
+  query: 'machine learning',
+  sources: ['col_123', 'col_456'], // Optional: specific sources
+  topK: 20,
+  mode: 'hybrid',
+  rerank: true,
+  dedupe: true,
+});
+
+// Source statistics
+results.sourceStats.forEach((s) => {
+  console.log(`${s.sourceId}: ${s.resultsCount} results in ${s.latencyMs}ms`);
+});
+```
+
+### RAG Query
+
+```typescript
+// Full RAG options
+const answer = await summer.rag({
+  collectionId: 'col_123',
+  query: 'What is machine learning?',
+  systemPrompt: 'You are a helpful assistant.',
+  contextLimit: 8000,
+  citationStyle: 'inline', // 'inline' | 'footnote' | 'none'
+  model: 'claude-sonnet',  // 'claude-sonnet' | 'claude-haiku'
+});
+
+// Quick ask shorthand
+const answer = await summer.ask('col_123', 'What is machine learning?');
+
+// Access answer
+console.log(answer.answer);
+
+// Access citations
+answer.citations.forEach((c) => {
+  console.log(`[${c.id}] ${c.title}: ${c.relevance}`);
+});
+
+// Usage stats
+console.log(`Tokens: ${answer.usage.totalTokens}`);
+```
+
+### Utilities
+
+```typescript
+// Generate embeddings
+const embeddings = await summer.embed(['text 1', 'text 2']);
+
+// Rerank results
+const ranked = await summer.rerank('query', [
+  { id: '1', text: 'Document 1' },
+  { id: '2', text: 'Document 2' },
+], 5);
+```
+
+### Analytics
+
+```typescript
+const analytics = await summer.getAnalytics('col_123', 'week');
+
+console.log(`Total searches: ${analytics.totalSearches}`);
+console.log(`Avg latency: ${analytics.averageLatencyMs}ms`);
+console.log('Top queries:', analytics.topQueries);
+```
+
+## Error Handling
+
+```typescript
+import { SummerClient, SummerError } from '@seizn/summer';
+
+const summer = new SummerClient({
+  apiKey: 'szn_...',
+  onError: (error: SummerError) => {
+    console.error(`Error [${error.code}]: ${error.message}`);
+  },
+});
+
+try {
+  await summer.search({ collectionId: 'col_123', query: 'test' });
+} catch (error) {
+  const err = error as SummerError;
+  if (err.code === 'RATE_LIMITED') {
+    // Handle rate limiting
+  } else if (err.code === 'NOT_FOUND') {
+    // Collection doesn't exist
+  }
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  Collection,
+  Document,
+  SearchRequest,
+  SearchResponse,
+  SearchResult,
+  RAGQueryResponse,
+  Citation,
+  SummerClientConfig,
+  SummerError,
+} from '@seizn/summer';
+```
+
+## License
+
+MIT - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [Documentation](https://docs.seizn.com/summer)
+- [API Reference](https://docs.seizn.com/api-reference)
+- [GitHub](https://github.com/iruhana/seizn)

package/dist/index.d.mts

@@ -0,0 +1,327 @@
+/**
+ * Seizn Summer SDK - External Client Types
+ *
+ * Type definitions for external applications to integrate with
+ * Seizn's Summer RAG infrastructure.
+ */
+interface Collection {
+    id: string;
+    name: string;
+    description?: string;
+    documentCount: number;
+    embeddingDimensions: number;
+    createdAt: string;
+    updatedAt?: string;
+}
+interface CreateCollectionRequest {
+    name: string;
+    description?: string;
+    embeddingModel?: 'voyage-3' | 'voyage-3-lite';
+}
+interface CreateCollectionResponse {
+    success: boolean;
+    collection: Collection;
+}
+interface Document {
+    id: string;
+    collectionId: string;
+    externalId?: string;
+    title?: string;
+    content: string;
+    metadata: Record<string, unknown>;
+    chunkCount: number;
+    createdAt: string;
+    updatedAt?: string;
+}
+interface IndexDocumentRequest {
+    collectionId: string;
+    externalId?: string;
+    title?: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+    chunkingStrategy?: 'fixed' | 'semantic' | 'paragraph';
+    chunkSize?: number;
+    chunkOverlap?: number;
+}
+interface IndexDocumentResponse {
+    success: boolean;
+    document: Document;
+    chunksCreated: number;
+}
+interface BulkIndexRequest {
+    collectionId: string;
+    documents: Array<{
+        externalId?: string;
+        title?: string;
+        content: string;
+        metadata?: Record<string, unknown>;
+    }>;
+    chunkingStrategy?: 'fixed' | 'semantic' | 'paragraph';
+}
+interface BulkIndexResponse {
+    success: boolean;
+    indexed: number;
+    failed: number;
+    errors?: Array<{
+        index: number;
+        error: string;
+    }>;
+}
+type SearchMode = 'vector' | 'keyword' | 'hybrid';
+interface SearchRequest {
+    collectionId: string;
+    query: string;
+    topK?: number;
+    threshold?: number;
+    mode?: SearchMode;
+    rerank?: boolean;
+    rerankTopN?: number;
+    filter?: Record<string, unknown>;
+    includeMetadata?: boolean;
+}
+interface SearchResult {
+    chunkId: string;
+    documentId: string;
+    externalId?: string;
+    title?: string;
+    content: string;
+    similarity: number;
+    rerankScore?: number;
+    metadata?: Record<string, unknown>;
+}
+interface SearchResponse {
+    success: boolean;
+    results: SearchResult[];
+    count: number;
+    mode: SearchMode;
+    timings: {
+        embedMs: number;
+        searchMs: number;
+        rerankMs?: number;
+        totalMs: number;
+    };
+}
+interface FederatedSource {
+    id: string;
+    name: string;
+    type: 'http' | 'agent';
+    priority: number;
+    weight: number;
+}
+interface FederatedSearchRequest {
+    query: string;
+    sources?: string[];
+    topK?: number;
+    mode?: SearchMode;
+    rerank?: boolean;
+    dedupe?: boolean;
+}
+interface FederatedSearchResponse {
+    success: boolean;
+    results: Array<SearchResult & {
+        source: string;
+    }>;
+    sourceStats: Array<{
+        sourceId: string;
+        resultsCount: number;
+        latencyMs: number;
+    }>;
+    timings: {
+        totalMs: number;
+    };
+}
+interface RAGQueryRequest {
+    collectionId: string;
+    query: string;
+    systemPrompt?: string;
+    contextLimit?: number;
+    citationStyle?: 'inline' | 'footnote' | 'none';
+    model?: 'claude-sonnet' | 'claude-haiku';
+    stream?: boolean;
+}
+interface Citation {
+    id: string;
+    documentId: string;
+    title?: string;
+    content: string;
+    relevance: number;
+}
+interface RAGQueryResponse {
+    success: boolean;
+    answer: string;
+    citations: Citation[];
+    usage: {
+        contextTokens: number;
+        responseTokens: number;
+        totalTokens: number;
+    };
+    timings: {
+        searchMs: number;
+        generationMs: number;
+        totalMs: number;
+    };
+}
+interface SummerClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+    retries?: number;
+    onError?: (error: SummerError) => void;
+}
+interface SummerError {
+    code: string;
+    message: string;
+    status?: number;
+    details?: Record<string, unknown>;
+}
+interface CollectionStats {
+    collectionId: string;
+    documentCount: number;
+    chunkCount: number;
+    totalTokens: number;
+    storageBytes: number;
+    lastIndexedAt?: string;
+}
+interface SearchAnalytics {
+    period: 'day' | 'week' | 'month';
+    totalSearches: number;
+    averageLatencyMs: number;
+    topQueries: Array<{
+        query: string;
+        count: number;
+    }>;
+    modeDistribution: Record<SearchMode, number>;
+}
+
+/**
+ * Seizn Summer SDK Client
+ *
+ * TypeScript SDK for Seizn's Summer RAG infrastructure.
+ * Enables external applications to integrate with Seizn's
+ * vector search and RAG capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { SummerClient } from '@seizn/summer';
+ *
+ * const summer = new SummerClient({
+ *   apiKey: process.env.SEIZN_API_KEY!,
+ * });
+ *
+ * // Index a document
+ * await summer.index({
+ *   collectionId: 'my-collection',
+ *   content: 'Document content...',
+ *   metadata: { source: 'my-app' },
+ * });
+ *
+ * // Search
+ * const results = await summer.search({
+ *   collectionId: 'my-collection',
+ *   query: 'What is machine learning?',
+ *   mode: 'hybrid',
+ *   rerank: true,
+ * });
+ * ```
+ */
+
+declare class SummerClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly retries;
+    private readonly onError?;
+    constructor(config: SummerClientConfig);
+    /**
+     * Create a new collection
+     */
+    createCollection(request: CreateCollectionRequest): Promise<Collection>;
+    /**
+     * List all collections
+     */
+    listCollections(): Promise<Collection[]>;
+    /**
+     * Get collection by ID
+     */
+    getCollection(collectionId: string): Promise<Collection>;
+    /**
+     * Delete a collection
+     */
+    deleteCollection(collectionId: string): Promise<void>;
+    /**
+     * Get collection statistics
+     */
+    getCollectionStats(collectionId: string): Promise<CollectionStats>;
+    /**
+     * Index a single document
+     */
+    index(request: IndexDocumentRequest): Promise<IndexDocumentResponse>;
+    /**
+     * Bulk index multiple documents
+     */
+    bulkIndex(request: BulkIndexRequest): Promise<BulkIndexResponse>;
+    /**
+     * Get document by ID
+     */
+    getDocument(documentId: string): Promise<Document>;
+    /**
+     * Delete a document
+     */
+    deleteDocument(documentId: string): Promise<void>;
+    /**
+     * Update document metadata
+     */
+    updateDocumentMetadata(documentId: string, metadata: Record<string, unknown>): Promise<Document>;
+    /**
+     * Search within a collection
+     */
+    search(request: SearchRequest): Promise<SearchResponse>;
+    /**
+     * Quick search shorthand
+     */
+    query(collectionId: string, query: string, options?: {
+        topK?: number;
+        mode?: 'vector' | 'keyword' | 'hybrid';
+        rerank?: boolean;
+    }): Promise<SearchResponse>;
+    /**
+     * Federated search across multiple sources
+     */
+    federatedSearch(request: FederatedSearchRequest): Promise<FederatedSearchResponse>;
+    /**
+     * RAG query with answer generation
+     */
+    rag(request: RAGQueryRequest): Promise<RAGQueryResponse>;
+    /**
+     * Quick RAG query shorthand
+     */
+    ask(collectionId: string, question: string, options?: {
+        systemPrompt?: string;
+        contextLimit?: number;
+    }): Promise<RAGQueryResponse>;
+    /**
+     * Get search analytics
+     */
+    getAnalytics(collectionId: string, period?: 'day' | 'week' | 'month'): Promise<SearchAnalytics>;
+    /**
+     * Generate embedding for text (for external use)
+     */
+    embed(text: string | string[]): Promise<number[][]>;
+    /**
+     * Rerank results
+     */
+    rerank(query: string, documents: Array<{
+        id: string;
+        text: string;
+    }>, topN?: number): Promise<Array<{
+        id: string;
+        score: number;
+    }>>;
+    private request;
+}
+/**
+ * Create a Summer client instance
+ */
+declare function createSummerClient(config: SummerClientConfig): SummerClient;
+
+export { type BulkIndexRequest, type BulkIndexResponse, type Citation, type Collection, type CollectionStats, type CreateCollectionRequest, type CreateCollectionResponse, type Document, type FederatedSearchRequest, type FederatedSearchResponse, type FederatedSource, type IndexDocumentRequest, type IndexDocumentResponse, type RAGQueryRequest, type RAGQueryResponse, type SearchAnalytics, type SearchMode, type SearchRequest, type SearchResponse, type SearchResult, SummerClient, type SummerClientConfig, type SummerError, createSummerClient };