@n1k1t/pipelain 0.1.4 → 0.1.6
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
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
<h1>PipelAIn</h1>
|
|
3
3
|
<p>Type-safe AI-powered execution pipelines</p>
|
|
4
4
|
|
|
5
|
-
<img src="https://raw.githubusercontent.com/n1k1t/pipelain/refs/heads/master/images/preview.png?raw=true" />
|
|
5
|
+
<img width="640px" src="https://raw.githubusercontent.com/n1k1t/pipelain/refs/heads/master/images/preview.png?raw=true" />
|
|
6
6
|
|
|
7
7
|
<br />
|
|
8
8
|
<br />
|
|
@@ -17,6 +17,7 @@ Powerful utility to build and execute type-safe AI pipelines with structured out
|
|
|
17
17
|
- [Features](#features)
|
|
18
18
|
- [Installation](#installation)
|
|
19
19
|
- [First Steps](#first-steps)
|
|
20
|
+
- [Add Skills](#add-skills)
|
|
20
21
|
- [Simple Example](#simple-example)
|
|
21
22
|
- [Environment Variables](#environment-variables)
|
|
22
23
|
- [Pipeline Step Utilities](#pipeline-step-utilities)
|
|
@@ -65,6 +66,14 @@ To use the library, you need to provide an API key for the LLM provider. Create
|
|
|
65
66
|
PIPELAIN_API_KEY=your_api_key_here
|
|
66
67
|
```
|
|
67
68
|
|
|
69
|
+
## Add Skills
|
|
70
|
+
|
|
71
|
+
If you are using the [skills](https://www.npmjs.com/package/skills) package, you can add `n1k1t/pipelain` to your project using the following command:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
npx skills add n1k1t/pipelain
|
|
75
|
+
```
|
|
76
|
+
|
|
68
77
|
## Simple Example
|
|
69
78
|
|
|
70
79
|
A basic pipeline that translates text and returns a structured response:
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../../../src/models/pipeline/stdout/model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,
|
|
1
|
+
{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../../../src/models/pipeline/stdout/model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA6B,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,KAAK,oBAAoB,GAAG;KACzB,CAAC,IAAI,MAAM,eAAe,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;CAC3F,CAAC;AAKF,qBAAa,cAAc;IAgCb,OAAO,CAAC,MAAM;IA/B1B,OAAO,CAAC,KAAK,CA6BX;gBAEkB,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAE1D,mCAAmC;IAC5B,QAAQ,CAAC,CAAC,SAAS,MAAM,oBAAoB,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,IAAI;IAK/F,MAAM,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAQ7C,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,cAAc;CAGhE"}
|
|
@@ -1,16 +1,17 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.PipelineStdout = void 0;
|
|
4
|
+
const checkIsFinalEventState = (state) => state === 'DONE' || state === 'ERROR';
|
|
4
5
|
class PipelineStdout {
|
|
5
6
|
constructor(logger) {
|
|
6
7
|
this.logger = logger;
|
|
7
8
|
this.hooks = {
|
|
8
9
|
'warning': (event) => this.logger.info(event.message),
|
|
9
10
|
'log': (event) => this.logger.info(`${event.pipeline.trace().reverse().map((entity) => entity.title).join(' - ')}:`, ...event.message),
|
|
10
|
-
'run': (event) => event.meta.state
|
|
11
|
-
'step:run': (event) => event.meta.state
|
|
12
|
-
'step:llm:tool': (event) => event.meta.state
|
|
13
|
-
'step:llm:reasoning': (event) => event.meta.state
|
|
11
|
+
'run': (event) => checkIsFinalEventState(event.meta.state) && this.logger.info(`${event.pipeline.trace().reverse().map((entity) => entity.title).join(' - ')}: [${event.meta.state}]`, `in ${event.meta.spent}ms`),
|
|
12
|
+
'step:run': (event) => checkIsFinalEventState(event.meta.state) && this.logger.info(`${event.step.trace().reverse().map((entity) => entity.title).join(' - ')}: [${event.meta.state}]`, `in ${event.meta.spent}ms`),
|
|
13
|
+
'step:llm:tool': (event) => checkIsFinalEventState(event.meta.state) && this.logger.info(`${event.step.trace().reverse().map((entity) => entity.title).join(' - ')}:`, `Tool [${event.name}] [${event.meta.state}] in ${event.meta.spent}ms`, `\n${event.message}`),
|
|
14
|
+
'step:llm:reasoning': (event) => checkIsFinalEventState(event.meta.state) && this.logger.info(`${event.step.trace().reverse().map((entity) => entity.title).join(' - ')}:`, `Reasoning [${event.meta.state}] in ${event.meta.spent}ms`, `\n${event.message}`),
|
|
14
15
|
};
|
|
15
16
|
}
|
|
16
17
|
/** Overrides default event hook */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../../../src/models/pipeline/stdout/model.ts"],"names":[],"mappings":";;;AAOA,MAAa,cAAc;
|
|
1
|
+
{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../../../src/models/pipeline/stdout/model.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -0,0 +1,371 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pipelain-basic
|
|
3
|
+
description: Skill for package @n1k1t/pipelain to build and execute type-safe AI pipelines with structured outputs and tool integration
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# PipelAIn Basic Skill
|
|
7
|
+
|
|
8
|
+
Instructions for building and executing type-safe AI pipelines with structured outputs, context sharing, parallel execution, loops, custom tools, and skills.
|
|
9
|
+
|
|
10
|
+
## When to Use
|
|
11
|
+
|
|
12
|
+
Use this skill when you need to:
|
|
13
|
+
1. Build and run complex workflows as a series of step-by-step execution pipelines.
|
|
14
|
+
2. Enforce AI responses to strictly match specified Zod schemas for full type safety.
|
|
15
|
+
3. Provide LLM tools (web interaction, file system, shell command execution) and register MCP servers.
|
|
16
|
+
4. Manage shared state and configuration across all pipeline steps using a global context.
|
|
17
|
+
5. Execute multiple tasks in parallel using a `swarm` step.
|
|
18
|
+
6. Build iterative workflows (e.g. self-correction, retries, and validations) using a `loop` step.
|
|
19
|
+
7. Inject reusable domain-specific instructions or workflows using LLM skills.
|
|
20
|
+
|
|
21
|
+
## Pipeline Utilities
|
|
22
|
+
|
|
23
|
+
Each pipeline step receives a set of utilities to interact with the environment, AI, and context.
|
|
24
|
+
|
|
25
|
+
### `factory`
|
|
26
|
+
Used to create different types of steps and retrieve tools or skills:
|
|
27
|
+
- `ai(description?)`: Creates a step that executes on the AI side.
|
|
28
|
+
- `self(description?)`: Creates a step that executes on the local machine.
|
|
29
|
+
- `swarm(description?)`: Executes multiple steps or pipelines in parallel.
|
|
30
|
+
- `loop(description?)`: Creates a loop of steps.
|
|
31
|
+
- `tools`: Access to LLM tools factory (e.g., `factory.tools.web()`).
|
|
32
|
+
- `skills`: Access to LLM skills factory (e.g., `factory.skills.all()`).
|
|
33
|
+
|
|
34
|
+
### `utils`
|
|
35
|
+
General-purpose utilities:
|
|
36
|
+
- `content`: `ContentFactory` instance to create structured prompt content (articles, tasks, rules, attachments, files, globs).
|
|
37
|
+
- `bash`: Execute shell commands on the local machine.
|
|
38
|
+
- `log`: Emit log events for the current pipeline session.
|
|
39
|
+
|
|
40
|
+
### `context`
|
|
41
|
+
Shared state and configuration:
|
|
42
|
+
- `input`: The input data provided to the pipeline.
|
|
43
|
+
- `state`: Shared state across all steps (contains results of previous steps).
|
|
44
|
+
- `llm`: Current LLM provider configuration.
|
|
45
|
+
- `project`: Information about the current project.
|
|
46
|
+
|
|
47
|
+
### `utils.content` (ContentFactory)
|
|
48
|
+
Used to create structured prompt content. These methods are available via `utils.content` in pipeline steps.
|
|
49
|
+
|
|
50
|
+
- `article(title, content)`: Creates a `## Title` section with nested markdown content.
|
|
51
|
+
- `rules(list)`: Creates a bulleted list of rules/constraints.
|
|
52
|
+
- `tasks(list)`: Creates a numbered list of tasks for the AI.
|
|
53
|
+
- `sources(list)`: Creates a list of source links.
|
|
54
|
+
- `attachment(title, payload)`: Attaches data (object, string) as a file-like block.
|
|
55
|
+
- `file(title, path)`: Reads a local file and attaches it as context.
|
|
56
|
+
- `glob(title, pattern)`: Reads multiple files by pattern and attaches them.
|
|
57
|
+
- `plain(text)`: Adds raw markdown text.
|
|
58
|
+
|
|
59
|
+
### `factory.tools` (LlmToolsFactory)
|
|
60
|
+
Used to provide tools to the AI. These methods are available via `factory.tools` in pipeline steps.
|
|
61
|
+
|
|
62
|
+
- `all()`: Includes all available tools.
|
|
63
|
+
- `web()`: Tools for web interaction (e.g., `search`, `fetch`).
|
|
64
|
+
- `files('read')`: Read-only file system tools (e.g., `read`, `grep`, `glob`, `ls`).
|
|
65
|
+
- `files('read-write', options?)`: Read and write file system tools (e.g., `read`, `grep`, `glob`, `ls`, `mkdir`, `write`, `edit`, `rm`). Can restrict write/edit/rm to specific glob patterns using the `allowed` parameter.
|
|
66
|
+
- `commands(allowedCmds)`: Package manager tools (e.g., `npm`, `npx`).
|
|
67
|
+
- `custom(tools)`: Includes custom tool implementations compiled with `LlmToolCompiler`.
|
|
68
|
+
|
|
69
|
+
### `factory.skills` (LlmSkillsFactory)
|
|
70
|
+
Used to provide domain-specific instructions and workflows to the AI.
|
|
71
|
+
|
|
72
|
+
- `all()`: Includes all registered skills.
|
|
73
|
+
- `match(pattern)`: Includes skills matching a minimatch pattern.
|
|
74
|
+
- `register(raw)`: Registers a new skill from raw markdown content (with frontmatter).
|
|
75
|
+
- `custom(skills)`: Includes custom skill objects.
|
|
76
|
+
- `provide()`: Returns the list of included skills for LLM configuration.
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Usage Examples
|
|
81
|
+
|
|
82
|
+
### Simple Pipeline
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
import z from 'zod';
|
|
86
|
+
import { PipelineCompiler } from '@n1k1t/pipelain';
|
|
87
|
+
|
|
88
|
+
const translate = PipelineCompiler
|
|
89
|
+
.build('Translator')
|
|
90
|
+
.input(z.string())
|
|
91
|
+
.step('translated', ({ factory, context }) => factory
|
|
92
|
+
.ai('Translating')
|
|
93
|
+
.schema(z.object({
|
|
94
|
+
ru: z.string().describe('Russian translation'),
|
|
95
|
+
es: z.string().describe('Spanish translation'),
|
|
96
|
+
en: z.string().describe('English translation'),
|
|
97
|
+
}))
|
|
98
|
+
.prompt([
|
|
99
|
+
`Translate this text to Russian, Spanish and English: ${context.input}`,
|
|
100
|
+
])
|
|
101
|
+
);
|
|
102
|
+
|
|
103
|
+
(async () => {
|
|
104
|
+
const compiled = await translate.compile();
|
|
105
|
+
const result = await compiled.run('Hello');
|
|
106
|
+
console.log(result.translated.es); // Hola
|
|
107
|
+
})();
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### Structured Prompt Content
|
|
111
|
+
|
|
112
|
+
Create rich, structured prompts for the AI by combining multiple content types.
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
.step('complex_task', async ({ factory, utils }) => factory
|
|
116
|
+
.ai('Complex Processing')
|
|
117
|
+
.prompt([
|
|
118
|
+
// 1. Global rules
|
|
119
|
+
utils.content.rules([
|
|
120
|
+
'Use professional tone',
|
|
121
|
+
'Output must be valid JSON'
|
|
122
|
+
]),
|
|
123
|
+
|
|
124
|
+
// 2. Structured article
|
|
125
|
+
utils.content.article('Project Overview', [
|
|
126
|
+
{ p: 'This project is a type-safe pipeline builder.' },
|
|
127
|
+
{ h2: 'Key Goals' },
|
|
128
|
+
{ ul: ['Safety', 'Performance', 'Flexibility'] }
|
|
129
|
+
]),
|
|
130
|
+
|
|
131
|
+
// 3. Attachments
|
|
132
|
+
utils.content.attachment('User Data', {
|
|
133
|
+
content: { id: 1, name: 'John Doe' }
|
|
134
|
+
}),
|
|
135
|
+
|
|
136
|
+
// 4. Local files and glob patterns
|
|
137
|
+
await utils.content.file('Package Info', 'package.json'),
|
|
138
|
+
await utils.content.glob('Source Code', 'src/utils/*.ts'),
|
|
139
|
+
|
|
140
|
+
// 5. External sources
|
|
141
|
+
utils.content.sources(['https://github.com/n1k1t/pipelain']),
|
|
142
|
+
|
|
143
|
+
// 6. Raw markdown
|
|
144
|
+
utils.content.plain('> Note: This is a critical task.'),
|
|
145
|
+
|
|
146
|
+
// 7. Specific tasks for the AI to complete
|
|
147
|
+
utils.content.tasks([
|
|
148
|
+
'Review the `Project Overview` article',
|
|
149
|
+
'Analyze `User Data` and `Source Code`',
|
|
150
|
+
'Generate a summary based on the rules'
|
|
151
|
+
])
|
|
152
|
+
])
|
|
153
|
+
)
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### AI Step with LLM Configuration and Restricted Tools
|
|
157
|
+
|
|
158
|
+
Customize LLM behavior (temperature, retry limits, tools, restricted paths) for specific steps.
|
|
159
|
+
|
|
160
|
+
```ts
|
|
161
|
+
.step('research', ({ factory, context, utils }) => factory
|
|
162
|
+
.ai('Researching')
|
|
163
|
+
.llm(({ context }) => context.llm.assign({
|
|
164
|
+
temperature: 0.7,
|
|
165
|
+
limit: 10, // Max tool execution attempts
|
|
166
|
+
tools: factory.tools
|
|
167
|
+
.web()
|
|
168
|
+
.files('read-write', {
|
|
169
|
+
allowed: {
|
|
170
|
+
write: ['src/generated/*.ts'],
|
|
171
|
+
edit: ['src/**/*.ts'],
|
|
172
|
+
rm: ['temp/**/*']
|
|
173
|
+
}
|
|
174
|
+
})
|
|
175
|
+
.provide(),
|
|
176
|
+
}))
|
|
177
|
+
.schema(z.object({
|
|
178
|
+
summary: z.string(),
|
|
179
|
+
links: z.array(z.string())
|
|
180
|
+
}))
|
|
181
|
+
.prompt([
|
|
182
|
+
utils.content.tasks([
|
|
183
|
+
`Find information about: ${context.input}`,
|
|
184
|
+
'Summarize findings and provide source links'
|
|
185
|
+
])
|
|
186
|
+
])
|
|
187
|
+
)
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### Combining `self` and `ai` Steps
|
|
191
|
+
|
|
192
|
+
Use `self` steps to perform local computations, log messages, or modify/transform the shared state.
|
|
193
|
+
|
|
194
|
+
```ts
|
|
195
|
+
const pipeline = PipelineCompiler
|
|
196
|
+
.build('Data Processor')
|
|
197
|
+
.input(z.string())
|
|
198
|
+
.step('extracted', ({ factory, context }) => factory
|
|
199
|
+
.ai('Extracting data')
|
|
200
|
+
.schema(z.object({
|
|
201
|
+
items: z.array(z.string())
|
|
202
|
+
}))
|
|
203
|
+
.prompt([`Extract items from: ${context.input}`])
|
|
204
|
+
)
|
|
205
|
+
// Local self step
|
|
206
|
+
.step(({ context, utils }) => {
|
|
207
|
+
utils.log(`Extracted ${context.state.extracted.items.length} items`);
|
|
208
|
+
|
|
209
|
+
context.merge({
|
|
210
|
+
state: {
|
|
211
|
+
processedCount: context.state.extracted.items.length
|
|
212
|
+
}
|
|
213
|
+
});
|
|
214
|
+
})
|
|
215
|
+
.step('summary', ({ factory, context }) => factory
|
|
216
|
+
.ai('Summarizing')
|
|
217
|
+
.schema(z.object({ text: z.string() }))
|
|
218
|
+
.prompt([
|
|
219
|
+
`Summarize these ${context.state.processedCount} items:`,
|
|
220
|
+
context.state.extracted.items.join(', ')
|
|
221
|
+
])
|
|
222
|
+
);
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
### Parallel Execution with `swarm`
|
|
226
|
+
|
|
227
|
+
Run multiple independent AI tasks in parallel to improve performance.
|
|
228
|
+
|
|
229
|
+
```ts
|
|
230
|
+
.step('analysis', ({ factory }) => factory
|
|
231
|
+
.swarm('Parallel Analysis')
|
|
232
|
+
.subtasks([
|
|
233
|
+
factory
|
|
234
|
+
.ai('Sentiment Analysis')
|
|
235
|
+
.schema(z.object({ score: z.number() }))
|
|
236
|
+
.prompt(({ context }) => [`Analyze sentiment of: ${context.input}`]),
|
|
237
|
+
|
|
238
|
+
factory
|
|
239
|
+
.ai('Keyword Extraction')
|
|
240
|
+
.schema(z.object({ tags: z.array(z.string()) }))
|
|
241
|
+
.prompt(({ context }) => [`Extract keywords from: ${context.input}`]),
|
|
242
|
+
])
|
|
243
|
+
.limit(2) // Limit parallel executions
|
|
244
|
+
)
|
|
245
|
+
// Results will be available in context.state.analysis as an array of PromiseSettledResult
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
### Iterative Execution with `loop` (Self-Correction)
|
|
249
|
+
|
|
250
|
+
Create validation loops where the AI evaluates its own responses or retries until a condition is met.
|
|
251
|
+
|
|
252
|
+
```ts
|
|
253
|
+
.step('refined_answer', ({ factory }) => factory
|
|
254
|
+
.loop('Self-Correction Loop')
|
|
255
|
+
.limit(3) // Max 3 attempts
|
|
256
|
+
.action(({ factory, context, verdict }) => factory
|
|
257
|
+
.ai('Answering')
|
|
258
|
+
.schema(z.object({
|
|
259
|
+
answer: z.string(),
|
|
260
|
+
isCorrect: z.boolean().describe('Self-check result')
|
|
261
|
+
}))
|
|
262
|
+
.prompt([
|
|
263
|
+
`Question: ${context.input}`,
|
|
264
|
+
verdict.status === 'pending' ? verdict.content : ''
|
|
265
|
+
])
|
|
266
|
+
)
|
|
267
|
+
.condition(({ result }) => {
|
|
268
|
+
if (result.isCorrect) {
|
|
269
|
+
return { status: 'fulfilled' };
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
return {
|
|
273
|
+
status: 'pending',
|
|
274
|
+
content: 'Your previous answer was incorrect. Please try again and be more specific.'
|
|
275
|
+
};
|
|
276
|
+
})
|
|
277
|
+
)
|
|
278
|
+
// Result will be { status: 'fulfilled' | 'voided', value: { answer, isCorrect } }
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
### Model Context Protocol (MCP) Integration
|
|
282
|
+
|
|
283
|
+
Integrate MCP servers to allow the AI to use tools provided by external service servers.
|
|
284
|
+
|
|
285
|
+
```ts
|
|
286
|
+
import { LlmMcp } from '@n1k1t/pipelain';
|
|
287
|
+
|
|
288
|
+
pipeline.step('mcp_research', ({ factory }) => factory
|
|
289
|
+
.ai('Researching with MCP')
|
|
290
|
+
.llm(({ context }) => context.llm.assign({
|
|
291
|
+
mcp: [
|
|
292
|
+
LlmMcp.build({
|
|
293
|
+
transport: {
|
|
294
|
+
type: 'stdio',
|
|
295
|
+
command: 'npx',
|
|
296
|
+
args: ['-y', '@modelcontextprotocol/server-gdrive'],
|
|
297
|
+
},
|
|
298
|
+
tools: {
|
|
299
|
+
enabled: ['list-files', 'read-file'], // Limit enabled tools
|
|
300
|
+
},
|
|
301
|
+
}),
|
|
302
|
+
],
|
|
303
|
+
}))
|
|
304
|
+
.prompt(['List my recent files in Google Drive and summarize them.'])
|
|
305
|
+
);
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
### Custom LLM Tools
|
|
309
|
+
|
|
310
|
+
Create and integrate your own custom tools using `LlmToolCompiler`.
|
|
311
|
+
|
|
312
|
+
```ts
|
|
313
|
+
import z from 'zod';
|
|
314
|
+
import { LlmToolCompiler } from '@n1k1t/pipelain';
|
|
315
|
+
|
|
316
|
+
const weatherTool = LlmToolCompiler
|
|
317
|
+
.build('Get current weather for a location')
|
|
318
|
+
.input(z.object({
|
|
319
|
+
city: z.string().describe('The city name')
|
|
320
|
+
}))
|
|
321
|
+
.output(z.object({
|
|
322
|
+
temperature: z.number(),
|
|
323
|
+
condition: z.string()
|
|
324
|
+
}))
|
|
325
|
+
.execute(() => async ({ city }) => {
|
|
326
|
+
return { temperature: 22, condition: 'Sunny' };
|
|
327
|
+
});
|
|
328
|
+
|
|
329
|
+
pipeline.step('weather_report', ({ factory, context }) => factory
|
|
330
|
+
.ai('Checking weather')
|
|
331
|
+
.llm(({ context }) => context.llm.assign({
|
|
332
|
+
tools: factory.tools
|
|
333
|
+
.web()
|
|
334
|
+
.custom({ weather: weatherTool })
|
|
335
|
+
.provide()
|
|
336
|
+
}))
|
|
337
|
+
.prompt([`Check weather in ${context.input}`])
|
|
338
|
+
);
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
---
|
|
342
|
+
|
|
343
|
+
## Steps
|
|
344
|
+
|
|
345
|
+
### 1. Analysis and Planning
|
|
346
|
+
|
|
347
|
+
Review the tasks and workflows that need to be accomplished by the AI:
|
|
348
|
+
- Determine step structure: Can the task be done in a single AI step, or does it require a sequence of steps?
|
|
349
|
+
- Assess if parallel execution (`swarm`) can speed up independent tasks.
|
|
350
|
+
- Assess if validation or correction is needed, requiring an iterative loop step (`loop`).
|
|
351
|
+
- Define inputs and outputs clearly, writing matching Zod schemas for structured responses.
|
|
352
|
+
|
|
353
|
+
### 2. Implementation Workflow
|
|
354
|
+
|
|
355
|
+
1. **Define Input**: Use `.input()` on `PipelineCompiler` to specify the entry schema.
|
|
356
|
+
2. **Chain Steps**: Chain `.step()` operations to orchestrate your workflow:
|
|
357
|
+
- Use `factory.ai()` for AI-driven steps, assigning prompt components (`utils.content`) and Zod schemas.
|
|
358
|
+
- Use local `self` steps (anonymous functions) to log, process outputs, or manipulate pipeline state.
|
|
359
|
+
3. **Configure Tools & Skills**: Use `.llm()` mapping to supply tools (`factory.tools`) or load skills (`factory.skills`) relevant to the current step.
|
|
360
|
+
4. **Compile and Execute**: Compile the pipeline using `.compile({ stdout })` and trigger execution using `.run(input)`.
|
|
361
|
+
|
|
362
|
+
### 3. Verification
|
|
363
|
+
|
|
364
|
+
- Enable debug mode `.debug()` on a step to mock execution and save the generated prompts into `.pipelain/${timestamp}-${session-id}/${step-title}.md` for inspection.
|
|
365
|
+
- Monitor log events by compiling the pipeline with `stdout: stdout.console`.
|
|
366
|
+
- Run TS type checking command `npm run build:check` to ensure correctness of Zod schemas and step definitions.
|
|
367
|
+
|
|
368
|
+
### 4. Refinement
|
|
369
|
+
|
|
370
|
+
- Optimize tokens and context size by restricting tool availability or specific paths (e.g. `allowed` paths in `files('read-write')`).
|
|
371
|
+
- If an AI step behaves inconsistently, split it into smaller, more granular steps or add a `loop` validation step.
|