feat: readme

README.md

@@ -1 +1,79 @@
-# dead-simple-ai-agent
+# Dead Simple AI Agent
+
+A lightweight, functional, and composable framework for building AI agents that work together to solve complex tasks. Built with TypeScript and designed to be serverless-ready.
+
+## Why Another AI Agent Framework?
+
+Most existing AI agent frameworks are either too complex, heavily object-oriented, or tightly coupled to specific infrastructure. We wanted something different - a framework that embraces functional programming principles, remains stateless, and stays laser-focused on composability.
+
+The framework is designed around the idea that AI agents should be:
+- Easy to create and compose
+- Infrastructure-agnostic
+- Stateless by default
+- Minimal in dependencies
+- Focused on team collaboration
+
+## Core Concepts
+
+### Agents
+
+Agents are specialized workers with specific roles and capabilities. Each agent has:
+- A defined role
+- A clear description of capabilities
+- Optional tools they can use
+- A configured language model provider
+
+### Tools
+
+Tools extend agent capabilities by providing concrete actions they can perform. Tools are pure functions with:
+- A description
+- Typed parameters (using Zod)
+- An execute function
+
+### Workflows
+
+Workflows define how agents collaborate to achieve a goal. They specify:
+- Team members
+- Task description
+- Expected output
+- Optional configuration
+
+### Iteration
+
+The framework provides two main ways to orchestrate agent collaboration:
+
+#### Teamwork
+
+The `teamwork` function handles complete workflow execution from start to finish, managing the entire process automatically. It's perfect for simple use cases where you want to get results in a single call.
+
+```typescript
+// This will block until the workflow is complete
+const result = await teamwork(workflow)
+```
+
+#### Iterate
+
+The `iterate` function provides a stateless, step-by-step execution model. Each call returns the new state without maintaining any internal state.
+
+```typescript
+// Initialize, or get from storage
+const initialState = workflowState(workflow)
+
+// Iterate over the workflow
+const newState = await iterate(workflow, initialState)
+
+// Check status
+console.log(newState.status)
+```
+
+This approach offers several benefits:
+
+- **Pausable Execution**: Stop and resume workflow execution at any point
+- **State Persistence**: Save the state between iterations to your preferred storage
+- **Progress Monitoring**: Inspect the workflow state after each iteration
+- **Error Recovery**: Handle failures gracefully by retrying from the last successful state
+- **Custom Control Flow**: Implement your own execution patterns and recovery strategies
+
+This functional approach makes the framework particularly well-suited for building long-running workflows that are distributed across multiple servers in the cloud.
+
+

example/README.md

@@ -0,0 +1,15 @@
+Examples
+====
+
+Each example is a self-contained TypeScript file that can be run with Bun, or with `tsx`
+
+```bash
+$ bun run example/<example-name>.ts
+```
+
+or
+
+```bash
+$ tsx example/<example-name>.ts
+```
+

example/src/medical_survey.ts

@@ -0,0 +1,7 @@
+import { teamwork } from '@dead-simple-ai-agent/framework/teamwork'
+
+import { preVisitNoteWorkflow } from './medical_survey_stateless.js'
+
+const result = await teamwork(preVisitNoteWorkflow)
+
+console.log(result)

example/src/stepping_survey.ts → example/src/medical_survey_stateless.ts

@@ -1,6 +1,7 @@
 /**
  * Example borrowed from CrewAI.
  */
+
 import { agent } from '@dead-simple-ai-agent/framework/agent'
 import { iterate } from '@dead-simple-ai-agent/framework/teamwork'
 import { tool } from '@dead-simple-ai-agent/framework/tool'
@@ -10,7 +11,7 @@ import { tmpdir } from 'os'
 import { join } from 'path'
 import { z } from 'zod'
 
-import { lookupWikipedia } from './tools.js'
+import { lookupWikipedia } from '../tools.js'
 
 async function requestUserInput(prompt: string): Promise<string> {
   return new Promise((resolve) => {
@@ -20,7 +21,8 @@ async function requestUserInput(prompt: string): Promise<string> {
     })
   })
 }
-export const askPatient = tool({
+
+const askPatient = tool({
   description: 'Tool for asking patient a question',
   parameters: z.object({
     query: z.string().describe('The question to ask the patient'),
@@ -56,7 +58,7 @@ const reporter = agent({
   },
 })
 
-const preVisitNoteWorkflow = workflow({
+export const preVisitNoteWorkflow = workflow({
   members: [nurse, reporter],
   description: `
     Create a pre-visit note for a patient that is about to come for a visit.

example/src/surprise_trip.ts

@@ -1,11 +1,12 @@
 /**
  * Example borrowed from CrewAI.
  */
+
 import { agent } from '@dead-simple-ai-agent/framework/agent'
 import { teamwork } from '@dead-simple-ai-agent/framework/teamwork'
 import { workflow } from '@dead-simple-ai-agent/framework/workflow'
 
-import { lookupWikipedia } from './tools.js'
+import { lookupWikipedia } from '../tools.js'
 
 const personalizedActivityPlanner = agent({
   role: 'Activity Planner',