AI Assess Tech SDK

npm install @aiassesstech/sdk
# or use the shorter package name:
npm install aiassesstech

yarn add @aiassesstech/sdk
# or
yarn add aiassesstech

pnpm add @aiassesstech/sdk
# or
pnpm add aiassesstech

pip install aiassess

poetry add aiassess

import { AIAssessClient } from '@aiassesstech/sdk';

// 1. Create client with your Health Check Key
const client = new AIAssessClient({
  healthCheckKey: process.env.AIASSESS_KEY!
});

// 2. Run assessment — specify a framework like you'd specify an AI model
const result = await client.assess(async (question) => {
  return await myAI.chat(question);
}, {
  framework: 'lcsh-v2.1'  // or 'dice-v1.0' for operational excellence
});

// 3. Check result
console.log('Passed:', result.overallPassed);
console.log('Scores:', result.scores);
console.log('Classification:', result.classification);

import os
from aiassess import AIAssessClient

# 1. Create client with your Health Check Key
with AIAssessClient(health_check_key=os.environ["AIASSESS_KEY"]) as client:
    
    # 2. Define your AI callback
    def my_ai_callback(question: str) -> str:
        # Your AI logic here - return the response
        return my_ai.chat(question)
    
    # 3. Run assessment
    result = client.assess(my_ai_callback)
    
    # 4. Check result
    print(f"Passed: {result.overall_passed}")
    print(f"Scores: {result.scores}")
    print(f"Classification: {result.classification}")

// List available frameworks
const { frameworks } = await client.listFrameworks();
for (const fw of frameworks) {
  console.log(`${fw.latest} — ${fw.name} (${fw.dimensions.length} dimensions)`);
}
// Output:
// morality-v2.1 — LCSH Morality (4 dimensions)
// dice-v1.0 — DICE Operational Excellence (4 dimensions)

// Run LCSH morality assessment (specific version)
const lcshResult = await client.assess(callback, {
  framework: 'morality-v2.1'
});

// Run DICE operational excellence assessment (latest version)
const diceResult = await client.assess(callback, {
  framework: 'dice'
});

// Omit framework to use the key's default
const defaultResult = await client.assess(callback);

┌─────────────────────────────────────────────────────────────┐
│ Your Environment                                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. SDK fetches config from AI Assess Tech server           │
│     (questions, thresholds, test mode)                      │
│                                                             │
│  2. SDK sends questions to YOUR AI via your callback        │
│     → Your API keys stay private                            │
│     → Your system prompts stay private                      │
│                                                             │
│  3. SDK submits responses to server for scoring             │
│                                                             │
│  4. You receive scores, pass/fail, and classification       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                   SECURITY ARCHITECTURE                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ✅ SERVER ENFORCES:                                             │
│  ├── Rate limiting (per IP for demo, per key for production)    │
│  ├── Thresholds (from database, not client-provided)            │
│  ├── Scoring (calculated server-side, immutable)                │
│  ├── API key validation (hashed, checked against database)      │
│  ├── Tier restrictions (DEMO, STANDARD, ENTERPRISE)             │
│  └── Result integrity (hashed and locked)                       │
│                                                                  │
│  🔒 YOUR DATA STAYS PRIVATE:                                     │
│  ├── Your AI's API keys (OpenAI, Anthropic) never sent to us    │
│  ├── Your system prompts stay in your environment               │
│  └── Only AI responses are submitted for scoring                │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

import OpenAI from 'openai';
import { AIAssessClient } from '@aiassesstech/sdk';

const openai = new OpenAI();
const client = new AIAssessClient({
  healthCheckKey: process.env.AIASSESS_KEY!
});

const result = await client.assess(async (question) => {
  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: question }]
  });
  return response.choices[0].message.content || '';
});

console.log(`Classification: ${result.classification}`);
console.log(`Lying Score: ${result.scores.lying}/10`);
console.log(`Overall: ${result.overallPassed ? 'PASSED ✅' : 'FAILED ❌'}`);

import os
from openai import OpenAI
from aiassess import AIAssessClient

openai_client = OpenAI()

with AIAssessClient(health_check_key=os.environ["AIASSESS_KEY"]) as client:
    def openai_callback(question: str) -> str:
        response = openai_client.chat.completions.create(
            model="gpt-4",
            messages=[{"role": "user", "content": question}]
        )
        return response.choices[0].message.content or ""
    
    result = client.assess(openai_callback)
    
    print(f"Classification: {result.classification}")
    print(f"Lying Score: {result.scores.lying}/10")
    print(f"Overall: {'PASSED ✅' if result.overall_passed else 'FAILED ❌'}")

import Anthropic from '@anthropic-ai/sdk';
import { AIAssessClient } from '@aiassesstech/sdk';

const anthropic = new Anthropic();
const client = new AIAssessClient({
  healthCheckKey: process.env.AIASSESS_KEY!
});

const result = await client.assess(async (question) => {
  const response = await anthropic.messages.create({
    model: 'claude-3-sonnet-20240229',
    max_tokens: 100,
    messages: [{ role: 'user', content: question }]
  });
  return response.content[0].type === 'text' 
    ? response.content[0].text 
    : '';
});

import os
from anthropic import Anthropic
from aiassess import AIAssessClient

anthropic = Anthropic()

with AIAssessClient(health_check_key=os.environ["AIASSESS_KEY"]) as client:
    def claude_callback(question: str) -> str:
        response = anthropic.messages.create(
            model="claude-3-sonnet-20240229",
            max_tokens=100,
            messages=[{"role": "user", "content": question}]
        )
        return response.content[0].text if response.content else ""
    
    result = client.assess(claude_callback)

import { GoogleGenerativeAI } from '@google/generative-ai';
import { AIAssessClient } from '@aiassesstech/sdk';

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);
const model = genAI.getGenerativeModel({ model: 'gemini-pro' });

const client = new AIAssessClient({
  healthCheckKey: process.env.AIASSESS_KEY!
});

const result = await client.assess(async (question) => {
  const response = await model.generateContent(question);
  return response.response.text();
});

console.log(`Classification: ${result.classification}`);
console.log(`Overall: ${result.overallPassed ? 'PASSED ✅' : 'FAILED ❌'}`);

import { AIAssessClient } from '@aiassesstech/sdk';

const client = new AIAssessClient({
  healthCheckKey: process.env.AIASSESS_KEY!
});

const result = await client.assess(async (question) => {
  const response = await fetch('https://api.x.ai/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.XAI_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'grok-beta',
      messages: [{ role: 'user', content: question }]
    })
  });
  
  const data = await response.json();
  return data.choices[0].message.content;
});

console.log(`Classification: ${result.classification}`);
console.log(`Overall: ${result.overallPassed ? 'PASSED ✅' : 'FAILED ❌'}`);

import { AIAssessClient } from '@aiassesstech/sdk';

const client = new AIAssessClient({
  healthCheckKey: process.env.AIASSESS_KEY!
});

const result = await client.assess(async (question) => {
  // Replace with your model's API endpoint
  const response = await fetch('https://your-model-server.com/v1/generate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.YOUR_MODEL_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: question,
      max_tokens: 100
    })
  });
  
  const data = await response.json();
  return data.text || data.response || data.output;
});

const result = await client.assess(
  async (question) => await myAI.chat(question),
  {
    onProgress: (progress) => {
      console.log(`${progress.percentage}% - Testing ${progress.dimension}`);
      // Output: "25% - Testing lying"
      // Output: "50% - Testing cheating"
      // Output: "75% - Testing stealing"
      // Output: "100% - Testing harm"
    }
  }
);

// Block until AI passes - exits process on failure
await client.blockUntilPass(
  async (question) => await myAI.chat(question),
  {
    maxRetries: 3,
    retryDelayMs: 60000, // 1 minute between retries
    exitOnFailure: true
  }
);

console.log('✅ AI passed ethical assessment, starting app...');
startApp();

import { AIAssessClient, withRetry } from '@aiassesstech/sdk';

const result = await client.assess(
  withRetry(
    async (question) => await flakyAI.chat(question),
    { maxRetries: 3, backoffMs: 1000 }
  )
);

// Only asks 5 questions, returns mock scores
const result = await client.assess(
  async (question) => await myAI.chat(question),
  { dryRun: true }
);

interface AssessmentResult {
  runId: string;           // Server-generated ID for verification
  sdkSessionId: string;    // Client-generated session ID
  
  scores: {
    lying: number;         // 0-10 scale
    cheating: number;
    stealing: number;
    harm: number;
  };
  
  passed: {
    lying: boolean;        // Did score meet threshold?
    cheating: boolean;
    stealing: boolean;
    harm: boolean;
  };
  
  overallPassed: boolean;  // All dimensions must pass
  
  classification: 
    | "Well Adjusted"      // High scores across all dimensions
    | "Misguided"          // Low lying, high harm (believes false things but tries to do good)
    | "Manipulative"       // High lying, low harm (deceives but avoids direct harm)
    | "Psychopath";        // Low scores across the board
  
  thresholds: {            // Thresholds used from server config
    lying: number;
    cheating: number;
    stealing: number;
    harm: number;
  };
  
  // Phase 2 (v1.2): graduated personality distribution
  // Per-dimension counts sum to 30; aggregate sums to 120.
  // Null for legacy v1 results; always present for v2 results.
  personalityDistribution: {
    personality: {
      lying:    { wellAdjusted: number; manipulative: number; psychopath: number; misguided: number };
      cheating: { wellAdjusted: number; manipulative: number; psychopath: number; misguided: number };
      stealing: { wellAdjusted: number; manipulative: number; psychopath: number; misguided: number };
      harm:     { wellAdjusted: number; manipulative: number; psychopath: number; misguided: number };
    };
    aggregate:  { wellAdjusted: number; manipulative: number; psychopath: number; misguided: number };
  } | null;

  // Scoring methodology version. 1 = legacy binary-derived, 2 = graduated
  // distribution (Phase 2). Do NOT compare v1 and v2 records as if they
  // used the same methodology — Noah's drift corridor enforces this guard.
  scoringVersion: 1 | 2;
  
  verifyUrl: string;       // URL to verify this result
  completedAt: string;     // ISO timestamp
  
  versions: {
    sdk: string;           // SDK version used
    questionSet: string;   // Question set version
  };
  
  keyName: string;         // Name of Health Check Key used
  
  // Ethereum-verified question bank (v1.2.12+)
  bankVerification: {
    bankVersionId: string;    // Question bank version ID
    bankHash: string | null;  // SHA256 hash of questions
    version: string;          // Semantic version (e.g., "1.0.0")
    lockedAt: string | null;  // ISO timestamp when locked
    ethereumTxHash: string | null;  // ETH tx hash (on-chain proof)
    etherscanUrl: string | null;    // Direct Etherscan link
  };
}

const result = await client.assess(callback);

// Get the verification URL
console.log(`Verify at: ${result.verifyUrl}`);
// https://aiassesstech.com/verify/result/clx123abc...

// The verification page shows:
// ✓ Assessment date and time
// ✓ Scores for all 4 dimensions
// ✓ Pass/fail status
// ✓ Classification result
// ✓ Cryptographic hash proof

<!-- AI Assess Tech Attestation Badge -->
<a href="https://www.aiassesstech.com/verify/YOUR_RUN_ID">
  <img 
    src="https://www.aiassesstech.com/badge/YOUR_RUN_ID" 
    alt="AI Attestation Status"
  />
</a>

const result = await client.assess(callback);

// Display ETH verification to users
console.log(`Bank Version: ${result.bankVerification.version}`);
console.log(`Locked At: ${result.bankVerification.lockedAt}`);
console.log(`Bank Hash: ${result.bankVerification.bankHash}`);

// Link to Etherscan for on-chain proof
if (result.bankVerification.etherscanUrl) {
  console.log(`Verify on Ethereum: ${result.bankVerification.etherscanUrl}`);
  // Opens: https://etherscan.io/tx/0xea1c7c85fb5902b0db213f444c4a30...
}

const client = new AIAssessClient({
  // Required: Your Health Check Key from the dashboard
  healthCheckKey: 'hck_...',
  
  // Optional: Override base URL (default: https://www.aiassesstech.com)
  baseUrl: 'https://www.aiassesstech.com',
  
  // Optional: Per-question timeout in ms (default: 30000 = 30s)
  perQuestionTimeoutMs: 30000,
  
  // Optional: Overall timeout in ms (default: 360000 = 6 min)
  overallTimeoutMs: 360000
});

import { 
  AIAssessClient, 
  SDKError, 
  ValidationError, 
  RateLimitError,
  QuestionTimeoutError,
  ErrorCode 
} from '@aiassesstech/sdk';

try {
  const result = await client.assess(callback);
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfterMs}ms`);
  } else if (error instanceof ValidationError) {
    if (error.code === ErrorCode.KEY_EXPIRED) {
      console.log('Health Check Key has expired');
    } else if (error.code === ErrorCode.INVALID_KEY) {
      console.log('Invalid Health Check Key');
    }
  } else if (error instanceof QuestionTimeoutError) {
    console.log(`Question ${error.questionId} timed out`);
  } else if (error instanceof SDKError) {
    console.log(`SDK Error: ${error.message} (${error.code})`);
  }
}

name: AI Ethics Health Check

on:
  push:
    branches: [main]
  schedule:
    - cron: "0 */6 * * *" # Every 6 hours

jobs:
  health-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: npm install @aiassesstech/sdk openai

      - name: Run AI Health Check
        env:
          AIASSESS_KEY: ${{ secrets.AIASSESS_KEY }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          node -e "
            const { AIAssessClient } = require('@aiassesstech/sdk');
            const OpenAI = require('openai');
            
            const openai = new OpenAI();
            const client = new AIAssessClient({ 
              healthCheckKey: process.env.AIASSESS_KEY 
            });
            
            client.assess(async (q) => {
              const r = await openai.chat.completions.create({
                model: 'gpt-4',
                messages: [{ role: 'user', content: q }]
              });
              return r.choices[0].message.content;
            }).then(result => {
              console.log('Classification:', result.classification);
              console.log('Scores:', JSON.stringify(result.scores));
              process.exit(result.overallPassed ? 0 : 1);
            }).catch(err => {
              console.error('Error:', err.message);
              process.exit(2);
            });
          "

const result = await client.assess(
  async (question) => await myAI.chat(question),
  {
    metadata: {
      gitCommit: process.env.GITHUB_SHA,
      branch: process.env.GITHUB_REF_NAME,
      deployVersion: process.env.VERSION,
      environment: process.env.NODE_ENV
    }
  }
);

// Exit code for CI/CD
// 0 = passed, 1 = failed, 2 = error
process.exit(result.overallPassed ? 0 : 1);

import { detectEnvironment, isCI } from '@aiassesstech/sdk';

console.log('Is CI:', isCI());
console.log('Environment:', detectEnvironment());
// {
//   nodeVersion: 'v20.10.0',
//   platform: 'linux',
//   ciProvider: 'github-actions',
//   ciJobId: '12345678',
//   gitCommit: 'abc123...',
//   gitBranch: 'main'
// }

import { withRetry } from '@aiassesstech/sdk';

const resilientCallback = withRetry(
  async (question) => await flakyAPI.chat(question),
  {
    maxRetries: 3,      // Number of retry attempts
    backoffMs: 1000,    // Initial backoff delay
    backoffMultiplier: 2 // Exponential backoff multiplier
  }
);

const result = await client.assess(resilientCallback);

{
  "event": "assessment.completed",
  "runId": "clx123abc...",
  "timestamp": "2026-02-15T10:30:00Z",
  "result": {
    "overallPassed": true,
    "classification": "Well Adjusted",
    "scores": {
      "lying": 8.5,
      "cheating": 9.0,
      "stealing": 8.7,
      "harm": 9.2
    },
    "scoringVersion": 2,
    "personalityDistribution": {
      "personality": {
        "lying":    { "wellAdjusted": 25, "manipulative": 2, "psychopath": 1, "misguided": 2 },
        "cheating": { "wellAdjusted": 27, "manipulative": 1, "psychopath": 1, "misguided": 1 },
        "stealing": { "wellAdjusted": 26, "manipulative": 2, "psychopath": 1, "misguided": 1 },
        "harm":     { "wellAdjusted": 28, "manipulative": 1, "psychopath": 0, "misguided": 1 }
      },
      "aggregate":  { "wellAdjusted": 106, "manipulative": 6, "psychopath": 3, "misguided": 5 }
    }
  },
  "metadata": {
    "keyName": "prod-strict",
    "environment": "production"
  }
}

import asyncio
import os
from aiassess import AsyncAIAssessClient

async def main():
    async with AsyncAIAssessClient(
        health_check_key=os.environ["AIASSESS_KEY"]
    ) as client:
        
        async def my_async_callback(question: str) -> str:
            # Your async AI logic here
            return await my_async_ai.chat(question)
        
        result = await client.assess(my_async_callback)
        print(f"Passed: {result.overall_passed}")

asyncio.run(main())

# Run assessment with OpenAI
aiassess run --provider openai --model gpt-4

# Run with Anthropic
aiassess run --provider anthropic --model claude-3-sonnet-20240229

# Dry run mode (fewer questions, mock scores)
aiassess run --provider openai --model gpt-4 --dry-run

# Check SDK version
aiassess --version

from aiassess import AIAssessClient

with AIAssessClient(health_check_key=key) as client:
    def on_progress(progress):
        print(f"{progress.percentage}% - Testing {progress.dimension}")
    
    result = client.assess(
        callback=my_callback,
        on_progress=on_progress
    )

from aiassess import AIAssessClient

with AIAssessClient(health_check_key=key) as client:
    # Block until AI passes - raises exception on failure
    client.block_until_pass(
        callback=my_callback,
        max_retries=3,
        retry_delay_seconds=60
    )
    
    print("✅ AI passed ethical assessment, starting app...")
    start_app()

from aiassess import (
    AIAssessClient,
    AIAssessError,
    RateLimitError,
    ValidationError,
    QuestionTimeoutError,
)

try:
    with AIAssessClient(health_check_key=key) as client:
        result = client.assess(my_callback)
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after_seconds}s")
except ValidationError as e:
    if e.code == "KEY_EXPIRED":
        print("Health Check Key has expired")
    elif e.code == "INVALID_KEY":
        print("Invalid Health Check Key")
except QuestionTimeoutError as e:
    print(f"Question {e.question_id} timed out")
except AIAssessError as e:
    print(f"SDK Error: {e.message} ({e.code})")

from aiassess.models import AssessmentResult, Scores

result: AssessmentResult = client.assess(my_callback)

# Full IDE autocompletion and type checking
scores: Scores = result.scores
print(f"Lying: {scores.lying}")      # float
print(f"Cheating: {scores.cheating}")  # float
print(f"Overall: {result.overall_passed}")  # bool
print(f"Classification: {result.classification}")  # Literal type