npm package: @mdp-framework/ai-services
Description: Provider-agnostic AI service layer for MDP Framework
Author: MDP Framework Contributors
Latest version: 1.1.99

# @mdp-framework/ai-services

Provider-agnostic AI service layer for MDP Framework.

## Status

✅ **IMPLEMENTED** - Stream 1 Complete

See: [Stream 1 Contract](../../Docs/contracts/STREAM-1-AI-SERVICES.md)

**TODO-STREAM-1**: Ready for consumption by dependent streams (2, 4, 5)

## Purpose

Foundation layer providing AI capabilities to:
- **Stream 2**: AI-powered policy evaluation
- **Stream 4**: AOI specification generation
- **Stream 5**: Multi-agent orchestration

## Frozen Interfaces

All interfaces in `src/contracts/` are **FROZEN** per [CONTRACTS-AI.md](../../Docs/CONTRACTS-AI.md).

Changes require:
1. Major version bump
2. Cross-team review
3. Migration guide

## Implemented Features

### Part 1: Core Providers
- ✅ `src/providers/anthropic.ts` - AnthropicProvider with structured output
- ✅ `src/registry.ts` - Multi-provider registry
- ✅ Comprehensive unit tests

### Part 2: Additional Providers
- ✅ `src/providers/openai.ts` - OpenAIProvider with embeddings
- ✅ `src/providers/mock.ts` - MockProvider for deterministic testing
- ✅ Provider parity tests

### Part 3: Advanced Features
- ✅ `src/prompts/template.ts` - Jinja2-like templating with validation
- ✅ `src/cost-tracker.ts` - Token counting & budget enforcement
- ✅ Integration tests covering full workflows

## Success Criteria

- ✅ Token cost estimation within 5%
- ✅ Embeddings <1s for 1KB text
- ✅ 100% test coverage
- ✅ All providers implement AIProvider interface

## Usage

### Basic Provider Usage

```typescript
import { AnthropicProvider, OpenAIProvider, MockProvider } from '@mdp-framework/ai-services';

// Initialize provider
const provider = new AnthropicProvider({
  apiKey: process.env.ANTHROPIC_API_KEY
});

// Complete with structured output
const response = await provider.complete({
  prompt: 'Evaluate this PR against policy...',
  schema: {
    type: 'object',
    properties: {
      violations: { type: 'array' }
    }
  },
  temperature: 0.1
});

console.log(`Cost: $${response.usage.cost_usd}`);
console.log('Violations:', response.structured.violations);
```

### Multi-Provider Registry

```typescript
import { DefaultAIProviderRegistry, AnthropicProvider, OpenAIProvider } from '@mdp-framework/ai-services';

const registry = new DefaultAIProviderRegistry();
registry.register(new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY }));
registry.register(new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }));

// Use default provider
const provider = registry.getDefault();
const response = await provider.complete({ prompt: 'Hello!' });

// Switch providers
registry.setDefault('openai');
```

### Prompt Templates

```typescript
import { PromptTemplateBuilder } from '@mdp-framework/ai-services';

const template = new PromptTemplateBuilder()
  .setName('policy-eval')
  .setTemplate('Evaluate: {{code}}\nPolicy: {{policy}}')
  .addVariable('code', 'string', { required: true })
  .addVariable('policy', 'string', { required: true })
  .build();

const prompt = template.render({
  code: 'console.log("test")',
  policy: 'No console.log statements'
});

const response = await provider.complete({ prompt });
```

### Cost Tracking

```typescript
import { CostTracker } from '@mdp-framework/ai-services';

const tracker = new CostTracker({
  max_cost_per_day: 10.0,
  alert_threshold_pct: 80
});

// Check budget before call
const estimate = provider.estimateTokens(prompt);
const check = tracker.wouldExceedBudget(estimate.cost_usd);

if (!check.exceeded) {
  const response = await provider.complete({ prompt });
  tracker.recordCost({
    provider: provider.name,
    model: response.model,
    input_tokens: response.usage.input_tokens,
    output_tokens: response.usage.output_tokens,
    total_tokens: response.usage.total_tokens,
    cost_usd: response.usage.cost_usd
  });
}

// Get summary
const summary = tracker.getSummary();
console.log(`Total spent: $${summary.total_cost_usd}`);
```

### Embeddings

```typescript
import { OpenAIProvider } from '@mdp-framework/ai-services';

const provider = new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY });

const embeddings = await provider.embed([
  'First document',
  'Second document',
  'Third document'
]);

console.log(`Embedding dimension: ${embeddings[0].vector.length}`);
```

## Dependencies

**Consumed By**:
- `@mdp-framework/gateway` (Stream 2, 4)
- `@mdp-framework/agents` (Stream 5)

**No Dependencies**: Foundation layer

## License

MIT