@loopstack/accessing-tool-results-example-workflow 0.22.1 → 0.23.1

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 CHANGED
@@ -1,37 +1,70 @@
1
+ ---
2
+ title: Accessing Tool Results Example
3
+ description: Example workflow showing how to store and access data across workflow transitions using typed workflow state
4
+ ---
5
+
1
6
  # @loopstack/accessing-tool-results-example-workflow
2
7
 
3
8
  > A module for the [Loopstack AI](https://loopstack.ai) automation framework.
4
9
 
5
- This module provides an example workflow demonstrating how to store and access data across workflow transitions using instance properties.
10
+ This module provides an example workflow demonstrating how to store and access data across workflow transitions using typed workflow state.
6
11
 
7
12
  ## Overview
8
13
 
9
- The Workflow State Example shows how to persist data between transitions using class instance properties. Understanding these patterns is essential for building workflows that pass data between operations.
14
+ The workflow shows how to persist data between transitions by returning updated state from transition methods. Understanding this pattern is essential for building workflows that pass data between steps. For example, storing tool results in one transition and reading them in the next.
10
15
 
11
16
  By using this workflow as a reference, you'll learn how to:
12
17
 
13
- - Store data as workflow instance properties for use across transitions
14
- - Access stored data in later transitions via instance properties
15
- - Create private helper methods to encapsulate data access logic
18
+ - Define a typed state interface for your workflow
19
+ - Store data in the initial transition and return updated state
20
+ - Access stored data in later transitions via the `state` parameter
21
+ - Save chat messages with `MessageDocument` and `DocumentStore`
16
22
 
17
23
  This example is useful for developers learning to build data-driven workflows that need to pass information between steps.
18
24
 
19
25
  ## Installation
20
26
 
21
- See [SETUP.md](./SETUP.md) for installation and setup instructions.
27
+ ```bash
28
+ npm install @loopstack/accessing-tool-results-example-workflow
29
+ ```
30
+
31
+ Then register the module in your app:
32
+
33
+ ```typescript
34
+ import {
35
+ ToolResultsExampleModule,
36
+ WorkflowToolResultsWorkflow,
37
+ } from '@loopstack/accessing-tool-results-example-workflow';
38
+ import { StudioApp } from '@loopstack/common';
39
+
40
+ @StudioApp({
41
+ title: 'Tool Results Example',
42
+ workflows: [WorkflowToolResultsWorkflow],
43
+ })
44
+ @Module({
45
+ imports: [ToolResultsExampleModule],
46
+ })
47
+ export class MyAppModule {}
48
+ ```
22
49
 
23
50
  ## How It Works
24
51
 
25
- ### Workflow Class
52
+ ### Workflow State
26
53
 
27
- The workflow extends `BaseWorkflow` and stores data as instance properties that persist across transitions:
54
+ State is defined as a TypeScript interface and passed to each transition method. Return the updated state from a transition to persist it for subsequent steps:
28
55
 
29
56
  ```typescript
57
+ interface ToolResultsState {
58
+ storedMessage?: string;
59
+ }
60
+
30
61
  @Workflow({
31
62
  uiConfig: __dirname + '/workflow-tool-results.ui.yaml',
32
63
  })
33
- export class WorkflowToolResultsWorkflow extends BaseWorkflow {
34
- storedMessage?: string;
64
+ export class WorkflowToolResultsWorkflow extends BaseWorkflow<Record<string, unknown>, ToolResultsState> {
65
+ constructor(@Inject(DOCUMENT_STORE) private readonly documentStore: DocumentStore) {
66
+ super();
67
+ }
35
68
  }
36
69
  ```
37
70
 
@@ -39,90 +72,79 @@ export class WorkflowToolResultsWorkflow extends BaseWorkflow {
39
72
 
40
73
  #### 1. Storing Data in State
41
74
 
42
- In a transition method, assign values to instance properties:
75
+ In the initial transition, save a message document and return updated state:
43
76
 
44
77
  ```typescript
45
- @Initial({ to: 'data_created' })
46
- async createSomeData() {
47
- this.storedMessage = 'Hello World.';
48
-
49
- await this.repository.save(MessageDocument, {
78
+ @Transition({ to: 'data_created' })
79
+ async createSomeData(
80
+ ctx: WorkflowContext,
81
+ args: Record<string, unknown>,
82
+ state: ToolResultsState,
83
+ ): Promise<ToolResultsState> {
84
+ await this.documentStore.save(MessageDocument, {
50
85
  role: 'assistant',
51
- content: `Stored in initial transition: ${this.storedMessage}`,
86
+ content: `Stored in initial transition: Hello World.`,
52
87
  });
88
+ return { ...state, storedMessage: 'Hello World.' };
53
89
  }
54
90
  ```
55
91
 
56
- The value is stored in `this.storedMessage` for later use.
92
+ The returned state is persisted automatically and available in later transitions.
57
93
 
58
94
  #### 2. Accessing Data Across Transitions
59
95
 
60
- Instance properties persist across transitions. In a subsequent `@Final` method, the stored data is still available:
96
+ In a subsequent transition, read values from the `state` parameter:
61
97
 
62
98
  ```typescript
63
- @Final({ from: 'data_created' })
64
- async accessData() {
65
- await this.repository.save(MessageDocument, {
99
+ @Transition({ from: 'data_created', to: 'end' })
100
+ async accessData(ctx: WorkflowContext, state: ToolResultsState): Promise<unknown> {
101
+ await this.documentStore.save(MessageDocument, {
66
102
  role: 'assistant',
67
- content: `Accessed from previous transition: ${this.storedMessage}`,
68
- });
69
-
70
- await this.repository.save(MessageDocument, {
71
- role: 'assistant',
72
- content: `Accessed via helper method: ${this.theMessage()}`,
103
+ content: `Accessed from previous transition: ${state.storedMessage}`,
73
104
  });
105
+ return {};
74
106
  }
75
107
  ```
76
108
 
77
- #### 3. Private Helper Methods
78
-
79
- Define private methods on the workflow class to encapsulate data access logic:
80
-
81
- ```typescript
82
- private theMessage(): string {
83
- return this.storedMessage!;
84
- }
85
- ```
86
-
87
- These are standard TypeScript methods -- no decorator needed. Call them from any transition method using `this.theMessage()`.
88
-
89
109
  ### Complete Workflow
90
110
 
91
111
  ```typescript
92
- import { BaseWorkflow, Final, Initial, Workflow } from '@loopstack/common';
93
- import { MessageDocument } from '@loopstack/common';
112
+ import { Inject } from '@nestjs/common';
113
+ import { BaseWorkflow, DOCUMENT_STORE, Final, Initial, MessageDocument, Workflow } from '@loopstack/common';
114
+ import type { DocumentStore, WorkflowContext } from '@loopstack/common';
115
+
116
+ interface ToolResultsState {
117
+ storedMessage?: string;
118
+ }
94
119
 
95
120
  @Workflow({
96
121
  uiConfig: __dirname + '/workflow-tool-results.ui.yaml',
97
122
  })
98
- export class WorkflowToolResultsWorkflow extends BaseWorkflow {
99
- storedMessage?: string;
100
-
101
- @Initial({ to: 'data_created' })
102
- async createSomeData() {
103
- this.storedMessage = 'Hello World.';
104
-
105
- await this.repository.save(MessageDocument, {
106
- role: 'assistant',
107
- content: `Stored in initial transition: ${this.storedMessage}`,
108
- });
123
+ export class WorkflowToolResultsWorkflow extends BaseWorkflow<Record<string, unknown>, ToolResultsState> {
124
+ constructor(@Inject(DOCUMENT_STORE) private readonly documentStore: DocumentStore) {
125
+ super();
109
126
  }
110
127
 
111
- @Final({ from: 'data_created' })
112
- async accessData() {
113
- await this.repository.save(MessageDocument, {
128
+ @Transition({ to: 'data_created' })
129
+ async createSomeData(
130
+ ctx: WorkflowContext,
131
+ args: Record<string, unknown>,
132
+ state: ToolResultsState,
133
+ ): Promise<ToolResultsState> {
134
+ await this.documentStore.save(MessageDocument, {
114
135
  role: 'assistant',
115
- content: `Accessed from previous transition: ${this.storedMessage}`,
136
+ content: `Stored in initial transition: Hello World.`,
116
137
  });
138
+ return { ...state, storedMessage: 'Hello World.' };
139
+ }
117
140
 
118
- await this.repository.save(MessageDocument, {
141
+ @Transition({ from: 'data_created', to: 'end' })
142
+ async accessData(ctx: WorkflowContext, state: ToolResultsState): Promise<unknown> {
143
+ await this.documentStore.save(MessageDocument, {
119
144
  role: 'assistant',
120
- content: `Accessed via helper method: ${this.theMessage()}`,
145
+ content: `Accessed from previous transition: ${state.storedMessage}`,
121
146
  });
122
- }
123
-
124
- private theMessage(): string {
125
- return this.storedMessage!;
147
+ return {};
126
148
  }
127
149
  }
128
150
  ```
@@ -131,8 +153,7 @@ export class WorkflowToolResultsWorkflow extends BaseWorkflow {
131
153
 
132
154
  This workflow uses the following Loopstack modules:
133
155
 
134
- - `@loopstack/common` - Base classes, decorators, and tool injection
135
- - `@loopstack/common` - Provides `MessageDocument` for chat messages
156
+ - `@loopstack/common` Base classes, decorators, `DocumentStore`, and `MessageDocument`
136
157
 
137
158
  ## About
138
159
 
@@ -1,8 +1,10 @@
1
1
  import { BaseWorkflow } from '@loopstack/common';
2
- export declare class WorkflowToolResultsWorkflow extends BaseWorkflow {
2
+ interface ToolResultsState {
3
3
  storedMessage?: string;
4
- createSomeData(): Promise<void>;
5
- accessData(): Promise<void>;
6
- private theMessage;
7
4
  }
5
+ export declare class WorkflowToolResultsWorkflow extends BaseWorkflow<Record<string, unknown>, ToolResultsState> {
6
+ createSomeData(state: ToolResultsState): Promise<ToolResultsState>;
7
+ accessData(state: ToolResultsState): Promise<unknown>;
8
+ }
9
+ export {};
8
10
  //# sourceMappingURL=workflow-tool-results.workflow.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"workflow-tool-results.workflow.d.ts","sourceRoot":"","sources":["../src/workflow-tool-results.workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAA6C,MAAM,mBAAmB,CAAC;AAE5F,qBAGa,2BAA4B,SAAQ,YAAY;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;IAGjB,cAAc;IAUd,UAAU;IAYhB,OAAO,CAAC,UAAU;CAGnB"}
1
+ {"version":3,"file":"workflow-tool-results.workflow.d.ts","sourceRoot":"","sources":["../src/workflow-tool-results.workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAyC,MAAM,mBAAmB,CAAC;AAExF,UAAU,gBAAgB;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAGa,2BAA4B,SAAQ,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAEhG,cAAc,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IASlE,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;CAO5D"}
@@ -12,44 +12,37 @@ Object.defineProperty(exports, "__esModule", { value: true });
12
12
  exports.WorkflowToolResultsWorkflow = void 0;
13
13
  const common_1 = require("@loopstack/common");
14
14
  let WorkflowToolResultsWorkflow = class WorkflowToolResultsWorkflow extends common_1.BaseWorkflow {
15
- storedMessage;
16
- async createSomeData() {
17
- this.storedMessage = 'Hello World.';
18
- await this.repository.save(common_1.MessageDocument, {
15
+ async createSomeData(state) {
16
+ await this.documentStore.save(common_1.MessageDocument, {
19
17
  role: 'assistant',
20
- content: `Stored in initial transition: ${this.storedMessage}`,
18
+ content: `Stored in initial transition: Hello World.`,
21
19
  });
20
+ return { ...state, storedMessage: 'Hello World.' };
22
21
  }
23
- async accessData() {
24
- await this.repository.save(common_1.MessageDocument, {
22
+ async accessData(state) {
23
+ await this.documentStore.save(common_1.MessageDocument, {
25
24
  role: 'assistant',
26
- content: `Accessed from previous transition: ${this.storedMessage}`,
25
+ content: `Accessed from previous transition: ${state.storedMessage}`,
27
26
  });
28
- await this.repository.save(common_1.MessageDocument, {
29
- role: 'assistant',
30
- content: `Accessed via helper method: ${this.theMessage()}`,
31
- });
32
- }
33
- theMessage() {
34
- return this.storedMessage;
27
+ return {};
35
28
  }
36
29
  };
37
30
  exports.WorkflowToolResultsWorkflow = WorkflowToolResultsWorkflow;
38
31
  __decorate([
39
- (0, common_1.Initial)({ to: 'data_created' }),
32
+ (0, common_1.Transition)({ to: 'data_created' }),
40
33
  __metadata("design:type", Function),
41
- __metadata("design:paramtypes", []),
34
+ __metadata("design:paramtypes", [Object]),
42
35
  __metadata("design:returntype", Promise)
43
36
  ], WorkflowToolResultsWorkflow.prototype, "createSomeData", null);
44
37
  __decorate([
45
- (0, common_1.Final)({ from: 'data_created' }),
38
+ (0, common_1.Transition)({ from: 'data_created', to: 'end' }),
46
39
  __metadata("design:type", Function),
47
- __metadata("design:paramtypes", []),
40
+ __metadata("design:paramtypes", [Object]),
48
41
  __metadata("design:returntype", Promise)
49
42
  ], WorkflowToolResultsWorkflow.prototype, "accessData", null);
50
43
  exports.WorkflowToolResultsWorkflow = WorkflowToolResultsWorkflow = __decorate([
51
44
  (0, common_1.Workflow)({
52
- uiConfig: __dirname + '/workflow-tool-results.ui.yaml',
45
+ title: 'Workflow Tool Result',
53
46
  })
54
47
  ], WorkflowToolResultsWorkflow);
55
48
  //# sourceMappingURL=workflow-tool-results.workflow.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"workflow-tool-results.workflow.js","sourceRoot":"","sources":["../src/workflow-tool-results.workflow.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,8CAA4F;AAKrF,IAAM,2BAA2B,GAAjC,MAAM,2BAA4B,SAAQ,qBAAY;IAC3D,aAAa,CAAU;IAGjB,AAAN,KAAK,CAAC,cAAc;QAClB,IAAI,CAAC,aAAa,GAAG,cAAc,CAAC;QAEpC,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC1C,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,iCAAiC,IAAI,CAAC,aAAa,EAAE;SAC/D,CAAC,CAAC;IACL,CAAC;IAGK,AAAN,KAAK,CAAC,UAAU;QACd,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC1C,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,sCAAsC,IAAI,CAAC,aAAa,EAAE;SACpE,CAAC,CAAC;QAEH,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC1C,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,+BAA+B,IAAI,CAAC,UAAU,EAAE,EAAE;SAC5D,CAAC,CAAC;IACL,CAAC;IAEO,UAAU;QAChB,OAAO,IAAI,CAAC,aAAc,CAAC;IAC7B,CAAC;CACF,CAAA;AA7BY,kEAA2B;AAIhC;IADL,IAAA,gBAAO,EAAC,EAAE,EAAE,EAAE,cAAc,EAAE,CAAC;;;;iEAQ/B;AAGK;IADL,IAAA,cAAK,EAAC,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;;;;6DAW/B;sCAxBU,2BAA2B;IAHvC,IAAA,iBAAQ,EAAC;QACR,QAAQ,EAAE,SAAS,GAAG,gCAAgC;KACvD,CAAC;GACW,2BAA2B,CA6BvC"}
1
+ {"version":3,"file":"workflow-tool-results.workflow.js","sourceRoot":"","sources":["../src/workflow-tool-results.workflow.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,8CAAwF;AASjF,IAAM,2BAA2B,GAAjC,MAAM,2BAA4B,SAAQ,qBAAuD;IAEhG,AAAN,KAAK,CAAC,cAAc,CAAC,KAAuB;QAC1C,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC7C,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,4CAA4C;SACtD,CAAC,CAAC;QACH,OAAO,EAAE,GAAG,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC;IACrD,CAAC;IAGK,AAAN,KAAK,CAAC,UAAU,CAAC,KAAuB;QACtC,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC7C,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,sCAAsC,KAAK,CAAC,aAAa,EAAE;SACrE,CAAC,CAAC;QACH,OAAO,EAAE,CAAC;IACZ,CAAC;CACF,CAAA;AAlBY,kEAA2B;AAEhC;IADL,IAAA,mBAAU,EAAC,EAAE,EAAE,EAAE,cAAc,EAAE,CAAC;;;;iEAOlC;AAGK;IADL,IAAA,mBAAU,EAAC,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;;;;6DAO/C;sCAjBU,2BAA2B;IAHvC,IAAA,iBAAQ,EAAC;QACR,KAAK,EAAE,sBAAsB;KAC9B,CAAC;GACW,2BAA2B,CAkBvC"}
package/package.json CHANGED
@@ -10,7 +10,7 @@
10
10
  "tool",
11
11
  "workflow"
12
12
  ],
13
- "version": "0.22.1",
13
+ "version": "0.23.1",
14
14
  "license": "MIT",
15
15
  "author": {
16
16
  "name": "Jakob Klippel",
@@ -31,8 +31,7 @@
31
31
  "watch": "nest build --watch"
32
32
  },
33
33
  "dependencies": {
34
- "@loopstack/common": "^0.31.0",
35
- "@loopstack/core": "^0.31.0",
34
+ "@loopstack/common": "^0.33.0",
36
35
  "@nestjs/common": "^11.1.19",
37
36
  "zod": "^4.3.6"
38
37
  },
@@ -34,7 +34,7 @@ describe('WorkflowToolResultsWorkflow', () => {
34
34
  expect(result.documents).toEqual(
35
35
  expect.arrayContaining([
36
36
  expect.objectContaining({
37
- className: 'MessageDocument',
37
+ documentName: 'message',
38
38
  content: expect.objectContaining({
39
39
  role: 'assistant',
40
40
  content: 'Stored in initial transition: Hello World.',
@@ -53,7 +53,7 @@ describe('WorkflowToolResultsWorkflow', () => {
53
53
  expect(result.documents).toEqual(
54
54
  expect.arrayContaining([
55
55
  expect.objectContaining({
56
- className: 'MessageDocument',
56
+ documentName: 'message',
57
57
  content: expect.objectContaining({
58
58
  role: 'assistant',
59
59
  content: 'Accessed from previous transition: Hello World.',
@@ -62,24 +62,5 @@ describe('WorkflowToolResultsWorkflow', () => {
62
62
  ]),
63
63
  );
64
64
  });
65
-
66
- it('should access stored data via a helper method', async () => {
67
- const context = createStatelessContext();
68
-
69
- const result = await processor.process(workflow, {}, context);
70
-
71
- expect(result.hasError).toBe(false);
72
- expect(result.documents).toEqual(
73
- expect.arrayContaining([
74
- expect.objectContaining({
75
- className: 'MessageDocument',
76
- content: expect.objectContaining({
77
- role: 'assistant',
78
- content: 'Accessed via helper method: Hello World.',
79
- }),
80
- }),
81
- ]),
82
- );
83
- });
84
65
  });
85
66
  });
@@ -1,35 +1,28 @@
1
- import { BaseWorkflow, Final, Initial, MessageDocument, Workflow } from '@loopstack/common';
1
+ import { BaseWorkflow, MessageDocument, Transition, Workflow } from '@loopstack/common';
2
2
 
3
- @Workflow({
4
- uiConfig: __dirname + '/workflow-tool-results.ui.yaml',
5
- })
6
- export class WorkflowToolResultsWorkflow extends BaseWorkflow {
3
+ interface ToolResultsState {
7
4
  storedMessage?: string;
5
+ }
8
6
 
9
- @Initial({ to: 'data_created' })
10
- async createSomeData() {
11
- this.storedMessage = 'Hello World.';
12
-
13
- await this.repository.save(MessageDocument, {
7
+ @Workflow({
8
+ title: 'Workflow Tool Result',
9
+ })
10
+ export class WorkflowToolResultsWorkflow extends BaseWorkflow<Record<string, unknown>, ToolResultsState> {
11
+ @Transition({ to: 'data_created' })
12
+ async createSomeData(state: ToolResultsState): Promise<ToolResultsState> {
13
+ await this.documentStore.save(MessageDocument, {
14
14
  role: 'assistant',
15
- content: `Stored in initial transition: ${this.storedMessage}`,
15
+ content: `Stored in initial transition: Hello World.`,
16
16
  });
17
+ return { ...state, storedMessage: 'Hello World.' };
17
18
  }
18
19
 
19
- @Final({ from: 'data_created' })
20
- async accessData() {
21
- await this.repository.save(MessageDocument, {
20
+ @Transition({ from: 'data_created', to: 'end' })
21
+ async accessData(state: ToolResultsState): Promise<unknown> {
22
+ await this.documentStore.save(MessageDocument, {
22
23
  role: 'assistant',
23
- content: `Accessed from previous transition: ${this.storedMessage}`,
24
+ content: `Accessed from previous transition: ${state.storedMessage}`,
24
25
  });
25
-
26
- await this.repository.save(MessageDocument, {
27
- role: 'assistant',
28
- content: `Accessed via helper method: ${this.theMessage()}`,
29
- });
30
- }
31
-
32
- private theMessage(): string {
33
- return this.storedMessage!;
26
+ return {};
34
27
  }
35
28
  }
@@ -1 +0,0 @@
1
- title: 'Workflow Tool Result'
@@ -1 +0,0 @@
1
- title: 'Workflow Tool Result'