npm package: @relayplane/core
Description: Agent optimization layer: intelligent routing, outcome tracking, and learning
Author: RelayPlane
Latest version: 0.1.4

# @relayplane/core

> Agent optimization layer for intelligent routing, outcome tracking, and learning.

## Overview

`@relayplane/core` is the brain of RelayPlane — it automatically routes your AI prompts to the best model for each task type and learns from outcomes to improve over time. Supports all 11 major providers: Anthropic, OpenAI, Google, xAI, OpenRouter, DeepSeek, Groq, Mistral, Together, Fireworks, and Perplexity.

**Key features:**

- 🎯 **Smart Routing** — Infers task type (code, summarization, analysis, etc.) and routes to optimal model
- 📊 **Outcome Tracking** — Record success/failure to improve future routing  
- 🧠 **Learning** — Generates suggestions based on performance data
- ⚡ **Fast** — <5ms routing decisions (no network calls for routing)
- 💾 **Local-First** — All data stored in SQLite at `~/.relayplane/data.db`
- 🆓 **Free forever** — Full functionality for solo devs, no artificial limits

## Installation

```bash
pnpm add @relayplane/core @relayplane/adapters
```

## Quick Start

```typescript
import { RelayPlane } from '@relayplane/core';

// Create instance
const relay = new RelayPlane();

// Run a prompt - automatically routes to best model
const result = await relay.run({
  prompt: 'Review this code for bugs: function add(a, b) { return a + b; }',
});

console.log(result.taskType);  // 'code_review'
console.log(result.model);     // 'anthropic:claude-3-5-sonnet-20241022'
console.log(result.output);    // The model's response

// Record outcome for learning
relay.recordOutcome(result.runId, {
  success: true,
  quality: 'good',
});

// Close when done
relay.close();
```

## Task Types

RelayPlane automatically infers one of 9 task types:

| Task Type | Description | Default Model |
|-----------|-------------|---------------|
| `code_generation` | Writing new code | claude-3-5-sonnet |
| `code_review` | Reviewing existing code | claude-3-5-sonnet |
| `summarization` | Condensing content | claude-3-haiku |
| `analysis` | Deep analysis | gpt-4o |
| `creative_writing` | Stories, articles | claude-3-opus |
| `data_extraction` | Extracting structured data | gpt-4o-mini |
| `translation` | Language translation | gpt-4o-mini |
| `question_answering` | Answering questions | claude-3-haiku |
| `general` | Everything else | claude-3-5-sonnet |

## API Reference

### RelayPlane

Main class for the agent optimization layer.

```typescript
const relay = new RelayPlane({
  dbPath?: string;          // Default: ~/.relayplane/data.db
  defaultProvider?: string; // Default: 'local'
  defaultModel?: string;    // Default: 'llama3.2'
  providers?: {
    openai?: { apiKey?: string; baseUrl?: string; };
    anthropic?: { apiKey?: string; };
    google?: { apiKey?: string; };
    xai?: { apiKey?: string; };
    local?: { baseUrl?: string; };
  };
});
```

### relay.run(input)

Routes a prompt to the best model.

```typescript
const result = await relay.run({
  prompt: string;           // Required
  systemPrompt?: string;    // Optional system prompt
  taskType?: TaskType;      // Override inferred task type
  model?: string;           // Override model selection
  metadata?: object;        // Attach metadata
});

// Returns
{
  runId: string;
  success: boolean;
  output?: string;
  error?: string;
  taskType: TaskType;
  model: string;
  durationMs: number;
  tokensIn?: number;
  tokensOut?: number;
  timestamp: string;
}
```

### relay.recordOutcome(runId, outcome)

Records outcome for learning.

```typescript
relay.recordOutcome(runId, {
  success: boolean;
  quality?: 'excellent' | 'good' | 'acceptable' | 'poor' | 'failed';
  latencySatisfactory?: boolean;
  costSatisfactory?: boolean;
  feedback?: string;
});
```

### relay.routing

Access routing rules directly.

```typescript
// Get rule for task type
const rule = relay.routing.get('code_generation');

// Set custom rule
relay.routing.set('code_generation', 'openai:gpt-4o', 'user');

// List all rules
const rules = relay.routing.list();

// Reset to default
relay.routing.delete('code_generation');
```

### relay.stats(options?)

Get statistics.

```typescript
const stats = relay.stats({
  from?: string; // ISO date
  to?: string;   // ISO date
});
```

### relay.getSuggestions()

Get routing improvement suggestions.

```typescript
const suggestions = relay.getSuggestions();
```

### relay.acceptSuggestion(id)

Accept a suggestion to update routing.

```typescript
relay.acceptSuggestion(suggestionId);
```

## Environment Variables

Set API keys via environment:

- `OPENAI_API_KEY` - OpenAI
- `ANTHROPIC_API_KEY` - Anthropic
- `GOOGLE_API_KEY` - Google AI
- `XAI_API_KEY` - xAI

## License

MIT