@xache/langchain 0.3.0 → 0.4.0

package/README.md

@@ -107,6 +107,62 @@ const result = await extractor.extract(
 console.log(`Extracted ${result.count} memories`);
 ```
 
+### Knowledge Graph
+
+Build and query a privacy-preserving knowledge graph of entities and relationships:
+
+```typescript
+import {
+  createGraphExtractTool,
+  createGraphQueryTool,
+  createGraphAskTool,
+  createGraphLoadTool,
+  createGraphAddEntityTool,
+  createGraphAddRelationshipTool,
+  createGraphMergeEntitiesTool,
+  createGraphEntityHistoryTool,
+  XacheGraphRetriever,
+} from '@xache/langchain';
+
+const config = {
+  walletAddress: '0x...',
+  privateKey: '0x...',
+  llmProvider: 'anthropic',
+  llmApiKey: 'sk-ant-...',
+};
+
+// Extract entities from text
+const extractTool = createGraphExtractTool(config);
+
+// Query graph around an entity
+const queryTool = createGraphQueryTool(config);
+
+// Ask natural language questions
+const askTool = createGraphAskTool(config);
+
+// Load the full graph
+const loadTool = createGraphLoadTool(config);
+
+// Add entities and relationships manually
+const addEntityTool = createGraphAddEntityTool(config);
+const addRelTool = createGraphAddRelationshipTool(config);
+
+// Merge duplicate entities
+const mergeTool = createGraphMergeEntitiesTool(config);
+
+// View entity version history
+const historyTool = createGraphEntityHistoryTool(config);
+
+// Use as a retriever for RAG
+const graphRetriever = new XacheGraphRetriever({
+  walletAddress: '0x...',
+  privateKey: '0x...',
+  k: 10,
+});
+
+const docs = await graphRetriever.getRelevantDocuments('engineering team');
+```
+
 ### Reputation
 
 Check and verify agent reputation:
@@ -160,6 +216,8 @@ All operations use x402 micropayments (auto-handled):
 | Collective Contribute| $0.002 |
 | Collective Query     | $0.011 |
 | Extraction (managed) | $0.011 |
+| Graph Operations     | $0.002 |
+| Graph Ask (managed)  | $0.011 |
 
 ## ERC-8004 Portable Reputation
 

package/dist/index.d.mts

@@ -4,7 +4,7 @@ import { BaseMessage } from '@langchain/core/messages';
 import { BaseRetriever, BaseRetrieverInput } from '@langchain/core/retrievers';
 import { Document } from '@langchain/core/documents';
 import { CallbackManagerForRetrieverRun } from '@langchain/core/callbacks/manager';
-import { LLMProvider, LLMApiFormat } from '@xache/sdk';
+import { LLMProvider, LLMApiFormat, SubjectContext } from '@xache/sdk';
 import { DynamicStructuredTool } from '@langchain/core/tools';
 
 /**
@@ -476,4 +476,168 @@ declare class XacheReputationChecker {
     meetsThreshold(agentDid: string, minScore: number): Promise<boolean>;
 }
 
-export { type CollectiveToolConfig, type ExtractedMemory, type ExtractionResult, type ReputationResult, type ReputationToolConfig, XacheChatMessageHistory, type XacheChatMessageHistoryConfig, XacheCollectiveContributeTool, XacheCollectiveQueryTool, XacheConversationBufferMemory, XacheExtractor, type XacheExtractorConfig, XacheMemory, type XacheMemoryConfig, XacheReputationChecker, XacheReputationTool, XacheRetriever, type XacheRetrieverConfig, createCollectiveContributeTool, createCollectiveQueryTool, createReputationTool };
+/**
+ * Xache Knowledge Graph for LangChain.js
+ * Extract, query, and manage entities/relationships in a privacy-preserving knowledge graph
+ */
+
+interface GraphToolConfig {
+    /** Wallet address for authentication */
+    walletAddress: string;
+    /** Private key for signing */
+    privateKey: string;
+    /** API URL (defaults to https://api.xache.xyz) */
+    apiUrl?: string;
+    /** Chain: 'base' or 'solana' */
+    chain?: 'base' | 'solana';
+    /** Subject context for graph scoping (defaults to GLOBAL) */
+    subject?: SubjectContext;
+    /** LLM provider for extract/ask (api-key mode) */
+    llmProvider?: LLMProvider;
+    /** LLM API key */
+    llmApiKey?: string;
+    /** LLM model override */
+    llmModel?: string;
+    /** LLM endpoint URL (endpoint mode) */
+    llmEndpoint?: string;
+    /** LLM auth token (endpoint mode) */
+    llmAuthToken?: string;
+    /** LLM API format (endpoint mode, default: openai) */
+    llmFormat?: LLMApiFormat;
+}
+/**
+ * Create a tool for extracting entities/relationships from agent traces.
+ *
+ * @example
+ * ```typescript
+ * const extractTool = createGraphExtractTool({
+ *   walletAddress: '0x...',
+ *   privateKey: '0x...',
+ *   llmProvider: 'anthropic',
+ *   llmApiKey: 'sk-ant-...',
+ * });
+ * ```
+ */
+declare function createGraphExtractTool(config: GraphToolConfig): DynamicStructuredTool;
+/**
+ * Create a tool for querying the knowledge graph around a specific entity.
+ */
+declare function createGraphQueryTool(config: GraphToolConfig): DynamicStructuredTool;
+/**
+ * Create a tool for asking natural language questions about the knowledge graph.
+ */
+declare function createGraphAskTool(config: GraphToolConfig): DynamicStructuredTool;
+/**
+ * Create a tool for adding entities to the knowledge graph.
+ */
+declare function createGraphAddEntityTool(config: GraphToolConfig): DynamicStructuredTool;
+/**
+ * Create a tool for adding relationships between entities.
+ */
+declare function createGraphAddRelationshipTool(config: GraphToolConfig): DynamicStructuredTool;
+/**
+ * Create a tool for loading the full knowledge graph.
+ */
+declare function createGraphLoadTool(config: GraphToolConfig): DynamicStructuredTool;
+/**
+ * Create a tool for merging two entities in the knowledge graph.
+ */
+declare function createGraphMergeEntitiesTool(config: GraphToolConfig): DynamicStructuredTool;
+/**
+ * Create a tool for getting the version history of an entity.
+ */
+declare function createGraphEntityHistoryTool(config: GraphToolConfig): DynamicStructuredTool;
+/**
+ * Class wrapper for graph extract tool
+ */
+declare class XacheGraphExtractTool {
+    private tool;
+    constructor(config: GraphToolConfig);
+    asTool(): DynamicStructuredTool;
+}
+/**
+ * Class wrapper for graph query tool
+ */
+declare class XacheGraphQueryTool {
+    private tool;
+    constructor(config: GraphToolConfig);
+    asTool(): DynamicStructuredTool;
+}
+/**
+ * Class wrapper for graph ask tool
+ */
+declare class XacheGraphAskTool {
+    private tool;
+    constructor(config: GraphToolConfig);
+    asTool(): DynamicStructuredTool;
+}
+/**
+ * Class wrapper for graph load tool
+ */
+declare class XacheGraphLoadTool {
+    private tool;
+    constructor(config: GraphToolConfig);
+    asTool(): DynamicStructuredTool;
+}
+/**
+ * Class wrapper for graph merge entities tool
+ */
+declare class XacheGraphMergeEntitiesTool {
+    private tool;
+    constructor(config: GraphToolConfig);
+    asTool(): DynamicStructuredTool;
+}
+/**
+ * Class wrapper for graph entity history tool
+ */
+declare class XacheGraphEntityHistoryTool {
+    private tool;
+    constructor(config: GraphToolConfig);
+    asTool(): DynamicStructuredTool;
+}
+interface XacheGraphRetrieverConfig extends BaseRetrieverInput {
+    /** Wallet address for authentication */
+    walletAddress: string;
+    /** Private key for signing */
+    privateKey: string;
+    /** API URL (defaults to https://api.xache.xyz) */
+    apiUrl?: string;
+    /** Chain: 'base' or 'solana' */
+    chain?: 'base' | 'solana';
+    /** Subject context for graph scoping */
+    subject?: SubjectContext;
+    /** Starting entity for subgraph query (optional — if not set, loads full graph) */
+    startEntity?: string;
+    /** Depth for subgraph query (default: 2) */
+    depth?: number;
+    /** Max results to return */
+    k?: number;
+}
+/**
+ * Retriever that fetches documents from the Xache knowledge graph.
+ * Each entity becomes a Document with its name, type, and summary.
+ *
+ * @example
+ * ```typescript
+ * const retriever = new XacheGraphRetriever({
+ *   walletAddress: '0x...',
+ *   privateKey: '0x...',
+ *   k: 10,
+ * });
+ *
+ * const docs = await retriever.getRelevantDocuments('engineering team');
+ * ```
+ */
+declare class XacheGraphRetriever extends BaseRetriever {
+    lc_namespace: string[];
+    static lc_name(): string;
+    private client;
+    private subject;
+    private startEntity?;
+    private depth;
+    private k;
+    constructor(config: XacheGraphRetrieverConfig);
+    _getRelevantDocuments(query: string, _runManager?: CallbackManagerForRetrieverRun): Promise<Document[]>;
+}
+
+export { type CollectiveToolConfig, type ExtractedMemory, type ExtractionResult, type GraphToolConfig, type ReputationResult, type ReputationToolConfig, XacheChatMessageHistory, type XacheChatMessageHistoryConfig, XacheCollectiveContributeTool, XacheCollectiveQueryTool, XacheConversationBufferMemory, XacheExtractor, type XacheExtractorConfig, XacheGraphAskTool, XacheGraphEntityHistoryTool, XacheGraphExtractTool, XacheGraphLoadTool, XacheGraphMergeEntitiesTool, XacheGraphQueryTool, XacheGraphRetriever, type XacheGraphRetrieverConfig, XacheMemory, type XacheMemoryConfig, XacheReputationChecker, XacheReputationTool, XacheRetriever, type XacheRetrieverConfig, createCollectiveContributeTool, createCollectiveQueryTool, createGraphAddEntityTool, createGraphAddRelationshipTool, createGraphAskTool, createGraphEntityHistoryTool, createGraphExtractTool, createGraphLoadTool, createGraphMergeEntitiesTool, createGraphQueryTool, createReputationTool };

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { BaseMessage } from '@langchain/core/messages';
 import { BaseRetriever, BaseRetrieverInput } from '@langchain/core/retrievers';
 import { Document } from '@langchain/core/documents';
 import { CallbackManagerForRetrieverRun } from '@langchain/core/callbacks/manager';
-import { LLMProvider, LLMApiFormat } from '@xache/sdk';
+import { LLMProvider, LLMApiFormat, SubjectContext } from '@xache/sdk';
 import { DynamicStructuredTool } from '@langchain/core/tools';
 
 /**
@@ -476,4 +476,168 @@ declare class XacheReputationChecker {
     meetsThreshold(agentDid: string, minScore: number): Promise<boolean>;
 }
 
-export { type CollectiveToolConfig, type ExtractedMemory, type ExtractionResult, type ReputationResult, type ReputationToolConfig, XacheChatMessageHistory, type XacheChatMessageHistoryConfig, XacheCollectiveContributeTool, XacheCollectiveQueryTool, XacheConversationBufferMemory, XacheExtractor, type XacheExtractorConfig, XacheMemory, type XacheMemoryConfig, XacheReputationChecker, XacheReputationTool, XacheRetriever, type XacheRetrieverConfig, createCollectiveContributeTool, createCollectiveQueryTool, createReputationTool };
+/**
+ * Xache Knowledge Graph for LangChain.js
+ * Extract, query, and manage entities/relationships in a privacy-preserving knowledge graph
+ */
+
+interface GraphToolConfig {
+    /** Wallet address for authentication */
+    walletAddress: string;
+    /** Private key for signing */
+    privateKey: string;
+    /** API URL (defaults to https://api.xache.xyz) */
+    apiUrl?: string;
+    /** Chain: 'base' or 'solana' */
+    chain?: 'base' | 'solana';
+    /** Subject context for graph scoping (defaults to GLOBAL) */
+    subject?: SubjectContext;
+    /** LLM provider for extract/ask (api-key mode) */
+    llmProvider?: LLMProvider;
+    /** LLM API key */
+    llmApiKey?: string;
+    /** LLM model override */
+    llmModel?: string;
+    /** LLM endpoint URL (endpoint mode) */
+    llmEndpoint?: string;
+    /** LLM auth token (endpoint mode) */
+    llmAuthToken?: string;
+    /** LLM API format (endpoint mode, default: openai) */
+    llmFormat?: LLMApiFormat;
+}
+/**
+ * Create a tool for extracting entities/relationships from agent traces.
+ *
+ * @example
+ * ```typescript
+ * const extractTool = createGraphExtractTool({
+ *   walletAddress: '0x...',
+ *   privateKey: '0x...',
+ *   llmProvider: 'anthropic',
+ *   llmApiKey: 'sk-ant-...',
+ * });
+ * ```
+ */
+declare function createGraphExtractTool(config: GraphToolConfig): DynamicStructuredTool;
+/**
+ * Create a tool for querying the knowledge graph around a specific entity.
+ */
+declare function createGraphQueryTool(config: GraphToolConfig): DynamicStructuredTool;
+/**
+ * Create a tool for asking natural language questions about the knowledge graph.
+ */
+declare function createGraphAskTool(config: GraphToolConfig): DynamicStructuredTool;
+/**
+ * Create a tool for adding entities to the knowledge graph.
+ */
+declare function createGraphAddEntityTool(config: GraphToolConfig): DynamicStructuredTool;
+/**
+ * Create a tool for adding relationships between entities.
+ */
+declare function createGraphAddRelationshipTool(config: GraphToolConfig): DynamicStructuredTool;
+/**
+ * Create a tool for loading the full knowledge graph.
+ */
+declare function createGraphLoadTool(config: GraphToolConfig): DynamicStructuredTool;
+/**
+ * Create a tool for merging two entities in the knowledge graph.
+ */
+declare function createGraphMergeEntitiesTool(config: GraphToolConfig): DynamicStructuredTool;
+/**
+ * Create a tool for getting the version history of an entity.
+ */
+declare function createGraphEntityHistoryTool(config: GraphToolConfig): DynamicStructuredTool;
+/**
+ * Class wrapper for graph extract tool
+ */
+declare class XacheGraphExtractTool {
+    private tool;
+    constructor(config: GraphToolConfig);
+    asTool(): DynamicStructuredTool;
+}
+/**
+ * Class wrapper for graph query tool
+ */
+declare class XacheGraphQueryTool {
+    private tool;
+    constructor(config: GraphToolConfig);
+    asTool(): DynamicStructuredTool;
+}
+/**
+ * Class wrapper for graph ask tool
+ */
+declare class XacheGraphAskTool {
+    private tool;
+    constructor(config: GraphToolConfig);
+    asTool(): DynamicStructuredTool;
+}
+/**
+ * Class wrapper for graph load tool
+ */
+declare class XacheGraphLoadTool {
+    private tool;
+    constructor(config: GraphToolConfig);
+    asTool(): DynamicStructuredTool;
+}
+/**
+ * Class wrapper for graph merge entities tool
+ */
+declare class XacheGraphMergeEntitiesTool {
+    private tool;
+    constructor(config: GraphToolConfig);
+    asTool(): DynamicStructuredTool;
+}
+/**
+ * Class wrapper for graph entity history tool
+ */
+declare class XacheGraphEntityHistoryTool {
+    private tool;
+    constructor(config: GraphToolConfig);
+    asTool(): DynamicStructuredTool;
+}
+interface XacheGraphRetrieverConfig extends BaseRetrieverInput {
+    /** Wallet address for authentication */
+    walletAddress: string;
+    /** Private key for signing */
+    privateKey: string;
+    /** API URL (defaults to https://api.xache.xyz) */
+    apiUrl?: string;
+    /** Chain: 'base' or 'solana' */
+    chain?: 'base' | 'solana';
+    /** Subject context for graph scoping */
+    subject?: SubjectContext;
+    /** Starting entity for subgraph query (optional — if not set, loads full graph) */
+    startEntity?: string;
+    /** Depth for subgraph query (default: 2) */
+    depth?: number;
+    /** Max results to return */
+    k?: number;
+}
+/**
+ * Retriever that fetches documents from the Xache knowledge graph.
+ * Each entity becomes a Document with its name, type, and summary.
+ *
+ * @example
+ * ```typescript
+ * const retriever = new XacheGraphRetriever({
+ *   walletAddress: '0x...',
+ *   privateKey: '0x...',
+ *   k: 10,
+ * });
+ *
+ * const docs = await retriever.getRelevantDocuments('engineering team');
+ * ```
+ */
+declare class XacheGraphRetriever extends BaseRetriever {
+    lc_namespace: string[];
+    static lc_name(): string;
+    private client;
+    private subject;
+    private startEntity?;
+    private depth;
+    private k;
+    constructor(config: XacheGraphRetrieverConfig);
+    _getRelevantDocuments(query: string, _runManager?: CallbackManagerForRetrieverRun): Promise<Document[]>;
+}
+
+export { type CollectiveToolConfig, type ExtractedMemory, type ExtractionResult, type GraphToolConfig, type ReputationResult, type ReputationToolConfig, XacheChatMessageHistory, type XacheChatMessageHistoryConfig, XacheCollectiveContributeTool, XacheCollectiveQueryTool, XacheConversationBufferMemory, XacheExtractor, type XacheExtractorConfig, XacheGraphAskTool, XacheGraphEntityHistoryTool, XacheGraphExtractTool, XacheGraphLoadTool, XacheGraphMergeEntitiesTool, XacheGraphQueryTool, XacheGraphRetriever, type XacheGraphRetrieverConfig, XacheMemory, type XacheMemoryConfig, XacheReputationChecker, XacheReputationTool, XacheRetriever, type XacheRetrieverConfig, createCollectiveContributeTool, createCollectiveQueryTool, createGraphAddEntityTool, createGraphAddRelationshipTool, createGraphAskTool, createGraphEntityHistoryTool, createGraphExtractTool, createGraphLoadTool, createGraphMergeEntitiesTool, createGraphQueryTool, createReputationTool };