feat(flow): add description and toFunction methods for enhanced flow metadata

This commit introduces the `description(name: string, description: string)` method to set flow-level names and descriptions, which are stored in the flow's inferred signature. Additionally, the `toFunction()` method is implemented to convert flows into AxFunction instances, utilizing the flow's inferred signature for generating function metadata. Examples in the documentation and various flow implementations have been updated to demonstrate these new features.

Author: dosco

docs/AXFLOW.md

@@ -305,6 +305,42 @@ flow.r((state) => ({ output: state.value }));
   format
 - When building reusable flows that need clear output contracts
 
+#### `description(name: string, description: string)`
+
+Set a flow-level name and description. The description is stored on the flow's
+inferred signature, and the name/description are used by `toFunction()` for the
+exported function metadata.
+
+```typescript
+const wf = flow<{ userQuestion: string }, { responseText: string }>()
+  .node("qa", "userQuestion:string -> responseText:string")
+  .description(
+    "Question Answerer",
+    "Answers user questions concisely using the configured AI model.",
+  );
+```
+
+#### `toFunction()`
+
+Convert the flow into an AxFunction using the flow's inferred signature. The
+function's `name` prefers the name set via `description(name, ...)` and falls
+back to the first line of the signature description. The `parameters` are
+generated from the inferred input fields as JSON Schema.
+
+```typescript
+const wf = flow<{ userQuestion: string }, { responseText: string }>()
+  .node("qa", "userQuestion:string -> responseText:string")
+  .description(
+    "Question Answerer",
+    "Answers user questions concisely using the configured AI model.",
+  );
+
+const fn = wf.toFunction();
+console.log(fn.name); // "questionAnswerer"
+console.log(fn.parameters); // JSON Schema from inferred input
+// You can call fn.func with args and { ai } to execute the flow
+```
+
 ### Control Flow Methods
 
 #### `while(condition: Function)` / `endWhile()`

src/ax/flow/flow.ts

@@ -7,7 +7,11 @@ import {
   SpanKind,
   trace,
 } from '@opentelemetry/api';
-import type { AxAIService } from '../ai/types.js';
+import type {
+  AxAIService,
+  AxFunction,
+  AxFunctionHandler,
+} from '../ai/types.js';
 import type { AxGen } from '../dsp/generate.js';
 import type { AxOptimizedProgram } from '../dsp/optimizer.js';
 import { AxProgram } from '../dsp/program.js';
@@ -105,6 +109,9 @@ export class AxFlow<
   // Program field that gets initialized when something is added to the graph
   private program?: AxProgram<IN, OUT>;
 
+  // Optional flow-level name used by toFunction()
+  private flowName?: string;
+
   // Node-level usage tracking
   private nodeUsage: Map<string, AxProgramUsage[]> = new Map();
 
@@ -713,6 +720,50 @@ export class AxFlow<
     this.program!.setDemos(demos);
   }
 
+  public description(name: string, description: string): this {
+    this.ensureProgram();
+    this.flowName = name;
+    this.program!.setDescription(description);
+    return this;
+  }
+
+  public toFunction(): AxFunction {
+    this.ensureProgram();
+    const sig = this.program!.getSignature();
+
+    const baseName =
+      this.flowName ??
+      (sig.getDescription()?.trim().split('\n')[0] || 'axFlow');
+    const safe = baseName.replace(/\s+/g, '_');
+    const name = this.toCamelCase(safe);
+
+    const handler: AxFunctionHandler = async (args?: any, extra?) => {
+      const ai = extra?.ai;
+      if (!ai) throw new Error('AI service is required to run the flow');
+
+      const ret = await this.forward(ai, (args ?? {}) as IN);
+      const outFields = sig.getOutputFields();
+
+      const resultObj = (ret ?? {}) as Record<string, unknown>;
+      return Object.keys(resultObj)
+        .map((k) => {
+          const f = outFields.find((of) => of.name === k);
+          if (f && (f as any).title) {
+            return `${(f as any).title}: ${resultObj[k]}`;
+          }
+          return `${k}: ${resultObj[k]}`;
+        })
+        .join('\n');
+    };
+
+    return {
+      name,
+      description: sig.getDescription() ?? 'Execute this AxFlow',
+      parameters: sig.toJSONSchema(),
+      func: handler,
+    };
+  }
+
   public getUsage(): AxProgramUsage[] {
     // Collect usage from all nodes and merge
     const allUsage: AxProgramUsage[] = [];

src/examples/ax-flow-to-function.ts

@@ -38,26 +38,20 @@ console.log('3. Named flow with function conversion:');
 const namedFlow = new AxFlow<
   { userQuestion: string },
   { responseText: string }
->();
+>().description(
+  'Question Answerer',
+  'Answers user questions concisely using the configured AI model.'
+);
 
 // Test function conversion
-try {
-  // toFunction method is not available in the current implementation
-  const flowAsFunction = {
-    name: 'Question Answerer',
-    description: 'Not available',
-    parameters: { properties: {} },
-  };
-  console.log('Function conversion successful:');
-  console.log('- Name:', flowAsFunction.name);
-  console.log('- Description:', flowAsFunction.description);
-  console.log(
-    '- Parameters schema keys:',
-    Object.keys(flowAsFunction.parameters?.properties || {})
-  );
-} catch (error) {
-  console.error('Function conversion failed:', error);
-}
+const flowAsFunction = namedFlow.toFunction();
+console.log('Function conversion successful:');
+console.log('- Name:', flowAsFunction.name);
+console.log('- Description:', flowAsFunction.description);
+console.log(
+  '- Parameters schema keys:',
+  Object.keys(flowAsFunction.parameters?.properties || {})
+);
 
 // Test direct execution of named flow
 const namedResult = await namedFlow.forward(ai, {

src/examples/ax-flow.ts

@@ -11,6 +11,10 @@ const llm = ai({
 const flowFull = AxFlow.create<{ documentContent: string }>({
   autoParallel: true,
 })
+  .description(
+    'Document Analysis Pipeline',
+    'Summarizes a document, extracts keywords, and analyzes sentiment.'
+  )
   .node('summarizer', 'documentContent:string -> documentSummary:string')
   .node('keywordExtractor', 'documentSummary:string -> keywords:string[]')
   .node(
@@ -37,6 +41,10 @@ const flowFull = AxFlow.create<{ documentContent: string }>({
 
 // Aliases example 1 - Customer support ticket processing with error handling
 const flowAlias1 = AxFlow.create<{ ticketMessage: string }>()
+  .description(
+    'Support Ticket Processor',
+    'Classifies incoming support messages and generates a suggested response.'
+  )
   .n(
     'classifier',
     'customerMessage:string -> ticketCategory:string, urgencyLevel:string'
@@ -59,6 +67,10 @@ const flowAlias2 = AxFlow.create<
 >({
   autoParallel: true,
 })
+  .description(
+    'Code Review Assistant',
+    'Analyzes a code snippet and produces a concise review with quality score.'
+  )
   .n(
     'codeAnalyzer',
     'sourceCode:string -> codeAnalysis:string, qualityScore:number'
@@ -79,6 +91,10 @@ const flowBranch = AxFlow.create<
   { userPost: string; postType: string },
   { moderationAction: string }
 >()
+  .description(
+    'Content Moderation Router',
+    'Routes content to the appropriate moderator and returns the moderation action.'
+  )
   .node(
     'socialMediaModerator',
     'postContent:string -> moderationDecision:string, reasoning:string'
@@ -102,6 +118,10 @@ const flowBranch = AxFlow.create<
 
 // Parallel example - Research paper analysis with manual parallelization
 const flowParallel = flow<{ paperAbstract: string }>()
+  .description(
+    'Research Paper Scorer',
+    'Scores novelty and clarity in parallel and computes a combined score.'
+  )
   .node('noveltyScorer', 'researchAbstract:string -> noveltyScore:number')
   .node('clarityScorer', 'researchAbstract:string -> clarityScore:number')
   .parallel([
@@ -134,6 +154,10 @@ const flowParallel = flow<{ paperAbstract: string }>()
 
 // While example - Iterative writing improvement with circuit breaker
 const flowWhile = AxFlow.create<{ draftArticle: string }>()
+  .description(
+    'Iterative Writing Improver',
+    'Loops to improve article quality until the target is reached.'
+  )
   .node(
     'qualityEvaluator',
     'articleDraft:string -> qualityScore:number, qualityFeedback:string'
@@ -160,6 +184,10 @@ const flowWhile = AxFlow.create<{ draftArticle: string }>()
 
 // Multi-hop RAG example - Research question answering with concurrency control
 const flowRAG = AxFlow.create<{ researchQuestion: string }>()
+  .description(
+    'Multi-hop Research QA',
+    'Generates a query, retrieves context, and answers a research question.'
+  )
   .node('queryGenerator', 'researchQuestion:string -> searchQuery:string')
   .node('retriever', 'searchQuery:string -> retrievedDocument:string')
   .node(
@@ -182,6 +210,10 @@ const flowRAG = AxFlow.create<{ researchQuestion: string }>()
 
 // Batched parallel example - Processing multiple documents with concurrency control
 const flowBatchedParallel = flow<{ documentBatch: string }>()
+  .description(
+    'Batched Parallel Processor',
+    'Processes a batch through multiple processors with limited concurrency.'
+  )
   .node('processor1', 'batchData:string -> processedResult1:string')
   .node('processor2', 'batchData:string -> processedResult2:string')
   .node('processor3', 'batchData:string -> processedResult3:string')

src/examples/flow-type-inference-demo.ts

@@ -9,6 +9,10 @@ const _basicFlow = flow<{ userQuestion: string }>().map((state) => ({
 
 // Example 2: Complex input type - Full type safety with multiple fields!
 const typedFlow = flow<{ userQuestion: string; context: string }>()
+  .description(
+    'Type Inference Demo',
+    'Demonstrates input typing, state evolution, and final typed outputs.'
+  )
   .map((state) => ({
     ...state,
     // TypeScript knows these fields exist!

src/examples/flow-type-safe-output.ts

@@ -8,6 +8,10 @@ const llm = ai({ name: 'openai', apiKey: process.env.OPENAI_APIKEY! });
 
 // Example: Building a type-safe document analysis workflow
 const documentAnalyzer = flow<{ documentText: string }>()
+  .description(
+    'Type-safe Document Analyzer',
+    'Summarizes, analyzes sentiment, and extracts keywords with typed output.'
+  )
   // Define reusable nodes
   .node('summarizer', 'documentText:string -> summaryText:string')
   .node(

src/examples/fluent-flow-example.ts

@@ -8,6 +8,10 @@ const documentAnalysisWorkflow = flow<{ userDocument: string }>({
   debug: true, // Enable logging to see the flow execution
   autoParallel: true, // Enable automatic parallelization
 })
+  .description(
+    'Fluent Document Analysis',
+    'Summarizes a document, analyzes sentiment, and extracts key topics.'
+  )
   // Step 1: Summarize the document
   .node(
     'summarizer',
@@ -62,6 +66,10 @@ console.log(
 
 // Example of a simpler workflow for comparison
 const _simpleWorkflow = flow<{ rawInput: string }>()
+  .description(
+    'Simple Processor',
+    'Processes a rawInput value through a single node and returns the result.'
+  )
   .node('processor', 'userInput:string -> processedOutput:string')
   .execute('processor', (state) => ({ userInput: state.rawInput || 'default' }))
   .map((state) => ({
@@ -72,6 +80,10 @@ console.log('\nSimple workflow also created successfully!');
 
 // Example showing different node creation methods
 const _advancedWorkflow = flow<{ inputDocument: string }>()
+  .description(
+    'Advanced Text Analyzer',
+    'Analyzes text and returns a final analysis using multiple steps.'
+  )
   // Basic string signature
   .node('textAnalyzer', 'documentText:string -> analysisResult:string')
 
@@ -97,6 +109,10 @@ console.log('✅ Automatic parallelization and optimization');
 
 // Show how to extend workflows
 const _extendedWorkflow = flow<{ sourceData: string }>()
+  .description(
+    'Extended Workflow',
+    'Demonstrates chaining, execution, and mapping across multiple steps.'
+  )
   .node('step1', 'userInput:string -> intermediateResult:string')
   .execute('step1', (state) => ({ userInput: state.sourceData || 'test' }))
 

src/examples/gepa-flow.ts

@@ -2,6 +2,10 @@ import { AxAI, AxAIOpenAIModel, AxGEPAFlow, flow } from '@ax-llm/ax';
 
 // Two-objective flow: classify priority and produce a brief rationale
 const flowEmail = flow<{ emailText: string }>()
+  .description(
+    'Email Priority Classifier',
+    'Classifies an email priority and produces a concise rationale.'
+  )
   .n('classifier', 'emailText:string -> priority:class "high, normal, low"')
   .n(
     'rationale',