@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

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

Quick Start

1. Get Your Configuration

1. Sign up at 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

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)

// 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)

// 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

// 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

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

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

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:

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):

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):

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):

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:

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

With Enrichment:

// 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

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)

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

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

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

Custom Types

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

Analytics API

Get Value Realization

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

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

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

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

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
• 💬 Discord
• 📧 Email