Eval0

Ship faster with micro-AI in one line

Eval0 is a lightweight TypeScript SDK that provides instant AI-powered evaluations, validations, and transformations with just one line of code. Built on top of OpenAI's GPT models, it offers type-safe responses using Zod schemas.

Features

• 🚀 Simple API - One function for all your AI needs
• 🔒 Type-Safe - Built-in TypeScript support with Zod schemas
• 🌊 Concise Responses - Optimized for 1-5 word answers
• 🛠 Flexible Input - Multiple function signatures for convenience
• 📦 Zero Config - Works out of the box with sensible defaults

Installation

npm install eval0
# or
yarn add eval0
# or
pnpm add eval0

Quick Start

One-Liners ⚡️

Create a concise title for a chat message

import { eval0 } from 'eval0';

const { value: title } = await eval0('Concise title for this message:', 'Hello, how can I help you today?');
console.log(title); // "Hello, how can I help?"

Quick classifications (returns string)

const { value: sentiment } = await eval0('positive or negative?', 'I love it!');

console.log(sentiment); // "positive"

Fast summaries (returns string)

const content = 'The quick brown fox jumps over the lazy dog';
const { value: summary } = await eval0('Summarize in one word', content);

console.log(summary); // "agility"

Quick content moderation (returns boolean)

const { value: isSafe } = await eval0('Is this message safe for kids?', 'Let\'s play minecraft!');

console.log(isSafe); // "true"

Advanced Usage with Schemas 🔒

import { eval0 } from 'eval0';
import { z } from 'zod';

// Enum-based classification with confidence
const { value: analysis } = await eval0({
    query: 'Analyze sentiment',
    input: 'I love this product!',
    schema: z.object({
        sentiment: z.enum(['positive', 'negative', 'neutral']),
        confidence: z.number().min(0).max(1)
    }),
    temperature: 0.3
});

if (analysis.sentiment === 'positive' && analysis.confidence > 0.8) {
    console.log('High confidence positive feedback!');
}

Usage

Basic Usage

Eval0 provides three ways to call the function:

1. Full Options Object

const { value: response } = await eval0({
    query: 'Your question here',
    input: 'Optional input data',
    schema: z.string(), // Zod schema for type-safe responses
    temperature: 0.5,   // Optional: Control randomness
    maxTokens: 50      // Optional: Limit response length
});

2. Query with Options

const { value: quote } = await eval0('a motivational quote', {
    schema: z.object({
        quote: z.string(),
        author: z.string()
    })
});

console.log(`${quote.quote} - ${quote.author}`);

3. Query, Input, and Options

const { value: response } = await eval0(
    'Your question here',
    'Input data',
    { schema: z.boolean() }
);

Type-Safe Responses

Use Zod schemas to ensure type safety:

// Enum responses
const { value: sentiment } = await eval0({
    query: 'Analyze sentiment',
    input: 'I love this product!',
    schema: z.object({
        sentiment: z.enum(['positive', 'negative', 'neutral'])
    })
});

if (sentiment.sentiment === 'positive') {
    console.log('Positive feedback!');
}

// Complex validations
const { value: analysis } = await eval0({
    query: 'Analyze text complexity',
    input: 'Your text here',
    schema: z.object({
        complexity: z.number().min(0).max(10),
        reasons: z.array(z.string()),
        suggestion: z.string().optional()
    })
});

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | query | string | Required | The question or instruction | | input | unknown | Optional | Input data to analyze | | schema | z.ZodType | z.string() | Zod schema for response type | | model | string | 'gpt-4o-mini' | OpenAI model to use | | temperature | number | 0.3 | Response randomness (0-1) | | maxTokens | number | 100 | Maximum response length | | apiKey | string | From env | OpenAI API key |

Response Structure

interface Eval0Response<T> {
    value: T;              // The typed response value based on schema
    metadata: {
        model: string;     // OpenAI model used (e.g., 'gpt-4o-mini')
        tokens: number;    // Total tokens consumed
        latency: number;   // Response time in milliseconds
        ai_sdk: any;      // Raw AI SDK response data
    };
}

const { value } = await eval0<Eval0Response<string>>('positive or negative?', 'I love it!');
console.log(value);

Environment Variables

# Required: Your OpenAI API key
OPENAI_API_KEY=your_openai_api_key_here

Examples

Check out the examples directory for more usage examples.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Built with ❤️ using:

• OpenAI
• Vercel AI SDK
• Zod

Made with ☕️ by @shakee93

Troubleshooting

Common Issues

1. API Key Not Found

// Error: OpenAI API key is required
// Solution: Set your API key in .env file or pass it in options
const response = await eval0('query', {
    apiKey: 'your_openai_api_key'
});

2. Schema Type Mismatch

// Error: Type mismatch in response
// Solution: Ensure your schema matches expected response
const response = await eval0({
    query: 'Is this valid?',
    schema: z.boolean(), // Use correct schema type
});

3. Rate Limiting

// Error: Too many requests
// Solution: Add delay between requests or upgrade API plan
await new Promise(r => setTimeout(r, 1000)); // Add delay
const response = await eval0('query');

4. Response Too Long

// Error: Response exceeds maxTokens
// Solution: Increase maxTokens or modify prompt
const response = await eval0('query', {
    maxTokens: 200 // Increase token limit
});

Examples

Check out the examples directory for more usage examples.