chore: better example

Author: grabbou

example/README.md

@@ -0,0 +1,19 @@
+# Examples
+
+This directory contains examples of using flows-ai in practice.
+
+## Prerequisites
+
+These examples use OpenAI and FireCrawl APIs. You need to have the following environment variables set:
+- `OPENAI_API_KEY` - Your OpenAI API key
+- `FIRECRAWL_API_KEY` - Your FireCrawl API key for GitHub and NPM data access
+
+## Structure
+
+- `flows.ts` - All flows are defined here
+- `agents.ts` - All agents are defined here
+
+## Running the examples
+
+- `bun run-organization-analysis.ts callstackincubator` - Analyzing an entire GitHub organization
+- `bun run-project-analysis.ts facebook/react-native` - Analyzing a single GitHub project

example/agents.ts

@@ -0,0 +1,36 @@
+import { createAISDKTools } from '@agentic/ai-sdk'
+import { FirecrawlClient } from '@agentic/firecrawl'
+import { openai } from '@ai-sdk/openai'
+import { agent } from 'flows-ai'
+
+const firecrawl = new FirecrawlClient()
+
+export const githubAgent = agent({
+  model: openai('gpt-4o'),
+  system: `
+    You are a Github analysis agent.
+    You can access Github repositories and extract meaningful insights about projects.
+    Focus on providing clear, structured data about repositories, issues, and project health.
+  `,
+  tools: createAISDKTools(firecrawl),
+})
+
+export const npmAgent = agent({
+  model: openai('gpt-4o'),
+  system: `
+    You are an NPM registry analysis agent.
+    You can access NPM registry data and provide package statistics.
+    Focus on download counts and package popularity metrics.
+  `,
+  tools: createAISDKTools(firecrawl),
+})
+
+export const analysisAgent = agent({
+  model: openai('gpt-4o'),
+  system: `
+    You are a data analysis agent.
+    You combine and analyze data from multiple sources to create meaningful summaries.
+    Focus on identifying patterns, trends, and key insights.
+  `,
+  tools: createAISDKTools(firecrawl),
+})

example/flows.ts

@@ -0,0 +1,68 @@
+import { forEach, parallel, sequence } from 'flows-ai/flows'
+import { z } from 'zod'
+
+/**
+ * Flow for analyzing a single GitHub project's health
+ */
+export const githubProjectHealthAnalysisFlow = sequence([
+  {
+    agent: 'githubAgent',
+    name: 'getIssues',
+    input:
+      'Get top 10 open issues with most "thumbs down" reactions. Each issue should have a title and a URL.',
+  },
+  forEach({
+    item: z.object({
+      title: z.string().describe('The issue title'),
+      url: z.string().describe('The URL of the issue'),
+    }),
+    input: sequence([
+      {
+        agent: 'githubAgent',
+        input: 'Analyze the issue carefuly and extract the root cause',
+      },
+    ]),
+  }),
+  {
+    agent: 'githubAgent',
+    input: 'Extract common patterns (if any) amongst all open issues, based on provided summaries.',
+  },
+])
+
+/**
+ * Flow for analyzing an entire GitHub organization
+ */
+export const organizationAnalysisFlow = sequence([
+  {
+    agent: 'githubAgent',
+    input:
+      'Get the top 5 repositories by stars from this organization. Return array of objects with repository URL.',
+  },
+  forEach({
+    item: z.object({
+      url: z.string().describe('The repository URL'),
+    }),
+    input: sequence([
+      parallel([
+        {
+          agent: 'githubAgent',
+          input:
+            'Analyze open issues and provide a summary including: total count, most common labels, and top 3 most discussed issues.',
+        },
+        {
+          agent: 'npmAgent',
+          input: 'Get weekly download count for this package from NPM registry.',
+        },
+      ]),
+      {
+        agent: 'analysisAgent',
+        input: 'Create a summary combining GitHub stats and NPM data for this project.',
+      },
+    ]),
+  }),
+  {
+    agent: 'analysisAgent',
+    input:
+      'Create an organization-wide summary analyzing patterns and insights across all projects.',
+  },
+])

example/github.ts

@@ -0,0 +1,33 @@
+import { execute } from 'flows-ai'
+
+import { analysisAgent, githubAgent, npmAgent } from './agents'
+import { organizationAnalysisFlow } from './flows'
+
+const orgName = process.argv[2]
+
+if (!orgName) {
+  console.error(
+    'Please provide an organization name, e.g.: bun run-organization-analysis.ts callstackincubator'
+  )
+  process.exit(1)
+}
+
+/**
+ * Example of running an organization analysis
+ */
+const response = await execute(organizationAnalysisFlow, {
+  agents: {
+    githubAgent,
+    npmAgent,
+    analysisAgent,
+  },
+  input: orgName,
+  onFlowStart: (flow) => {
+    console.log('Executing', flow.agent.name)
+  },
+  onFlowFinish: (flow, response) => {
+    console.log('Flow finished', flow.agent.name, response)
+  },
+})
+
+console.log(response)

example/run-organization-analysis.ts

@@ -0,0 +1,28 @@
+import { execute } from 'flows-ai'
+
+import { githubAgent } from './agents'
+import { githubProjectHealthAnalysisFlow } from './flows'
+
+const projectName = process.argv[2]
+
+if (!projectName) {
+  console.error(
+    'Please provide a project name, e.g.: bun run-project-analysis.ts facebook/react-native'
+  )
+  process.exit(1)
+}
+
+/**
+ * Example of running a project health analysis
+ */
+const response = await execute(githubProjectHealthAnalysisFlow, {
+  agents: {
+    githubAgent,
+  },
+  input: projectName,
+  onFlowStart: (flow) => {
+    console.log('Executing', flow.agent.name)
+  },
+})
+
+console.log(response)

example/run-project-analysis.ts

@@ -44,6 +44,9 @@ export type FlowDefinition = {
    * or an array of objects (nested flow definitions).
    */
   input: FlowDefinition | FlowDefinition[] | string
+  /**
+   * Structured output for the flow.
+   */
   /**
    * Optional name of the flow.
    */