ai-core

Lightweight AI primitives for minimal footprint.

Need just the basics without all the extras? ai-core gives you the essential AI building blocks—no batch processing, no retry logic, no caching overhead. Just the primitives you need to ship.

``typescript
import { ai, list, is } from 'ai-core'

const ideas = liststartup ideas for ${industry}
const qualified = is${idea} worth pursuing?
const { summary, plan } = aianalyze: ${idea}
`

When to Use ai-core vs ai-functions

| Choose ai-core when... | Choose ai-functions when... |
|--------------------------|-------------------------------|
| Building serverless functions | Processing large batches |
| Bundle size matters | Need automatic retries |
| Simple AI interactions | Caching generations/embeddings |
| Prototyping quickly | Tool orchestration (agentic loops) |
| Edge deployments | Budget tracking |

ai-core is the foundation. ai-functions builds on top of it with production resilience patterns.

Installation

`bash
pnpm add ai-core
`

Or with npm/yarn:

`bash
npm install ai-core
yarn add ai-core
`

Basic Examples

$3

Destructure to get exactly what you need—schema is inferred automatically:

`typescript
import { ai } from 'ai-core'

// Simple text
const text = await aiwrite a tagline for ${product}

// Structured output via destructuring
const { summary, keyPoints, conclusion } = aianalyze this article: ${article}
console.log(await summary)
console.log(await keyPoints)
`

$3

Objects and arrays automatically convert to YAML for better LLM comprehension:

`typescript
import { ai } from 'ai-core'

const user = { name: 'Alice', role: 'developer', experience: 5 }
const feedback = aiperformance review for ${user}

// The user object becomes readable YAML in the prompt
`

$3

`typescript
import { list, lists } from 'ai-core'

// Single list
const ideas = await listblog post topics for ${audience}

// Multiple named lists via destructuring
const { pros, cons } = listspros and cons of ${decision}
const { mustHave, niceToHave } = listsfeature requirements for ${product}
`

$3

`typescript
import { is } from 'ai-core'

const isSpam = await is${email} is spam
const isUrgent = await is${ticket} requires immediate attention
const isQualified = await is${lead} matches our ideal customer profile
`

$3

Chain AI operations without awaiting each one—dependencies resolve automatically:

`typescript
import { ai, is, list } from 'ai-core'

// No await needed until the end
const { analysis, recommendation } = aianalyze ${data}
const isValid = is${recommendation} is actionable
const alternatives = listalternatives if ${recommendation} fails

// Only await when you need the actual values
if (await isValid) {
console.log(await recommendation)
} else {
console.log(await alternatives)
}
`

$3

For more control, use the underlying generate functions:

`typescript
import { generateText, generateObject } from 'ai-core'

// Text generation with model alias
const { text } = await generateText({
model: 'sonnet',
prompt: 'Explain quantum computing simply.',
})

// Structured object generation
const { object } = await generateObject({
model: 'sonnet',
schema: {
name: 'Recipe name',
ingredients: ['List of ingredients'],
steps: ['Cooking steps'],
},
prompt: 'Generate a pasta recipe.',
})
`

What's NOT Included

ai-core intentionally omits production patterns to stay lightweight. These features are available in ai-functions:

| Feature | Description | Package |
|---------|-------------|---------|
| Batch Processing | BatchQueue, .map() on lists | ai-functions |
| Retry & Resilience | RetryPolicy, CircuitBreaker, FallbackChain | ai-functions |
| Caching | MemoryCache, EmbeddingCache, GenerationCache | ai-functions |
| Budget Tracking | BudgetTracker, TokenCounter, cost limits | ai-functions |
| Tool Orchestration | AgenticLoop, ToolRouter, multi-step agents | ai-functions |
| Embeddings | Vector embeddings and similarity search | ai-functions |

Migration Path to ai-functions

When you need more power, upgrading is seamless—same API, more features:

`diff
- import { ai, list, is } from 'ai-core'
+ import { ai, list, is } from 'ai-functions'
`

Your existing code works unchanged. Then add the features you need:

`typescript
import { ai, list, withRetry, withCache, BatchQueue } from 'ai-functions'

// Add automatic retries
const result = await withRetry(() => aianalyze ${data}, {
maxRetries: 3,
backoff: 'exponential',
})

// Add caching
const cachedGenerate = withCache(
(prompt) => ai${prompt},
{ ttl: 3600 }
)

// Process batches efficiently
const items = await listitems from ${source}
const analyzed = await items.map(item => ({
item,
score: aiscore: ${item},
valid: is${item} is valid,
}))
`

API Reference

$3

| Function | Returns | Description |
|----------|---------|-------------|
| ai | AIPromise | Flexible generation with dynamic schema |
| write | AIPromise | Long-form text content |
| code | AIPromise | Code generation |
| list | AIPromise | List of items |
| lists | AIPromise> | Named lists via destructuring |
| extract | AIPromise | Structured data extraction |
| summarize | AIPromise | Content summarization |

$3

| Function | Returns | Description |
|----------|---------|-------------|
| is | AIPromise | Boolean classification |
| decide | AIPromise | LLM-as-judge comparison |

$3

| Function | Returns | Description |
|----------|---------|-------------|
| diagram | AIPromise | Mermaid diagrams |
| slides | AIPromise | Slidev/Marp presentations |
| image | AIPromise | Image generation |
| video | AIPromise | Video generation |

$3

| Function | Returns | Description |
|----------|---------|-------------|
| do | AIPromise<{ summary, actions }> | Task execution |
| research | AIPromise<{ summary, findings, sources }> | Web research |
| ask | AIPromise | Request human input |
| approve | AIPromise | Request approval |
| review | AIPromise | Request review |

Related Packages

- ai-functions — Full-featured AI primitives with batch, retry, cache
- ai-providers — Model provider abstraction and routing
- language-models` — Model definitions and aliases