Unified SDK for NotionAlpha Clarity - AI Value Realization Platform
npm install @notionalpha/clarity-sdkUnified SDK for NotionAlpha Clarity - AI Value Realization Platform
- 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
``bash`
npm install @notionalpha/clarity-sdk openai @anthropic-ai/sdk
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
`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
}
});
`
`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 ✅
`
`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 ✅
`typescript
// Get ROI summary
const value = await clarity.getValueRealization();
console.log(
Total Cost: $${value.totalCost}
Total Value: $${value.totalValue}
ROI: ${value.roi}x);`
`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)});Answer: ${answer}
console.log();
// 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"`
`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!' }]
});
`
`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!' }]
});
`
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
}
});
Unlock Maximum Agent Intelligence - Add optional enrichment metadata to help NotionAlpha agents deliver better insights, optimization recommendations, and strategic guidance.
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 (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"
| 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 |
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)"
`
High Priority (Include These):
- complexityScore - Always include if you can classify query complexityretryCount
- - Track if LLM needed multiple attemptshumanEscalationRequired
- - Track if human had to intervene
Medium Priority (Use for Multi-Turn Apps):
- sessionId - Essential for chatbots and multi-step flowsconversationTurns
- - Track multi-turn efficiencyoutcomeQuality
- - Measure output quality
Optional (Use for Advanced Analysis):
- processingTimeMs - For latency optimizationcapturedAt
- - For data quality assessment
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
}
});
}
`
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"
`typescript`
type OutcomeType =
| 'customer_support_ticket_resolved'
| 'code_generated'
| 'content_created'
| 'lead_qualified'
| 'error_prevented'
| 'time_saved'
| 'quality_improvement'
| 'revenue_generated'
| 'cost_reduction';
`typescript`
await clarity.trackOutcome({
transactionId,
type: 'custom_use_case', // Any string
metadata: {
// Your custom fields
customMetric: 100,
customValue: 'success'
}
});
`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
`
`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
`
`typescript
const recommendations = await clarity.getRecommendations();
for (const rec of recommendations) {
console.log(${rec.title}: Save $${rec.estimatedSavings}/month);Implementation: ${rec.implementationSteps.join(', ')}
console.log();`
}
`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!
}
});
MIT
- 📖 Documentation
- 💬 Discord
- 📧 Email