@loopstack/accessing-tool-results-example-workflow 0.22.0 → 0.23.0

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.
Files changed (10) hide show
  1. package/README.md +59 -64
  2. package/dist/workflow-tool-results.workflow.d.ts +6 -4
  3. package/dist/workflow-tool-results.workflow.d.ts.map +1 -1
  4. package/dist/workflow-tool-results.workflow.js +13 -20
  5. package/dist/workflow-tool-results.workflow.js.map +1 -1
  6. package/package.json +2 -3
  7. package/src/__tests__/workflow-tool-results.workflow.spec.ts +2 -21
  8. package/src/workflow-tool-results.workflow.ts +17 -24
  9. package/dist/workflow-tool-results.ui.yaml +0 -1
  10. package/src/workflow-tool-results.ui.yaml +0 -1
package/README.md CHANGED
@@ -2,17 +2,18 @@
2
2
 
3
3
  > A module for the [Loopstack AI](https://loopstack.ai) automation framework.
4
4
 
5
- This module provides an example workflow demonstrating how to store and access data across workflow transitions using instance properties.
5
+ This module provides an example workflow demonstrating how to store and access data across workflow transitions using typed workflow state.
6
6
 
7
7
  ## Overview
8
8
 
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.
9
+ 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
10
 
11
11
  By using this workflow as a reference, you'll learn how to:
12
12
 
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
13
+ - Define a typed state interface for your workflow
14
+ - Store data in the initial transition and return updated state
15
+ - Access stored data in later transitions via the `state` parameter
16
+ - Save chat messages with `MessageDocument` and `DocumentStore`
16
17
 
17
18
  This example is useful for developers learning to build data-driven workflows that need to pass information between steps.
18
19
 
@@ -22,16 +23,22 @@ See [SETUP.md](./SETUP.md) for installation and setup instructions.
22
23
 
23
24
  ## How It Works
24
25
 
25
- ### Workflow Class
26
+ ### Workflow State
26
27
 
27
- The workflow extends `BaseWorkflow` and stores data as instance properties that persist across transitions:
28
+ 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
29
 
29
30
  ```typescript
31
+ interface ToolResultsState {
32
+ storedMessage?: string;
33
+ }
34
+
30
35
  @Workflow({
31
36
  uiConfig: __dirname + '/workflow-tool-results.ui.yaml',
32
37
  })
33
- export class WorkflowToolResultsWorkflow extends BaseWorkflow {
34
- storedMessage?: string;
38
+ export class WorkflowToolResultsWorkflow extends BaseWorkflow<Record<string, unknown>, ToolResultsState> {
39
+ constructor(@Inject(DOCUMENT_STORE) private readonly documentStore: DocumentStore) {
40
+ super();
41
+ }
35
42
  }
36
43
  ```
37
44
 
@@ -39,90 +46,79 @@ export class WorkflowToolResultsWorkflow extends BaseWorkflow {
39
46
 
40
47
  #### 1. Storing Data in State
41
48
 
42
- In a transition method, assign values to instance properties:
49
+ In the initial transition, save a message document and return updated state:
43
50
 
44
51
  ```typescript
45
- @Initial({ to: 'data_created' })
46
- async createSomeData() {
47
- this.storedMessage = 'Hello World.';
48
-
49
- await this.repository.save(MessageDocument, {
52
+ @Transition({ to: 'data_created' })
53
+ async createSomeData(
54
+ ctx: WorkflowContext,
55
+ args: Record<string, unknown>,
56
+ state: ToolResultsState,
57
+ ): Promise<ToolResultsState> {
58
+ await this.documentStore.save(MessageDocument, {
50
59
  role: 'assistant',
51
- content: `Stored in initial transition: ${this.storedMessage}`,
60
+ content: `Stored in initial transition: Hello World.`,
52
61
  });
62
+ return { ...state, storedMessage: 'Hello World.' };
53
63
  }
54
64
  ```
55
65
 
56
- The value is stored in `this.storedMessage` for later use.
66
+ The returned state is persisted automatically and available in later transitions.
57
67
 
58
68
  #### 2. Accessing Data Across Transitions
59
69
 
60
- Instance properties persist across transitions. In a subsequent `@Final` method, the stored data is still available:
70
+ In a subsequent transition, read values from the `state` parameter:
61
71
 
62
72
  ```typescript
63
- @Final({ from: 'data_created' })
64
- async accessData() {
65
- await this.repository.save(MessageDocument, {
66
- role: 'assistant',
67
- content: `Accessed from previous transition: ${this.storedMessage}`,
68
- });
69
-
70
- await this.repository.save(MessageDocument, {
73
+ @Transition({ from: 'data_created', to: 'end' })
74
+ async accessData(ctx: WorkflowContext, state: ToolResultsState): Promise<unknown> {
75
+ await this.documentStore.save(MessageDocument, {
71
76
  role: 'assistant',
72
- content: `Accessed via helper method: ${this.theMessage()}`,
77
+ content: `Accessed from previous transition: ${state.storedMessage}`,
73
78
  });
79
+ return {};
74
80
  }
75
81
  ```
76
82
 
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
83
  ### Complete Workflow
90
84
 
91
85
  ```typescript
92
- import { BaseWorkflow, Final, Initial, Workflow } from '@loopstack/common';
93
- import { MessageDocument } from '@loopstack/common';
86
+ import { Inject } from '@nestjs/common';
87
+ import { BaseWorkflow, DOCUMENT_STORE, Final, Initial, MessageDocument, Workflow } from '@loopstack/common';
88
+ import type { DocumentStore, WorkflowContext } from '@loopstack/common';
89
+
90
+ interface ToolResultsState {
91
+ storedMessage?: string;
92
+ }
94
93
 
95
94
  @Workflow({
96
95
  uiConfig: __dirname + '/workflow-tool-results.ui.yaml',
97
96
  })
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
- });
97
+ export class WorkflowToolResultsWorkflow extends BaseWorkflow<Record<string, unknown>, ToolResultsState> {
98
+ constructor(@Inject(DOCUMENT_STORE) private readonly documentStore: DocumentStore) {
99
+ super();
109
100
  }
110
101
 
111
- @Final({ from: 'data_created' })
112
- async accessData() {
113
- await this.repository.save(MessageDocument, {
102
+ @Transition({ to: 'data_created' })
103
+ async createSomeData(
104
+ ctx: WorkflowContext,
105
+ args: Record<string, unknown>,
106
+ state: ToolResultsState,
107
+ ): Promise<ToolResultsState> {
108
+ await this.documentStore.save(MessageDocument, {
114
109
  role: 'assistant',
115
- content: `Accessed from previous transition: ${this.storedMessage}`,
110
+ content: `Stored in initial transition: Hello World.`,
116
111
  });
112
+ return { ...state, storedMessage: 'Hello World.' };
113
+ }
117
114
 
118
- await this.repository.save(MessageDocument, {
115
+ @Transition({ from: 'data_created', to: 'end' })
116
+ async accessData(ctx: WorkflowContext, state: ToolResultsState): Promise<unknown> {
117
+ await this.documentStore.save(MessageDocument, {
119
118
  role: 'assistant',
120
- content: `Accessed via helper method: ${this.theMessage()}`,
119
+ content: `Accessed from previous transition: ${state.storedMessage}`,
121
120
  });
122
- }
123
-
124
- private theMessage(): string {
125
- return this.storedMessage!;
121
+ return {};
126
122
  }
127
123
  }
128
124
  ```
@@ -131,8 +127,7 @@ export class WorkflowToolResultsWorkflow extends BaseWorkflow {
131
127
 
132
128
  This workflow uses the following Loopstack modules:
133
129
 
134
- - `@loopstack/common` - Base classes, decorators, and tool injection
135
- - `@loopstack/common` - Provides `MessageDocument` for chat messages
130
+ - `@loopstack/common` — Base classes, decorators, `DocumentStore`, and `MessageDocument`
136
131
 
137
132
  ## About
138
133
 
package/dist/workflow-tool-results.workflow.d.ts CHANGED
@@ -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
package/dist/workflow-tool-results.workflow.d.ts.map CHANGED
@@ -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"}
package/dist/workflow-tool-results.workflow.js CHANGED
@@ -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
package/dist/workflow-tool-results.workflow.js.map CHANGED
@@ -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.0",
13
+ "version": "0.23.0",
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.30.0",
35
- "@loopstack/core": "^0.30.0",
34
+ "@loopstack/common": "^0.32.0",
36
35
  "@nestjs/common": "^11.1.19",
37
36
  "zod": "^4.3.6"
38
37
  },
package/src/__tests__/workflow-tool-results.workflow.spec.ts CHANGED
@@ -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
  });
package/src/workflow-tool-results.workflow.ts CHANGED
@@ -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
  }
package/dist/workflow-tool-results.ui.yaml DELETED
@@ -1 +0,0 @@
1
- title: 'Workflow Tool Result'
package/src/workflow-tool-results.ui.yaml DELETED
@@ -1 +0,0 @@
1
- title: 'Workflow Tool Result'