@seizn/summer 0.1.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -0,0 +1,298 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SummerClient: () => SummerClient,
+  createSummerClient: () => createSummerClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://seizn.com/api/summer";
+var DEFAULT_TIMEOUT = 6e4;
+var DEFAULT_RETRIES = 3;
+var SummerClient = class {
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("API key is required");
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.retries = config.retries ?? DEFAULT_RETRIES;
+    this.onError = config.onError;
+  }
+  // ============================================
+  // Collection Management
+  // ============================================
+  /**
+   * Create a new collection
+   */
+  async createCollection(request) {
+    const response = await this.request("/collections", {
+      method: "POST",
+      body: request
+    });
+    return response.collection;
+  }
+  /**
+   * List all collections
+   */
+  async listCollections() {
+    const response = await this.request("/collections");
+    return response.collections;
+  }
+  /**
+   * Get collection by ID
+   */
+  async getCollection(collectionId) {
+    const response = await this.request(
+      `/collections/${collectionId}`
+    );
+    return response.collection;
+  }
+  /**
+   * Delete a collection
+   */
+  async deleteCollection(collectionId) {
+    await this.request(`/collections/${collectionId}`, { method: "DELETE" });
+  }
+  /**
+   * Get collection statistics
+   */
+  async getCollectionStats(collectionId) {
+    return this.request(`/collections/${collectionId}/stats`);
+  }
+  // ============================================
+  // Document Indexing
+  // ============================================
+  /**
+   * Index a single document
+   */
+  async index(request) {
+    return this.request("/index", {
+      method: "POST",
+      body: request
+    });
+  }
+  /**
+   * Bulk index multiple documents
+   */
+  async bulkIndex(request) {
+    return this.request("/index/bulk", {
+      method: "POST",
+      body: request
+    });
+  }
+  /**
+   * Get document by ID
+   */
+  async getDocument(documentId) {
+    const response = await this.request(
+      `/documents/${documentId}`
+    );
+    return response.document;
+  }
+  /**
+   * Delete a document
+   */
+  async deleteDocument(documentId) {
+    await this.request(`/documents/${documentId}`, { method: "DELETE" });
+  }
+  /**
+   * Update document metadata
+   */
+  async updateDocumentMetadata(documentId, metadata) {
+    const response = await this.request(
+      `/documents/${documentId}`,
+      {
+        method: "PATCH",
+        body: { metadata }
+      }
+    );
+    return response.document;
+  }
+  // ============================================
+  // Search
+  // ============================================
+  /**
+   * Search within a collection
+   */
+  async search(request) {
+    return this.request("/search", {
+      method: "POST",
+      body: request
+    });
+  }
+  /**
+   * Quick search shorthand
+   */
+  async query(collectionId, query, options) {
+    return this.search({
+      collectionId,
+      query,
+      topK: options?.topK ?? 10,
+      mode: options?.mode ?? "hybrid",
+      rerank: options?.rerank ?? false
+    });
+  }
+  /**
+   * Federated search across multiple sources
+   */
+  async federatedSearch(request) {
+    return this.request("/search/federated", {
+      method: "POST",
+      body: request
+    });
+  }
+  // ============================================
+  // RAG Query
+  // ============================================
+  /**
+   * RAG query with answer generation
+   */
+  async rag(request) {
+    return this.request("/rag", {
+      method: "POST",
+      body: request
+    });
+  }
+  /**
+   * Quick RAG query shorthand
+   */
+  async ask(collectionId, question, options) {
+    return this.rag({
+      collectionId,
+      query: question,
+      systemPrompt: options?.systemPrompt,
+      contextLimit: options?.contextLimit ?? 8e3,
+      citationStyle: "inline"
+    });
+  }
+  // ============================================
+  // Analytics
+  // ============================================
+  /**
+   * Get search analytics
+   */
+  async getAnalytics(collectionId, period = "week") {
+    return this.request(
+      `/collections/${collectionId}/analytics?period=${period}`
+    );
+  }
+  // ============================================
+  // Utilities
+  // ============================================
+  /**
+   * Generate embedding for text (for external use)
+   */
+  async embed(text) {
+    const texts = Array.isArray(text) ? text : [text];
+    const response = await this.request("/embed", {
+      method: "POST",
+      body: { texts }
+    });
+    return response.embeddings;
+  }
+  /**
+   * Rerank results
+   */
+  async rerank(query, documents, topN) {
+    const response = await this.request(
+      "/rerank",
+      {
+        method: "POST",
+        body: { query, documents, topN }
+      }
+    );
+    return response.results;
+  }
+  // ============================================
+  // Internal
+  // ============================================
+  async request(path, options) {
+    const url = `${this.baseUrl}${path}`;
+    const method = options?.method ?? "GET";
+    let lastError = null;
+    for (let attempt = 0; attempt < this.retries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        const response = await fetch(url, {
+          method,
+          headers: {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json"
+          },
+          body: options?.body ? JSON.stringify(options.body) : void 0,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+          const errorData = await response.json().catch(() => ({}));
+          const error = {
+            code: errorData.code ?? "REQUEST_FAILED",
+            message: errorData.error ?? errorData.message ?? `Request failed with status ${response.status}`,
+            status: response.status,
+            details: errorData
+          };
+          if (response.status >= 400 && response.status < 500) {
+            this.onError?.(error);
+            throw error;
+          }
+          lastError = error;
+          continue;
+        }
+        return response.json();
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+          lastError = {
+            code: "TIMEOUT",
+            message: `Request timed out after ${this.timeout}ms`
+          };
+        } else if (error.code) {
+          throw error;
+        } else {
+          lastError = {
+            code: "NETWORK_ERROR",
+            message: error instanceof Error ? error.message : "Network error"
+          };
+        }
+        if (attempt < this.retries - 1) {
+          await new Promise((resolve) => setTimeout(resolve, Math.pow(2, attempt) * 1e3));
+        }
+      }
+    }
+    if (lastError) {
+      this.onError?.(lastError);
+      throw lastError;
+    }
+    throw { code: "UNKNOWN", message: "Unknown error" };
+  }
+};
+function createSummerClient(config) {
+  return new SummerClient(config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SummerClient,
+  createSummerClient
+});