@cilow/sdk 0.2.0 → 0.2.1

package/dist/providers/langchain.mjs

@@ -0,0 +1,816 @@
+// src/client.ts
+async function fetchWithRetry(url, options, config) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), config.timeout);
+  let lastError = null;
+  for (let attempt = 0; attempt <= config.retries; attempt++) {
+    try {
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const errorBody = await response.text();
+        let apiError;
+        try {
+          apiError = JSON.parse(errorBody);
+        } catch {
+          apiError = {
+            code: `HTTP_${response.status}`,
+            message: errorBody || response.statusText
+          };
+        }
+        throw new CilowApiError(apiError.message, apiError.code, response.status, apiError.details);
+      }
+      return response;
+    } catch (error) {
+      lastError = error;
+      if (error instanceof CilowApiError) {
+        throw error;
+      }
+      if (config.debug) {
+        console.warn(`Cilow API request failed (attempt ${attempt + 1}/${config.retries + 1}):`, error);
+      }
+      if (attempt < config.retries) {
+        await new Promise((resolve) => setTimeout(resolve, Math.pow(2, attempt) * 100));
+      }
+    }
+  }
+  clearTimeout(timeoutId);
+  throw lastError || new Error("Request failed");
+}
+var CilowApiError = class extends Error {
+  constructor(message, code, statusCode, details) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "CilowApiError";
+  }
+};
+var CilowClient = class {
+  constructor(config) {
+    this.baseUrl = config.apiUrl.replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+    this.timeout = config.timeout ?? 3e4;
+    this.retries = config.retries ?? 3;
+    this.debug = config.debug ?? false;
+    const authHeaders = this.apiKey.startsWith("cilow_") ? { "X-API-Key": this.apiKey } : { Authorization: `Bearer ${this.apiKey}` };
+    this.headers = {
+      "Content-Type": "application/json",
+      ...authHeaders,
+      ...config.headers
+    };
+  }
+  /**
+   * Make an API request
+   */
+  async request(method, path, body, queryParams) {
+    let url = `${this.baseUrl}${path}`;
+    if (queryParams) {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(queryParams)) {
+        if (value !== void 0) {
+          params.append(key, String(value));
+        }
+      }
+      const queryString = params.toString();
+      if (queryString) {
+        url += `?${queryString}`;
+      }
+    }
+    if (this.debug) {
+      console.log(`Cilow API: ${method} ${url}`);
+    }
+    const response = await fetchWithRetry(
+      url,
+      {
+        method,
+        headers: this.headers,
+        body: body ? JSON.stringify(body) : void 0
+      },
+      { timeout: this.timeout, retries: this.retries, debug: this.debug }
+    );
+    const text = await response.text();
+    if (!text) {
+      return void 0;
+    }
+    return JSON.parse(text);
+  }
+  // ===========================================================================
+  // Simple API (remember, recall, forget)
+  // ===========================================================================
+  /**
+   * Store a memory (simple API)
+   *
+   * @param content - The content to remember
+   * @param options - Optional configuration
+   * @returns The created memory ID
+   *
+   * @example
+   * ```typescript
+   * await cilow.remember("User prefers dark mode", {
+   *   tags: ["preference"],
+   *   userId: "user-123"
+   * });
+   * ```
+   */
+  async remember(content, options) {
+    const response = await this.request("POST", "/api/v1/memory/add", {
+      content,
+      tags: options?.tags ?? [],
+      user_id: options?.userId,
+      session_id: options?.sessionId,
+      metadata: options?.metadata,
+      type: options?.tier
+    });
+    return response.memory_id || response.id || "";
+  }
+  /**
+   * Search memories (simple API)
+   *
+   * @param query - Search query text
+   * @param options - Search options
+   * @returns Array of search results
+   *
+   * @example
+   * ```typescript
+   * const memories = await cilow.recall("user preferences", {
+   *   limit: 10,
+   *   tags: ["preference"]
+   * });
+   * ```
+   */
+  async recall(query, options) {
+    const response = await this.request("POST", "/api/v1/memory/search", {
+      query,
+      limit: options?.limit ?? 10,
+      min_score: options?.minRelevance ?? 0.3,
+      tags: options?.tags,
+      user_id: options?.userId
+    });
+    return (response.results ?? []).map((r) => ({
+      memory: {
+        id: r.memory_id,
+        content: r.content,
+        tags: r.tags ?? [],
+        tier: "hot",
+        status: "active",
+        accessCount: 0,
+        tokenCount: Math.ceil(r.content.length / 4),
+        metadata: {},
+        createdAt: r.created_at ?? (/* @__PURE__ */ new Date()).toISOString(),
+        updatedAt: r.created_at ?? (/* @__PURE__ */ new Date()).toISOString(),
+        lastAccessedAt: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      score: r.similarity,
+      highlights: []
+    }));
+  }
+  /**
+   * Delete memories (simple API)
+   *
+   * @param filter - Filter criteria for deletion
+   * @returns Number of memories deleted
+   *
+   * @example
+   * ```typescript
+   * // Delete by tags
+   * await cilow.forget({ tags: ["temporary"] });
+   *
+   * // Delete by user
+   * await cilow.forget({ userId: "user-123" });
+   *
+   * // Delete specific memory
+   * await cilow.forget({ memoryId: "mem-abc" });
+   * ```
+   */
+  async forget(filter) {
+    if (filter.memoryId) {
+      await this.deleteMemory(filter.memoryId);
+      return 1;
+    }
+    const response = await this.request("DELETE", "/api/v1/memories/bulk", {
+      filter_tags: filter.tags,
+      user_id: filter.userId,
+      session_id: filter.sessionId,
+      older_than: filter.olderThan
+    });
+    return response.deleted ?? 0;
+  }
+  // ===========================================================================
+  // Memory CRUD Operations
+  // ===========================================================================
+  /**
+   * Create a new memory
+   */
+  async createMemory(content, options) {
+    return this.request("POST", "/api/v1/memories", {
+      content,
+      tags: options?.tags ?? [],
+      user_id: options?.userId,
+      session_id: options?.sessionId,
+      metadata: options?.metadata,
+      tier: options?.tier
+    });
+  }
+  /**
+   * Get a memory by ID
+   */
+  async getMemory(memoryId) {
+    return this.request("GET", `/api/v1/memories/${memoryId}`);
+  }
+  /**
+   * Update a memory
+   */
+  async updateMemory(memoryId, updates) {
+    return this.request("PATCH", `/api/v1/memories/${memoryId}`, {
+      content: updates.content,
+      tags: updates.tags,
+      metadata: updates.metadata,
+      tier: updates.tier
+    });
+  }
+  /**
+   * Delete a memory
+   */
+  async deleteMemory(memoryId) {
+    await this.request("DELETE", `/api/v1/memories/${memoryId}`);
+  }
+  /**
+   * List memories with pagination
+   */
+  async listMemories(options) {
+    const response = await this.request(
+      "GET",
+      "/api/v1/memory/list",
+      void 0,
+      {
+        limit: options?.limit ?? 20,
+        offset: options?.offset ?? 0,
+        user_id: options?.userId,
+        session_id: options?.sessionId,
+        tags: options?.tags?.join(","),
+        type: options?.tier
+      }
+    );
+    const items = (response.memories ?? []).map((m) => ({
+      id: m.memory_id || m.id || "",
+      content: m.content,
+      tags: m.tags ?? [],
+      createdAt: m.created_at ?? (/* @__PURE__ */ new Date()).toISOString(),
+      tier: m.type || "hot"
+    }));
+    const limit = options?.limit ?? 20;
+    const offset = options?.offset ?? 0;
+    const total = response.total ?? items.length;
+    return {
+      items,
+      total,
+      limit,
+      offset,
+      hasMore: offset + items.length < total
+    };
+  }
+  // ===========================================================================
+  // Search Operations
+  // ===========================================================================
+  /**
+   * Search memories with full options
+   */
+  async searchMemories(query) {
+    const response = await this.request("POST", "/api/v1/memories/search", {
+      text: query.text,
+      limit: query.limit ?? 10,
+      min_relevance: query.minRelevance ?? 0.3,
+      filter_tags: query.tags,
+      user_id: query.userId,
+      session_id: query.sessionId,
+      tier: query.tier,
+      created_after: query.createdAfter,
+      created_before: query.createdBefore,
+      include_archived: query.includeArchived,
+      mode: query.mode ?? "hybrid"
+    });
+    return response.results ?? [];
+  }
+  /**
+   * Advanced search with reranking and boosts
+   */
+  async advancedSearch(query) {
+    const response = await this.request("POST", "/api/v1/memories/search/advanced", {
+      text: query.text,
+      limit: query.limit ?? 10,
+      min_relevance: query.minRelevance ?? 0.3,
+      filter_tags: query.tags,
+      required_tags: query.requiredTags,
+      excluded_tags: query.excludedTags,
+      user_id: query.userId,
+      session_id: query.sessionId,
+      recency_boost: query.recencyBoost,
+      frequency_boost: query.frequencyBoost,
+      metadata_filters: query.metadataFilters,
+      reranker: query.reranker
+    });
+    return response.results ?? [];
+  }
+  /**
+   * Get context for AI applications
+   */
+  async getContext(query, options) {
+    const maxTokens = options?.maxTokens ?? 4e3;
+    const tokensPerChar = 0.25;
+    const results = await this.searchMemories({
+      text: query,
+      limit: 30,
+      minRelevance: 0.3,
+      userId: options?.userId,
+      tags: options?.tags
+    });
+    let context = "";
+    let estimatedTokens = 0;
+    const memoryIds = [];
+    const scores = [];
+    for (const result of results) {
+      const memoryText = `[Relevance: ${(result.score * 100).toFixed(0)}%]
+${result.memory.content}
+
+`;
+      const memoryTokens = Math.ceil(memoryText.length * tokensPerChar);
+      if (estimatedTokens + memoryTokens > maxTokens) break;
+      context += memoryText;
+      estimatedTokens += memoryTokens;
+      memoryIds.push(result.memory.id);
+      scores.push(result.score);
+    }
+    return {
+      context: context.trim(),
+      memoriesUsed: memoryIds.length,
+      estimatedTokens,
+      memoryIds,
+      scores
+    };
+  }
+  // ===========================================================================
+  // Conversation Operations
+  // ===========================================================================
+  /**
+   * Store a conversation turn
+   */
+  async storeConversation(turn) {
+    const content = `User: ${turn.userMessage}
+
+Assistant: ${turn.assistantResponse}`;
+    const tags = ["conversation"];
+    if (turn.sessionId) {
+      tags.push(`session:${turn.sessionId}`);
+    }
+    return this.remember(content, {
+      tags,
+      userId: turn.userId,
+      sessionId: turn.sessionId,
+      metadata: {
+        type: "conversation",
+        ...turn.metadata
+      }
+    });
+  }
+  /**
+   * Get conversation history for a session
+   */
+  async getConversationHistory(sessionId, options) {
+    const response = await this.listMemories({
+      sessionId,
+      tags: ["conversation"],
+      limit: options?.limit ?? 50,
+      offset: options?.offset ?? 0
+    });
+    return response.items;
+  }
+  // ===========================================================================
+  // Graph Operations
+  // ===========================================================================
+  /**
+   * Get a graph node
+   */
+  async getGraphNode(nodeId) {
+    return this.request("GET", `/api/v1/graph/nodes/${nodeId}`);
+  }
+  /**
+   * Create a graph node
+   */
+  async createGraphNode(type, name, properties) {
+    return this.request("POST", "/api/v1/graph/nodes", {
+      type,
+      name,
+      properties: properties ?? {}
+    });
+  }
+  /**
+   * Create a graph edge
+   */
+  async createGraphEdge(sourceId, targetId, type, properties) {
+    return this.request("POST", "/api/v1/graph/edges", {
+      source_id: sourceId,
+      target_id: targetId,
+      type,
+      properties: properties ?? {}
+    });
+  }
+  /**
+   * Traverse the graph from a starting node
+   */
+  async traverseGraph(options) {
+    return this.request("POST", "/api/v1/graph/traverse", {
+      start_node_id: options.startNodeId,
+      max_depth: options.maxDepth ?? 3,
+      relationship_types: options.relationshipTypes,
+      limit: options.limit ?? 100,
+      direction: options.direction ?? "both"
+    });
+  }
+  /**
+   * Get related nodes for a memory
+   */
+  async getRelatedNodes(memoryId) {
+    const response = await this.request(
+      "GET",
+      `/api/v1/memories/${memoryId}/related-nodes`
+    );
+    return response.nodes ?? [];
+  }
+  // ===========================================================================
+  // Statistics & Admin
+  // ===========================================================================
+  /**
+   * Get memory statistics
+   */
+  async getStats() {
+    return this.request("GET", "/api/v1/stats");
+  }
+  /**
+   * Get all tags with counts
+   */
+  async getTags() {
+    const response = await this.request("GET", "/api/v1/tags");
+    return response.tags ?? [];
+  }
+  /**
+   * Get user statistics
+   */
+  async getUserStats(userId) {
+    return this.request("GET", `/api/v1/users/${userId}/stats`);
+  }
+  /**
+   * Health check
+   */
+  async healthCheck() {
+    return this.request("GET", "/health");
+  }
+  // ===========================================================================
+  // Batch Operations
+  // ===========================================================================
+  /**
+   * Batch create memories
+   */
+  async batchCreate(items) {
+    const response = await this.request("POST", "/api/v1/memories/batch", {
+      memories: items.map((item) => ({
+        content: item.content,
+        tags: item.options?.tags ?? [],
+        user_id: item.options?.userId,
+        session_id: item.options?.sessionId,
+        metadata: item.options?.metadata
+      }))
+    });
+    return response.ids ?? [];
+  }
+  /**
+   * Batch delete memories
+   */
+  async batchDelete(memoryIds) {
+    const response = await this.request("DELETE", "/api/v1/memories/batch", {
+      ids: memoryIds
+    });
+    return response.deleted ?? 0;
+  }
+};
+
+// src/providers/langchain.ts
+var CilowMemory = class {
+  constructor(config) {
+    this.client = new CilowClient(config);
+    this.userId = config.userId;
+    this.sessionId = config.sessionId;
+    this.memoryKey = config.memoryKey ?? "history";
+    this.inputKey = config.inputKey ?? "input";
+    this.outputKey = config.outputKey ?? "output";
+    this.returnMessages = config.returnMessages ?? true;
+    this.maxMemories = config.maxMemories ?? 10;
+    this.minRelevance = config.minRelevance ?? 0.3;
+    this.memoryKeys = [this.memoryKey];
+  }
+  /**
+   * Load memory variables based on input
+   */
+  async loadMemoryVariables(values) {
+    const input = values[this.inputKey];
+    const query = typeof input === "string" ? input : JSON.stringify(input);
+    const results = await this.client.recall(query, {
+      limit: this.maxMemories,
+      minRelevance: this.minRelevance,
+      userId: this.userId
+    });
+    if (this.returnMessages) {
+      const messages = this.resultsToMessages(results);
+      return { [this.memoryKey]: messages };
+    } else {
+      const history = this.resultsToString(results);
+      return { [this.memoryKey]: history };
+    }
+  }
+  /**
+   * Save context from a conversation turn
+   */
+  async saveContext(inputValues, outputValues) {
+    const input = inputValues[this.inputKey];
+    const output = outputValues[this.outputKey];
+    const userMessage = typeof input === "string" ? input : JSON.stringify(input);
+    const assistantMessage = typeof output === "string" ? output : JSON.stringify(output);
+    await this.client.storeConversation({
+      userMessage,
+      assistantResponse: assistantMessage,
+      userId: this.userId ?? "anonymous",
+      sessionId: this.sessionId
+    });
+  }
+  /**
+   * Clear memory for the current session
+   */
+  async clear() {
+    if (this.sessionId) {
+      await this.client.forget({
+        sessionId: this.sessionId
+      });
+    } else if (this.userId) {
+      await this.client.forget({
+        userId: this.userId,
+        tags: ["conversation"]
+      });
+    }
+  }
+  /**
+   * Convert search results to LangChain messages
+   */
+  resultsToMessages(results) {
+    const messages = [];
+    for (const result of results) {
+      const content = result.memory.content;
+      if (content.includes("User:") && content.includes("Assistant:")) {
+        const [userPart, assistantPart] = content.split("\n\nAssistant:");
+        const userMessage = userPart.replace("User:", "").trim();
+        const assistantMessage = assistantPart?.trim() ?? "";
+        messages.push({
+          _getType: () => "human",
+          content: userMessage
+        });
+        if (assistantMessage) {
+          messages.push({
+            _getType: () => "ai",
+            content: assistantMessage
+          });
+        }
+      } else {
+        messages.push({
+          _getType: () => "system",
+          content
+        });
+      }
+    }
+    return messages;
+  }
+  /**
+   * Convert search results to string history
+   */
+  resultsToString(results) {
+    return results.map((r, i) => `[Memory ${i + 1} - Relevance: ${(r.score * 100).toFixed(0)}%]
+${r.memory.content}`).join("\n\n");
+  }
+  /**
+   * Set user ID
+   */
+  setUserId(userId) {
+    this.userId = userId;
+  }
+  /**
+   * Set session ID
+   */
+  setSessionId(sessionId) {
+    this.sessionId = sessionId;
+  }
+};
+var CilowRetriever = class {
+  constructor(config) {
+    this.client = new CilowClient(config);
+    this.userId = config.userId;
+    this.tags = config.tags;
+    this.topK = config.topK ?? 5;
+    this.minRelevance = config.minRelevance ?? 0.3;
+  }
+  /**
+   * Retrieve relevant documents for a query
+   */
+  async getRelevantDocuments(query) {
+    const results = await this.client.recall(query, {
+      limit: this.topK,
+      minRelevance: this.minRelevance,
+      tags: this.tags,
+      userId: this.userId
+    });
+    return results.map((result) => this.resultToDocument(result));
+  }
+  /**
+   * Alias for getRelevantDocuments (LangChain compatibility)
+   */
+  async invoke(query) {
+    return this.getRelevantDocuments(query);
+  }
+  /**
+   * Convert search result to LangChain document
+   */
+  resultToDocument(result) {
+    return {
+      pageContent: result.memory.content,
+      metadata: {
+        id: result.memory.id,
+        score: result.score,
+        tags: result.memory.tags,
+        tier: result.memory.tier,
+        createdAt: result.memory.createdAt,
+        ...result.memory.metadata
+      }
+    };
+  }
+  /**
+   * Add documents to the memory store
+   */
+  async addDocuments(documents) {
+    const ids = [];
+    for (const doc of documents) {
+      const id = await this.client.remember(doc.pageContent, {
+        tags: doc.metadata?.tags ?? [],
+        userId: this.userId,
+        metadata: doc.metadata
+      });
+      ids.push(id);
+    }
+    return ids;
+  }
+  /**
+   * Delete documents by IDs
+   */
+  async deleteDocuments(ids) {
+    await this.client.batchDelete(ids);
+  }
+  /**
+   * Set user ID for filtering
+   */
+  setUserId(userId) {
+    this.userId = userId;
+  }
+  /**
+   * Set tags for filtering
+   */
+  setTags(tags) {
+    this.tags = tags;
+  }
+};
+var CilowVectorStore = class {
+  constructor(config) {
+    this.client = new CilowClient(config);
+    this.userId = config.userId;
+    this.defaultTags = config.defaultTags ?? [];
+  }
+  /**
+   * Add documents to the vector store
+   */
+  async addDocuments(documents) {
+    const items = documents.map((doc) => ({
+      content: doc.pageContent,
+      options: {
+        tags: [...this.defaultTags, ...doc.metadata?.tags ?? []],
+        userId: this.userId,
+        metadata: doc.metadata
+      }
+    }));
+    return this.client.batchCreate(items);
+  }
+  /**
+   * Add texts to the vector store
+   */
+  async addTexts(texts, metadatas) {
+    const documents = texts.map((text, i) => ({
+      pageContent: text,
+      metadata: metadatas?.[i] ?? {}
+    }));
+    return this.addDocuments(documents);
+  }
+  /**
+   * Similarity search by query text
+   */
+  async similaritySearch(query, k = 5) {
+    const results = await this.client.recall(query, {
+      limit: k,
+      userId: this.userId
+    });
+    return results.map((r) => ({
+      pageContent: r.memory.content,
+      metadata: {
+        id: r.memory.id,
+        score: r.score,
+        tags: r.memory.tags,
+        ...r.memory.metadata
+      }
+    }));
+  }
+  /**
+   * Similarity search with scores
+   */
+  async similaritySearchWithScore(query, k = 5) {
+    const results = await this.client.recall(query, {
+      limit: k,
+      userId: this.userId
+    });
+    return results.map((r) => [
+      {
+        pageContent: r.memory.content,
+        metadata: {
+          id: r.memory.id,
+          tags: r.memory.tags,
+          ...r.memory.metadata
+        }
+      },
+      r.score
+    ]);
+  }
+  /**
+   * Maximum marginal relevance search
+   */
+  async maxMarginalRelevanceSearch(query, options) {
+    return this.similaritySearch(query, options?.k ?? 5);
+  }
+  /**
+   * Delete documents by IDs
+   */
+  async delete(ids) {
+    await this.client.batchDelete(ids);
+  }
+  /**
+   * Get retriever from this vector store
+   */
+  asRetriever(options) {
+    return new CilowRetriever({
+      apiUrl: "",
+      // Will be overridden
+      apiKey: "",
+      // Will be overridden
+      userId: this.userId,
+      topK: options?.k ?? 5
+    });
+  }
+  /**
+   * Set user ID
+   */
+  setUserId(userId) {
+    this.userId = userId;
+  }
+};
+function createMemoryCallbackHandler(config) {
+  const client = new CilowClient(config);
+  const userId = config.userId ?? "anonymous";
+  let currentInput = "";
+  return {
+    handleChainStart(chain, inputs) {
+      currentInput = typeof inputs.input === "string" ? inputs.input : JSON.stringify(inputs.input);
+    },
+    async handleChainEnd(outputs) {
+      const output = typeof outputs.output === "string" ? outputs.output : typeof outputs.text === "string" ? outputs.text : JSON.stringify(outputs);
+      if (currentInput && output) {
+        await client.storeConversation({
+          userMessage: currentInput,
+          assistantResponse: output,
+          userId
+        });
+      }
+      currentInput = "";
+    },
+    handleChainError(_error) {
+      currentInput = "";
+    }
+  };
+}
+
+export { CilowMemory, CilowRetriever, CilowVectorStore, createMemoryCallbackHandler };
+//# sourceMappingURL=langchain.mjs.map
+//# sourceMappingURL=langchain.mjs.map