@xache/langchain 0.3.0 → 0.5.0

package/dist/index.js

@@ -25,12 +25,27 @@ __export(index_exports, {
   XacheCollectiveQueryTool: () => XacheCollectiveQueryTool,
   XacheConversationBufferMemory: () => XacheConversationBufferMemory,
   XacheExtractor: () => XacheExtractor,
+  XacheGraphAskTool: () => XacheGraphAskTool,
+  XacheGraphEntityHistoryTool: () => XacheGraphEntityHistoryTool,
+  XacheGraphExtractTool: () => XacheGraphExtractTool,
+  XacheGraphLoadTool: () => XacheGraphLoadTool,
+  XacheGraphMergeEntitiesTool: () => XacheGraphMergeEntitiesTool,
+  XacheGraphQueryTool: () => XacheGraphQueryTool,
+  XacheGraphRetriever: () => XacheGraphRetriever,
   XacheMemory: () => XacheMemory,
   XacheReputationChecker: () => XacheReputationChecker,
   XacheReputationTool: () => XacheReputationTool,
   XacheRetriever: () => XacheRetriever,
   createCollectiveContributeTool: () => createCollectiveContributeTool,
   createCollectiveQueryTool: () => createCollectiveQueryTool,
+  createGraphAddEntityTool: () => createGraphAddEntityTool,
+  createGraphAddRelationshipTool: () => createGraphAddRelationshipTool,
+  createGraphAskTool: () => createGraphAskTool,
+  createGraphEntityHistoryTool: () => createGraphEntityHistoryTool,
+  createGraphExtractTool: () => createGraphExtractTool,
+  createGraphLoadTool: () => createGraphLoadTool,
+  createGraphMergeEntitiesTool: () => createGraphMergeEntitiesTool,
+  createGraphQueryTool: () => createGraphQueryTool,
   createReputationTool: () => createReputationTool
 });
 module.exports = __toCommonJS(index_exports);
@@ -55,6 +70,9 @@ var XacheChatMessageHistory = class extends import_chat_history.BaseListChatMess
       apiUrl: config.apiUrl || "https://api.xache.xyz",
       did,
       privateKey: config.privateKey,
+      signer: config.signer,
+      walletProvider: config.walletProvider,
+      encryptionKey: config.encryptionKey,
       timeout: config.timeout,
       debug: config.debug
     });
@@ -249,7 +267,10 @@ var XacheRetriever = class extends import_retrievers.BaseRetriever {
     this.client = new import_sdk2.XacheClient({
       apiUrl: config.apiUrl || "https://api.xache.xyz",
       did,
-      privateKey: config.privateKey
+      privateKey: config.privateKey,
+      signer: config.signer,
+      walletProvider: config.walletProvider,
+      encryptionKey: config.encryptionKey
     });
     this.k = config.k ?? 5;
     this.filterContext = config.context;
@@ -295,6 +316,9 @@ var XacheExtractor = class {
       apiUrl: config.apiUrl || "https://api.xache.xyz",
       did,
       privateKey: config.privateKey,
+      signer: config.signer,
+      walletProvider: config.walletProvider,
+      encryptionKey: config.encryptionKey,
       timeout: config.timeout,
       debug: config.debug
     });
@@ -383,7 +407,10 @@ function createClient(config) {
   return new import_sdk4.XacheClient({
     apiUrl: config.apiUrl || "https://api.xache.xyz",
     did,
-    privateKey: config.privateKey
+    privateKey: config.privateKey,
+    signer: config.signer,
+    walletProvider: config.walletProvider,
+    encryptionKey: config.encryptionKey
   });
 }
 function createCollectiveContributeTool(config) {
@@ -492,7 +519,10 @@ function createClient2(config) {
   return new import_sdk5.XacheClient({
     apiUrl: config.apiUrl || "https://api.xache.xyz",
     did,
-    privateKey: config.privateKey
+    privateKey: config.privateKey,
+    signer: config.signer,
+    walletProvider: config.walletProvider,
+    encryptionKey: config.encryptionKey
   });
 }
 function createReputationTool(config) {
@@ -574,6 +604,392 @@ var XacheReputationChecker = class {
     return result.score >= minScore;
   }
 };
+
+// src/graph.ts
+var import_tools3 = require("@langchain/core/tools");
+var import_retrievers2 = require("@langchain/core/retrievers");
+var import_documents2 = require("@langchain/core/documents");
+var import_zod3 = require("zod");
+var import_sdk6 = require("@xache/sdk");
+function createClient3(config) {
+  const chainPrefix = config.chain === "solana" ? "sol" : "evm";
+  const did = `did:agent:${chainPrefix}:${config.walletAddress.toLowerCase()}`;
+  return new import_sdk6.XacheClient({
+    apiUrl: config.apiUrl || "https://api.xache.xyz",
+    did,
+    privateKey: config.privateKey,
+    signer: config.signer,
+    walletProvider: config.walletProvider,
+    encryptionKey: config.encryptionKey
+  });
+}
+function getSubject(config) {
+  return config.subject || { scope: "GLOBAL" };
+}
+function buildLLMConfig(config) {
+  if (config.llmEndpoint) {
+    return {
+      type: "endpoint",
+      url: config.llmEndpoint,
+      authToken: config.llmAuthToken,
+      format: config.llmFormat || "openai",
+      model: config.llmModel
+    };
+  } else if (config.llmApiKey && config.llmProvider) {
+    return {
+      type: "api-key",
+      provider: config.llmProvider,
+      apiKey: config.llmApiKey,
+      model: config.llmModel
+    };
+  } else {
+    return {
+      type: "xache-managed",
+      provider: "anthropic",
+      model: config.llmModel
+    };
+  }
+}
+function createGraphExtractTool(config) {
+  const client = createClient3(config);
+  const subject = getSubject(config);
+  return new import_tools3.DynamicStructuredTool({
+    name: "xache_graph_extract",
+    description: "Extract entities and relationships from text into the knowledge graph. Identifies people, organizations, tools, concepts and their connections.",
+    schema: import_zod3.z.object({
+      trace: import_zod3.z.string().describe("The text/trace to extract entities from"),
+      contextHint: import_zod3.z.string().optional().describe('Domain hint (e.g., "engineering", "customer-support")')
+    }),
+    func: async ({ trace, contextHint }) => {
+      const result = await client.graph.extract({
+        trace,
+        llmConfig: buildLLMConfig(config),
+        subject,
+        options: {
+          contextHint,
+          confidenceThreshold: 0.7
+        }
+      });
+      const entities = result.entities || [];
+      const relationships = result.relationships || [];
+      if (entities.length === 0 && relationships.length === 0) {
+        return "No entities or relationships extracted.";
+      }
+      let output = `Extracted ${entities.length} entities, ${relationships.length} relationships.
+`;
+      for (const e of entities) {
+        output += `  Entity: ${e.name} [${e.type}]${e.isNew ? " (new)" : ""}
+`;
+      }
+      for (const r of relationships) {
+        output += `  Rel: ${r.from} \u2192 ${r.type} \u2192 ${r.to}
+`;
+      }
+      return output;
+    }
+  });
+}
+function createGraphQueryTool(config) {
+  const client = createClient3(config);
+  const subject = getSubject(config);
+  return new import_tools3.DynamicStructuredTool({
+    name: "xache_graph_query",
+    description: "Query the knowledge graph around a specific entity. Returns connected entities and relationships within the specified depth.",
+    schema: import_zod3.z.object({
+      startEntity: import_zod3.z.string().describe("Name of the entity to start from"),
+      depth: import_zod3.z.number().optional().default(2).describe("Number of hops (default: 2)")
+    }),
+    func: async ({ startEntity, depth }) => {
+      const graph = await client.graph.query({
+        subject,
+        startEntity,
+        depth: depth || 2
+      });
+      const data = graph.toJSON();
+      if (data.entities.length === 0) {
+        return `No entities found connected to "${startEntity}".`;
+      }
+      let output = `Subgraph: ${data.entities.length} entities, ${data.relationships.length} relationships
+`;
+      for (const e of data.entities) {
+        output += `  ${e.name} [${e.type}]`;
+        if (e.summary) output += ` \u2014 ${e.summary.substring(0, 80)}`;
+        output += "\n";
+      }
+      return output;
+    }
+  });
+}
+function createGraphAskTool(config) {
+  const client = createClient3(config);
+  const subject = getSubject(config);
+  return new import_tools3.DynamicStructuredTool({
+    name: "xache_graph_ask",
+    description: "Ask a natural language question about the knowledge graph. Uses LLM to analyze entities and relationships and provide an answer.",
+    schema: import_zod3.z.object({
+      question: import_zod3.z.string().describe("The question to ask about the knowledge graph")
+    }),
+    func: async ({ question }) => {
+      const answer = await client.graph.ask({
+        subject,
+        question,
+        llmConfig: buildLLMConfig(config)
+      });
+      let output = `Answer: ${answer.answer}
+Confidence: ${(answer.confidence * 100).toFixed(0)}%`;
+      if (answer.sources?.length > 0) {
+        output += "\nSources: " + answer.sources.map((s) => `${s.name} [${s.type}]`).join(", ");
+      }
+      return output;
+    }
+  });
+}
+function createGraphAddEntityTool(config) {
+  const client = createClient3(config);
+  const subject = getSubject(config);
+  return new import_tools3.DynamicStructuredTool({
+    name: "xache_graph_add_entity",
+    description: "Add an entity to the knowledge graph. Creates a person, organization, tool, concept, or other entity type.",
+    schema: import_zod3.z.object({
+      name: import_zod3.z.string().describe("Entity name"),
+      type: import_zod3.z.string().describe("Entity type (person, organization, tool, concept, etc.)"),
+      summary: import_zod3.z.string().optional().describe("Brief description"),
+      attributes: import_zod3.z.record(import_zod3.z.string(), import_zod3.z.unknown()).optional().describe("Key-value attributes")
+    }),
+    func: async ({ name, type, summary, attributes }) => {
+      const entity = await client.graph.addEntity({
+        subject,
+        name,
+        type,
+        summary,
+        attributes
+      });
+      return `Created entity "${entity.name}" [${entity.type}], key: ${entity.key}`;
+    }
+  });
+}
+function createGraphAddRelationshipTool(config) {
+  const client = createClient3(config);
+  const subject = getSubject(config);
+  return new import_tools3.DynamicStructuredTool({
+    name: "xache_graph_add_relationship",
+    description: "Create a relationship between two entities in the knowledge graph.",
+    schema: import_zod3.z.object({
+      from: import_zod3.z.string().describe("Source entity name"),
+      to: import_zod3.z.string().describe("Target entity name"),
+      type: import_zod3.z.string().describe("Relationship type (works_at, knows, uses, manages, etc.)"),
+      description: import_zod3.z.string().optional().describe("Relationship description")
+    }),
+    func: async ({ from, to, type, description }) => {
+      const rel = await client.graph.addRelationship({
+        subject,
+        from,
+        to,
+        type,
+        description
+      });
+      return `Created relationship: ${from} \u2192 ${rel.type} \u2192 ${to}`;
+    }
+  });
+}
+function createGraphLoadTool(config) {
+  const client = createClient3(config);
+  const subject = getSubject(config);
+  return new import_tools3.DynamicStructuredTool({
+    name: "xache_graph_load",
+    description: "Load the full knowledge graph. Returns all entities and relationships. Optionally filter by entity type or load a historical snapshot.",
+    schema: import_zod3.z.object({
+      entityTypes: import_zod3.z.array(import_zod3.z.string()).optional().describe("Filter to specific entity types"),
+      validAt: import_zod3.z.string().optional().describe("Load graph as it existed at this time (ISO8601)")
+    }),
+    func: async ({ entityTypes, validAt }) => {
+      const graph = await client.graph.load({
+        subject,
+        entityTypes,
+        validAt
+      });
+      const data = graph.toJSON();
+      if (data.entities.length === 0) {
+        return "Knowledge graph is empty.";
+      }
+      let output = `Knowledge graph: ${data.entities.length} entities, ${data.relationships.length} relationships
+`;
+      for (const e of data.entities) {
+        output += `  ${e.name} [${e.type}]`;
+        if (e.summary) output += ` \u2014 ${e.summary.substring(0, 80)}`;
+        output += "\n";
+      }
+      return output;
+    }
+  });
+}
+function createGraphMergeEntitiesTool(config) {
+  const client = createClient3(config);
+  const subject = getSubject(config);
+  return new import_tools3.DynamicStructuredTool({
+    name: "xache_graph_merge_entities",
+    description: "Merge two entities into one. The source entity is superseded and the target entity is updated with merged attributes. Relationships are transferred.",
+    schema: import_zod3.z.object({
+      sourceName: import_zod3.z.string().describe("Entity to merge FROM (will be superseded)"),
+      targetName: import_zod3.z.string().describe("Entity to merge INTO (will be updated)")
+    }),
+    func: async ({ sourceName, targetName }) => {
+      const merged = await client.graph.mergeEntities({
+        subject,
+        sourceName,
+        targetName
+      });
+      return `Merged "${sourceName}" into "${targetName}". Result: ${merged.name} [${merged.type}] (v${merged.version})`;
+    }
+  });
+}
+function createGraphEntityHistoryTool(config) {
+  const client = createClient3(config);
+  const subject = getSubject(config);
+  return new import_tools3.DynamicStructuredTool({
+    name: "xache_graph_entity_history",
+    description: "Get the full version history of an entity. Shows how the entity has changed over time.",
+    schema: import_zod3.z.object({
+      name: import_zod3.z.string().describe("Entity name to look up history for")
+    }),
+    func: async ({ name }) => {
+      const versions = await client.graph.getEntityHistory({
+        subject,
+        name
+      });
+      if (versions.length === 0) {
+        return `No history found for entity "${name}".`;
+      }
+      let output = `History for "${name}": ${versions.length} version(s)
+`;
+      for (const v of versions) {
+        output += `  v${v.version} \u2014 ${v.name} [${v.type}]`;
+        if (v.summary) output += ` | ${v.summary.substring(0, 80)}`;
+        output += `
+    Valid: ${v.validFrom}${v.validTo ? ` \u2192 ${v.validTo}` : " \u2192 current"}
+`;
+      }
+      return output;
+    }
+  });
+}
+var XacheGraphExtractTool = class {
+  constructor(config) {
+    this.tool = createGraphExtractTool(config);
+  }
+  asTool() {
+    return this.tool;
+  }
+};
+var XacheGraphQueryTool = class {
+  constructor(config) {
+    this.tool = createGraphQueryTool(config);
+  }
+  asTool() {
+    return this.tool;
+  }
+};
+var XacheGraphAskTool = class {
+  constructor(config) {
+    this.tool = createGraphAskTool(config);
+  }
+  asTool() {
+    return this.tool;
+  }
+};
+var XacheGraphLoadTool = class {
+  constructor(config) {
+    this.tool = createGraphLoadTool(config);
+  }
+  asTool() {
+    return this.tool;
+  }
+};
+var XacheGraphMergeEntitiesTool = class {
+  constructor(config) {
+    this.tool = createGraphMergeEntitiesTool(config);
+  }
+  asTool() {
+    return this.tool;
+  }
+};
+var XacheGraphEntityHistoryTool = class {
+  constructor(config) {
+    this.tool = createGraphEntityHistoryTool(config);
+  }
+  asTool() {
+    return this.tool;
+  }
+};
+var XacheGraphRetriever = class extends import_retrievers2.BaseRetriever {
+  constructor(config) {
+    super(config);
+    this.lc_namespace = ["xache", "graph_retriever"];
+    const chainPrefix = config.chain === "solana" ? "sol" : "evm";
+    const did = `did:agent:${chainPrefix}:${config.walletAddress.toLowerCase()}`;
+    this.client = new import_sdk6.XacheClient({
+      apiUrl: config.apiUrl || "https://api.xache.xyz",
+      did,
+      privateKey: config.privateKey,
+      signer: config.signer,
+      walletProvider: config.walletProvider,
+      encryptionKey: config.encryptionKey
+    });
+    this.subject = config.subject || { scope: "GLOBAL" };
+    this.startEntity = config.startEntity;
+    this.depth = config.depth ?? 2;
+    this.k = config.k ?? 10;
+  }
+  static lc_name() {
+    return "XacheGraphRetriever";
+  }
+  async _getRelevantDocuments(query, _runManager) {
+    let graph;
+    if (this.startEntity) {
+      graph = await this.client.graph.query({
+        subject: this.subject,
+        startEntity: this.startEntity,
+        depth: this.depth
+      });
+    } else {
+      graph = await this.client.graph.load({ subject: this.subject });
+    }
+    const data = graph.toJSON();
+    const queryLower = query.toLowerCase();
+    const scored = data.entities.map((entity) => {
+      let score = 0;
+      const nameLower = entity.name.toLowerCase();
+      const summaryLower = (entity.summary || "").toLowerCase();
+      if (nameLower.includes(queryLower)) score += 3;
+      if (summaryLower.includes(queryLower)) score += 2;
+      const terms = queryLower.split(/\s+/);
+      for (const term of terms) {
+        if (nameLower.includes(term)) score += 1;
+        if (summaryLower.includes(term)) score += 0.5;
+      }
+      return { entity, score };
+    });
+    scored.sort((a, b) => b.score - a.score);
+    const topEntities = scored.slice(0, this.k);
+    return topEntities.map(({ entity }) => {
+      const content = [
+        `Name: ${entity.name}`,
+        `Type: ${entity.type}`,
+        entity.summary ? `Summary: ${entity.summary}` : null
+      ].filter(Boolean).join("\n");
+      return new import_documents2.Document({
+        pageContent: content,
+        metadata: {
+          source: "xache-graph",
+          entityKey: entity.key,
+          entityName: entity.name,
+          entityType: entity.type,
+          storageKey: entity.storageKey
+        }
+      });
+    });
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   XacheChatMessageHistory,
@@ -581,12 +997,27 @@ var XacheReputationChecker = class {
   XacheCollectiveQueryTool,
   XacheConversationBufferMemory,
   XacheExtractor,
+  XacheGraphAskTool,
+  XacheGraphEntityHistoryTool,
+  XacheGraphExtractTool,
+  XacheGraphLoadTool,
+  XacheGraphMergeEntitiesTool,
+  XacheGraphQueryTool,
+  XacheGraphRetriever,
   XacheMemory,
   XacheReputationChecker,
   XacheReputationTool,
   XacheRetriever,
   createCollectiveContributeTool,
   createCollectiveQueryTool,
+  createGraphAddEntityTool,
+  createGraphAddRelationshipTool,
+  createGraphAskTool,
+  createGraphEntityHistoryTool,
+  createGraphExtractTool,
+  createGraphLoadTool,
+  createGraphMergeEntitiesTool,
+  createGraphQueryTool,
   createReputationTool
 });
 //# sourceMappingURL=index.js.map