ai-audit-sdk

AI Audit Trail SDK - Node.js

Drop-in SDK for logging AI/ML decisions with compliance tracking. Get GDPR and EU AI Act compliant audit trails in under 15 minutes.

Installation

npm install ai-audit-sdk

Quick Start

import { AuditLogger } from 'ai-audit-sdk';
import OpenAI from 'openai';

// Initialize the logger with your API key
const logger = new AuditLogger({ 
  apiKey: 'your_api_key',
  timeout: 15000,          // optional (ms) overrides env AI_AUDIT_TIMEOUT
  maxRetries: 2,            // optional retry attempts after first try
  backoffBaseMs: 500,       // optional base for exponential backoff
  backoffCapMs: 5000,       // optional cap for backoff delay
  debug: false              // set true to see internal retry logs
});

// For development/testing, use your sandbox API key:
// const logger = new AuditLogger({ apiKey: 'your_sandbox_api_key' });

// Your existing OpenAI code
const openai = new OpenAI({ apiKey: 'your_openai_key' });

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

// Log the decision for compliance
await logger.logDecision({
  input: 'Hello, world!',
  output: response.choices[0].message.content,
  modelName: 'gpt-4',
  metadata: {
    userId: 'user123',
    sessionId: 'session456'
  }
});

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import { AuditLogger, LogDecisionOptions } from 'ai-audit-sdk';

const logger = new AuditLogger({ apiKey: 'your_key' });

const options: LogDecisionOptions = {
  input: 'prompt',
  output: 'response',
  modelName: 'gpt-4',
  metadata: { userId: 'user123' },
  confidence: 0.95,
  responseTime: 1200
};

await logger.logDecision(options);

Features

• Asynchronous Logging: Won't slow down your application
• TypeScript Support: Full type safety and IntelliSense
• Compliance Ready: GDPR Article 22 and EU AI Act support
• Multi-Model Support: Works with any AI/ML model
• Secure: API key authentication with encrypted transmission
• Reliable: Built-in error handling and timeout management

API Reference

AuditLogger

Main class for logging AI decisions.

const logger = new AuditLogger({
  apiKey: 'your_key',
  timeout: 15000,     // default if not set: 15000ms or AI_AUDIT_TIMEOUT env
  maxRetries: 2,       // total attempts = maxRetries + 1
  debug: false
});

Production:

const logger = new AuditLogger({ apiKey: 'prod_api_key_xxx' });

Development/Testing:

const logger = new AuditLogger({ apiKey: 'sandbox_api_key_xxx' });

Note: All traffic goes through the production infrastructure at https://explainableai.azurewebsites.net. Tenant isolation is handled via API keys, not URLs.

Methods

logDecision(options)

Log an AI decision asynchronously (recommended).

await logger.logDecision({
  input: 'The input prompt',
  output: 'The AI response',
  modelName: 'gpt-4', // optional, defaults to 'unknown'
  metadata: { // optional
    userId: 'user123',
    sessionId: 'session456',
    tags: ['production', 'chat']
  },
  confidence: 0.95, // optional, 0.0 to 1.0
  responseTime: 1200, // optional, in milliseconds
  provider: 'openai', // optional
  modelVersion: '2024-02-01', // optional
  riskLevel: 'low', // optional: 'low', 'medium', 'high'
  promptTokens: 100, // optional
  completionTokens: 50, // optional
  totalTokens: 150, // optional
  costMicros: 1000, // optional, cost in millionths of currency unit
  externalRef: 'req_123', // optional, your internal reference
  dataSubjectId: 'user_123', // optional, for GDPR compliance
  lawfulBasis: 'consent', // optional, GDPR lawful basis
  automatedDecision: true, // optional, GDPR Article 22
  redactPII: false, // optional, redact PII from stored data
  priority: 'normal' // optional: 'low', 'normal', 'high'
});

logDecisionSync(options)

Same as logDecision() but waits for completion. Returns true if successful.

const success = await logger.logDecisionSync(options);
if (!success) {
  console.error('Failed to log decision');
}

Static Methods

AuditLogger.fromEnv(baseUrl?)

Create a logger using the AI_AUDIT_API_KEY environment variable:

##### `AuditLogger.fromEnv()`

Create a logger using the `AI_AUDIT_API_KEY` environment variable:

```javascript
const logger = AuditLogger.fromEnv();

### Convenience Function

For one-off logging:

```javascript
import { logAiDecision } from 'ai-audit-sdk';

await logAiDecision('your_api_key', {
  input: 'prompt',
  output: 'response',
  modelName: 'gpt-4'
});

Configuration

Set your API key as an environment variable:

export AI_AUDIT_API_KEY="your_api_key"
export AI_AUDIT_TIMEOUT=20000          # optional: override default timeout (ms)
export AI_AUDIT_TIMEOUT=12000          # another example (12s)
export AI_AUDIT_TIMEOUT=5000           # reduce timeout

Then use it in your code:

import { AuditLogger } from 'ai-audit-sdk';

const logger = AuditLogger.fromEnv();

Error Handling & Retries

The SDK uses fire-and-forget async logging by default. Errors are logged to console but won't crash your application.

Retry & timeout behavior (v1.0.1+):

• Default timeout: 15000ms (can override with timeout option or AI_AUDIT_TIMEOUT env var)
• Retries: 2 retries (3 total attempts) on: network errors, timeouts, HTTP 429, and HTTP 5xx
• Backoff: Exponential base (default 500ms) with jitter, capped optionally via backoffCapMs
• Debug: Set debug: true or DEBUG=ai-audit-sdk (future) to inspect attempt details

For critical applications, use synchronous logging:

const success = await logger.logDecisionSync(options);
if (!success) {
  // Handle logging failure
  console.error('Failed to log decision');
}

// Custom configuration example with retries & debug
const strictLogger = new AuditLogger({
  apiKey: process.env.AI_AUDIT_API_KEY!,
  timeout: 20000,
  maxRetries: 3,
  backoffBaseMs: 400,
  backoffCapMs: 6000,
  debug: true
});

Examples

OpenAI Integration

import OpenAI from 'openai';
import { AuditLogger } from 'ai-audit-sdk';

const logger = new AuditLogger({ apiKey: process.env.AI_AUDIT_API_KEY });
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function getAiResponse(prompt, userId) {
  const startTime = Date.now();
  
  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: prompt }]
  });
  
  const responseTime = Date.now() - startTime;
  
  // Log for compliance
  await logger.logDecision({
    input: prompt,
    output: response.choices[0].message.content,
    modelName: 'gpt-4',
    metadata: { userId },
    responseTime
  });
  
  return response.choices[0].message.content;
}

Express.js Middleware

import express from 'express';
import { AuditLogger } from 'ai-audit-sdk';

const app = express();
const logger = AuditLogger.fromEnv();

app.use('/api/ai', async (req, res, next) => {
  const originalSend = res.send;
  
  res.send = function(body) {
    // Log the AI interaction
    logger.logDecision({
      input: JSON.stringify(req.body),
      output: body,
      modelName: req.body.model || 'unknown',
      metadata: {
        userId: req.user?.id,
        endpoint: req.path,
        method: req.method
      }
    });
    
    return originalSend.call(this, body);
  };
  
  next();
});

With Anthropic

import Anthropic from '@anthropic-ai/sdk';
import { AuditLogger } from 'ai-audit-sdk';

const logger = new AuditLogger({ apiKey: process.env.AI_AUDIT_API_KEY });
const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

async function callClaude(prompt) {
  const response = await anthropic.messages.create({
    model: 'claude-3-sonnet-20240229',
    max_tokens: 1000,
    messages: [{ role: 'user', content: prompt }]
  });
  
  await logger.logDecision({
    input: prompt,
    output: response.content[0].text,
    modelName: 'claude-3-sonnet-20240229'
  });
  
  return response.content[0].text;
}

License

MIT License