@cloudbase/agent-adapter-langgraph 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# @cloudbase/agent-adapter-langgraph
+
+## 0.0.10
+
+### Patch Changes
+
+- stable release 0.0.10
+  - Update all public packages to version 0.0.10
+  - Trigger automated stable release workflow
+  - Includes latest features and improvements
+
+- Updated dependencies
+  - @cloudbase/agent-agents@0.0.10
+
+## 0.0.10-alpha.1
+
+### Patch Changes
+
+- alpha release 0.0.9-alpha.3
+  - Update all public packages to version 0.0.9-alpha.3
+  - Trigger automated alpha release workflow
+  - Includes latest features and improvements
+
+- Updated dependencies
+  - @cloudbase/agent-agents@0.0.10-alpha.1
+
+## 0.0.10-alpha.0
+
+### Patch Changes
+
+- alpha release 0.0.9-alpha.3
+  - Update all public packages to version 0.0.9-alpha.3
+  - Trigger automated alpha release workflow
+  - Includes latest features and improvements
+
+- Updated dependencies
+  - @cloudbase/agent-agents@0.0.10-alpha.0

package/README.md

@@ -0,0 +1,125 @@
+# @cloudbase/agent-adapter-langgraph
+
+LangGraph adapter for AG-Kit agents. This package provides integration between AG-Kit and LangGraph framework, enabling you to use LangGraph workflows with AG-Kit's agent infrastructure.
+
+## Installation
+
+```bash
+npm install @cloudbase/agent-agents @cloudbase/agent-adapter-langgraph
+```
+
+## Features
+
+- **LangGraphAgent**: Agent implementation that works with compiled LangGraph workflows
+- **TDAISaver**: Checkpoint saver implementation using TDAI Memory
+- **TDAIStore**: Store implementation for LangGraph using TDAI Memory
+- **AGKitStateAnnotation**: Pre-configured state annotation for AG-Kit integration
+
+## Usage
+
+### Basic Agent Setup
+
+```typescript
+import { StateGraph, START, END } from "@langchain/langgraph";
+import { AGKitStateAnnotation, LanggraphAgent } from "@cloudbase/agent-adapter-langgraph";
+import { AgentConfig } from "@cloudbase/agent-agents/abstract";
+
+// Create your LangGraph workflow
+const workflow = new StateGraph(AGKitStateAnnotation)
+  .addNode("chat_node", chatNode)
+  .addEdge(START, "chat_node")
+  .addEdge("chat_node", END);
+
+const compiledWorkflow = workflow.compile();
+
+// Create the agent
+const agent = new LanggraphAgent({
+  name: "my-langgraph-agent",
+  description: "A LangGraph agent",
+  compiledWorkflow,
+});
+```
+
+### Using TDAISaver for Checkpoints
+
+```typescript
+import { TDAISaver } from "@cloudbase/agent-adapter-langgraph";
+import { MemoryClient } from "@cloudbase/agent-agents";
+
+const memoryClient = new MemoryClient({
+  endpoint: "https://api.tdai.com",
+  apiKey: "your-api-key",
+  memoryId: "your-memory-id",
+});
+
+const checkpointer = new TDAISaver({
+  endpoint: "https://api.tdai.com",
+  apiKey: "your-api-key",
+  memoryId: "your-memory-id",
+});
+
+const compiledWorkflow = workflow.compile({
+  checkpointer,
+});
+```
+
+### Using TDAIStore
+
+```typescript
+import { TDAIStore } from "@cloudbase/agent-adapter-langgraph";
+import { MemoryClient } from "@cloudbase/agent-agents";
+
+const memoryClient = new MemoryClient({
+  endpoint: "https://api.tdai.com",
+  apiKey: "your-api-key",
+  memoryId: "your-memory-id",
+});
+
+const store = new TDAIStore({
+  memoryClient,
+  sessionId: "session-123",
+});
+```
+
+## API Reference
+
+### LanggraphAgent
+
+Agent class that extends `AbstractAgent` and works with compiled LangGraph workflows.
+
+**Constructor:**
+```typescript
+constructor(config: AgentConfig & { compiledWorkflow: CompiledStateGraph })
+```
+
+### TDAISaver
+
+Checkpoint saver implementation for LangGraph using TDAI Memory.
+
+**Constructor:**
+```typescript
+constructor(config: TDAISaverConfig)
+```
+
+### TDAIStore
+
+Store implementation for LangGraph using TDAI Memory.
+
+**Constructor:**
+```typescript
+constructor(config: TDAIStoreConfig)
+```
+
+## Requirements
+
+- `@cloudbase/agent-agents`: Core agent functionality
+- `@langchain/langgraph`: LangGraph framework
+- `@langchain/core`: LangChain core utilities
+- `rxjs`: Reactive extensions for JavaScript
+
+## Related Resources
+
+- [AG-Kit Documentation](https://docs.agkit.dev)
+- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)
+- [AG-Kit Examples](https://github.com/agkit/agkit/tree/main/typescript-sdk/packages/examples)
+

package/dist/index.d.mts

@@ -0,0 +1,289 @@
+import * as _langchain_core_messages from '@langchain/core/messages';
+import * as _langchain_langgraph from '@langchain/langgraph';
+import { AnnotationRoot, StateDefinition, StateGraph, BaseCheckpointSaver, CheckpointTuple, Checkpoint, CheckpointMetadata, BaseStore, Item, Operation, OperationResults } from '@langchain/langgraph';
+import { RunAgentInput, EventType, BaseEvent } from '@ag-ui/client';
+import { AbstractAgent, AgentConfig } from '@cloudbase/agent-agents/abstract';
+import { Observable, Subscriber } from 'rxjs';
+import { InteropZodObject } from '@langchain/core/utils/types';
+import { RunnableConfig } from '@langchain/core/runnables';
+import { IMemoryClientOptions, MemoryClient } from '@cloudbase/agent-agents';
+
+type SDZod = StateDefinition | InteropZodObject;
+type CompiledStateGraph<SD extends SDZod> = ReturnType<StateGraph<SD>["compile"]>;
+type AnnotationInside<T> = T extends AnnotationRoot<infer U> ? U : never;
+type AGKitStateDefinition = AnnotationInside<typeof AGKitStateAnnotation>;
+declare const AGKitPropertiesAnnotation: AnnotationRoot<{
+    actions: {
+        (): _langchain_langgraph.LastValue<any[]>;
+        (annotation: _langchain_langgraph.SingleReducer<any[], any[]>): _langchain_langgraph.BinaryOperatorAggregate<any[], any[]>;
+        Root: <S extends StateDefinition>(sd: S) => AnnotationRoot<S>;
+    };
+}>;
+declare const AGKitStateAnnotation: AnnotationRoot<{
+    messages: _langchain_langgraph.BinaryOperatorAggregate<_langchain_core_messages.BaseMessage<_langchain_core_messages.MessageStructure, _langchain_core_messages.MessageType>[], _langchain_langgraph.Messages>;
+    agKit: {
+        (): _langchain_langgraph.LastValue<_langchain_langgraph.StateType<{
+            actions: {
+                (): _langchain_langgraph.LastValue<any[]>;
+                (annotation: _langchain_langgraph.SingleReducer<any[], any[]>): _langchain_langgraph.BinaryOperatorAggregate<any[], any[]>;
+                Root: <S extends StateDefinition>(sd: S) => AnnotationRoot<S>;
+            };
+        }>>;
+        (annotation: _langchain_langgraph.SingleReducer<_langchain_langgraph.StateType<{
+            actions: {
+                (): _langchain_langgraph.LastValue<any[]>;
+                (annotation: _langchain_langgraph.SingleReducer<any[], any[]>): _langchain_langgraph.BinaryOperatorAggregate<any[], any[]>;
+                Root: <S extends StateDefinition>(sd: S) => AnnotationRoot<S>;
+            };
+        }>, _langchain_langgraph.StateType<{
+            actions: {
+                (): _langchain_langgraph.LastValue<any[]>;
+                (annotation: _langchain_langgraph.SingleReducer<any[], any[]>): _langchain_langgraph.BinaryOperatorAggregate<any[], any[]>;
+                Root: <S extends StateDefinition>(sd: S) => AnnotationRoot<S>;
+            };
+        }>>): _langchain_langgraph.BinaryOperatorAggregate<_langchain_langgraph.StateType<{
+            actions: {
+                (): _langchain_langgraph.LastValue<any[]>;
+                (annotation: _langchain_langgraph.SingleReducer<any[], any[]>): _langchain_langgraph.BinaryOperatorAggregate<any[], any[]>;
+                Root: <S extends StateDefinition>(sd: S) => AnnotationRoot<S>;
+            };
+        }>, _langchain_langgraph.StateType<{
+            actions: {
+                (): _langchain_langgraph.LastValue<any[]>;
+                (annotation: _langchain_langgraph.SingleReducer<any[], any[]>): _langchain_langgraph.BinaryOperatorAggregate<any[], any[]>;
+                Root: <S extends StateDefinition>(sd: S) => AnnotationRoot<S>;
+            };
+        }>>;
+        Root: <S extends StateDefinition>(sd: S) => AnnotationRoot<S>;
+    };
+}>;
+type AGKitState = typeof AGKitStateAnnotation.State;
+declare class LanggraphAgent extends AbstractAgent {
+    compiledWorkflow?: CompiledStateGraph<AGKitStateDefinition>;
+    constructor(agentConfig: AgentConfig & {
+        compiledWorkflow: any;
+    });
+    run(input: RunAgentInput): Observable<{
+        type: EventType;
+        timestamp?: number | undefined;
+        rawEvent?: any;
+    }>;
+    _run(subscriber: Subscriber<BaseEvent>, input: RunAgentInput): Promise<void>;
+    clone(): any;
+}
+
+type PendingWrite = [string, any];
+interface CheckpointListOptions {
+    limit?: number;
+    before?: RunnableConfig;
+    filter?: Record<string, any>;
+}
+interface TDAISaverConfig extends IMemoryClientOptions {
+    checkpointType?: string;
+    checkpointWritesType?: string;
+}
+/**
+ * TDAISaver - LangGraph checkpoint saver implementation using TDAI Memory
+ *
+ * Storage Strategy:
+ * - Events (NoSQL): Store checkpoint data and pending writes in separate collections
+ * - Supports namespaces and parent checkpoint relationships
+ */
+declare class TDAISaver extends BaseCheckpointSaver {
+    private memoryClient;
+    private checkpointType;
+    private checkpointWritesType;
+    constructor(config: TDAISaverConfig);
+    /**
+     * Retrieves a checkpoint from TDAI Memory based on the provided config.
+     * If the config contains a "checkpoint_id" key, the checkpoint with the matching
+     * thread ID and checkpoint ID is retrieved. Otherwise, the latest checkpoint
+     * for the given thread ID is retrieved.
+     */
+    getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
+    /**
+     * Retrieve a list of checkpoint tuples from TDAI Memory based on the provided config.
+     * The checkpoints are ordered by checkpoint ID in descending order (newest first).
+     */
+    list(config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;
+    /**
+     * Saves a checkpoint to TDAI Memory. The checkpoint is associated with the
+     * provided config and its parent config (if any).
+     */
+    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata): Promise<RunnableConfig>;
+    /**
+     * Saves intermediate writes associated with a checkpoint to TDAI Memory.
+     */
+    putWrites(config: RunnableConfig, writes: PendingWrite[], taskId: string): Promise<void>;
+    /**
+     * Delete all checkpoints and writes for a thread from TDAI Memory.
+     */
+    deleteThread(threadId: string): Promise<void>;
+    /**
+     * Close the memory client connection
+     */
+    close(): void;
+}
+
+/**
+ * TDAI Store configuration
+ */
+interface TDAIStoreConfig {
+    /**
+     * TDAI Memory Client instance for long-term storage
+     */
+    memoryClient: MemoryClient;
+    /**
+     * Session ID for storing records
+     */
+    sessionId: string;
+    /**
+     * Optional namespace prefix for all operations
+     */
+    namespacePrefix?: string[];
+    /**
+     * TTL configuration for records
+     */
+    ttl?: {
+        defaultTtlSeconds?: number;
+        sweepIntervalMinutes?: number;
+    };
+    /**
+     * Whether to ensure tables/collections exist on startup
+     */
+    ensureTables?: boolean;
+    /**
+     * Default strategy for storing records
+     */
+    defaultStrategy?: string;
+}
+/**
+ * Filter operators for advanced filtering
+ */
+interface FilterOperators {
+    $eq?: unknown;
+    $ne?: unknown;
+    $gt?: number | Date;
+    $gte?: number | Date;
+    $lt?: number | Date;
+    $lte?: number | Date;
+    $in?: unknown[];
+    $nin?: unknown[];
+    $exists?: boolean;
+    $regex?: string;
+}
+/**
+ * TDAI implementation of the BaseStore interface.
+ * Uses TDAI Memory Client for long-term record storage.
+ */
+declare class TDAIStore extends BaseStore {
+    private client;
+    private namespacePrefix;
+    private ttlConfig?;
+    private ensureTables;
+    private isSetup;
+    private isClosed;
+    private sweepInterval?;
+    private sessionId;
+    private defaultStrategy;
+    constructor(config: TDAIStoreConfig);
+    /**
+     * Create a storage key from namespace and key
+     */
+    private createStorageKey;
+    /**
+     * Parse a storage key back to namespace and key
+     */
+    private parseStorageKey;
+    /**
+     * Put an item with optional TTL.
+     */
+    put(namespace: string[], key: string, value: Record<string, unknown>, index?: false | string[], options?: {
+        ttl?: number;
+    }): Promise<void>;
+    /**
+     * Get an item by namespace and key.
+     */
+    get(namespace: string[], key: string): Promise<Item | null>;
+    /**
+     * Delete an item by namespace and key.
+     */
+    delete(namespace: string[], key: string): Promise<void>;
+    /**
+     * List namespaces with optional filtering.
+     */
+    listNamespaces(options?: {
+        prefix?: string[];
+        suffix?: string[];
+        maxDepth?: number;
+        limit?: number;
+        offset?: number;
+    }): Promise<string[][]>;
+    /**
+     * Execute multiple operations in a single batch.
+     */
+    batch<Op extends Operation[]>(operations: Op): Promise<OperationResults<Op>>;
+    /**
+     * Execute search operation
+     */
+    private executeSearch;
+    /**
+     * Execute list namespaces operation
+     */
+    private executeListNamespaces;
+    /**
+     * Initialize the store.
+     */
+    setup(): Promise<void>;
+    /**
+     * Start the store.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the store and close all connections.
+     */
+    stop(): Promise<void>;
+    /**
+     * Manually sweep expired items from the store.
+     */
+    sweepExpiredItems(): Promise<number>;
+    /**
+     * Get statistics about the store.
+     */
+    getStats(): Promise<{
+        totalItems: number;
+        expiredItems: number;
+        namespaceCount: number;
+        oldestItem: Date | null;
+        newestItem: Date | null;
+    }>;
+    /**
+     * Search for items in the store with support for text search and filtering.
+     */
+    search(namespacePrefix: string[], options?: {
+        /**
+         * Filter conditions with support for advanced operators.
+         */
+        filter?: Record<string, string | number | boolean | null | FilterOperators>;
+        /**
+         * Natural language search query.
+         */
+        query?: string;
+        /**
+         * Maximum number of results to return.
+         * @default 10
+         */
+        limit?: number;
+        /**
+         * Number of results to skip for pagination.
+         * @default 0
+         */
+        offset?: number;
+        /**
+         * Whether to refresh TTL for returned items.
+         */
+        refreshTtl?: boolean;
+    }): Promise<Item[]>;
+}
+
+export { AGKitPropertiesAnnotation, type AGKitState, AGKitStateAnnotation, LanggraphAgent, TDAISaver, type TDAISaverConfig, TDAIStore, type TDAIStoreConfig };