# SDK Documentation

Official SDKs for integrating AI Assess Tech assessments into your applications. Privacy-first design — your AI API keys and system prompts never leave your environment.

**Current version**: v0.7.2

## Installation

### TypeScript / Node.js

```bash
npm install @aiassesstech/sdk
# or
yarn add @aiassesstech/sdk
# or
pnpm add @aiassesstech/sdk
```

### Python

```bash
pip install aiassess
# or
poetry add aiassess
```

## Quick Start

### TypeScript

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

const client = new AIAssessClient({
  healthCheckKey: 'hck_your_key_here',
});

const result = await client.assess({
  provider: 'openai',
  model: 'gpt-4o',
  assess: async (question) => {
    // Call your AI and return its response
    return await yourAI.chat(question);
  },
});

console.log(`Score: ${result.compositeScore}/10`);
console.log(`Classification: ${result.classification}`);
console.log(`Passed: ${result.passed}`);
```

### Python

```python
from aiassess import AIAssessClient

client = AIAssessClient(health_check_key="hck_your_key_here")

result = client.assess(
    provider="openai",
    model="gpt-4o",
    assess=lambda question: your_ai.chat(question),
)

print(f"Score: {result.composite_score}/10")
print(f"Classification: {result.classification}")
print(f"Passed: {result.passed}")
```

## Supported Providers

| Provider | Models | Notes |
|----------|--------|-------|
| OpenAI | GPT-4, GPT-4o, GPT-4o-mini | Recommended starting point |
| Anthropic | Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku | Strong ethical performance |
| Google | Gemini Pro, Gemini 1.5, Gemini 2.0 | Free tier available |
| xAI | Grok 3, Grok 3 Mini | $25 free credits |
| Custom | Any model | Bring your own inference |

## How It Works

1. SDK fetches assessment configuration from AI Assess Tech server (questions, thresholds, mode)
2. SDK sends each question to YOUR AI via the callback function (your API key never leaves your environment)
3. SDK submits the AI's responses to AI Assess Tech for scoring
4. Server returns scored results with cryptographic verification

**Privacy guarantee**: Your AI API keys and system prompts are never sent to AI Assess Tech. The SDK runs the AI interaction locally in your environment.

## Security Architecture

**Server enforces**: Rate limiting, scoring thresholds, API key validation, tier restrictions, result integrity.

**Private data (never sent)**: AI API keys, system prompts.

### Rate Limits by Tier

Hourly and daily limits protect against burst abuse. Monthly included counts and overage rates match [aiassesstech.com/pricing](https://www.aiassesstech.com/pricing).

| Tier | Hourly | Daily | Monthly Included | Overage |
|------|--------|-------|------------------|---------|
| Free Trial | 5 | 10 | 20 | — |
| Demo | 5 per IP | 10 | — | — |
| Starter | 20 | 50 | 200 | $0.25 |
| Professional | 50 | 150 | 500 | $0.20 |
| Business | 100 | 400 | 1,500 | $0.16 |
| Scale | 250 | 1,000 | 4,000 | $0.125 |
| Enterprise | 1,000 | 3,000 | 10,000 | $0.10 |

## Assessment Results

Results include:
- `compositeScore` — Average across all four dimensions (0-10)
- `dimensions` — Individual scores for Lying, Cheating, Stealing, Harm
- `passed` — Boolean per dimension and overall
- `classification` — Well Adjusted, Misguided, Manipulative, or Psychopath
- `verificationUrl` — Tamper-proof, shareable URL for the result
- `bankHash` — SHA-256 hash proof
- `ethTxHash` — Ethereum transaction hash (when available)

## Error Handling

| Error | Cause | Resolution |
|-------|-------|------------|
| `RateLimitError` | Too many assessments in time window | Wait and retry, or upgrade tier |
| `ValidationError` | Invalid configuration or API key | Check healthCheckKey and provider config |
| `QuestionTimeoutError` | AI took too long to respond | Increase timeout or use faster model |
| `SDKError` | General SDK error | Check error message for details |

## CI/CD Integration

The SDK auto-detects 12 CI providers (GitHub Actions, GitLab CI, CircleCI, Jenkins, Travis CI, Buildkite, Azure Pipelines, AWS CodeBuild, Bitbucket Pipelines, Drone CI, Vercel, Netlify) and adds environment metadata to assessment results for traceability.

## Getting a Health Check Key

1. Sign in at https://www.aiassesstech.com
2. Go to Settings > Health Check Keys
3. Click "Create New Key"
4. Copy the key (starts with `hck_`)
5. Use it in your SDK client configuration

## Requirements

- **TypeScript SDK**: Node.js 18+
- **Python SDK**: Python 3.8+, Pydantic v2

## Links

- npm: https://www.npmjs.com/package/@aiassesstech/sdk
- PyPI: https://pypi.org/project/aiassess/
- Documentation: https://www.aiassesstech.com/docs/sdk
- Support: support@aiassesstech.com

## Changelog

### 2026-10-16 — Question plans

`POST /api/sdk/assess` accepts optional `questionPlan` (`screen`, `full`, or `adaptive`), `screenThreshold` (an integer from 50 to 100, required for `adaptive`), and `supportsContinuation`. When `supportsContinuation` is `true` and `questionPlan` is omitted, the organization default applies. When `supportsContinuation` is omitted, the run is a full bank.

A response may include `questionsPlanned`, `coverage`, `continueFullBank`, `remainingQuestionIds`, and `modeOverride`. A screen stops at 36. A full bank is 120. An adaptive run under the threshold returns `continueFullBank: true` and the remaining ids. A bank that is not 12 principles by 10 questions stores `questionPlan: "full"` and records `modeOverride: "bank_not_12x10"`.

`locked: false` on the run means the result is not a full-bank attestation. The result hash stays locked, and the verify URL still verifies. A client that treats `locked: false` as incomplete will misread a finished screen.

Verify JSON adds `questionPlan`, `questionsAnswered`, `coverage`, `screenThreshold`, `screenScore`, and `screenAxisScores`. The bank size stays 120. On a completed webhook, `questionCount` is the number answered and `bankQuestionCount` is the bank size. A finished screen reports `questionCount` 36. The webhook fires when status becomes `completed`, including a trial whose `coverage` is null. It does not fire while `coverage` is `screen_running` or `continuing`. An expired run fires none.

New error codes: `question_plan_invalid` (400), `screen_threshold_required` (400), `screen_threshold_out_of_range` (400), `run_expired` (409), and `screen_not_certifiable` (422). A certificate request for a screen run id returns 422. A full-bank or legacy run id still issues.

`@aiassesstech/sdk` 0.10.0 sends `supportsContinuation: true` and follows `continueFullBank`. That version publishes after the server release. A client that omits `supportsContinuation` receives a full bank. The CLI prints 9 per dimension and 36 in total for a screen, and 30 and 120 for a full bank.

Python `aiassess` 0.7.0 stays on the full bank. It does not send `supportsContinuation`.