@n1k1t/pipelain 0.4.14 → 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx jest *)"
+    ]
+  }
+}

package/AGENTS.md

@@ -0,0 +1,20 @@
+# AGENTS.md
+
+Instructions for AI agents working in this repository (`@n1k1t/pipelain`).
+
+## Mandatory rules
+
+- If the `caveman` skill is installed, use it for communication in this session.
+
+## Project documentation
+
+Before starting work, review the documentation in `.ai/docs`:
+
+- [`.ai/docs/structure.md`](.ai/docs/structure.md) — project structure, purpose of the main directories and files.
+- [`.ai/docs/style.md`](.ai/docs/style.md) — code style: import/export order, object and function formatting.
+
+## Useful commands
+
+- `npm test` — run tests (Jest).
+- `npm run build:check` — type-check without building (`tsc --noEmit`).
+- `npm run build` — build the project into `lib/`.

package/README.md

@@ -33,14 +33,17 @@ Powerful utility to build and execute type-safe AI pipelines with structured out
   - [AI Step with LLM Configuration](#ai-step-with-llm-configuration)
   - [AI Step with Fallback](#ai-step-with-fallback)
   - [Debugging AI Steps](#debugging-ai-steps)
+  - [Execution Reports](#execution-reports)
   - [Combining self and ai Steps](#combining-self-and-ai-steps)
   - [Parallel Execution with swarm](#parallel-execution-with-swarm)
   - [Iterative Execution with loop](#iterative-execution-with-loop)
   - [Multi-Provider Pipelines](#multi-provider-pipelines)
+  - [Custom Model Routing](#custom-model-routing)
   - [MCP (Model Context Protocol) Integration](#mcp-model-context-protocol-integration)
   - [Using Skills](#using-skills)
 - [Extensions](#extensions)
   - [Custom LLM Tools](#custom-llm-tools)
+  - [LLM Tool Hooks](#llm-tool-hooks)
   - [Custom LLM Skills](#custom-llm-skills)
   - [Registering Skills from Markdown](#registering-skills-from-markdown)
 - [License](#license)
@@ -114,9 +117,11 @@ The following environment variables are supported:
 | --- | --- | --- |
 | `PIPELAIN_API_KEY` | API key for the LLM provider. | - |
 | `PIPELAIN_API_URL` | Custom API URL for the LLM provider. | - |
-| `PIPELAIN_SKILLS_PATHS` | Directories paths where LLM skills are stored (separated by `;`). | `~/.agents/skills` |
+| `PIPELAIN_SKILLS_PATHS` | Directories paths where LLM skills are stored (separated by `;`). | `./.agents/skills;~/.agents/skills` |
 | `PIPELAIN_MODEL` | Default LLM model to use. | `gemini-flash-latest` |
 | `PIPELAIN_PROVIDER` | LLM provider name (e.g., `google`, `openai`). | - |
+| `PIPELAIN_FLAGS_REPORT` | Save an HTML report of the pipeline execution. | `false` |
+| `PIPELAIN_FLAGS_DEBUG` | Enable debug mode for all AI steps. | `false` |
 | `EXA_API_KEY` | API key for Exa web search tools. | - |
 
 ## Pipeline Step Utilities
@@ -136,7 +141,7 @@ Used to create different types of steps:
 General-purpose utilities:
 - `content`: `ContentFactory` instance to create structured prompt content (articles, tasks, rules, attachments).
 - `bash`: Execute shell commands on the local machine.
-- `log`: Emit log events for the current pipeline session.
+- `log`: Emit `INFO` log events for the current pipeline session (shown in stdout and HTML reports).
 
 ### `context`
 Shared state and configuration:
@@ -158,6 +163,10 @@ Used to create structured prompt content. These methods are available via `utils
 | `file(title, path)` | Reads a local file and attaches it as context. | `await utils.content.file('Config', 'package.json')` |
 | `glob(title, pattern)` | Reads multiple files by pattern and attaches them. | `await utils.content.glob('Source', 'src/**/*.ts')` |
 | `plain(text)` | Adds raw markdown text. | `utils.content.plain('### Subtitle\nText')` |
+| `user(content)` | Forces content to be placed into the `user` message. | `utils.content.user('Say hi')` |
+| `system(content)` | Forces content to be placed into the `system` message. | `utils.content.system('You are a helpful assistant')` |
+
+Each content kind has a default location it is rendered into (`tasks` and plain strings default to `user`, everything else defaults to `system`). Wrap any content in `utils.content.user()` / `utils.content.system()` to override that placement explicitly.
 
 ### `factory.tools` (LlmToolsFactory)
 Used to provide tools to the AI. These methods are available via `factory.tools` in pipeline steps.
@@ -205,13 +214,13 @@ To use a custom logger or override specific event handlers, use `PipelineStdout`
 import { PipelineStdout } from '@n1k1t/pipelain';
 
 const customStdout = PipelineStdout
-  .build(console) // Pass any logger with .info and .warn methods
-  .override('log', (event) => {
-    console.log(`[CUSTOM LOG] ${event.message}`);
+  .build(console) // Pass any logger with .info, .warn and .debug methods
+  .override('log', ({ level, message }) => {
+    console.log(`[${level}]`, ...message);
   })
-  .override('step:run', (event) => {
-    if (event.meta.state === 'SUCCESS') {
-      console.log(`Step ${event.step.title} finished in ${event.meta.spent}ms`);
+  .override('step:run', ({ step }) => {
+    if (step.meta.is('DONE')) {
+      console.log(`Step ${step.title} finished in ${step.meta.spent}ms`);
     }
   });
 
@@ -221,6 +230,17 @@ const customStdout = PipelineStdout
 })();
 ```
 
+Each pipeline, step and AI action has a `meta` object with its execution state:
+
+| Property / Method | Description |
+| --- | --- |
+| `state` | `'INIT' \| 'PENDING' \| 'DONE' \| 'ERROR'` |
+| `spent` | Time spent since creation (ms). |
+| `timestamp` | Creation timestamp. |
+| `is(state \| state[])` | Checks the current state. |
+
+The `log` event has a `level` field: `'DEBUG' | 'INFO' | 'WARN'`. `utils.log(...)` emits `INFO`.
+
 ### Structured Prompt Content
 
 You can combine multiple content types to create a rich, structured prompt for the AI:
@@ -349,7 +369,28 @@ You can use the `.debug()` method to inspect the prompts sent to the AI. When de
 )
 ```
 
-The prompt will be saved to: `.pipelain/${timestamp}-${session-id}/${step-title}.md`.
+The prompt will be saved to: `.pipelain/debug/YYYY-MM-DD--HH-mm-ss--<session-id>/<step-number>.<step-trace>.md`.
+
+### Execution Reports
+
+Use `.report()` on the pipeline compiler (or set `PIPELAIN_FLAGS_REPORT=true`) to save an HTML report of the AI steps execution:
+
+```ts
+const pipeline = PipelineCompiler
+  .build('Translate')
+  .report() // Enables HTML report
+  .input(z.string())
+  .step('translated', ({ factory, context }) => factory
+    .ai('Translating')
+    .prompt([`Translate "${context.input}" into Spanish`])
+  );
+```
+
+The report is saved into `.pipelain/reports/YYYY-MM-DD--HH-mm-ss--<session-id>.html` and includes:
+
+- AI steps with messages, actions (tools, reasoning, fallbacks), output and timing;
+- `INFO` and `WARN` logs emitted via `utils.log`;
+- token usage per provider and model (prompt, cached, completion) and total session time.
 
 ### Combining `self` and `ai` Steps
 
@@ -389,12 +430,14 @@ const pipeline = PipelineCompiler
 
 ### Parallel Execution with `swarm`
 
-Use `swarm` to execute multiple AI tasks in parallel. You can define subtasks using the `subtasks` method:
+Use `swarm` to execute multiple AI tasks in parallel. You can define subtasks as a `list` (array) or as a `map` (keyed object), optionally limiting how many run concurrently with `.limit()`.
+
+#### `list`
 
 ```ts
 .step('analysis', ({ factory }) => factory
   .swarm('Parallel Analysis')
-  .subtasks([
+  .list([
     factory
       .ai('Sentiment Analysis')
       .schema(z.object({ score: z.number() }))
@@ -410,6 +453,32 @@ Use `swarm` to execute multiple AI tasks in parallel. You can define subtasks us
 // Results will be available in context.state.analysis as an array of PromiseSettledResult
 ```
 
+> `subtasks(...)` is a deprecated alias of `list(...)` kept for backward compatibility — prefer `list`.
+
+#### `map`
+
+Use `map` when you need to address each subtask result by name instead of by array index:
+
+```ts
+.step('analysis', ({ factory }) => factory
+  .swarm('Parallel Analysis')
+  .map({
+    sentiment: factory
+      .ai('Sentiment Analysis')
+      .schema(z.object({ score: z.number() }))
+      .prompt(({ context }) => [`Analyze sentiment of: ${context.input}`]),
+
+    keywords: factory
+      .ai('Keyword Extraction')
+      .schema(z.object({ tags: z.array(z.string()) }))
+      .prompt(({ context }) => [`Extract keywords from: ${context.input}`]),
+  })
+  .limit(2) // Optional: limit parallel executions
+)
+// context.state.analysis.sentiment -> PromiseSettledResult<{ score: number }>
+// context.state.analysis.keywords -> PromiseSettledResult<{ tags: string[] }>
+```
+
 ### Iterative Execution with `loop`
 
 Use `loop` for tasks that require multiple iterations or validation, such as self-correction:
@@ -472,6 +541,29 @@ const pipeline = PipelineCompiler
   );
 ```
 
+### Custom Model Routing
+
+`LlmRouter` picks a provider by model name. Use `register` to route models matched by a [minimatch](https://github.com/isaacs/minimatch) pattern to your own provider:
+
+```ts
+import { LlmRouter, llm } from '@n1k1t/pipelain';
+
+const router = LlmRouter
+  .build()
+  .register('corp-*', (model) => llm.providers.LlmProxyProvider.build(model, {
+    name: 'corp', // Shown in usage stats and reports instead of "proxy"
+    connection: { key: process.env.CORP_API_KEY!, url: 'https://llm.corp.local/v1' },
+  }));
+
+pipeline.step('analysis', ({ factory }) => factory
+  .ai('Corp Analysis')
+  .llm(() => router.provide('corp-gpt-4o'))
+  .prompt(['...'])
+);
+```
+
+Registrations are checked in order and the first match wins. Unmatched models fall back to the default routing.
+
 ### MCP (Model Context Protocol) Integration
 
 You can integrate MCP servers into your pipeline steps. This allows the AI to use tools provided by external MCP servers. You can also filter which tools are enabled:
@@ -494,6 +586,9 @@ pipeline.step('mcp_research', ({ factory, context }) => factory
           enabled: ['list-files', 'read-file'],
           // Or disable specific tools
           // disabled: ['delete-file'],
+
+          // Add prefix to tool names (e.g. "gdrive_read-file")
+          prefix: 'gdrive_',
         },
       }),
     ],
@@ -502,6 +597,8 @@ pipeline.step('mcp_research', ({ factory, context }) => factory
 );
 ```
 
+Use `tools.prefix` to avoid name conflicts between MCP servers or with built-in tools. The `enabled` and `disabled` patterns match tool names without the prefix. Hooks by name (`LlmHook.build('gdrive_read-file')`) match tool names with the prefix.
+
 ### Using Skills
 
 Skills allow you to inject reusable domain-specific instructions or workflows into your AI steps. You can manage them via `factory.skills`:
@@ -530,7 +627,7 @@ You can create custom tools for the AI using `LlmToolCompiler`. This allows the
 
 ```ts
 import z from 'zod/v3';
-import { LlmToolCompiler } from '@n1k1t/pipelain';
+import { LlmToolCompiler, LlmToolExecutionError } from '@n1k1t/pipelain';
 
 // 1. Define the tool
 const weatherTool = LlmToolCompiler
@@ -543,6 +640,11 @@ const weatherTool = LlmToolCompiler
     condition: z.string()
   }))
   .execute(() => async ({ city }) => {
+    if (!city.trim()) {
+      // Errors are reported back to the AI as "Execution failed: <reason>"
+      throw LlmToolExecutionError.build('City name is empty');
+    }
+
     // Your implementation here
     return { temperature: 22, condition: 'Sunny' };
   });
@@ -560,6 +662,77 @@ pipeline.step('weather_report', ({ factory, context }) => factory
 );
 ```
 
+### LLM Tool Hooks
+
+Use `LlmHook` to intercept tool calls inside an `ai` step. With a hook you can validate or modify the input, override the output, skip the original execution or handle errors. Provide hooks to the step with the `.hooks([...])` method.
+
+A hook matches a tool by one of these targets:
+
+- `LlmHook.build('name')` matches a tool by its name (built-in, custom or MCP tool).
+- `LlmHook.build(compiler)` matches a tool compiled from the same `LlmToolCompiler` instance.
+- `LlmHook.build(tool)` matches the same `Tool` instance.
+
+When a hook has a name (`LlmHook.build(compiler, { name: 'weather' })`), the name has priority over the compiler or tool.
+
+Each hook has two handlers:
+
+- `before({ input, next, session, context, step })` runs instead of the original `execute`. The original `execute` runs only when you call `next(input)`. If you do not call `next`, the returned value becomes the tool output.
+- `after({ output, input, session, context, step })` runs after `before` is settled. `output` is a `PromiseSettledResult`, so you can handle errors. The returned value becomes the final tool output and must match the tool output type. By default, `after` rethrows the error or returns the value.
+
+```ts
+import { LlmHook, LlmToolExecutionError } from '@n1k1t/pipelain';
+
+// Restrict paths of the built-in "write" tool
+const guard = LlmHook
+  .build<{ input: { path: string; content: string } }>('write')
+  .before(({ input, next }) => {
+    if (input.path.startsWith('/etc')) {
+      throw LlmToolExecutionError.build('Writing to /etc is not allowed');
+    }
+
+    return next(input);
+  });
+
+// Cache results of the custom tool and convert errors for the AI
+const cache = new Map<string, { temperature: number; condition: string }>();
+const weather = LlmHook
+  .build(weatherTool)
+  .before(async ({ input, next }) => {
+    const cached = cache.get(input.city);
+    if (cached) {
+      return cached;
+    }
+
+    const output = await next(input);
+
+    cache.set(input.city, output);
+    return output;
+  })
+  .after(({ output }) => {
+    if (output.status === 'rejected') {
+      throw LlmToolExecutionError.build(output.reason);
+    }
+
+    return output.value;
+  });
+
+pipeline.step('hooked', ({ factory, context }) => factory
+  .ai('Executing with hooks')
+  .llm(({ context }) => context.llm.assign({
+    tools: factory.tools
+      .files('read-write')
+      .custom({ weather: weatherTool })
+      .provide(),
+  }))
+  .hooks([guard, weather])
+  .prompt([`Check weather in ${context.input} and save it to weather.md`])
+);
+```
+
+When several hooks match the same tool, they run in the order of the array: the `before` handler of the first hook runs first, and its `after` handler runs last.
+
+> Built-in tools with options (for example, `write` in `files('read-write')`) are clones of the original compiler. Match built-in tools by name.
+
 ### Custom LLM Skills
 
 You can also provide custom skills programmatically: