@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

$3

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

$3

`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

`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 ✅
`

$3

`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 ✅
`

$3

`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

$3

`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!' }]
});
`

$3

`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!' }]
});
`

$3

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.

$3

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

$3

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"
`

$3

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

$3

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)"
`

$3

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

$3

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
}
});
}
`

$3

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

$3

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

$3

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

Analytics API

$3

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

$3

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

$3

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