ai-functions 0.2.19 → 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,59 +1,254 @@
-# AI Functions
+# ai-functions
 
-Library for Developing and Managing AI Functions (including OpenAI GPT4 / GPT3.5)
+Call AI like you'd talk to a colleague. No prompts. No configuration. Just say what you need.
 
-Key Features:
+```typescript
+import { ai, list, is } from 'ai-functions'
 
-- Enables easy development of AI functions
+// 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}`
+```
 
-```javascript
-import { AI } from 'ai-functions'
+## Installation
 
-const { ai, gpt, list } = AI({ apiKey: OPENAI_API_KEY })
+```bash
+pnpm add ai-functions
 ```
 
-Then you can use magic `ai` functions:
+## The Magic: Promise Pipelining
 
-```javascript
-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',
-})
+Chain operations naturally—no `await` needed until you actually need the result:
 
-const product = await categorizeProduct({ domain: name })
-```
+```typescript
+// Destructure to get exactly what you need
+const { qualified, score, reason } = ai`qualify this lead: ${lead}`
 
-you can also use `list` tagged template as a convienence function:
+// Chain functions together—dependencies resolve automatically
+const followUp = ai`write follow-up email based on: ${reason}`
+const subject = ai`subject line for: ${followUp}`
 
-```javascript
-const things = await list`fun things to do in Miami`
-console.log(things)
+// Only await when you need the actual value
+if (await qualified) {
+  await sendEmail({ to: lead.email, subject: await subject, body: await followUp })
+}
 ```
 
-or with Async iterators:
+## Real-World Examples
 
-```javascript
-for await (const thing of list`fun things to do in Miami`) {
-  console.log(thing)
+### Lead Qualification
+
+```typescript
+const { score, qualified, reasoning } = ai`
+  qualify ${lead} for our product
+  considering: ${idealCustomerProfile}
+`
+
+if (await qualified) {
+  await assignToSales(lead)
 }
 ```
 
-Or in a more complex example:
+### Content Marketing
 
-```javascript
-const listBlogPosts = (count, topic) => list`${count} blog post titles about ${topic}`
-const writeBlogPost = (title) => gpt`write a blog post in markdown starting with "# ${title}"`
+```typescript
+// Generate topic ideas for your audience
+const topics = list`content ideas for ${persona} in ${industry}`
 
-async function* writeBlog(count, topic) {
-  for await (const title of listBlogPosts(count, topic)) {
-    const content = await writeBlogPost(title)
-    yield { title, content }
-  }
-}
+// 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')
+```
+
+### Sales Intelligence
+
+```typescript
+const { pros, cons, objections } = lists`
+  competitive analysis: ${ourProduct} vs ${competitor}
+`
+
+const battleCard = ai`
+  sales battlecard addressing: ${objections}
+  highlighting: ${pros}
+`
+```
+
+### Customer Success
 
-for await (const post of writeBlog(25, 'future of car sales')) {
-  console.log({ post })
+```typescript
+// 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)
 }
 ```
+
+### Recruiting
+
+```typescript
+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 shortlist = evaluated.filter(c => c.fit)
+```
+
+## API Reference
+
+### Generation
+
+```typescript
+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
+```
+
+### Classification
+
+```typescript
+is`${email} spam?`                           // boolean
+decide`which converts better?`(optionA, optionB)  // pick best
+```
+
+### Code & Visuals
+
+```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
+```
+
+## The `lists` Function
+
+Get exactly what you ask for through destructuring:
+
+```typescript
+// 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}`
+```
+
+## Batch Processing with `.map()`
+
+Process arrays in a single LLM call:
+
+```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))
+```
+
+## Typed Schemas with `AI()`
+
+For reusable, typed functions:
+
+```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',
+  },
+})
+
+// Fully typed!
+const result = await ai.qualifyLead('Enterprise CTO interested in AI automation')
+result.score      // number
+result.qualified  // boolean
+result.nextSteps  // string[]
+```
+
+## 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
+
+**Code should read like conversation.**
+
+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)
+```
+
+```typescript
+// ai-functions
+const { qualified, score, nextStep } = ai`analyze lead: ${lead}`
+```
+
+The second version is what you'd say to a colleague. That's the goal.
+
+## Related Packages
+
+- [`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