ai-props 0.1.2 → 2.0.2

package/README.md

@@ -1,9 +1,10 @@
 # ai-props
 
-[![npm version](https://badge.fury.io/js/ai-props.svg)](https://www.npmjs.com/package/ai-props)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+AI-powered props primitives for intelligent component properties.
 
-A React component package that provides an AI component for generating and spreading AI-generated props to child components.
+## Overview
+
+`ai-props` provides utilities for automatically generating component props using AI based on schema definitions. It's designed to work seamlessly with React components, Next.js, and other frameworks.
 
 ## Installation
 
@@ -11,412 +12,404 @@ A React component package that provides an AI component for generating and sprea
 npm install ai-props
 ```
 
-## Usage
-
-The `AI` component mirrors the `generateObject` function from the `ai` package and spreads the generated object's properties to its children.
-
-### Model Configuration
-
-The AI component supports both string-based OpenAI models and provider-specific model objects:
-
-```tsx
-// Simple string-based OpenAI model (recommended for OpenAI)
-<AI
-  model='gpt-4'
-  schema={schema}
-  prompt='Generate content'
-/>
-
-// Provider-specific model object (required for other providers)
-import { anthropic } from '@ai-sdk/anthropic'
-
-const model = anthropic('claude-2')
-<AI
-  model={model}
-  schema={schema}
-  prompt='Generate content'
-/>
-
-### Streaming Support
-
-The AI component supports real-time streaming of generated content, providing a more interactive user experience:
-
-```tsx
-<AI
-  model='gpt-4'
-  stream={true}
-  schema={{
-    title: 'string',
-    content: 'string'
-  }}
-  prompt='Generate an article about React'
->
-  {(props, { isStreaming }) => (
-    <article className={isStreaming ? 'animate-pulse' : ''}>
-      <h1>{props.title}</h1>
-      <div>{props.content}</div>
-      {isStreaming && (
-        <div className='text-gray-500'>Generating content...</div>
-      )}
-    </article>
-  )}
-</AI>
+## Quick Start
+
+```typescript
+import { AI, generateProps } from 'ai-props'
+
+// Define an AI-powered component schema
+const UserCard = AI({
+  schema: {
+    name: 'User name',
+    bio: 'User biography',
+    avatar: 'Avatar URL',
+  },
+  defaults: {
+    avatar: '/default-avatar.png',
+  },
+})
+
+// Generate props with AI
+const props = await UserCard({ name: 'John' })
+// { name: 'John', bio: 'AI-generated bio...', avatar: '/default-avatar.png' }
 ```
 
-When using streaming:
-- Set `stream={true}` to enable real-time updates
-- Access streaming status via `isStreaming` in render prop
-- UI updates automatically as content arrives
-- Maintain type safety with your schema
-- Reduced time to first content display
-
-### API Proxy Integration
-
-For enhanced security and control, you can route requests through your own API endpoint:
-
-```tsx
-<AI
-  model='gpt-4'
-  apiEndpoint='/api/generate'
-  headers={{
-    'Authorization': 'Bearer ${process.env.API_KEY}',
-    'X-Custom-Header': 'value'
-  }}
-  schema={schema}
-  prompt='Generate content'
-/>
+## Core Features
+
+### AI() Wrapper
+
+Create AI-powered component wrappers that automatically fill in missing props:
+
+```typescript
+import { AI } from 'ai-props'
+
+const ProductCard = AI({
+  schema: {
+    title: 'Product title',
+    description: 'Product description',
+    price: 'Price (number)',
+  },
+  required: ['price'],  // Required props won't be generated
+  exclude: ['internal'], // Exclude props from generation
+})
+
+// Use the component
+const props = await ProductCard({ price: 99 })
 ```
 
-Your API endpoint should:
-- Accept the same parameters as the AI provider
-- Return compatible streaming or non-streaming responses
-- Handle authentication and rate limiting
-- Implement proper error handling
+### generateProps()
 
-Benefits of using an API proxy:
-- Keep API keys secure on your server
-- Add custom request validation
-- Implement usage tracking
-- Control model access and costs
-- Add custom error handling
+Low-level function for direct prop generation:
 
-Example API endpoint implementation:
 ```typescript
-// pages/api/generate.ts
-import { OpenAIStream } from 'ai'
-
-export async function POST(req: Request) {
-  const { prompt, schema, stream } = await req.json()
-
-  const response = await fetch('https://api.openai.com/v1/chat/completions', {
-    method: 'POST',
-    headers: {
-      'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`,
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify({
-      model: 'gpt-4',
-      messages: [{ role: 'user', content: prompt }],
-      stream: stream,
-    }),
-  })
-
-  if (stream) {
-    const stream = OpenAIStream(response)
-    return new Response(stream)
-  }
+import { generateProps } from 'ai-props'
 
-  const json = await response.json()
-  return Response.json(json)
-}
+const result = await generateProps({
+  schema: {
+    title: 'SEO-optimized page title',
+    description: 'Meta description',
+    keywords: ['Relevant keywords'],
+  },
+  context: { topic: 'AI-powered applications' },
+})
+
+console.log(result.props)    // Generated props
+console.log(result.cached)   // Whether result came from cache
+console.log(result.metadata) // Model info, duration, etc.
 ```
 
-### Simplified Schema Interface
+### createAIComponent()
 
-You can define your schema using a simple object structure without importing Zod:
+Create typed AI components:
 
-```tsx
-import { AI } from 'ai-props'
+```typescript
+import { createAIComponent } from 'ai-props'
 
-function MyComponent() {
-  return (
-    <AI
-      schema={{
-        productType: 'App | API | Marketplace | Platform | Packaged Service | Professional Service | Website',
-        profile: {
-          customer: 'ideal customer profile in 3-5 words',
-          solution: 'describe the offer in 4-10 words'
-        },
-        description: 'website meta description',
-        tags: ['SEO-optimized meta tags']
-      }}
-      prompt='Generate product details'
-    >
-      {(props) => (
-        <article>
-          <h1>{props.productType}</h1>
-          <div>
-            <p>Customer: {props.profile.customer}</p>
-            <p>Solution: {props.profile.solution}</p>
-          </div>
-          <p>{props.description}</p>
-          <ul>
-            {props.tags.map((tag, i) => (
-              <li key={i}>{tag}</li>
-            ))}
-          </ul>
-        </article>
-      )}
-    </AI>
-  )
+interface ProductProps {
+  title: string
+  price: number
+  description: string
 }
+
+const ProductCard = createAIComponent<ProductProps>({
+  schema: {
+    title: 'Product title',
+    price: 'Price (number)',
+    description: 'Product description',
+  },
+})
+
+const props = await ProductCard({})
+// props is typed as ProductProps
 ```
 
-The simplified schema interface supports:
-- Pipe-separated strings (`'Option1 | Option2 | Option3'`) which are automatically converted to enums
-- Nested objects with type descriptions
-- Array types with description hints
+### createComponentFactory()
 
-### Direct Zod Schema Usage
+Create a factory for generating multiple instances:
 
-You can also use Zod schemas directly for more complex validation:
+```typescript
+import { createComponentFactory } from 'ai-props'
 
-```tsx
-import { AI } from 'ai-props'
-import { z } from 'zod'
+const factory = createComponentFactory({
+  schema: {
+    name: 'Product name',
+    price: 'Price (number)',
+  },
+})
+
+// Generate a single instance
+const product = await factory.generate({ category: 'electronics' })
+
+// Generate multiple instances
+const products = await factory.generateMany([
+  { category: 'electronics' },
+  { category: 'clothing' },
+])
+
+// Generate with overrides
+const custom = await factory.generateWith(
+  { category: 'tech' },
+  { price: 99 }
+)
+```
 
-// Define your schema
-const schema = z.object({
-  title: z.string(),
-  description: z.string()
+### composeAIComponents()
+
+Compose multiple schemas together:
+
+```typescript
+import { composeAIComponents } from 'ai-props'
+
+const FullProfile = composeAIComponents({
+  user: {
+    schema: { name: 'User name', bio: 'Biography' },
+  },
+  settings: {
+    schema: { theme: 'Theme preference', notifications: 'Notification pref' },
+  },
 })
 
-// Use the AI component
-function MyComponent() {
-  return (
-    <AI
-      schema={schema}
-      prompt='Generate a title and description for a blog post about React'
-    >
-      {(props) => (
-        <article>
-          <h1>{props.title}</h1>
-          <p>{props.description}</p>
-        </article>
-      )}
-    </AI>
-  )
-}
+const profile = await FullProfile({
+  user: { name: 'John' },
+  settings: {},
+})
 ```
 
-## Default Model Configuration
+## HOC Utilities
+
+### createPropsEnhancer()
 
-The AI component uses a default model configuration:
+Create a props enhancer for any component system:
 
 ```typescript
-import { openai } from '@ai-sdk/openai'
-const model = openai('gpt-4o')
+import { createPropsEnhancer } from 'ai-props'
+
+const enhancer = createPropsEnhancer({
+  schema: {
+    title: 'Page title',
+    description: 'Page description',
+  },
+  defaults: { title: 'Default Title' },
+})
+
+const props = await enhancer({ description: 'My page' })
 ```
 
-You can override this by providing your own model configuration through props.
-
-## Props
-
-The `AI` component accepts all props from the `generateObject` function:
-
-### Required Props
-- `schema`: A Zod schema or Schema object defining the structure of the generated object. Supports:
-  - Direct Zod schemas for complex validation
-  - Simplified object syntax without Zod imports
-  - Pipe-separated strings for automatic enum conversion (e.g., `'Option1 | Option2'`)
-- `prompt`: The prompt to send to the language model
-
-### Optional Props
-- `output`: Type of output ('object' | 'array' | 'enum' | 'no-schema')
-- `schemaName`: Optional name for the output schema
-- `schemaDescription`: Optional description for the output schema
-- `mode`: Generation mode ('auto' | 'json' | 'tool'), defaults to 'auto'
-- `model`: Override the default model
-- `experimental_telemetry`: Optional telemetry configuration
-- `experimental_providerMetadata`: Additional provider-specific metadata
-
-### Array Output Mode
-
-The `AI` component supports generating and rendering arrays of items using the `output='array'` prop. When using array output mode, you can also enable CSS Grid layout with the `cols` prop:
-
-```tsx
-<AI
-  schema={blogSchema}
-  prompt='Generate 6 blog post previews'
-  output='array'
-  cols={3}
-  gap='2rem'
-  className='grid-container'
-  itemClassName='grid-item'
->
-  {(props) => (
-    <article>{/* Item content */}</article>
-  )}
-</AI>
+### createAsyncPropsProvider()
+
+Create an async props provider for SSR:
+
+```typescript
+import { createAsyncPropsProvider } from 'ai-props'
+
+const getPageProps = createAsyncPropsProvider({
+  schema: {
+    title: 'SEO title',
+    meta: { description: 'Meta description' },
+  },
+})
+
+// In getStaticProps or getServerSideProps
+export async function getStaticProps() {
+  const props = await getPageProps.getProps({ slug: 'about' })
+  return { props }
+}
 ```
 
-#### Grid Support Props
-- `cols`: Number of columns in the grid (default: 3)
-- `gap`: Gap between grid items (CSS gap value)
-- `className`: Class applied to the grid container
-- `itemClassName`: Class applied to each grid item
+### createBatchGenerator()
+
+Generate props for multiple items efficiently:
 
-### Styling Support
+```typescript
+import { createBatchGenerator } from 'ai-props'
 
-The `AI` component integrates with `clsx` and `tailwind-merge` for flexible styling:
+const batch = createBatchGenerator({
+  schema: { title: 'Item title', description: 'Description' },
+  concurrency: 3,
+})
 
-```tsx
-<AI
-  className='max-w-7xl mx-auto px-4 py-16 grid-cols-1 md:grid-cols-2 lg:grid-cols-3'
-  itemClassName='bg-white p-6 rounded-lg shadow-md h-full flex flex-col'
->
-  {/* Component content */}
-</AI>
+const items = await batch.generate([
+  { id: 1, category: 'tech' },
+  { id: 2, category: 'science' },
+])
 ```
 
-Class names are merged using the `cn` utility, which combines `clsx` and `tailwind-merge` for conflict-free class composition.
+## Validation
 
-### Examples
+### validateProps()
 
-#### Hero Section Example
+Validate props against a schema:
 
-A waitlist landing page hero section for an AI-powered SaaS product:
+```typescript
+import { validateProps } from 'ai-props'
 
-```tsx
-import { AI } from 'ai-props'
+const result = validateProps(
+  { name: 'John', age: '25' },
+  { name: 'Name', age: 'Age (number)' }
+)
 
-const heroSchema = {
-  productType: 'App | API | Marketplace | Platform',
-  profile: {
-    customer: 'ideal customer profile in 3-5 words',
-    solution: 'describe the offer in 4-10 words'
-  },
-  description: 'website meta description',
-  tags: ['SEO-optimized meta tags'],
-  headline: 'compelling headline for AI SaaS product',
-  subheadline: 'engaging subheadline explaining value proposition',
-  ctaText: 'action-oriented button text',
-  benefits: ['3-5 key benefits'],
-  targetAudience: 'specific target audience description'
+if (!result.valid) {
+  console.log(result.errors)
+  // [{ path: 'age', message: 'Expected number, got string' }]
 }
+```
 
-export function HeroSection() {
-  return (
-    <AI<typeof heroSchema>
-      schema={heroSchema}
-      prompt='Generate a hero section for an AI-powered SaaS product waitlist landing page'
-      className='bg-gradient-to-br from-blue-50 to-indigo-50'
-    >
-      {(props) => (
-        <div className='max-w-6xl mx-auto px-4 py-16'>
-          <h1 className='text-5xl font-bold mb-4 bg-clip-text text-transparent bg-gradient-to-r from-blue-600 to-indigo-600'>
-            {props.headline}
-          </h1>
-          <p className='text-xl text-gray-600 mb-8'>{props.subheadline}</p>
-          <button className='bg-blue-600 text-white px-8 py-3 rounded-lg text-lg font-medium hover:bg-blue-700 transition-colors'>
-            {props.ctaText}
-          </button>
-          <div className='mt-12'>
-            <h2 className='text-2xl font-semibold mb-4'>Perfect for {props.targetAudience}</h2>
-            <ul className='grid grid-cols-1 md:grid-cols-2 gap-4'>
-              {props.benefits.map((benefit, index) => (
-                <li key={index} className='flex items-start bg-white p-4 rounded-lg shadow-sm'>
-                  <span className='text-blue-500 mr-2'>✓</span>
-                  {benefit}
-                </li>
-              ))}
-            </ul>
-          </div>
-        </div>
-      )}
-    </AI>
-  )
-}
+### assertValidProps()
 
-#### Blog List Example
+Assert props are valid (throws on error):
 
-A grid of blog post previews using array output mode:
+```typescript
+import { assertValidProps } from 'ai-props'
 
-```tsx
-import { AI } from 'ai-props'
+assertValidProps(
+  { name: 'John', age: 25 },
+  { name: 'Name', age: 'Age (number)' }
+)
+```
+
+### Other Validation Utilities
+
+```typescript
+import {
+  hasRequiredProps,
+  getMissingProps,
+  isComplete,
+  getMissingFromSchema,
+  sanitizeProps,
+  mergeWithDefaults,
+  createValidator,
+} from 'ai-props'
+
+// Check required props
+hasRequiredProps({ name: 'John' }, ['name', 'email']) // false
+
+// Get missing props
+getMissingProps({ name: 'John' }, ['name', 'email']) // ['email']
+
+// Check schema completion
+isComplete({ name: 'John' }, { name: 'Name', age: 'Age' }) // false
+
+// Sanitize extra props
+sanitizeProps({ name: 'John', extra: 'value' }, { name: 'Name' })
+// { name: 'John' }
+
+// Merge with defaults
+mergeWithDefaults({ name: 'John' }, { age: 0 }, { name: 'Name', age: 'Age' })
+// { name: 'John', age: 0 }
+
+// Create reusable validator
+const validate = createValidator({ name: 'Name', age: 'Age (number)' })
+validate({ name: 'John', age: 25 }) // { valid: true, errors: [] }
+```
+
+## Caching
+
+### Cache Configuration
+
+```typescript
+import { configureAIProps, configureCache, clearCache } from 'ai-props'
+
+// Configure global settings
+configureAIProps({
+  model: 'gpt-4',
+  cache: true,
+  cacheTTL: 5 * 60 * 1000, // 5 minutes
+})
+
+// Configure cache with custom TTL
+configureCache(10 * 60 * 1000) // 10 minutes
+
+// Clear all cached props
+clearCache()
+```
+
+### Cache Classes
+
+```typescript
+import { MemoryPropsCache, LRUPropsCache } from 'ai-props'
+
+// Simple memory cache
+const memCache = new MemoryPropsCache(5 * 60 * 1000)
+
+// LRU cache with max entries
+const lruCache = new LRUPropsCache(100, 5 * 60 * 1000)
+
+// Cache operations
+lruCache.set('key', { name: 'John' })
+const entry = lruCache.get<{ name: string }>('key')
+lruCache.delete('key')
+lruCache.clear()
+console.log(lruCache.size)
+```
+
+## Schema Type Hints
+
+Use type hints in schema strings:
 
-const blogSchema = {
-  productType: 'App | API | Marketplace | Platform',
-  profile: {
-    customer: 'ideal customer profile in 3-5 words',
-    solution: 'describe the offer in 4-10 words'
+```typescript
+const schema = {
+  name: 'User name',                    // string
+  age: 'User age (number)',             // number
+  count: 'Item count (integer)',        // integer
+  active: 'Is active (boolean)',        // boolean
+  tags: ['Tag names'],                  // array
+  status: 'pending | active | done',    // enum
+  profile: {                            // nested object
+    bio: 'User bio',
+    avatar: 'Avatar URL',
   },
-  description: 'website meta description',
-  tags: ['relevant topic tags'],
-  title: 'engaging blog post title',
-  excerpt: 'compelling 2-3 sentence excerpt',
-  readTime: 'estimated read time',
-  category: 'Blog | Tutorial | Case Study | News'
 }
+```
 
-export function BlogList() {
-  return (
-    <AI<typeof blogSchema>
-      schema={blogSchema}
-      prompt='Generate 6 blog post previews about AI and machine learning'
-      output='array'
-      cols={3}
-      gap='2rem'
-      className='max-w-7xl mx-auto px-4 py-16 grid-cols-1 md:grid-cols-2 lg:grid-cols-3'
-      itemClassName='h-full'
-    >
-      {(props) => (
-        <article className='bg-white p-6 rounded-lg shadow-md h-full flex flex-col'>
-          <div className='text-sm text-gray-500 mb-2 flex items-center justify-between'>
-            <span>{props.category}</span>
-            <span>{props.readTime}</span>
-          </div>
-          <h2 className='text-xl font-semibold mb-3'>{props.title}</h2>
-          <p className='text-gray-600 mb-4 flex-grow'>{props.excerpt}</p>
-          <div className='flex flex-wrap gap-2 mt-auto'>
-            {props.tags.map((tag, index) => (
-              <span key={index} className='bg-gray-100 text-gray-600 px-3 py-1 rounded-full text-sm'>
-                {tag}
-              </span>
-            ))}
-          </div>
-        </article>
-      )}
-    </AI>
-  )
-}
+## Configuration
 
-## Development
+```typescript
+import { configureAIProps, getConfig, resetConfig } from 'ai-props'
+
+// Configure globally
+configureAIProps({
+  model: 'sonnet',           // Default model
+  cache: true,               // Enable caching
+  cacheTTL: 300000,          // Cache TTL in ms
+  system: 'Custom prompt',   // System prompt
+  generate: async (schema, context) => {
+    // Custom generator
+    return { /* generated props */ }
+  },
+})
 
-This package uses:
-- Vite for building
-- Vitest for testing
-- React Cosmos for component development and testing
+// Get current config
+const config = getConfig()
 
-## Dependencies
+// Reset to defaults
+resetConfig()
+```
 
-This package requires the following peer dependencies:
-- `react` (^18.2.0)
-- `react-dom` (^18.2.0)
-- `@types/react` (^18.2.0)
-- `@types/react-dom` (^18.2.0)
+## API Reference
 
-And the following runtime dependencies:
-- `ai` (^4.0.18)
-- `@ai-sdk/openai` (^1.0.8)
-- `clsx` (^2.1.1)
-- `tailwind-merge` (^2.5.5)
-- `zod` (^3.22.4)
+### Types
 
-Make sure to install these dependencies if they're not already in your project:
+```typescript
+interface PropSchema {
+  [key: string]: string | string[] | PropSchema
+}
 
-```bash
-npm install ai @ai-sdk/openai clsx tailwind-merge zod
+interface GeneratePropsOptions {
+  schema: PropSchema
+  context?: Record<string, unknown>
+  prompt?: string
+  model?: string
+  system?: string
+}
+
+interface GeneratePropsResult<T> {
+  props: T
+  cached: boolean
+  metadata: {
+    model: string
+    duration?: number
+  }
+}
+
+interface AIComponentOptions<P> {
+  schema: PropSchema
+  defaults?: Partial<P>
+  required?: (keyof P)[]
+  exclude?: (keyof P)[]
+  config?: AIPropsConfig
+}
+
+interface ValidationResult {
+  valid: boolean
+  errors: ValidationError[]
+}
+
+interface ValidationError {
+  path: string
+  message: string
+  expected?: string
+  received?: unknown
+}
 ```
 
 ## License