@aiassesstech/sdk 0.7.0

package/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2025 AI Assess Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+
+
+
+
+
+

package/README.md

@@ -0,0 +1,350 @@
+# AI Assess Tech SDK
+
+Official TypeScript SDK for assessing AI systems for ethical alignment. Test your AI across 4 dimensions: **Lying**, **Cheating**, **Stealing**, and **Harm**.
+
+[![npm version](https://badge.fury.io/js/@aiassesstech%2Fsdk.svg)](https://www.npmjs.com/package/@aiassesstech/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🔒 **Privacy-First**: Your AI's API keys, system prompts, and configuration never leave your environment
+- 🎯 **Server-Controlled**: Test configuration, questions, and thresholds managed via Health Check Key
+- 🔄 **CI/CD Ready**: Auto-detects GitHub Actions, GitLab CI, CircleCI, and more
+- 📊 **Full Traceability**: Each assessment generates IDs for audit trails
+- ⚡ **Simple Integration**: One-line assessment with any AI provider
+
+## Installation
+
+```bash
+npm install @aiassesstech/sdk
+```
+
+## Quick Start
+
+```typescript
+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 - configuration comes from server
+const result = await client.assess(async (question) => {
+  // Your AI callback - send question to your AI and return response
+  return await myAI.chat(question);
+});
+
+// 3. Check result
+console.log('Passed:', result.overallPassed);
+console.log('Scores:', result.scores);
+console.log('Classification:', result.classification);
+```
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 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       │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Usage Examples
+
+### Basic Assessment
+
+```typescript
+const result = await client.assess(async (question) => {
+  return await myAI.chat(question);
+});
+
+console.log(`Classification: ${result.classification}`);
+console.log(`Lying Score: ${result.scores.lying}/10`);
+console.log(`Overall: ${result.overallPassed ? 'PASSED ✅' : 'FAILED ❌'}`);
+```
+
+### With Progress Updates
+
+```typescript
+const result = await client.assess(
+  async (question) => await myAI.chat(question),
+  {
+    onProgress: (progress) => {
+      console.log(`${progress.percentage}% - Testing ${progress.dimension}`);
+    }
+  }
+);
+```
+
+### Startup Health Check (Blocking)
+
+```typescript
+// 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();
+```
+
+### CI/CD Pipeline Integration
+
+```typescript
+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
+    }
+  }
+);
+
+// Exit code for CI/CD
+process.exit(result.overallPassed ? 0 : 1);
+```
+
+### With OpenAI
+
+```typescript
+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 || '';
+});
+```
+
+### With Anthropic
+
+```typescript
+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 
+    : '';
+});
+```
+
+### With Retry Wrapper (for Flaky APIs)
+
+```typescript
+import { AIAssessClient, withRetry } from '@aiassesstech/sdk';
+
+const result = await client.assess(
+  withRetry(
+    async (question) => await flakyAI.chat(question),
+    { maxRetries: 3, backoffMs: 1000 }
+  )
+);
+```
+
+### Dry Run Mode (Development)
+
+```typescript
+// Only asks 5 questions, returns mock scores
+const result = await client.assess(
+  async (question) => await myAI.chat(question),
+  { dryRun: true }
+);
+```
+
+## Assessment Result
+
+The `assess()` method returns an `AssessmentResult` object:
+
+```typescript
+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
+  verifyUrl: string;       // URL to verify this result
+  completedAt: string;     // ISO timestamp
+  versions: { ... };       // SDK and question set versions
+  keyName: string;         // Name of Health Check Key used
+}
+```
+
+## Server-Controlled Configuration
+
+Configuration is managed via the **Health Check Key** on the AI Assess Tech dashboard:
+
+- **Test Mode**: ISOLATED (each question independent) or CONVERSATIONAL (coming in v0.8.0)
+- **Framework**: Which question set to use
+- **Thresholds**: Pass thresholds per dimension (0-10 scale)
+- **Rate Limits**: Hourly/monthly assessment limits
+
+Create different keys for different scenarios:
+- `prod-strict`: Production with strict thresholds
+- `staging-relaxed`: Staging with relaxed thresholds
+- `ci-quick`: CI/CD pipeline checks
+
+## Error Handling
+
+```typescript
+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})`);
+  }
+}
+```
+
+## Configuration Options
+
+```typescript
+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
+});
+```
+
+## Environment Detection
+
+The SDK automatically detects CI/CD environments:
+
+```typescript
+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'
+// }
+```
+
+Supported CI providers:
+- GitHub Actions
+- GitLab CI
+- CircleCI
+- Jenkins
+- Travis CI
+- Buildkite
+- Azure Pipelines
+- AWS CodeBuild
+- Bitbucket Pipelines
+- Drone CI
+- Vercel
+- Netlify
+- And more...
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+- Valid Health Check Key from [AI Assess Tech](https://www.aiassesstech.com)
+
+## Getting a Health Check Key
+
+1. Sign up at [https://www.aiassesstech.com](https://www.aiassesstech.com)
+2. Go to Settings → Health Check Keys
+3. Click "Create New Key"
+4. Configure your key (test mode, thresholds, rate limits)
+5. Copy the key (`hck_...`) and store it securely
+
+## Support
+
+- 📚 [Documentation](https://www.aiassesstech.com/docs)
+- 🐛 [Issue Tracker](https://github.com/aiassesstech/sdk-ts/issues)
+- 📧 [Support](mailto:support@aiassesstech.com)
+
+## License
+
+MIT © AI Assess Tech

package/dist/__tests__/__mocks__/node-fetch.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Mock for node-fetch module
+ * This ensures fetch is mocked correctly in tests
+ */
+declare const _default: typeof fetch;
+export default _default;

package/dist/__tests__/__mocks__/node-fetch.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Mock for node-fetch module
+ * This ensures fetch is mocked correctly in tests
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = global.fetch;

package/dist/__tests__/setup.d.ts

@@ -0,0 +1,3 @@
+/**
+ * Jest setup for SDK tests
+ */

package/dist/__tests__/setup.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Jest setup for SDK tests
+ */
+// Mock node-fetch globally
+global.fetch = jest.fn();
+// Mock console methods to keep test output clean
+global.console = {
+    ...console,
+    log: jest.fn(),
+    error: jest.fn(),
+    warn: jest.fn(),
+};

package/dist/api.d.ts

@@ -0,0 +1,55 @@
+/**
+ * AI Assess Tech SDK - API Functions
+ *
+ * Server communication functions for config fetching and response submission
+ *
+ * @version 0.7.0
+ */
+import { ServerConfig, AssessmentResult, ClientEnvironment } from "./types";
+/**
+ * Parameters for fetching configuration
+ */
+interface FetchConfigParams {
+    healthCheckKey: string;
+    baseUrl: string;
+    sdkVersion: string;
+}
+/**
+ * Fetch server configuration for a Health Check Key
+ *
+ * @param params - Configuration fetch parameters
+ * @returns Server configuration including questions and thresholds
+ */
+export declare function fetchConfig(params: FetchConfigParams): Promise<ServerConfig>;
+/**
+ * Parameters for submitting responses
+ */
+interface SubmitResponsesParams {
+    healthCheckKey: string;
+    baseUrl: string;
+    sdkSessionId: string;
+    sdkVersion: string;
+    questionSetVersion: string;
+    responses: Array<{
+        questionId: string;
+        response: string;
+        answerLetter: string;
+        durationMs: number;
+    }>;
+    timing: {
+        clientStartedAt: string;
+        clientCompletedAt: string;
+        totalDurationMs: number;
+        averageQuestionMs: number;
+    };
+    environment?: ClientEnvironment;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Submit responses to server for scoring
+ *
+ * @param params - Response submission parameters
+ * @returns Assessment result with scores and pass/fail
+ */
+export declare function submitResponses(params: SubmitResponsesParams): Promise<AssessmentResult>;
+export {};

package/dist/api.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * AI Assess Tech SDK - API Functions
+ *
+ * Server communication functions for config fetching and response submission
+ *
+ * @version 0.7.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchConfig = fetchConfig;
+exports.submitResponses = submitResponses;
+const errors_1 = require("./errors");
+/**
+ * Fetch server configuration for a Health Check Key
+ *
+ * @param params - Configuration fetch parameters
+ * @returns Server configuration including questions and thresholds
+ */
+async function fetchConfig(params) {
+    const response = await fetch(`${params.baseUrl}/api/sdk/config`, {
+        method: "GET",
+        headers: {
+            "X-Health-Check-Key": params.healthCheckKey,
+            "X-SDK-Version": params.sdkVersion,
+        },
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        if (response.status === 401) {
+            throw new errors_1.ValidationError(error.error || error.message || "Invalid Health Check Key", error.code === "KEY_EXPIRED"
+                ? errors_1.ErrorCode.KEY_EXPIRED
+                : errors_1.ErrorCode.INVALID_KEY);
+        }
+        if (response.status === 429) {
+            const retryAfterMs = parseInt(response.headers.get("Retry-After") || "3600") * 1000;
+            throw new errors_1.RateLimitError("Rate limit exceeded", retryAfterMs);
+        }
+        throw new errors_1.NetworkError(`Failed to fetch config: ${response.status}`, response.status);
+    }
+    return await response.json();
+}
+/**
+ * Submit responses to server for scoring
+ *
+ * @param params - Response submission parameters
+ * @returns Assessment result with scores and pass/fail
+ */
+async function submitResponses(params) {
+    const response = await fetch(`${params.baseUrl}/api/sdk/assess`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "X-Health-Check-Key": params.healthCheckKey,
+            "X-SDK-Version": params.sdkVersion,
+        },
+        body: JSON.stringify({
+            sdkSessionId: params.sdkSessionId,
+            questionSetVersion: params.questionSetVersion,
+            responses: params.responses,
+            timing: params.timing,
+            environment: params.environment,
+            metadata: params.metadata,
+        }),
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        if (response.status === 401) {
+            throw new errors_1.ValidationError(error.error || error.message || "Invalid Health Check Key", error.code === "KEY_EXPIRED"
+                ? errors_1.ErrorCode.KEY_EXPIRED
+                : errors_1.ErrorCode.INVALID_KEY);
+        }
+        if (response.status === 429) {
+            throw new errors_1.RateLimitError("Rate limit exceeded", error.retryAfterMs || parseInt(response.headers.get("Retry-After") || "3600") * 1000);
+        }
+        throw new errors_1.NetworkError(error.error || error.message || `Server error: ${response.status}`, response.status);
+    }
+    return await response.json();
+}

package/dist/cli.d.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * AI Assess Tech CLI
+ *
+ * Command-line utility for SDK operations.
+ *
+ * Note: For actual assessments, use the SDK programmatically
+ * since assessments require a custom callback to your AI.
+ *
+ * @version 0.7.0
+ */
+declare const VERSION = "0.7.0";
+/**
+ * Print CLI help
+ */
+declare function printHelp(): void;
+/**
+ * Print SDK information
+ */
+declare function printInfo(): void;
+/**
+ * Verify a test result
+ */
+declare function verify(runId: string, baseUrl: string): Promise<void>;
+/**
+ * Main CLI function
+ */
+declare function main(): Promise<void>;