# 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