@doclo/flows 0.1.8 → 0.1.9

package/README.md

@@ -1,41 +1,65 @@
 # @doclo/flows
 
-Flow orchestration and execution engine for document processing pipelines in the Doclo SDK.
+Flow builder and execution engine for document processing pipelines.
 
 ## Installation
 
 ```bash
-npm install @doclo/flows
-# or
 pnpm add @doclo/flows
 ```
 
-## Features
-
-- **FlowBuilder** - Declarative API for building document processing flows
-- **FlowExecutor** - Execute flows with automatic dependency resolution
-- **Composite Nodes** - Combine multiple nodes (sequence, parallel, forEach, conditional)
-- **Metrics Aggregation** - Automatic cost and token tracking across flow execution
-
 ## Usage
 
 ```typescript
-import { FlowBuilder, FlowExecutor } from '@doclo/flows';
+import { createFlow, parse, extract } from '@doclo/flows';
+import { createVLMProvider } from '@doclo/providers-llm';
+
+const provider = createVLMProvider({
+  provider: 'google',
+  model: 'gemini-2.5-flash',
+  apiKey: process.env.GOOGLE_API_KEY!
+});
 
-// Build a flow
-const flow = new FlowBuilder()
-  .addStep('categorize', categorizeNode)
-  .addStep('extract', extractNode, { dependsOn: ['categorize'] })
+const schema = {
+  type: 'object',
+  properties: {
+    invoiceNumber: { type: 'string' },
+    total: { type: 'number' }
+  }
+};
+
+const flow = createFlow()
+  .step('parse', parse({ provider }))
+  .step('extract', extract({ provider, schema }))
   .build();
 
-// Execute the flow
-const executor = new FlowExecutor(flow);
-const result = await executor.execute({
-  text: "Document content...",
-  images: [{ base64: "...", mimeType: "image/jpeg" }]
-});
+const result = await flow.run({ base64: documentBase64 });
+console.log(result.output);
 ```
 
+## Flow Methods
+
+```typescript
+createFlow()
+  .step(id, node)           // Add a sequential step
+  .conditional(id, fn)      // Add conditional branching
+  .forEach(id, childFlowFn) // Process arrays in parallel
+  .output({ name, source }) // Mark explicit output
+  .build()                  // Build executable flow
+```
+
+## Available Nodes
+
+Re-exported from `@doclo/nodes`:
+
+- `parse` - Extract text from documents
+- `split` - Split multi-doc PDFs into segments
+- `categorize` - Classify documents into categories
+- `extract` - Extract structured data using schema
+- `chunk` - Split text into chunks
+- `combine` - Merge results
+- `trigger` - Execute another flow
+
 ## License
 
 MIT

package/dist/index.js

@@ -666,6 +666,11 @@ var Flow = class {
                 stepId: step.id
               }, artifacts);
               artifacts[step.id] = result2.output;
+              for (const [key, value] of Object.entries(result2.artifacts)) {
+                if (!(key in artifacts)) {
+                  artifacts[key] = value;
+                }
+              }
               metrics.push(...result2.metrics);
               completedSteps.push(step.id);
               const stepDuration = Date.now() - stepStartTime;
@@ -1283,6 +1288,14 @@ function flattenMetrics(childMetrics, prefix) {
     nested: true
   }));
 }
+function flattenArtifacts(childArtifacts, prefix) {
+  const flattened = {};
+  for (const [key, value] of Object.entries(childArtifacts)) {
+    if (key.startsWith("__")) continue;
+    flattened[`${prefix}.${key}`] = value;
+  }
+  return flattened;
+}
 function createConditionalCompositeNode(config) {
   const { stepId, categorizeConfig, branches, providers, flows } = config;
   return {
@@ -1351,7 +1364,16 @@ function createConditionalCompositeNode(config) {
         }
         if (ctx?.emit) {
           ctx.emit(`${stepId}:branchOutput`, branchResult.output);
-          ctx.emit(`${stepId}:branchArtifacts`, branchResult.artifacts);
+          if (branchResult.artifacts) {
+            const flattenedArtifacts = flattenArtifacts(
+              branchResult.artifacts,
+              `${stepId}.branch.${selectedCategory}`
+            );
+            for (const [key, value] of Object.entries(flattenedArtifacts)) {
+              ctx.emit(key, value);
+            }
+            ctx.emit(`${stepId}:branchArtifacts`, branchResult.artifacts);
+          }
         }
         const categorizeCost = categorizeCostTracker.reduce((sum, m) => sum + (m.costUSD ?? 0), 0);
         const branchCost = branchResult.metrics ? branchResult.metrics.reduce((sum, m) => sum + (m.costUSD ?? 0), 0) : 0;
@@ -1536,6 +1558,18 @@ function createForEachCompositeNode(config) {
           ctx.emit(`${stepId}:results`, results);
           ctx.emit(`${stepId}:successCount`, successCount);
           ctx.emit(`${stepId}:failureCount`, failureCount);
+          itemFlowResults.forEach((result, index) => {
+            if (result.artifacts) {
+              const flattenedArtifacts = flattenArtifacts(
+                result.artifacts,
+                `${stepId}.item[${index}]`
+              );
+              for (const [key, value] of Object.entries(flattenedArtifacts)) {
+                ctx.emit(key, value);
+              }
+            }
+          });
+          ctx.emit(`${stepId}:itemArtifacts`, itemFlowResults.map((r) => r.artifacts));
         }
         if (ctx?.metrics) {
           const provider = providers[splitConfig.providerRef];
@@ -1755,7 +1789,16 @@ function createRouteCompositeNode(config) {
         }
         if (ctx?.emit) {
           ctx.emit(`${stepId}:branchOutput`, branchResult.output);
-          ctx.emit(`${stepId}:branchArtifacts`, branchResult.artifacts);
+          if (branchResult.artifacts) {
+            const flattenedArtifacts = flattenArtifacts(
+              branchResult.artifacts,
+              `${stepId}.branch.${selectedBranch}`
+            );
+            for (const [key, value] of Object.entries(flattenedArtifacts)) {
+              ctx.emit(key, value);
+            }
+            ctx.emit(`${stepId}:branchArtifacts`, branchResult.artifacts);
+          }
         }
         const branchCost = branchResult.metrics ? branchResult.metrics.reduce((sum, m) => sum + (m.costUSD ?? 0), 0) : 0;
         const totalMs = Date.now() - t0;