@mondaydotcomorg/atp-langchain 0.17.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +434 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +5 -0
- package/dist/index.js.map +1 -0
- package/dist/langgraph-client.d.ts +156 -0
- package/dist/langgraph-client.d.ts.map +1 -0
- package/dist/langgraph-client.js +231 -0
- package/dist/langgraph-client.js.map +1 -0
- package/dist/langgraph-tools.d.ts +79 -0
- package/dist/langgraph-tools.d.ts.map +1 -0
- package/dist/langgraph-tools.js +149 -0
- package/dist/langgraph-tools.js.map +1 -0
- package/dist/node.d.ts +29 -0
- package/dist/node.d.ts.map +1 -0
- package/dist/node.js +49 -0
- package/dist/node.js.map +1 -0
- package/dist/tools.d.ts +39 -0
- package/dist/tools.d.ts.map +1 -0
- package/dist/tools.js +52 -0
- package/dist/tools.js.map +1 -0
- package/package.json +45 -0
- package/src/index.ts +11 -0
- package/src/langgraph-client.ts +369 -0
- package/src/langgraph-tools.ts +219 -0
- package/src/node.ts +60 -0
- package/src/tools.ts +72 -0
package/README.md
ADDED
|
@@ -0,0 +1,434 @@
|
|
|
1
|
+
# @mondaydotcomorg/atp-langchain
|
|
2
|
+
|
|
3
|
+
LangChain and LangGraph integration for Agent Tool Protocol with production-ready human-in-the-loop support.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
This package integrates ATP with LangChain and LangGraph, enabling agents to generate and execute ATP code as tools. Includes production-ready async approval workflows using LangGraph interrupts and checkpoints.
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install @mondaydotcomorg/atp-langchain @langchain/core @langchain/langgraph
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Architecture
|
|
16
|
+
|
|
17
|
+
```mermaid
|
|
18
|
+
graph TB
|
|
19
|
+
LangChain[LangChain Agent] --> Tools[ATP Tools]
|
|
20
|
+
Tools --> Client[LangGraphATPClient]
|
|
21
|
+
|
|
22
|
+
Client --> Server[ATP Server]
|
|
23
|
+
Server --> Runtime[Runtime APIs]
|
|
24
|
+
|
|
25
|
+
Runtime --> LLM[atp.llm.*]
|
|
26
|
+
Runtime --> Embed[atp.embedding.*]
|
|
27
|
+
Runtime --> Approval[atp.approval.*]
|
|
28
|
+
|
|
29
|
+
LLM --> Callback[Client LLM Callback]
|
|
30
|
+
Embed --> EmbedCallback[Client Embedding Callback]
|
|
31
|
+
Approval --> Interrupt[LangGraph Interrupt]
|
|
32
|
+
|
|
33
|
+
Interrupt --> Checkpoint[Save State]
|
|
34
|
+
Checkpoint --> Resume[Resume Later]
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Features
|
|
38
|
+
|
|
39
|
+
- 🤖 **LangChain Tools** - Use ATP as tools in any LangChain agent
|
|
40
|
+
- 🔄 **LangGraph Interrupts** - Production-ready async approvals
|
|
41
|
+
- 🧠 **LLM Sampling** - `atp.llm.call()` routes to your LangChain LLM
|
|
42
|
+
- 🔍 **Embedding Support** - `atp.embedding.*` routes to your embeddings model
|
|
43
|
+
- ✅ **Approval Workflows** - Human-in-the-loop via LangGraph checkpoints
|
|
44
|
+
- 💾 **State Persistence** - PostgreSQL/Redis checkpointing
|
|
45
|
+
- 📝 **TypeScript** - Full type safety
|
|
46
|
+
|
|
47
|
+
## Quick Start
|
|
48
|
+
|
|
49
|
+
### Simple Agent
|
|
50
|
+
|
|
51
|
+
```typescript
|
|
52
|
+
import { ChatOpenAI } from '@langchain/openai';
|
|
53
|
+
import { createReactAgent } from '@langchain/langgraph/prebuilt';
|
|
54
|
+
import { createATPTools } from '@mondaydotcomorg/atp-langchain';
|
|
55
|
+
|
|
56
|
+
const llm = new ChatOpenAI({ modelName: 'gpt-4' });
|
|
57
|
+
|
|
58
|
+
// Create ATP tools
|
|
59
|
+
const { tools } = await createATPTools('http://localhost:3333', 'your-api-key', { llm });
|
|
60
|
+
|
|
61
|
+
// Create agent
|
|
62
|
+
const agent = createReactAgent({ llm, tools });
|
|
63
|
+
|
|
64
|
+
// Run agent
|
|
65
|
+
const result = await agent.invoke({
|
|
66
|
+
messages: [{ role: 'user', content: 'Execute ATP code to get a joke from the LLM' }],
|
|
67
|
+
});
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### Production Agent with Approvals
|
|
71
|
+
|
|
72
|
+
```typescript
|
|
73
|
+
import { MemorySaver } from '@langchain/langgraph';
|
|
74
|
+
import { createATPTools, ApprovalRequiredException } from '@mondaydotcomorg/atp-langchain';
|
|
75
|
+
|
|
76
|
+
const llm = new ChatOpenAI({ modelName: 'gpt-4' });
|
|
77
|
+
|
|
78
|
+
// Create tools with interrupt-based approvals
|
|
79
|
+
const { client, tools, isApprovalRequired, resumeWithApproval } =
|
|
80
|
+
await createATPTools('http://localhost:3333', 'api-key', { llm });
|
|
81
|
+
|
|
82
|
+
// Create agent with checkpointer
|
|
83
|
+
const checkpointer = new MemorySaver();
|
|
84
|
+
const agent = createReactAgent({ llm, tools, checkpointSaver: checkpointer });
|
|
85
|
+
|
|
86
|
+
try {
|
|
87
|
+
await agent.invoke({ messages: [...] }, { configurable: { thread_id: 'thread-1' } });
|
|
88
|
+
} catch (error) {
|
|
89
|
+
if (isApprovalRequired(error)) {
|
|
90
|
+
const { executionId, message, context } = error.approvalRequest;
|
|
91
|
+
|
|
92
|
+
// Save to DB, notify user via Slack/email
|
|
93
|
+
console.log(`Approval needed: ${message}`);
|
|
94
|
+
await notifyUser(message);
|
|
95
|
+
|
|
96
|
+
// Wait for approval (async - can take hours/days)
|
|
97
|
+
const approved = await waitForUserApproval(executionId);
|
|
98
|
+
|
|
99
|
+
// Resume execution
|
|
100
|
+
const result = await resumeWithApproval(executionId, approved);
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### With Embeddings
|
|
106
|
+
|
|
107
|
+
```typescript
|
|
108
|
+
import { ChatOpenAI, OpenAIEmbeddings } from '@langchain/openai';
|
|
109
|
+
import { createATPTools } from '@mondaydotcomorg/atp-langchain';
|
|
110
|
+
|
|
111
|
+
const llm = new ChatOpenAI({ modelName: 'gpt-4' });
|
|
112
|
+
const embeddings = new OpenAIEmbeddings({ model: 'text-embedding-3-small' });
|
|
113
|
+
|
|
114
|
+
// Create tools with LLM and embedding support
|
|
115
|
+
const { tools } = await createATPTools('http://localhost:3333', 'api-key', {
|
|
116
|
+
llm,
|
|
117
|
+
embeddings, // Enable atp.embedding.*
|
|
118
|
+
});
|
|
119
|
+
|
|
120
|
+
const agent = createReactAgent({ llm, tools });
|
|
121
|
+
|
|
122
|
+
// Agent can now generate code that uses embeddings:
|
|
123
|
+
// const id = await atp.embedding.embed("Store this text");
|
|
124
|
+
// const results = await atp.embedding.search("Find similar", { topK: 5 });
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## How It Works
|
|
128
|
+
|
|
129
|
+
### ATP Runtime in LangChain
|
|
130
|
+
|
|
131
|
+
When agents use ATP tools, they can generate TypeScript code using ATP's runtime APIs:
|
|
132
|
+
|
|
133
|
+
```typescript
|
|
134
|
+
// Agent generates this code:
|
|
135
|
+
const idea = await atp.llm.call({
|
|
136
|
+
prompt: 'Generate a product idea',
|
|
137
|
+
});
|
|
138
|
+
|
|
139
|
+
// Store embedding for semantic search
|
|
140
|
+
const embeddingId = await atp.embedding.embed(idea);
|
|
141
|
+
|
|
142
|
+
// Request approval
|
|
143
|
+
const approval = await atp.approval.request(`Launch product: ${idea}?`, { idea });
|
|
144
|
+
|
|
145
|
+
if (approval.approved) {
|
|
146
|
+
return await atp.llm.call({
|
|
147
|
+
prompt: `Create marketing copy for: ${idea}`,
|
|
148
|
+
});
|
|
149
|
+
}
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
### LLM Sampling
|
|
153
|
+
|
|
154
|
+
`atp.llm.call()` routes to your LangChain LLM:
|
|
155
|
+
|
|
156
|
+
- Uses the same LLM as your agent
|
|
157
|
+
- Fresh context for sub-reasoning
|
|
158
|
+
- Supports `call()`, `extract()`, `classify()`
|
|
159
|
+
|
|
160
|
+
```typescript
|
|
161
|
+
// In ATP code:
|
|
162
|
+
const analysis = await atp.llm.call({
|
|
163
|
+
prompt: 'Analyze this data: ' + JSON.stringify(data),
|
|
164
|
+
temperature: 0.7,
|
|
165
|
+
model: 'gpt-4',
|
|
166
|
+
});
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
### Approval Interrupts
|
|
170
|
+
|
|
171
|
+
When ATP code calls `atp.approval.request()`, LangGraph interrupts:
|
|
172
|
+
|
|
173
|
+
1. **Pause** - Execution pauses, state saved to checkpoint
|
|
174
|
+
2. **Notify** - Your code sends approval request (Slack, email, UI)
|
|
175
|
+
3. **Wait** - User reviews asynchronously (hours/days OK)
|
|
176
|
+
4. **Resume** - Call `resumeWithApproval()` with decision
|
|
177
|
+
5. **Continue** - Execution resumes from checkpoint
|
|
178
|
+
|
|
179
|
+
```mermaid
|
|
180
|
+
sequenceDiagram
|
|
181
|
+
participant Agent
|
|
182
|
+
participant ATP
|
|
183
|
+
participant Checkpoint
|
|
184
|
+
participant User
|
|
185
|
+
|
|
186
|
+
Agent->>ATP: Execute code
|
|
187
|
+
ATP->>ATP: atp.approval.request()
|
|
188
|
+
ATP->>Checkpoint: Save state
|
|
189
|
+
ATP-->>Agent: Throw ApprovalRequiredException
|
|
190
|
+
Agent->>User: Notify (Slack/Email)
|
|
191
|
+
|
|
192
|
+
Note over User: User reviews<br/>(async, can take hours)
|
|
193
|
+
|
|
194
|
+
User->>Agent: Approve/Deny
|
|
195
|
+
Agent->>ATP: resumeWithApproval(executionId, approved)
|
|
196
|
+
ATP->>Checkpoint: Restore state
|
|
197
|
+
ATP->>ATP: Continue execution
|
|
198
|
+
ATP-->>Agent: Final result
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
## API Reference
|
|
202
|
+
|
|
203
|
+
### createATPTools()
|
|
204
|
+
|
|
205
|
+
```typescript
|
|
206
|
+
async function createATPTools(
|
|
207
|
+
serverUrl: string,
|
|
208
|
+
apiKey: string,
|
|
209
|
+
options: CreateATPToolsOptions
|
|
210
|
+
): Promise<ATPToolsResult>;
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
**Options:**
|
|
214
|
+
|
|
215
|
+
```typescript
|
|
216
|
+
interface CreateATPToolsOptions {
|
|
217
|
+
llm: BaseChatModel; // Required: LangChain LLM
|
|
218
|
+
embeddings?: Embeddings; // Optional: Embeddings model
|
|
219
|
+
useLangGraphInterrupts?: boolean; // Default: true
|
|
220
|
+
approvalHandler?: ApprovalHandler; // If interrupts disabled
|
|
221
|
+
defaultExecutionConfig?: ExecutionConfig;
|
|
222
|
+
}
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
**Returns:**
|
|
226
|
+
|
|
227
|
+
```typescript
|
|
228
|
+
interface ATPToolsResult {
|
|
229
|
+
client: LangGraphATPClient;
|
|
230
|
+
tools: Tool[]; // LangChain tools
|
|
231
|
+
isApprovalRequired: (error: any) => boolean;
|
|
232
|
+
resumeWithApproval: (executionId: string, approved: boolean, reason?: string) => Promise<any>;
|
|
233
|
+
}
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
### LangGraphATPClient
|
|
237
|
+
|
|
238
|
+
```typescript
|
|
239
|
+
class LangGraphATPClient extends AgentToolProtocolClient {
|
|
240
|
+
execute(code: string, config?: ExecutionConfig): Promise<ExecutionResult>;
|
|
241
|
+
resumeWithApproval(executionId: string, approved: boolean, reason?: string): Promise<any>;
|
|
242
|
+
getPendingApproval(executionId: string): Promise<ApprovalRequest | null>;
|
|
243
|
+
}
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
### ApprovalRequiredException
|
|
247
|
+
|
|
248
|
+
```typescript
|
|
249
|
+
class ApprovalRequiredException extends Error {
|
|
250
|
+
approvalRequest: {
|
|
251
|
+
executionId: string;
|
|
252
|
+
message: string;
|
|
253
|
+
context?: any;
|
|
254
|
+
timestamp: number;
|
|
255
|
+
};
|
|
256
|
+
}
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
## Production Patterns
|
|
260
|
+
|
|
261
|
+
### PostgreSQL Checkpointing
|
|
262
|
+
|
|
263
|
+
```typescript
|
|
264
|
+
import { PostgresSaver } from '@langchain/langgraph-checkpoint-postgres';
|
|
265
|
+
|
|
266
|
+
const checkpointer = new PostgresSaver({
|
|
267
|
+
connectionString: process.env.DATABASE_URL,
|
|
268
|
+
});
|
|
269
|
+
|
|
270
|
+
const agent = createReactAgent({
|
|
271
|
+
llm,
|
|
272
|
+
tools,
|
|
273
|
+
checkpointSaver: checkpointer,
|
|
274
|
+
});
|
|
275
|
+
|
|
276
|
+
// State persists across restarts
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
### Async Approval via Slack
|
|
280
|
+
|
|
281
|
+
```typescript
|
|
282
|
+
if (isApprovalRequired(error)) {
|
|
283
|
+
const { executionId, message, context } = error.approvalRequest;
|
|
284
|
+
|
|
285
|
+
// Save to database
|
|
286
|
+
await db.approvals.create({
|
|
287
|
+
id: executionId,
|
|
288
|
+
message,
|
|
289
|
+
context,
|
|
290
|
+
status: 'pending',
|
|
291
|
+
});
|
|
292
|
+
|
|
293
|
+
// Send Slack notification
|
|
294
|
+
await slack.chat.postMessage({
|
|
295
|
+
channel: '#approvals',
|
|
296
|
+
text: message,
|
|
297
|
+
blocks: [
|
|
298
|
+
{
|
|
299
|
+
type: 'actions',
|
|
300
|
+
elements: [
|
|
301
|
+
{ type: 'button', text: 'Approve', action_id: 'approve' },
|
|
302
|
+
{ type: 'button', text: 'Deny', action_id: 'deny' },
|
|
303
|
+
],
|
|
304
|
+
},
|
|
305
|
+
],
|
|
306
|
+
});
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
// In Slack webhook handler:
|
|
310
|
+
app.post('/slack/actions', async (req, res) => {
|
|
311
|
+
const { action_id } = req.body;
|
|
312
|
+
const executionId = req.body.state.executionId;
|
|
313
|
+
|
|
314
|
+
const approved = action_id === 'approve';
|
|
315
|
+
const result = await resumeWithApproval(executionId, approved);
|
|
316
|
+
|
|
317
|
+
await db.approvals.update(executionId, { status: approved ? 'approved' : 'denied' });
|
|
318
|
+
res.json({ ok: true });
|
|
319
|
+
});
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
### Multiple Sequential Approvals
|
|
323
|
+
|
|
324
|
+
```typescript
|
|
325
|
+
// Agent generates ATP code with multiple approvals:
|
|
326
|
+
const step1 = await atp.approval.request('Approve step 1?');
|
|
327
|
+
if (!step1.approved) return { cancelled: true };
|
|
328
|
+
|
|
329
|
+
const step2 = await atp.approval.request('Approve step 2?');
|
|
330
|
+
if (!step2.approved) return { cancelled: true };
|
|
331
|
+
|
|
332
|
+
return { success: true };
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
Each `atp.approval.request()` triggers a new interrupt → checkpoint → resume cycle.
|
|
336
|
+
|
|
337
|
+
## Comparison: Direct vs Interrupt Mode
|
|
338
|
+
|
|
339
|
+
### Direct Mode
|
|
340
|
+
|
|
341
|
+
```typescript
|
|
342
|
+
const { tools } = await createATPTools(url, key, {
|
|
343
|
+
llm,
|
|
344
|
+
useLangGraphInterrupts: false,
|
|
345
|
+
approvalHandler: async (message) => {
|
|
346
|
+
return await promptUser(message); // Blocks
|
|
347
|
+
},
|
|
348
|
+
});
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
**Pros:** Simpler setup, good for CLI tools
|
|
352
|
+
**Cons:** Blocks execution, no persistence, not production-ready
|
|
353
|
+
|
|
354
|
+
### Interrupt Mode ⭐ Recommended
|
|
355
|
+
|
|
356
|
+
```typescript
|
|
357
|
+
const { tools, isApprovalRequired, resumeWithApproval } = await createATPTools(url, key, { llm });
|
|
358
|
+
|
|
359
|
+
try {
|
|
360
|
+
await agent.invoke({ messages });
|
|
361
|
+
} catch (error) {
|
|
362
|
+
if (isApprovalRequired(error)) {
|
|
363
|
+
await handleApprovalAsync(error.approvalRequest);
|
|
364
|
+
}
|
|
365
|
+
}
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
**Pros:** Non-blocking, state persists, production-ready, multi-user support
|
|
369
|
+
**Cons:** Slightly more complex setup
|
|
370
|
+
|
|
371
|
+
## Examples
|
|
372
|
+
|
|
373
|
+
See [`examples/langchain-react-agent/`](../../examples/langchain-react-agent/):
|
|
374
|
+
|
|
375
|
+
- **`simple-test.ts`** - Integration test with all 3 ATP tools
|
|
376
|
+
- **`simple-agent.ts`** - Basic React agent without approvals
|
|
377
|
+
- **`agent.ts`** - Production agent with interrupts and checkpoints
|
|
378
|
+
|
|
379
|
+
### RAG with Embeddings
|
|
380
|
+
|
|
381
|
+
```typescript
|
|
382
|
+
import { ChatOpenAI, OpenAIEmbeddings } from '@langchain/openai';
|
|
383
|
+
import { createATPTools } from '@mondaydotcomorg/atp-langchain';
|
|
384
|
+
|
|
385
|
+
const llm = new ChatOpenAI({ modelName: 'gpt-4' });
|
|
386
|
+
const embeddings = new OpenAIEmbeddings();
|
|
387
|
+
|
|
388
|
+
const { tools } = await createATPTools(url, key, { llm, embeddings });
|
|
389
|
+
const agent = createReactAgent({ llm, tools });
|
|
390
|
+
|
|
391
|
+
// Agent can do RAG:
|
|
392
|
+
const result = await agent.invoke({
|
|
393
|
+
messages: [
|
|
394
|
+
{
|
|
395
|
+
role: 'user',
|
|
396
|
+
content: `Use ATP to:
|
|
397
|
+
1. Embed these documents: ["AI is...", "ML is...", "DL is..."]
|
|
398
|
+
2. Search for content similar to "neural networks"
|
|
399
|
+
3. Use atp.llm.call() to answer based on results`,
|
|
400
|
+
},
|
|
401
|
+
],
|
|
402
|
+
});
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
## TypeScript Support
|
|
406
|
+
|
|
407
|
+
```typescript
|
|
408
|
+
import type {
|
|
409
|
+
LangGraphATPClient,
|
|
410
|
+
LangGraphATPClientOptions,
|
|
411
|
+
ApprovalRequest,
|
|
412
|
+
ApprovalResponse,
|
|
413
|
+
CreateATPToolsOptions,
|
|
414
|
+
ATPToolsResult,
|
|
415
|
+
} from '@mondaydotcomorg/atp-langchain';
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
## Requirements
|
|
419
|
+
|
|
420
|
+
- Node.js 18+
|
|
421
|
+
- TypeScript 5.0+
|
|
422
|
+
- `@langchain/core` ^0.3.0
|
|
423
|
+
- `@langchain/langgraph` ^0.2.0
|
|
424
|
+
|
|
425
|
+
## License
|
|
426
|
+
|
|
427
|
+
MIT
|
|
428
|
+
|
|
429
|
+
## Learn More
|
|
430
|
+
|
|
431
|
+
- [ATP Documentation](../../README.md)
|
|
432
|
+
- [LangGraph Human-in-the-Loop](https://langchain-ai.github.io/langgraphjs/how-tos/human-in-the-loop/)
|
|
433
|
+
- [LangChain Tools](https://js.langchain.com/docs/modules/agents/tools/)
|
|
434
|
+
- [Examples](../../examples/langchain-react-agent/)
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export { createATPTools as createATPToolsBasic, convertToLangChainTools } from './tools.js';
|
|
2
|
+
export * from './langgraph-client.js';
|
|
3
|
+
export { createATPTools, createSimpleATPTool, type CreateATPToolsOptions, type ATPToolsResult, } from './langgraph-tools.js';
|
|
4
|
+
export * from './node.js';
|
|
5
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,IAAI,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE5F,cAAc,uBAAuB,CAAC;AACtC,OAAO,EACN,cAAc,EACd,mBAAmB,EACnB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,GACnB,MAAM,sBAAsB,CAAC;AAE9B,cAAc,WAAW,CAAC"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export { createATPTools as createATPToolsBasic, convertToLangChainTools } from './tools.js';
|
|
2
|
+
export * from './langgraph-client.js';
|
|
3
|
+
export { createATPTools, createSimpleATPTool, } from './langgraph-tools.js';
|
|
4
|
+
export * from './node.js';
|
|
5
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,IAAI,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE5F,cAAc,uBAAuB,CAAC;AACtC,OAAO,EACN,cAAc,EACd,mBAAmB,GAGnB,MAAM,sBAAsB,CAAC;AAE9B,cAAc,WAAW,CAAC"}
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* LangGraph-aware ATP Client
|
|
3
|
+
*
|
|
4
|
+
* This client integrates ATP execution with LangGraph's interrupt-based
|
|
5
|
+
* human-in-the-loop (HITL) system. When ATP code calls atp.approval.request(),
|
|
6
|
+
* it triggers a LangGraph interrupt for production-ready async approval flows.
|
|
7
|
+
*
|
|
8
|
+
* Features:
|
|
9
|
+
* - LangGraph interrupt integration for approvals
|
|
10
|
+
* - LLM sampling via LangChain models
|
|
11
|
+
* - Checkpoint-aware state management
|
|
12
|
+
* - Production-ready async approval workflows
|
|
13
|
+
*/
|
|
14
|
+
import { AgentToolProtocolClient, ClientCallbackError } from '@mondaydotcomorg/atp-client';
|
|
15
|
+
import type { ClientHooks } from '@mondaydotcomorg/atp-client';
|
|
16
|
+
import type { ExecutionResult, ExecutionConfig, ClientTool } from '@mondaydotcomorg/atp-protocol';
|
|
17
|
+
import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
|
|
18
|
+
import type { Embeddings } from '@langchain/core/embeddings';
|
|
19
|
+
/**
|
|
20
|
+
* Approval request that needs human decision
|
|
21
|
+
*/
|
|
22
|
+
export interface ApprovalRequest {
|
|
23
|
+
message: string;
|
|
24
|
+
context?: Record<string, unknown>;
|
|
25
|
+
executionId: string;
|
|
26
|
+
timestamp: number;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Approval response from human
|
|
30
|
+
*/
|
|
31
|
+
export interface ApprovalResponse {
|
|
32
|
+
approved: boolean;
|
|
33
|
+
reason?: string;
|
|
34
|
+
timestamp: number;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Options for creating the LangGraph ATP client
|
|
38
|
+
*/
|
|
39
|
+
export interface LangGraphATPClientOptions {
|
|
40
|
+
/** Base URL of ATP server */
|
|
41
|
+
serverUrl: string;
|
|
42
|
+
/** Custom headers for authentication (e.g., { Authorization: 'Bearer token' }) */
|
|
43
|
+
headers?: Record<string, string>;
|
|
44
|
+
/** LangChain LLM for atp.llm.call() sampling */
|
|
45
|
+
llm: BaseChatModel;
|
|
46
|
+
/**
|
|
47
|
+
* LangChain embeddings model for atp.embedding.embed() and atp.embedding.search()
|
|
48
|
+
* Optional - if not provided, embedding calls will fail
|
|
49
|
+
*/
|
|
50
|
+
embeddings?: Embeddings;
|
|
51
|
+
/**
|
|
52
|
+
* Client-provided tools that execute locally (e.g., file operations, browser automation)
|
|
53
|
+
* These tools are registered with the server and can be called from server code execution
|
|
54
|
+
*/
|
|
55
|
+
tools?: ClientTool[];
|
|
56
|
+
/**
|
|
57
|
+
* Whether to use LangGraph interrupts for approvals (production mode).
|
|
58
|
+
* If false, will use a direct callback handler.
|
|
59
|
+
* Default: true
|
|
60
|
+
*/
|
|
61
|
+
useLangGraphInterrupts?: boolean;
|
|
62
|
+
/**
|
|
63
|
+
* Direct approval handler (only used if useLangGraphInterrupts = false)
|
|
64
|
+
*/
|
|
65
|
+
approvalHandler?: (message: string, context?: Record<string, unknown>) => Promise<boolean>;
|
|
66
|
+
/**
|
|
67
|
+
* Hooks for intercepting and modifying client behavior
|
|
68
|
+
*/
|
|
69
|
+
hooks?: ClientHooks;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Result of ATP execution that may need approval
|
|
73
|
+
*/
|
|
74
|
+
export interface ATPExecutionResult {
|
|
75
|
+
/** Standard execution result */
|
|
76
|
+
result: ExecutionResult;
|
|
77
|
+
/** If true, execution is waiting for approval via LangGraph interrupt */
|
|
78
|
+
needsApproval: boolean;
|
|
79
|
+
/** Approval request details (if needsApproval = true) */
|
|
80
|
+
approvalRequest?: ApprovalRequest;
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* Exception thrown when approval is needed - this triggers LangGraph interrupt
|
|
84
|
+
*/
|
|
85
|
+
export declare class ApprovalRequiredException extends ClientCallbackError {
|
|
86
|
+
readonly approvalRequest: ApprovalRequest;
|
|
87
|
+
constructor(approvalRequest: ApprovalRequest);
|
|
88
|
+
}
|
|
89
|
+
/**
|
|
90
|
+
* LangGraph-aware ATP Client
|
|
91
|
+
*
|
|
92
|
+
* Integrates ATP with LangGraph's production-ready interrupt system:
|
|
93
|
+
* - atp.llm.call() → Routes to LangChain LLM (no interrupt)
|
|
94
|
+
* - atp.approval.request() → Throws ApprovalRequiredException (triggers LangGraph interrupt)
|
|
95
|
+
* - Supports checkpoint-based state persistence
|
|
96
|
+
* - Enables async approval workflows
|
|
97
|
+
*/
|
|
98
|
+
export declare class LangGraphATPClient {
|
|
99
|
+
private client;
|
|
100
|
+
private llm;
|
|
101
|
+
private embeddings?;
|
|
102
|
+
private useLangGraphInterrupts;
|
|
103
|
+
private directApprovalHandler?;
|
|
104
|
+
private pendingApprovals;
|
|
105
|
+
constructor(options: LangGraphATPClientOptions);
|
|
106
|
+
/**
|
|
107
|
+
* Initialize the client connection
|
|
108
|
+
*/
|
|
109
|
+
connect(): Promise<void>;
|
|
110
|
+
/**
|
|
111
|
+
* Get TypeScript API definitions
|
|
112
|
+
*/
|
|
113
|
+
getTypeDefinitions(): string;
|
|
114
|
+
/**
|
|
115
|
+
* Execute ATP code with LangGraph interrupt support
|
|
116
|
+
*
|
|
117
|
+
* When approval is needed:
|
|
118
|
+
* - If useLangGraphInterrupts=true: Throws ApprovalRequiredException
|
|
119
|
+
* - If useLangGraphInterrupts=false: Uses direct approval handler
|
|
120
|
+
*
|
|
121
|
+
* @throws ApprovalRequiredException when approval is needed (interrupt mode)
|
|
122
|
+
*/
|
|
123
|
+
execute(code: string, config?: Partial<ExecutionConfig>): Promise<ATPExecutionResult>;
|
|
124
|
+
/**
|
|
125
|
+
* Resume execution after approval decision
|
|
126
|
+
*
|
|
127
|
+
* Call this after LangGraph resumes from interrupt with approval decision.
|
|
128
|
+
*/
|
|
129
|
+
resumeWithApproval(executionId: string, approved: boolean, reason?: string): Promise<ExecutionResult>;
|
|
130
|
+
/**
|
|
131
|
+
* Get pending approval request for an execution
|
|
132
|
+
*/
|
|
133
|
+
getPendingApproval(executionId: string): ApprovalRequest | undefined;
|
|
134
|
+
/**
|
|
135
|
+
* Handle LLM call - route to LangChain LLM
|
|
136
|
+
*/
|
|
137
|
+
private handleLLMCall;
|
|
138
|
+
/**
|
|
139
|
+
* Handle LLM extract - route to LangChain LLM with structured output
|
|
140
|
+
*/
|
|
141
|
+
private handleLLMExtract;
|
|
142
|
+
/**
|
|
143
|
+
* Handle LLM classify - route to LangChain LLM
|
|
144
|
+
*/
|
|
145
|
+
private handleLLMClassify;
|
|
146
|
+
/**
|
|
147
|
+
* Handle embedding - route to LangChain embeddings model
|
|
148
|
+
*/
|
|
149
|
+
private handleEmbedding;
|
|
150
|
+
/**
|
|
151
|
+
* Get the underlying ATP client for advanced usage
|
|
152
|
+
*/
|
|
153
|
+
getUnderlyingClient(): AgentToolProtocolClient;
|
|
154
|
+
private handleApprovalRequest;
|
|
155
|
+
}
|
|
156
|
+
//# sourceMappingURL=langgraph-client.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"langgraph-client.d.ts","sourceRoot":"","sources":["../src/langgraph-client.ts"],"names":[],"mappings":"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"}
|