npm package: @notionalpha/clarity-sdk
Description: Unified SDK for NotionAlpha Clarity - AI Value Realization Platform
Author: NotionAlpha
Latest version: 0.3.1

# @notionalpha/clarity-sdk

**Unified SDK for NotionAlpha Clarity - AI Value Realization Platform**

## Features

- **Cost Tracking** - Track LLM costs across providers (OpenAI, Anthropic, Azure OpenAI)
- **Outcome Tracking** - Link business outcomes to LLM calls
- **ROI Calculation** - Calculate return on investment for AI features
- **Forecasting** - Predict future costs, value, and ROI with ML-powered insights
- **Recommendations** - Get AI-generated optimization suggestions
- **Signal Enrichment** - Automatic agent-aware signal capture and analysis

## Installation

```bash
npm install @notionalpha/clarity-sdk openai @anthropic-ai/sdk
```

## Quick Start

### 1. Get Your Configuration

1. Sign up at [notionalpha.com](https://notionalpha.com)
2. Create a provider (OpenAI, Anthropic, or Azure OpenAI)
3. Create a team for cost attribution
4. Copy your `orgId`, `teamId`, and `providerId`

### 2. Initialize the Client

```typescript
import { NotionAlphaClient } from '@notionalpha/clarity-sdk';

const clarity = new NotionAlphaClient({
  orgId: 'org_xxx',              // From NotionAlpha dashboard
  teamId: 'team-uuid',           // From NotionAlpha dashboard
  provider: {
    type: 'openai',
    providerId: 'provider-uuid'  // From NotionAlpha dashboard
  }
});
```

### 3. Make LLM Calls (FinOps + Security Automatic)

```typescript
// OpenAI
const { response, transactionId } = await clarity.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Help me resolve this ticket' }]
});

console.log(response.choices[0].message.content);
// FinOps: Cost automatically tracked ✅
// Security: Threats automatically detected ✅
```

### 4. Track Outcomes (One Line)

```typescript
// Link business outcome to LLM call
await clarity.trackOutcome({
  transactionId,
  type: 'customer_support_ticket_resolved',
  metadata: {
    ticketId: 'TICKET-456',
    resolutionTimeSeconds: 120,
    customerSatisfaction: 5,
    timeSavedMinutes: 15  // Human time saved
  }
});
// ROI: Automatically calculated ✅
```

### 5. View Value Realization

```typescript
// Get ROI summary
const value = await clarity.getValueRealization();

console.log(`
  Total Cost: $${value.totalCost}
  Total Value: $${value.totalValue}
  ROI: ${value.roi}x
`);
```

## Complete Example: Customer Support Bot

```typescript
import { NotionAlphaClient } from '@notionalpha/clarity-sdk';

const clarity = new NotionAlphaClient({
  orgId: process.env.NOTIONALPHA_ORG_ID!,
  teamId: process.env.NOTIONALPHA_TEAM_ID!,
  provider: {
    type: 'openai',
    providerId: process.env.NOTIONALPHA_PROVIDER_ID!
  }
});

async function resolveTicket(ticketId: string, question: string) {
  // 1. Make LLM call (FinOps + Security automatic)
  const { response, transactionId, cost } = await clarity.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [
      { role: 'system', content: 'You are a helpful customer support agent.' },
      { role: 'user', content: question }
    ]
  });

  const answer = response.choices[0].message.content;
  
  console.log(`Cost: $${cost?.totalCost.toFixed(4)}`);
  console.log(`Answer: ${answer}`);

  // 2. Track outcome (one line)
  await clarity.trackOutcome({
    transactionId,
    type: 'customer_support_ticket_resolved',
    metadata: {
      ticketId,
      resolutionTimeSeconds: 120,
      customerSatisfaction: 5,
      timeSavedMinutes: 15  // vs manual resolution
    }
  });

  return answer;
}

// Use it
await resolveTicket('TICKET-123', 'How do I reset my password?');

// Later: View ROI
const value = await clarity.getValueRealization();
console.log(`ROI: ${value.roi}x`);  // e.g., "ROI: 25x"
```

## Supported Providers

### OpenAI

```typescript
const clarity = new NotionAlphaClient({
  orgId: 'org_xxx',
  teamId: 'team-uuid',
  provider: { type: 'openai', providerId: 'provider-uuid' }
});

const { response, transactionId } = await clarity.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello!' }]
});
```

### Anthropic

```typescript
const clarity = new NotionAlphaClient({
  orgId: 'org_xxx',
  teamId: 'team-uuid',
  provider: { type: 'anthropic', providerId: 'provider-uuid' }
});

const { response, transactionId } = await clarity.messages.create({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello!' }]
});
```

### Azure OpenAI

**Configuration Notes:**
- Uses API version `2024-12-01-preview` (latest stable version)
- Supports both legacy Azure OpenAI and AI Foundry endpoints
- Credentials (API key, endpoint) are stored securely in NotionAlpha backend
- Deployment name must match your Azure OpenAI deployment

**Basic Usage:**

```typescript
const clarity = new NotionAlphaClient({
  orgId: 'org_xxx',
  teamId: 'team-uuid',
  provider: {
    type: 'azure-openai',
    providerId: 'provider-uuid',
    deploymentName: 'gpt-4o-mini'  // Your Azure deployment name
  }
});

const { response, transactionId } = await clarity.chat.completions.create({
  model: 'gpt-4o-mini',  // Must match deploymentName
  messages: [{ role: 'user', content: 'Hello!' }]
});
```

**Advanced Configuration (Optional):**

```typescript
const clarity = new NotionAlphaClient({
  orgId: 'org_xxx',
  teamId: 'team-uuid',
  provider: {
    type: 'azure-openai',
    providerId: 'provider-uuid',
    deploymentName: 'gpt-4o-mini',
    resourceName: 'my-resource',      // Optional: Azure resource name
    projectName: 'my-project'         // Optional: AI Foundry project name
  }
});
```

## Agent-Aware Enrichment

**Unlock Maximum Agent Intelligence** - Add optional enrichment metadata to help NotionAlpha agents deliver better insights, optimization recommendations, and strategic guidance.

### Why Enrichment Matters

Without enrichment, agents can only see basic metrics (cost, outcomes). With enrichment, agents can:

- **Advisory Agent**: Find 90% more optimization opportunities (complexity-based model selection, waste patterns)
- **Data Readiness Agent**: Assess outcome tracking quality and data readiness
- **Orchestrator Agent**: Analyze multi-step journeys and session patterns
- **Value Activation Agent**: Detect low match rates and suggest improvements

### Basic Tracking vs Enhanced Tracking

**Basic (60% Intelligence):**
```typescript
await clarity.trackOutcome({
  transactionId,
  type: 'customer_support_ticket_resolved',
  metadata: { ticketId: 'T-456', timeSavedMinutes: 15 }
});
// Agent sees: "Ticket resolved, 15 min saved"
// Missing: Why simple? Could we use cheaper model? Quality good?
```

**Enhanced with Enrichment (90% Intelligence):**
```typescript
await clarity.trackOutcome({
  transactionId,
  type: 'customer_support_ticket_resolved',
  metadata: { ticketId: 'T-456', timeSavedMinutes: 15 },
  enrichment: {
    complexityScore: 2,           // 1-10 scale (1=simple, 10=complex)
    queryType: 'simple',          // simple | moderate | complex
    retryCount: 0,                // Number of retries needed
    humanEscalationRequired: false,
    outcomeQuality: 'high',       // high | medium | low
    sessionId: 'session-123',     // Link multi-step interactions
    conversationTurns: 3,         // Number of back-and-forth turns
    processingTimeMs: 1200        // Processing latency
  }
});
// Agent sees: "Simple ticket (2/10 complexity), high quality, no retries"
// Agent recommends: "70% of tickets are simple - switch to GPT-4o-mini, save $8K/month"
```

### Enrichment Fields Reference

| Field | Type | Agent Use Case |
|-------|------|----------------|
| `complexityScore` | `number (1-10)` | **Advisory**: Identify overuse of expensive models for simple tasks |
| `queryType` | `'simple' \| 'moderate' \| 'complex'` | **Advisory**: Route queries to appropriate model tier |
| `retryCount` | `number` | **Advisory**: Detect prompt quality issues causing waste |
| `humanEscalationRequired` | `boolean` | **Advisory**: Measure AI effectiveness and automation gaps |
| `outcomeQuality` | `'high' \| 'medium' \| 'low'` | **Data Readiness**: Assess data quality and model performance |
| `sessionId` | `string` | **Orchestrator**: Analyze multi-step user journeys |
| `conversationTurns` | `number` | **Advisory**: Detect inefficient multi-turn patterns |
| `processingTimeMs` | `number` | **Engineering**: Identify latency issues |
| `capturedAt` | `Date` | **Data Readiness**: Detect labeling delays |

### Real-World Example: Customer Support Optimization

**Scenario**: Your customer support bot handles 5,000 tickets/month with GPT-4o

**Without Enrichment:**
```typescript
// Advisory Agent analysis:
"Customer Support: $25,000/month, 5,000 tickets, 6.4x ROI"
// ❌ No optimization recommendations (can't see complexity patterns)
```

**With Enrichment:**
```typescript
// Track outcomes with complexity
await clarity.trackOutcome({
  transactionId,
  type: 'customer_support_ticket_resolved',
  metadata: { ticketId: ticket.id, timeSavedMinutes: 15 },
  enrichment: {
    complexityScore: ticket.estimatedComplexity(),  // Your logic
    queryType: ticket.category === 'password_reset' ? 'simple' : 'moderate',
    retryCount: attempt - 1,
    humanEscalationRequired: escalated,
    outcomeQuality: customerSatisfaction > 4 ? 'high' : 'medium'
  }
});

// Advisory Agent analysis with enrichment:
"Customer Support: $25,000/month, 5,000 tickets, 6.4x ROI

OPTIMIZATION OPPORTUNITY:
- 70% of tickets are simple (complexity ≤ 3)
- These simple tickets cost $17,500/month using GPT-4o
- Recommendation: Route simple tickets to GPT-4o-mini
- Expected Savings: $14,000/month (80% cost reduction)
- Expected ROI Improvement: 6.4x → 12.8x
- Implementation: 1 week
- Risk: Low (quality maintained for simple queries)"
```

### When to Use Enrichment

**High Priority (Include These):**
- `complexityScore` - Always include if you can classify query complexity
- `retryCount` - Track if LLM needed multiple attempts
- `humanEscalationRequired` - Track if human had to intervene

**Medium Priority (Use for Multi-Turn Apps):**
- `sessionId` - Essential for chatbots and multi-step flows
- `conversationTurns` - Track multi-turn efficiency
- `outcomeQuality` - Measure output quality

**Optional (Use for Advanced Analysis):**
- `processingTimeMs` - For latency optimization
- `capturedAt` - For data quality assessment

### Implementation Patterns

**Pattern 1: Simple Classification**
```typescript
function classifyComplexity(userQuery: string): number {
  const keywords = {
    simple: ['password', 'reset', 'login', 'where is'],
    moderate: ['how to', 'explain', 'difference'],
    complex: ['analyze', 'compare', 'recommend', 'design']
  };

  // Simple keyword-based scoring (1-10)
  if (keywords.simple.some(k => userQuery.toLowerCase().includes(k))) return 2;
  if (keywords.complex.some(k => userQuery.toLowerCase().includes(k))) return 8;
  return 5;
}

const complexity = classifyComplexity(userMessage);
await clarity.trackOutcome({
  transactionId,
  type: 'customer_support_ticket_resolved',
  metadata: { ticketId: 'T-456' },
  enrichment: {
    complexityScore: complexity,
    queryType: complexity <= 3 ? 'simple' : complexity <= 7 ? 'moderate' : 'complex'
  }
});
```

**Pattern 2: Session Tracking (Multi-Turn)**
```typescript
class ConversationSession {
  sessionId = crypto.randomUUID();
  turns = 0;
  retries = 0;

  async sendMessage(message: string) {
    this.turns++;

    const { response, transactionId } = await clarity.chat.completions.create({
      model: 'gpt-4o-mini',
      messages: this.history
    });

    // Track with session context
    await clarity.trackOutcome({
      transactionId,
      type: 'customer_support_ticket_resolved',
      metadata: { sessionId: this.sessionId },
      enrichment: {
        sessionId: this.sessionId,
        conversationTurns: this.turns,
        retryCount: this.retries,
        humanEscalationRequired: this.escalated
      }
    });
  }
}
```

**Pattern 3: Quality Assessment**
```typescript
async function generateContent(prompt: string) {
  let attempts = 0;
  let quality: 'high' | 'medium' | 'low' = 'high';

  const { response, transactionId } = await clarity.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: prompt }]
  });

  const content = response.choices[0].message.content;

  // Assess quality (your logic)
  if (content.length < 100) quality = 'low';
  else if (await passesValidation(content)) quality = 'high';
  else quality = 'medium';

  await clarity.trackOutcome({
    transactionId,
    type: 'content_created',
    metadata: { contentLength: content.length },
    enrichment: {
      complexityScore: estimateComplexity(prompt),
      retryCount: attempts,
      outcomeQuality: quality,
      processingTimeMs: Date.now() - startTime
    }
  });
}
```

### Agent Insights Examples

**Advisory Agent with Enrichment:**
```
"Detected waste pattern:
- 45% of complex queries (complexity ≥ 7) required retries (avg 2.3 retries)
- Root cause: Underpowered model for complex analysis
- Recommendation: Use GPT-4o for complexity ≥ 7 queries
- Impact: Reduce retries by 80%, save $3K/month in wasted tokens"
```

**Data Readiness Agent with Enrichment:**
```
"Outcome tracking quality: 68/100
- Issue: 35% of outcomes marked as low quality
- Issue: Average labeling delay of 2.5 hours (capturedAt vs timestamp)
- Recommendation: Implement real-time outcome capture
- Impact: Improve data quality to 95/100"
```

**Orchestrator Agent with Enrichment:**
```
"Multi-step journey analysis:
- Average session length: 4.2 turns
- 30% of sessions exceed 6 turns (inefficiency signal)
- Recommendation: Improve prompt to reduce multi-turn interactions
- Impact: Save $5K/month, improve user experience"
```

## Outcome Types

### Predefined Types

```typescript
type OutcomeType =
  | 'customer_support_ticket_resolved'
  | 'code_generated'
  | 'content_created'
  | 'lead_qualified'
  | 'error_prevented'
  | 'time_saved'
  | 'quality_improvement'
  | 'revenue_generated'
  | 'cost_reduction';
```

### Custom Types

```typescript
await clarity.trackOutcome({
  transactionId,
  type: 'custom_use_case',  // Any string
  metadata: {
    // Your custom fields
    customMetric: 100,
    customValue: 'success'
  }
});
```

## Analytics API

### Get Value Realization

```typescript
const value = await clarity.getValueRealization({
  startDate: new Date('2025-01-01'),
  endDate: new Date('2025-01-31')
});

console.log(value.totalCost);      // Total AI spend
console.log(value.totalValue);     // Total value created
console.log(value.roi);            // ROI multiplier
console.log(value.byUseCase);      // Breakdown by outcome type
console.log(value.byTeam);         // Breakdown by team
```

### Get Forecast

```typescript
const forecast = await clarity.getForecast(30, 'hybrid');

console.log(forecast.predictions.cost);   // 30-day cost forecast
console.log(forecast.predictions.value);  // 30-day value forecast
console.log(forecast.predictions.roi);    // 30-day ROI forecast
console.log(forecast.insights);           // AI-generated insights
```

### Get Recommendations

```typescript
const recommendations = await clarity.getRecommendations();

for (const rec of recommendations) {
  console.log(`${rec.title}: Save $${rec.estimatedSavings}/month`);
  console.log(`Implementation: ${rec.implementationSteps.join(', ')}`);
}
```

## Environment Variables

```bash
# .env
NOTIONALPHA_ORG_ID=org_xxx
NOTIONALPHA_TEAM_ID=team-uuid
NOTIONALPHA_PROVIDER_ID=provider-uuid
NOTIONALPHA_ENVIRONMENT=production
```

```typescript
const clarity = new NotionAlphaClient({
  orgId: process.env.NOTIONALPHA_ORG_ID!,
  teamId: process.env.NOTIONALPHA_TEAM_ID!,
  environment: process.env.NOTIONALPHA_ENVIRONMENT,
  provider: {
    type: 'openai',
    providerId: process.env.NOTIONALPHA_PROVIDER_ID!
  }
});
```

## License

MIT

## Support

- 📖 [Documentation](https://notionalpha.com/docs)
- 💬 [Discord](https://discord.gg/notionalpha)
- 📧 [Email](mailto:support@notionalpha.com)