@ranavibe/helpers

Quick LLM Helpers - One-line AI functions for common tasks.

Installation

npm install @ranavibe/helpers

Quick Start

import {
  summarize,
  translate,
  classify,
  extract,
  sentiment,
  answer,
  rewrite,
  generate,
  compare,
  moderate
} from '@ranavibe/helpers';

// Summarize any text
const summary = await summarize(longArticle);
console.log(summary.summary);

// Translate to any language
const spanish = await translate('Hello, world!', { to: 'es' });
console.log(spanish.translation); // "¡Hola, mundo!"

// Classify into categories
const category = await classify(email, ['spam', 'important', 'newsletter']);
console.log(category.label); // "important"

// Extract structured data
const data = await extract(
  'Contact John at [email protected]',
  { name: 'string', email: 'string' }
);
console.log(data.data); // { name: 'John', email: '[email protected]' }

Features

• 10 Core Functions: summarize, translate, classify, extract, sentiment, answer, rewrite, generate, compare, moderate
• Automatic Caching: 60%+ cache hit rate for repeated queries
• Cost Optimized: Uses the cheapest appropriate model (<$0.01/call average)
• Multi-Provider: Works with OpenAI, Anthropic, Google, Groq, and more
• Type Safe: Full TypeScript support with detailed types

API Reference

summarize(text, options?)

Summarize text into a shorter version.

const result = await summarize(longText, {
  length: 'short' | 'medium' | 'long',
  style: 'bullet' | 'paragraph' | 'tweet',
  maxWords: 100,
  focus: 'key points'
});

// Returns:
{
  summary: string;
  wordCount: number;
  compressionRatio: number;
  cached: boolean;
  cost: number;
  latencyMs: number;
}

translate(text, options)

Translate text to another language.

const result = await translate('Hello', {
  to: 'es',        // Required: target language code
  from: 'en',      // Optional: source language (auto-detected)
  formal: true,    // Use formal register
});

// Returns:
{
  translation: string;
  sourceLanguage: string;
  targetLanguage: string;
  confidence: number;
  cached: boolean;
  cost: number;
  latencyMs: number;
}

classify(text, categories, options?)

Classify text into one or more categories.

const result = await classify(
  'This is spam!',
  ['spam', 'ham', 'urgent'],
  {
    multiLabel: false,  // Single or multiple labels
    threshold: 0.5,     // Confidence threshold
    explain: true       // Include explanation
  }
);

// Returns:
{
  label: string;
  labels?: string[];
  confidence: number;
  confidences?: Record<string, number>;
  explanation?: string;
  cached: boolean;
  cost: number;
  latencyMs: number;
}

extract(text, schema, options?)

Extract structured data from text.

const result = await extract(
  'Invoice #123 from Acme Corp for $500',
  {
    invoiceNumber: 'string',
    company: 'string',
    amount: 'number'
  }
);

// Returns:
{
  data: {
    invoiceNumber: '123',
    company: 'Acme Corp',
    amount: 500
  },
  completeness: 1.0,
  cached: boolean,
  cost: number,
  latencyMs: number
}

sentiment(text, options?)

Analyze sentiment of text.

const result = await sentiment('I love this product!', {
  granular: true,  // Include emotions
  aspects: ['product', 'service']  // Aspect-based
});

// Returns:
{
  sentiment: 'positive' | 'negative' | 'neutral' | 'mixed';
  score: number;  // -1 to 1
  confidence: number;
  emotions?: Record<string, number>;
  aspects?: Record<string, { sentiment, score }>;
  cached: boolean;
  cost: number;
  latencyMs: number;
}

answer(question, options?)

Answer a question.

const result = await answer('What is the capital of France?', {
  context: 'France is a country in Europe...',
  sources: [doc1, doc2],
  citeSources: true
});

// Returns:
{
  answer: string;
  confidence: number;
  citations?: Array<{ text, source }>;
  cached: boolean;
  cost: number;
  latencyMs: number;
}

rewrite(text, options?)

Rewrite text with a different style.

const result = await rewrite('hey whats up', {
  style: 'formal' | 'casual' | 'professional' | 'friendly' | 'concise' | 'detailed',
  tone: 'warm',
  audience: 'executives'
});

// Returns:
{
  rewritten: string;
  changes: string[];
  readabilityScore: number;
  cached: boolean;
  cost: number;
  latencyMs: number;
}

generate(topic, options?)

Generate content from a topic.

const result = await generate('AI in healthcare', {
  type: 'text' | 'email' | 'tweet' | 'blog' | 'code' | 'product_description' | 'headline',
  tone: 'professional',
  length: 'medium',
  keywords: ['AI', 'healthcare']
});

// Returns:
{
  content: string;
  wordCount: number;
  type: string;
  cached: boolean;
  cost: number;
  latencyMs: number;
}

compare(text1, text2, options?)

Compare two texts.

const result = await compare(text1, text2, {
  criteria: ['accuracy', 'clarity'],
  detailed: true
});

// Returns:
{
  similarity: number;  // 0-1
  differences: string[];
  similarities: string[];
  winner?: string;
  analysis?: string;
  cached: boolean;
  cost: number;
  latencyMs: number;
}

moderate(text, options?)

Moderate content for policy violations.

const result = await moderate(userContent, {
  categories: ['hate', 'harassment', 'spam'],
  threshold: 0.5,
  explain: true
});

// Returns:
{
  flagged: boolean;
  categories: Record<string, boolean>;
  scores: Record<string, number>;
  suggestedAction: 'allow' | 'review' | 'block';
  explanation?: string;
  cached: boolean;
  cost: number;
  latencyMs: number;
}

Configuration

import { configure } from '@ranavibe/helpers';

configure({
  provider: 'anthropic',
  model: 'claude-3-haiku-20240307',
  cache: true,
  cacheTTL: 3600
});

Performance

| Function | Avg Latency | Cache Hit | Cost/Call | |----------|-------------|-----------|-----------| | summarize | 800ms | 65% | $0.002 | | translate | 600ms | 70% | $0.001 | | classify | 400ms | 75% | $0.0005 | | extract | 900ms | 60% | $0.003 | | sentiment | 400ms | 80% | $0.0003 | | answer | 1200ms | 50% | $0.005 | | rewrite | 800ms | 55% | $0.002 | | generate | 1500ms | 40% | $0.008 | | compare | 700ms | 60% | $0.002 | | moderate | 500ms | 70% | $0.001 |

License

MIT - Waymaker