ai-functions 0.3.0 → 0.4.0

package/.turbo/turbo-build.log

@@ -0,0 +1,5 @@
+
+
+> ai-functions@0.4.0 build /Users/nathanclevenger/projects/mdx.org.ai/primitives/packages/ai-functions
+> tsc -p tsconfig.json
+

package/.turbo/turbo-test.log

@@ -0,0 +1,105 @@
+
+> ai-functions@0.0.1 test /Users/nathanclevenger/projects/mdx.org.ai/primitives/packages/ai-functions
+> vitest
+
+[dotenv@17.2.3] injecting env (2) from ../../../.env -- tip: 📡 add observability to secrets: https://dotenvx.com/ops
+
+ DEV  v2.1.9 /Users/nathanclevenger/projects/mdx.org.ai/primitives/packages/ai-functions
+
+ ✓ test/core-functions.test.ts (38 tests) 11ms
+ ✓ test/function-types.test.ts (35 tests) 4ms
+ ✓ test/browse-read.test.ts (31 tests) 5ms
+ ✓ test/batch-background.test.ts (20 tests) 2ms
+ ✓ test/decide.test.ts (15 tests) 2ms
+ ✓ test/async-iterators.test.ts (13 tests) 336ms
+ ✓ test/generate-core.test.ts (18 tests) 2ms
+ ✓ test/tagged-templates.test.ts (19 tests) 3ms
+ ✓ test/define.test.ts (18 tests) 955ms
+   ✓ generative function execution > executes a generative string function 456ms
+ ✓ test/embeddings.test.ts (24 tests | 2 skipped) 36ms
+ ✓ test/ai-proxy.test.ts (14 tests) 1585ms
+   ✓ ai proxy auto-define > uses cached definition on second call 524ms
+   ✓ AI() schema functions > generates nested objects 339ms
+ ✓ test/generate.test.ts (9 tests) 1702ms
+   ✓ generateText > generates simple text response 323ms
+ ✓ test/schema.test.ts (12 tests) 2ms
+
+ Test Files  13 passed (13)
+      Tests  264 passed | 2 skipped (266)
+   Start at  14:14:37
+   Duration  5.46s (transform 171ms, setup 0ms, collect 351ms, tests 4.65s, environment 0ms, prepare 84ms)
+
+ PASS  Waiting for file changes...
+       press h to show help, press q to quit
+c RERUN  ../language-models/dist/aliases.js 
+
+ ✓ test/generate.test.ts (9 tests) 1916ms
+   ✓ generateObject > generates a simple object with string fields 622ms
+ ✓ test/ai-proxy.test.ts (14 tests) 1361ms
+   ✓ ai proxy auto-define > uses cached definition on second call 540ms
+ ✓ test/define.test.ts (18 tests) 349ms
+ ✓ test/embeddings.test.ts (24 tests | 2 skipped) 32ms
+ ✓ test/schema.test.ts (12 tests) 1ms
+
+ Test Files  5 passed (5)
+      Tests  75 passed | 2 skipped (77)
+   Start at  14:22:55
+   Duration  3.99s
+
+ PASS  Waiting for file changes...
+       press h to show help, press q to quit
+c RERUN  ../language-models/dist/aliases.js 
+
+ ✓ test/generate.test.ts (9 tests) 948ms
+ ✓ test/ai-proxy.test.ts (14 tests) 610ms
+ ✓ test/define.test.ts (18 tests) 289ms
+ ✓ test/embeddings.test.ts (24 tests | 2 skipped) 30ms
+ ✓ test/schema.test.ts (12 tests) 1ms
+
+ Test Files  5 passed (5)
+      Tests  75 passed | 2 skipped (77)
+   Start at  14:31:30
+   Duration  2.00s
+
+ PASS  Waiting for file changes...
+       press h to show help, press q to quit
+c RERUN  src/index.ts 
+
+ ✓ test/generate.test.ts (9 tests) 2001ms
+   ✓ generateObject > generates a simple object with string fields 481ms
+ ✓ test/ai-proxy.test.ts (14 tests) 1395ms
+   ✓ ai proxy auto-define > auto-defines a function on first call 320ms
+   ✓ ai proxy auto-define > uses cached definition on second call 541ms
+ ✓ test/define.test.ts (18 tests) 844ms
+ ✓ test/embeddings.test.ts (24 tests | 2 skipped) 47ms
+ ✓ test/schema.test.ts (12 tests) 1ms
+
+ Test Files  5 passed (5)
+      Tests  75 passed | 2 skipped (77)
+   Start at  01:20:37
+   Duration  4.50s
+
+ PASS  Waiting for file changes...
+       press h to show help, press q to quit
+c RERUN  test/implicit-batch.test.ts 
+
+ ✓ test/batch-blog-posts.test.ts (15 tests) 411ms
+ ✓ test/implicit-batch.test.ts (26 tests) 4ms
+ ✓ test/generate.test.ts (9 tests) 1676ms
+   ✓ generateObject > generates a simple object with string fields 498ms
+ ✓ test/ai-proxy.test.ts (14 tests) 1328ms
+   ✓ ai proxy auto-define > auto-defines a function on first call 380ms
+   ✓ ai proxy auto-define > uses cached definition on second call 525ms
+ ✓ test/define.test.ts (18 tests) 869ms
+   ✓ generative function execution > executes a generative string function 315ms
+ ✓ test/embeddings.test.ts (24 tests | 2 skipped) 36ms
+ ✓ test/schema.test.ts (12 tests) 1ms
+
+ Test Files  7 passed (7)
+      Tests  116 passed | 2 skipped (118)
+   Start at  03:35:28
+   Duration  4.48s
+
+ PASS  Waiting for file changes...
+       press h to show help, press q to quit
+ ELIFECYCLE  Test failed. See above for more details.

package/README.md

@@ -1,18 +1,15 @@
 # ai-functions
 
-[![npm version](https://badge.fury.io/js/ai-functions.svg)](https://www.npmjs.com/package/ai-functions)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+Call AI like you'd talk to a colleague. No prompts. No configuration. Just say what you need.
 
-A powerful TypeScript library for building AI-powered applications with template literals and structured outputs. Uses `ai` SDK with OpenAI `gpt-4o` by default.
-
-## Features
+```typescript
+import { ai, list, is } from 'ai-functions'
 
-- 🚀 Template literal API for natural AI prompts
-- 🔄 Async iterator support for streaming responses
-- 📝 Structured output generation with Zod schemas
-- 🎯 Type-safe API with full TypeScript support
-- ⚡️ Built on `ai` SDK for streaming & object generation
-- 🔍 Support for various output formats (objects, arrays, enums)
+// Ask for anything - it reads like English
+const qualified = is`${lead} a good fit for our enterprise plan?`
+const ideas = list`blog posts that would resonate with ${persona}`
+const { summary, nextSteps } = ai`analyze this sales call: ${transcript}`
+```
 
 ## Installation
 
@@ -20,131 +17,238 @@ A powerful TypeScript library for building AI-powered applications with template
 pnpm add ai-functions
 ```
 
-## Usage
+## The Magic: Promise Pipelining
 
-### Basic Template Literals
+Chain operations naturally—no `await` needed until you actually need the result:
 
 ```typescript
-import { ai, list } from 'ai-functions'
+// Destructure to get exactly what you need
+const { qualified, score, reason } = ai`qualify this lead: ${lead}`
+
+// Chain functions together—dependencies resolve automatically
+const followUp = ai`write follow-up email based on: ${reason}`
+const subject = ai`subject line for: ${followUp}`
+
+// Only await when you need the actual value
+if (await qualified) {
+  await sendEmail({ to: lead.email, subject: await subject, body: await followUp })
+}
+```
 
-// Simple text generation
-const text = ai`write a blog post in markdown starting with '# ${title}'`
+## Real-World Examples
 
-// Complex objects/arrays dumped to YAML
-const summary = ai`Summarize the itinerary: ${itinerary}`
+### Lead Qualification
 
-// Basic list generation
-const things = await list`fun things to do in Miami`
-console.log(things)
+```typescript
+const { score, qualified, reasoning } = ai`
+  qualify ${lead} for our product
+  considering: ${idealCustomerProfile}
+`
 
-// Using async iterator
-for await (const thing of list`fun things to do in Miami`) {
-  console.log(thing)
+if (await qualified) {
+  await assignToSales(lead)
 }
+```
 
-// Structured output
-const categorizeProduct = ai.categorizeProduct({
-  productType: 'App | API | Marketplace | Platform | Packaged Service | Professional Service | Website',
-  customer: 'ideal customer profile in 3-5 words',
-  solution: 'describe the offer in 4-10 words',
-  description: 'website meta description',
-})
+### Content Marketing
 
-const product = await categorizeProduct({ domain: name })
+```typescript
+// Generate topic ideas for your audience
+const topics = list`content ideas for ${persona} in ${industry}`
+
+// Evaluate each in parallel—single LLM call!
+const evaluated = await topics.map(topic => ({
+  topic,
+  potential: is`${topic} would drive signups?`,
+  difficulty: ai`content difficulty for: ${topic}`,
+}))
+
+// Pick the best
+const winner = evaluated.find(t => t.potential && t.difficulty === 'easy')
 ```
 
-### Configuration
+### Sales Intelligence
 
-#### Specifying the model
+```typescript
+const { pros, cons, objections } = lists`
+  competitive analysis: ${ourProduct} vs ${competitor}
+`
+
+const battleCard = ai`
+  sales battlecard addressing: ${objections}
+  highlighting: ${pros}
+`
+```
 
-By default `ai-functions` uses the `openai` provider from the `ai` SDK. You can specify any openai model name as a string.
+### Customer Success
 
 ```typescript
-const text = ai`write a blog post in markdown starting with "# ${title}"`({ model: 'gpt-4o' })
+// Analyze customer health
+const { healthy, churnRisk, opportunities } = ai`
+  analyze customer health for ${customer}
+  based on: ${usageData}
+`
+
+if (await churnRisk) {
+  const outreach = ai`retention outreach for ${customer} addressing ${churnRisk}`
+  await scheduleCall(customer, await outreach)
+}
 ```
 
-Or you can pass in any other provider compatible with the `ai` SDK.
+### Recruiting
 
 ```typescript
-import { anthropic } from '@ai-sdk/anthropic'
+const candidates = list`source ${role} candidates from ${jobBoards}`
+
+const evaluated = await candidates.map(candidate => ({
+  candidate,
+  fit: is`${candidate} matches ${requirements}?`,
+  summary: ai`one-line summary of ${candidate}`,
+}))
 
-const text = ai`write a function in TypeScript called ${name}`({ model: anthropic('claude-3-5-sonnet-20241022') })
+const shortlist = evaluated.filter(c => c.fit)
 ```
 
-#### Specifying other options
+## API Reference
 
-You can pass in any other options supported by the `ai` SDK, like `system`, `temperature`, `maxTokens`, etc.
+### Generation
 
 ```typescript
-const things = await list`fun things to do in ${city}`({ system: 'You are an expert tour guide', temperature: 0.2 })
+ai`anything you need`              // flexible object/text
+write`blog post about ${topic}`    // long-form content
+summarize`${document}`             // condense to key points
+list`ideas for ${topic}`           // array of items
+lists`pros and cons of ${topic}`   // named lists
+extract`emails from ${text}`       // structured extraction
 ```
 
-### Composable Functions & Workflows
+### Classification
 
 ```typescript
-const listBlogPosts = (count, topic) => list`${count} blog post titles about ${topic}`
-const writeBlogPost = (title) => ai`write a blog post in markdown starting with '# ${title}'`
+is`${email} spam?`                           // boolean
+decide`which converts better?`(optionA, optionB)  // pick best
+```
 
-async function* writeBlog(count, topic) {
-  for await (const title of listBlogPosts(count, topic)) {
-    const content = await writeBlogPost(title)
-    yield { title, content }
-  }
-}
+### Code & Visuals
 
-for await (const post of writeBlog(25, 'future of car sales')) {
-  console.log({ post })
-}
+```typescript
+code`email validation function`    // generate code
+diagram`user flow for ${feature}`  // mermaid diagrams
+slides`pitch deck for ${startup}`  // presentations
+image`hero image for ${brand}`     // image generation
+```
+
+### Research & Web
+
+```typescript
+research`${competitor} market position`  // web research
+read`${url}`                              // url to markdown
+browse`${url}`                            // browser automation
+```
+
+### Human-in-the-Loop
+
+```typescript
+ask`what's the priority for ${feature}?`   // free-form input
+approve`deploy ${version} to production?`  // yes/no approval
+review`${document}`                        // detailed feedback
 ```
 
-### Concurrency
+## The `lists` Function
 
-you can specify the `concurrency` option to limit the number of concurrent requests.
+Get exactly what you ask for through destructuring:
 
 ```typescript
-activities.map(async (activity) => {
-  const result = await ai`write a paragraph overview of ${activity}`({ concurrency: 5 })
-})
+// Just name what you want—the schema is inferred!
+const { pros, cons } = lists`pros and cons of ${decision}`
+const { strengths, weaknesses, opportunities, threats } = lists`SWOT for ${company}`
+const { mustHave, niceToHave, outOfScope } = lists`requirements for ${feature}`
 ```
 
-## Development
+## Batch Processing with `.map()`
 
-```bash
-# Install dependencies
-pnpm install
+Process arrays in a single LLM call:
 
-# Run tests
-pnpm test
+```typescript
+const leads = await list`leads from ${campaign}`
+
+// Each field evaluated for each lead—all in ONE call
+const qualified = await leads.map(lead => ({
+  lead,
+  score: ai`score 1-100: ${lead}`,
+  qualified: is`${lead} matches ${icp}?`,
+  nextStep: ai`recommended action for ${lead}`,
+}))
+
+// Filter and act
+qualified
+  .filter(l => l.qualified)
+  .forEach(l => createTask(l.nextStep))
+```
 
-# Run tests in watch mode
-pnpm test:watch
+## Typed Schemas with `AI()`
 
-# Build the package
-pnpm build
+For reusable, typed functions:
 
-# Lint the code
-pnpm lint
+```typescript
+const ai = AI({
+  qualifyLead: {
+    score: 'Lead score 1-100 (number)',
+    qualified: 'Whether to pursue (boolean)',
+    reasoning: 'Explanation of score',
+    nextSteps: ['Recommended actions'],
+  },
+
+  analyzeCompetitor: {
+    positioning: 'How they position themselves',
+    strengths: ['Their advantages'],
+    weaknesses: ['Their disadvantages'],
+    battleCard: 'Key talking points for sales',
+  },
+})
 
-# Format the code
-pnpm format
+// Fully typed!
+const result = await ai.qualifyLead('Enterprise CTO interested in AI automation')
+result.score      // number
+result.qualified  // boolean
+result.nextSteps  // string[]
 ```
 
-## Contributing
+## Schema Syntax
+
+| Syntax | Type | Example |
+|--------|------|---------|
+| `'description'` | string | `name: 'Company name'` |
+| `'desc (number)'` | number | `score: 'Score 1-100 (number)'` |
+| `'desc (boolean)'` | boolean | `qualified: 'Pursue? (boolean)'` |
+| `'opt1 \| opt2'` | enum | `priority: 'high \| medium \| low'` |
+| `['description']` | array | `steps: ['Action items']` |
+| `{ nested }` | object | `contact: { name, email }` |
+
+## Philosophy
 
-Please read our [Contributing Guide](./CONTRIBUTING.md) to learn about our development process and how to propose bugfixes and improvements.
+**Code should read like conversation.**
 
-## License
+Compare:
+```typescript
+// Traditional AI code
+const response = await openai.chat.completions.create({
+  model: "gpt-4",
+  messages: [{ role: "user", content: `Analyze this lead: ${JSON.stringify(lead)}` }],
+  response_format: { type: "json_object" },
+})
+const result = JSON.parse(response.choices[0].message.content)
+```
 
-MIT © [Drivly](https://driv.ly)
+```typescript
+// ai-functions
+const { qualified, score, nextStep } = ai`analyze lead: ${lead}`
+```
 
-## Dependencies
+The second version is what you'd say to a colleague. That's the goal.
 
-This package uses the following key dependencies:
+## Related Packages
 
-- `ai` SDK for AI model integration
-- Defaults to `@ai-sdk/openai` provider
-- TypeScript for static typing
-- Zod for schema validation
-- Vitest for testing
-- ESLint for linting
-- Prettier for code formatting
+- [`ai-database`](../ai-database) — AI-powered database operations
+- [`ai-providers`](../ai-providers) — Model provider abstraction
+- [`language-models`](../language-models) — Model definitions

package/TODO.md

@@ -0,0 +1,138 @@
+# ai-functions TODO
+
+Changes from README that need implementation in tests/code.
+
+## Function Types System
+
+- [ ] Implement 4 function types: `Generative`, `Code`, `Agentic`, `Human`
+- [ ] Type inference from function name + argument names + argument values
+- [ ] Subjective judgment (e.g., `processRefund({ amount: 12.99 })` vs `amount: 50000`)
+
+## Core Architecture
+
+- [ ] `generate(type, prompt, opts?)` as the core primitive
+  - [ ] Types: `json`, `text`, `code`, `list`, `extract`, `summary`, `diagram`, `slides`, `markdown`, `yaml`, `xml`
+  - [ ] Schema support for `json` type
+  - [ ] All other functions call `generate` under the hood
+- [ ] `define(name, schema)` - foundation function
+  - [ ] Infers function type from name + args
+  - [ ] Creates appropriate function (Generative, Code, Agentic, Human)
+  - [ ] Caches definition for subsequent calls
+- [ ] `AI({ schemas })` factory for typed instances
+
+## Tagged Template Support
+
+- [ ] Every function supports tagged template syntax
+- [ ] Objects/arrays in templates auto-stringify to YAML
+- [ ] Template + options chaining: ``fn`prompt`({ model: '...' })``
+
+## Standalone Exports
+
+All functions exported directly (not just on `ai` object):
+
+- [ ] `ai` - text generation
+- [ ] `summarize` - condense text
+- [ ] `do` - single-pass task executor with tools (not agentic loop)
+- [ ] `is` - boolean classification
+- [ ] `list` - generate list
+- [ ] `lists` - multiple named lists
+- [ ] `extract` - extract from text
+- [ ] `write` - generate content
+- [ ] `generate` - core primitive
+- [ ] `decide` - LLM as judge, picks from options
+- [ ] `code` - generate code
+- [ ] `diagram` - generate diagrams (mermaid, etc.)
+- [ ] `slides` - generate presentations (slidev, marp, reveal.js)
+- [ ] `image` - generate images
+- [ ] `video` - generate videos
+- [ ] `research` - agentic research
+- [ ] `read` - URL to markdown (Firecrawl)
+- [ ] `browse` - browser automation (Stagehand/Browserbase)
+  - [ ] `page.extract` - extract data from page
+  - [ ] `page.do` - perform action on page
+
+## Magic Proxy (`ai.*`)
+
+- [ ] `ai.anyFunctionName(args)` auto-defines on first call
+- [ ] Infers function type from name + args
+- [ ] Examples:
+  - [ ] `ai.fizzBuzz()` → CodeFunction
+  - [ ] `ai.storyBrand()` → GenerativeFunction with schema
+  - [ ] `ai.launchProductHunt()` → AgenticFunction
+  - [ ] `ai.approveExpense()` → HumanFunction
+
+## Human Functions
+
+- [ ] `ask` - ask human a question
+- [ ] `approve` - request human approval
+- [ ] `review` - request human review
+- [ ] Integration with `human-in-the-loop`, `digital-workers`, `autonomous-agents` packages
+
+## Async Iterators
+
+- [ ] `list` returns `AsyncIterable` for streaming
+- [ ] `extract` returns `AsyncIterable` for streaming
+- [ ] `for await (const item of list`...`)` pattern
+- [ ] Early termination with `break`
+
+## `decide` - LLM as Judge
+
+- [ ] Syntax: ``decide`criteria`(optionA, optionB, ...)``
+- [ ] Returns the winning option (same type as inputs)
+- [ ] Type-safe: passing `Product` objects returns `Product`
+
+## Options Parameter
+
+Every function accepts options as last parameter:
+
+- [ ] `model` - model selection
+- [ ] `thinking` - `'low' | 'medium' | 'high' | number` (token budget)
+- [ ] `temperature`
+- [ ] `maxTokens`
+
+## Batch & Background Processing
+
+- [ ] Background mode: `{ mode: 'background' }` returns job immediately
+  - [ ] `job.result()` to get result later
+  - [ ] `job.status` for status
+- [ ] Batch mode: `fn.batch([contexts])`
+  - [ ] Better pricing (50% off on OpenAI)
+  - [ ] Processes all at once
+- [ ] Batch streaming: `fn.batch.stream([contexts])`
+  - [ ] `for await` as results complete
+
+## Integration with Other Packages
+
+- [ ] `ai-sandbox` - `evaluate({ code, tests, module, script })` for CodeFunctions
+- [ ] `ai-database` - `embed` moved there, used by `db.search()`
+- [ ] `ai-providers` / `language-models` - model resolution
+- [ ] `human-in-the-loop` - Human function implementation
+- [ ] `autonomous-agents` - Agent loop (vs single-pass `do`)
+
+## Type System
+
+- [ ] `AIFunction<TArgs, TReturn>` - callable + tagged template
+- [ ] Schema syntax parsing:
+  - [ ] `'description'` → string
+  - [ ] `'desc (number)'` → number
+  - [ ] `'desc (boolean)'` → boolean
+  - [ ] `'opt1 | opt2'` → enum
+  - [ ] `['description']` → array
+  - [ ] `{ nested }` → object
+- [ ] Type inference for `AI()` factory schemas
+
+## Tests to Write
+
+- [ ] Tagged template parsing and YAML conversion
+- [ ] Each function type (Generative, Code, Agentic, Human)
+- [ ] Function type inference from name + args
+- [ ] `generate` with all type options
+- [ ] `define` creating correct function types
+- [ ] Magic proxy auto-definition
+- [ ] Async iterators on `list` and `extract`
+- [ ] `decide` returning correct option
+- [ ] Batch and background modes
+- [ ] Options parameter (model, thinking, etc.)
+- [ ] `browse` with `page.extract` and `page.do`
+- [ ] `read` URL fetching
+- [ ] `research` agentic flow