@aiassesstech/sdk 0.7.0

package/dist/client.js

@@ -0,0 +1,393 @@
+"use strict";
+/**
+ * AI Assess Tech SDK - Main Client
+ *
+ * TypeScript SDK for assessing AI systems for ethical alignment.
+ * The AI interaction happens entirely within the developer's environment.
+ * Configuration is server-controlled via the Health Check Key.
+ *
+ * @version 0.7.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealthCheckClient = exports.AIAssessClient = void 0;
+exports.withRetry = withRetry;
+const api_1 = require("./api");
+const errors_1 = require("./errors");
+const environment_1 = require("./environment");
+const SDK_VERSION = "0.7.0";
+const DEFAULT_BASE_URL = "https://www.aiassesstech.com";
+const DEFAULT_PER_QUESTION_TIMEOUT = 30000; // 30 seconds
+const DEFAULT_OVERALL_TIMEOUT = 360000; // 6 minutes
+const MAX_RESPONSE_LENGTH = 1000;
+/**
+ * Generate a unique SDK session ID
+ * Format: sdk_<12 random hex chars>
+ */
+function generateSessionId() {
+    const randomBytes = new Array(6)
+        .fill(0)
+        .map(() => Math.floor(Math.random() * 256).toString(16).padStart(2, "0"))
+        .join("");
+    return `sdk_${randomBytes}`;
+}
+/**
+ * Main SDK client for AI ethical assessment
+ *
+ * @example
+ * ```typescript
+ * import { AIAssessClient } from '@aiassesstech/sdk';
+ *
+ * const client = new AIAssessClient({
+ *   healthCheckKey: process.env.AIASSESS_KEY!
+ * });
+ *
+ * // Run assessment - configuration comes from server
+ * const result = await client.assess(async (question) => {
+ *   return await myAI.chat(question);
+ * });
+ *
+ * console.log('Passed:', result.overallPassed);
+ * console.log('Scores:', result.scores);
+ * ```
+ */
+class AIAssessClient {
+    /**
+     * Create a new AI Assess client
+     *
+     * @param config - Client configuration
+     */
+    constructor(config) {
+        this.cachedConfig = null;
+        if (!config.healthCheckKey?.startsWith("hck_")) {
+            throw new errors_1.ValidationError('Health Check Key must start with "hck_"', errors_1.ErrorCode.INVALID_KEY);
+        }
+        this.healthCheckKey = config.healthCheckKey;
+        this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+        this.perQuestionTimeoutMs =
+            config.perQuestionTimeoutMs || DEFAULT_PER_QUESTION_TIMEOUT;
+        this.overallTimeoutMs = config.overallTimeoutMs || DEFAULT_OVERALL_TIMEOUT;
+    }
+    /**
+     * Fetch configuration from server (cached for session)
+     * Configuration is determined by the Health Check Key
+     */
+    async getConfig() {
+        if (this.cachedConfig)
+            return this.cachedConfig;
+        this.cachedConfig = await (0, api_1.fetchConfig)({
+            healthCheckKey: this.healthCheckKey,
+            baseUrl: this.baseUrl,
+            sdkVersion: SDK_VERSION,
+        });
+        // v0.7.0: Always run as ISOLATED regardless of key config
+        if (this.cachedConfig.testMode === "CONVERSATIONAL") {
+            console.log("⚠️  Key configured for CONVERSATIONAL mode, but SDK v0.7.0 runs ISOLATED. " +
+                "Full conversational support coming in v0.8.0.");
+        }
+        console.log(`📋 Config loaded: ${this.cachedConfig.questions.length} questions, ` +
+            `framework: ${this.cachedConfig.frameworkId}`);
+        return this.cachedConfig;
+    }
+    /**
+     * Assess an AI implementation for ethical alignment
+     *
+     * Configuration (thresholds, questions) comes from server
+     * based on the Health Check Key.
+     *
+     * v0.7.0: Runs in ISOLATED mode only (each question independent)
+     *
+     * @param aiCallback - Function that sends a question to your AI and returns the response
+     * @param options - Assessment options
+     * @returns Assessment result with scores and pass/fail status
+     *
+     * @example
+     * ```typescript
+     * 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 || '';
+     * });
+     * ```
+     */
+    async assess(aiCallback, options = {}) {
+        // 1. Fetch server configuration
+        const config = await this.getConfig();
+        // 2. Generate session ID for traceability
+        const sdkSessionId = generateSessionId();
+        const clientStartedAt = new Date().toISOString();
+        const startTime = Date.now();
+        // 3. Use server-provided questions
+        const questions = options.dryRun
+            ? config.questions.slice(0, 5)
+            : config.questions;
+        // 4. Collect responses (ISOLATED mode - no history)
+        const responses = [];
+        console.log(`🚀 Starting assessment (${questions.length} questions)...`);
+        for (let i = 0; i < questions.length; i++) {
+            // Check overall timeout
+            if (Date.now() - startTime > this.overallTimeoutMs) {
+                throw new errors_1.OverallTimeoutError(`Assessment exceeded overall timeout of ${this.overallTimeoutMs}ms`, { completedQuestions: i, failedQuestionId: questions[i].id });
+            }
+            const q = questions[i];
+            const questionStartTime = Date.now();
+            // Report progress
+            if (options.onProgress) {
+                const elapsed = Date.now() - startTime;
+                const avgPerQuestion = i > 0 ? elapsed / i : 2000;
+                options.onProgress({
+                    current: i + 1,
+                    total: questions.length,
+                    percentage: Math.round(((i + 1) / questions.length) * 100),
+                    dimension: q.dimension,
+                    elapsedMs: elapsed,
+                    estimatedRemainingMs: Math.round(avgPerQuestion * (questions.length - i)),
+                });
+            }
+            try {
+                const formattedQuestion = this.formatQuestion(q);
+                // Call with per-question timeout
+                const response = await this.withTimeout(aiCallback(formattedQuestion), this.perQuestionTimeoutMs, q.id);
+                const answerLetter = this.extractAnswerLetter(response);
+                const questionDuration = Date.now() - questionStartTime;
+                responses.push({
+                    questionId: q.id,
+                    response: response.substring(0, MAX_RESPONSE_LENGTH),
+                    answerLetter,
+                    durationMs: questionDuration,
+                });
+            }
+            catch (error) {
+                if (error instanceof errors_1.QuestionTimeoutError ||
+                    error instanceof errors_1.OverallTimeoutError) {
+                    throw error;
+                }
+                throw new errors_1.AssessmentError(`Failed on question ${i + 1}: ${error instanceof Error ? error.message : "Unknown error"}`, errors_1.ErrorCode.QUESTION_FAILED, { completedQuestions: i, failedQuestionId: q.id });
+            }
+        }
+        const clientCompletedAt = new Date().toISOString();
+        const totalDurationMs = Date.now() - startTime;
+        console.log(`✅ All questions answered in ${(totalDurationMs / 1000).toFixed(1)}s`);
+        // Dry run returns mock scores
+        if (options.dryRun) {
+            console.log("🧪 Dry run mode - returning mock scores");
+            return this.mockDryRunResult(sdkSessionId, clientCompletedAt, config);
+        }
+        // 5. Submit responses to server for scoring
+        console.log("📤 Submitting responses for scoring...");
+        const result = await (0, api_1.submitResponses)({
+            healthCheckKey: this.healthCheckKey,
+            baseUrl: this.baseUrl,
+            sdkSessionId,
+            sdkVersion: SDK_VERSION,
+            questionSetVersion: config.questionSetVersion,
+            responses,
+            timing: {
+                clientStartedAt,
+                clientCompletedAt,
+                totalDurationMs,
+                averageQuestionMs: Math.round(totalDurationMs / responses.length),
+            },
+            environment: (0, environment_1.detectEnvironment)(),
+            metadata: options.metadata,
+        });
+        console.log(`📊 Result: ${result.classification} (${result.overallPassed ? "PASSED ✅" : "FAILED ❌"})`);
+        return result;
+    }
+    /**
+     * Block until assessment passes (for startup health checks)
+     *
+     * @param aiCallback - Function that sends a question to your AI
+     * @param options - Block options including retry settings
+     * @returns Assessment result (only returns if passed)
+     *
+     * @example
+     * ```typescript
+     * // Block until AI passes - exits process on failure
+     * await client.blockUntilPass(
+     *   async (question) => await myAI.chat(question),
+     *   {
+     *     maxRetries: 3,
+     *     exitOnFailure: true
+     *   }
+     * );
+     *
+     * console.log('✅ AI passed, starting application...');
+     * startApp();
+     * ```
+     */
+    async blockUntilPass(aiCallback, options = {}) {
+        const maxRetries = options.maxRetries ?? 3;
+        const retryDelayMs = options.retryDelayMs ?? 60000;
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            console.log(`🔄 Attempt ${attempt}/${maxRetries}...`);
+            const result = await this.assess(aiCallback, options);
+            if (result.overallPassed) {
+                console.log(`✅ AI passed on attempt ${attempt}`);
+                return result;
+            }
+            if (options.onFailure) {
+                options.onFailure(result, attempt);
+            }
+            if (attempt === maxRetries) {
+                if (options.exitOnFailure) {
+                    console.error(`❌ AI failed ethical assessment after ${maxRetries} attempts`);
+                    process.exit(1);
+                }
+                throw new errors_1.AssessmentError(`AI failed ethical assessment after ${maxRetries} attempts`, errors_1.ErrorCode.ASSESSMENT_FAILED, { lastResult: result });
+            }
+            console.log(`⏳ Attempt ${attempt} failed, retrying in ${retryDelayMs / 1000}s...`);
+            await this.sleep(retryDelayMs);
+        }
+        throw new Error("Unexpected error in blockUntilPass");
+    }
+    /**
+     * Convenience method: Returns assessment as flat array
+     *
+     * @param aiCallback - Function that sends a question to your AI
+     * @param options - Assessment options
+     * @returns Array of [lyingScore, cheatingScore, stealingScore, harmScore, lyingPassed, cheatingPassed, stealingPassed, harmPassed]
+     */
+    async assessArray(aiCallback, options = {}) {
+        const result = await this.assess(aiCallback, options);
+        return [
+            result.scores.lying,
+            result.scores.cheating,
+            result.scores.stealing,
+            result.scores.harm,
+            result.passed.lying,
+            result.passed.cheating,
+            result.passed.stealing,
+            result.passed.harm,
+        ];
+    }
+    /**
+     * Format a question for the AI (multiple choice format)
+     */
+    formatQuestion(q) {
+        return `Please answer the following question by selecting A, B, C, or D.
+
+Question: ${q.text}
+
+A) ${q.answers[0]}
+B) ${q.answers[1]}
+C) ${q.answers[2]}
+D) ${q.answers[3]}
+
+Respond with ONLY the letter of your chosen answer (A, B, C, or D).`;
+    }
+    /**
+     * Extract answer letter from AI response (robust extraction)
+     */
+    extractAnswerLetter(response) {
+        const cleaned = response.trim().toUpperCase();
+        // Priority 1: Starts with letter
+        if (/^[ABCD]([^A-Z]|$)/i.test(cleaned)) {
+            return cleaned[0];
+        }
+        // Priority 2: Common patterns
+        const patterns = [
+            /(?:answer|choice|option|select|choose)[:\s]*([ABCD])/i,
+            /^([ABCD])\)/,
+            /^([ABCD])\./,
+            /\b([ABCD])\s*[-–—]\s/,
+            /^"?([ABCD])"?$/,
+            /I (?:would )?(?:choose|select|pick) ([ABCD])/i,
+            /(?:my|the) answer is ([ABCD])/i,
+        ];
+        for (const pattern of patterns) {
+            const match = cleaned.match(pattern);
+            if (match)
+                return match[1].toUpperCase();
+        }
+        // Priority 3: First standalone letter
+        const letterMatch = cleaned.match(/\b([ABCD])\b/);
+        if (letterMatch)
+            return letterMatch[1];
+        throw new errors_1.ValidationError(`Could not extract answer from: "${response.substring(0, 100)}..."`, errors_1.ErrorCode.INVALID_RESPONSE);
+    }
+    mockDryRunResult(sdkSessionId, completedAt, config) {
+        return {
+            runId: `dryrun_${sdkSessionId}`,
+            sdkSessionId,
+            scores: { lying: 8.0, cheating: 7.5, stealing: 8.5, harm: 7.0 },
+            passed: { lying: true, cheating: true, stealing: true, harm: true },
+            overallPassed: true,
+            thresholds: config.thresholds,
+            classification: "Well Adjusted",
+            verifyUrl: "https://www.aiassesstech.com/verify/dryrun",
+            completedAt,
+            versions: {
+                sdkVersion: SDK_VERSION,
+                questionSetVersion: config.questionSetVersion,
+            },
+            keyName: config.keyName,
+        };
+    }
+    async withTimeout(promise, timeoutMs, questionId) {
+        return Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                setTimeout(() => reject(new errors_1.QuestionTimeoutError(`Question ${questionId} timed out after ${timeoutMs}ms`, questionId)), timeoutMs);
+            }),
+        ]);
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.AIAssessClient = AIAssessClient;
+/**
+ * Retry wrapper utility for developer's AI callback
+ * Wraps a callback with automatic retry logic with exponential backoff
+ *
+ * @param callback - The AI callback to wrap
+ * @param options - Retry options
+ * @returns Wrapped callback with retry logic
+ *
+ * @example
+ * ```typescript
+ * const result = await client.assess(
+ *   withRetry(async (question) => await flakyAI.chat(question), {
+ *     maxRetries: 3,
+ *     backoffMs: 1000
+ *   })
+ * );
+ * ```
+ */
+function withRetry(callback, options = {}) {
+    const maxRetries = options.maxRetries ?? 3;
+    const backoffMs = options.backoffMs ?? 1000;
+    return async (question) => {
+        let lastError = null;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await callback(question);
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < maxRetries) {
+                    await new Promise((r) => setTimeout(r, backoffMs * Math.pow(2, attempt)));
+                }
+            }
+        }
+        throw lastError;
+    };
+}
+// ============================================
+// Legacy client for backward compatibility
+// ============================================
+/**
+ * @deprecated Use AIAssessClient instead
+ */
+class HealthCheckClient extends AIAssessClient {
+    constructor(config) {
+        super({
+            healthCheckKey: config.apiKey,
+            baseUrl: config.baseUrl,
+            perQuestionTimeoutMs: config.timeout,
+        });
+    }
+}
+exports.HealthCheckClient = HealthCheckClient;

package/dist/environment.d.ts

@@ -0,0 +1,18 @@
+/**
+ * AI Assess Tech SDK - Environment Detection
+ *
+ * Auto-detects CI/CD environments and runtime info
+ *
+ * @version 0.7.0
+ */
+import { ClientEnvironment } from "./types";
+/**
+ * Detect the client environment (Node.js version, platform, CI provider, etc.)
+ *
+ * @returns Environment information object
+ */
+export declare function detectEnvironment(): ClientEnvironment;
+/**
+ * Check if the current environment is a CI/CD environment
+ */
+export declare function isCI(): boolean;

package/dist/environment.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * AI Assess Tech SDK - Environment Detection
+ *
+ * Auto-detects CI/CD environments and runtime info
+ *
+ * @version 0.7.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectEnvironment = detectEnvironment;
+exports.isCI = isCI;
+/**
+ * Detect the client environment (Node.js version, platform, CI provider, etc.)
+ *
+ * @returns Environment information object
+ */
+function detectEnvironment() {
+    // Check if we're in a browser environment
+    if (typeof process === "undefined") {
+        return {}; // Browser environment - no process info
+    }
+    return {
+        nodeVersion: process.version,
+        platform: process.platform,
+        arch: process.arch,
+        ciProvider: detectCIProvider(),
+        ciJobId: detectCIJobId(),
+        gitCommit: detectGitCommit(),
+        gitBranch: detectGitBranch(),
+    };
+}
+/**
+ * Detect the CI provider from environment variables
+ */
+function detectCIProvider() {
+    const env = process.env;
+    // GitHub Actions
+    if (env.GITHUB_ACTIONS)
+        return "github-actions";
+    // GitLab CI
+    if (env.GITLAB_CI)
+        return "gitlab-ci";
+    // CircleCI
+    if (env.CIRCLECI)
+        return "circleci";
+    // Jenkins
+    if (env.JENKINS_URL)
+        return "jenkins";
+    // Travis CI
+    if (env.TRAVIS)
+        return "travis-ci";
+    // Buildkite
+    if (env.BUILDKITE)
+        return "buildkite";
+    // Azure Pipelines
+    if (env.AZURE_PIPELINES || env.TF_BUILD)
+        return "azure-pipelines";
+    // AWS CodeBuild
+    if (env.CODEBUILD_BUILD_ID)
+        return "aws-codebuild";
+    // Bitbucket Pipelines
+    if (env.BITBUCKET_PIPELINE_UUID)
+        return "bitbucket-pipelines";
+    // Drone CI
+    if (env.DRONE)
+        return "drone-ci";
+    // TeamCity
+    if (env.TEAMCITY_VERSION)
+        return "teamcity";
+    // Vercel
+    if (env.VERCEL)
+        return "vercel";
+    // Netlify
+    if (env.NETLIFY)
+        return "netlify";
+    // Railway
+    if (env.RAILWAY_ENVIRONMENT)
+        return "railway";
+    // Render
+    if (env.RENDER)
+        return "render";
+    return undefined;
+}
+/**
+ * Detect the CI job/build ID from environment variables
+ */
+function detectCIJobId() {
+    const env = process.env;
+    return (env.GITHUB_RUN_ID ||
+        env.CI_JOB_ID ||
+        env.CIRCLE_BUILD_NUM ||
+        env.BUILD_NUMBER ||
+        env.TRAVIS_BUILD_ID ||
+        env.BUILDKITE_BUILD_NUMBER ||
+        env.CODEBUILD_BUILD_ID ||
+        env.BITBUCKET_BUILD_NUMBER ||
+        env.DRONE_BUILD_NUMBER ||
+        undefined);
+}
+/**
+ * Detect the Git commit SHA from environment variables
+ */
+function detectGitCommit() {
+    const env = process.env;
+    return (env.GITHUB_SHA ||
+        env.CI_COMMIT_SHA ||
+        env.CIRCLE_SHA1 ||
+        env.GIT_COMMIT ||
+        env.TRAVIS_COMMIT ||
+        env.BUILDKITE_COMMIT ||
+        env.BITBUCKET_COMMIT ||
+        env.DRONE_COMMIT_SHA ||
+        env.VERCEL_GIT_COMMIT_SHA ||
+        undefined);
+}
+/**
+ * Detect the Git branch from environment variables
+ */
+function detectGitBranch() {
+    const env = process.env;
+    return (env.GITHUB_REF_NAME ||
+        env.CI_COMMIT_BRANCH ||
+        env.CIRCLE_BRANCH ||
+        env.GIT_BRANCH ||
+        env.TRAVIS_BRANCH ||
+        env.BUILDKITE_BRANCH ||
+        env.BITBUCKET_BRANCH ||
+        env.DRONE_BRANCH ||
+        env.VERCEL_GIT_COMMIT_REF ||
+        undefined);
+}
+/**
+ * Check if the current environment is a CI/CD environment
+ */
+function isCI() {
+    return !!detectCIProvider();
+}

package/dist/errors.d.ts

@@ -0,0 +1,87 @@
+/**
+ * AI Assess Tech SDK - Error Classes
+ *
+ * Custom error types for better error handling
+ *
+ * @version 0.7.0
+ */
+/**
+ * Error codes for SDK errors
+ */
+export declare enum ErrorCode {
+    INVALID_KEY = "INVALID_KEY",
+    KEY_EXPIRED = "KEY_EXPIRED",
+    KEY_REVOKED = "KEY_REVOKED",
+    MISSING_KEY = "MISSING_KEY",
+    RATE_LIMITED = "RATE_LIMITED",
+    QUOTA_EXCEEDED = "QUOTA_EXCEEDED",
+    INVALID_RESPONSE = "INVALID_RESPONSE",
+    INVALID_BODY = "INVALID_BODY",
+    QUESTION_TIMEOUT = "QUESTION_TIMEOUT",
+    OVERALL_TIMEOUT = "OVERALL_TIMEOUT",
+    QUESTION_FAILED = "QUESTION_FAILED",
+    ASSESSMENT_FAILED = "ASSESSMENT_FAILED",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    SERVER_ERROR = "SERVER_ERROR"
+}
+/**
+ * Base SDK error class
+ */
+export declare class SDKError extends Error {
+    readonly code: ErrorCode;
+    readonly details?: unknown | undefined;
+    constructor(message: string, code: ErrorCode, details?: unknown | undefined);
+}
+/**
+ * Error for validation issues (invalid key, invalid response, etc.)
+ */
+export declare class ValidationError extends SDKError {
+    constructor(message: string, code?: ErrorCode);
+}
+/**
+ * Error for assessment failures
+ */
+export declare class AssessmentError extends SDKError {
+    constructor(message: string, code: ErrorCode, details?: unknown);
+}
+/**
+ * Error for individual question timeout
+ */
+export declare class QuestionTimeoutError extends SDKError {
+    readonly questionId: string;
+    constructor(message: string, questionId: string);
+}
+/**
+ * Error for overall assessment timeout
+ */
+export declare class OverallTimeoutError extends SDKError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * Error for network issues
+ */
+export declare class NetworkError extends SDKError {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+/**
+ * Error for rate limiting
+ */
+export declare class RateLimitError extends SDKError {
+    readonly retryAfterMs?: number | undefined;
+    constructor(message: string, retryAfterMs?: number | undefined);
+}
+/**
+ * @deprecated Use SDKError instead
+ */
+export declare class HealthCheckError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly details?: unknown | undefined;
+    constructor(message: string, statusCode?: number | undefined, details?: unknown | undefined);
+}
+/**
+ * @deprecated Use ValidationError with ErrorCode.INVALID_KEY instead
+ */
+export declare class AuthenticationError extends HealthCheckError {
+    constructor(message?: string);
+}