@more-ink/irt-edge 2.1.3 → 2.2.0

package/README.md

@@ -1,526 +1,530 @@
-# @more-ink/irt-edge
-
-**Two packages in one:**
-1. **SDK** - Lightweight API client for JavaScript/TypeScript frontends (published to npm)
-2. **Backend Server** - Production HTTP API server built with Hono for Aliyun Function Compute (not published)
-
----
-
-## Table of Contents
-
-- [SDK Usage (Frontend)](#sdk-usage-frontend)
-  - [Installation](#installation)
-  - [Quick Start](#quick-start)
-  - [Configuration](#configuration)
-  - [API Methods](#api-methods)
-  - [Error Handling](#error-handling)
-  - [Best Practices](#best-practices)
-- [Backend Server Setup](#backend-server-setup)
-- [Backend Deployment](#backend-deployment-aliyun-fc)
-- [SDK Publishing](#sdk-publishing-npm)
-- [Package Scripts](#package-scripts)
-
----
-
-## SDK Usage (Frontend)
-
-### Installation
-
-```bash
-npm install @more-ink/irt-edge @more-ink/irt-core
-# or
-yarn add @more-ink/irt-edge @more-ink/irt-core
-```
-
-**Note:** `@more-ink/irt-core` is a peer dependency that provides type definitions.
-
-### Quick Start
-
-```typescript
-import { IrtClient } from '@more-ink/irt-edge'
-
-const client = new IrtClient({
-  baseUrl: 'https://your-api.example.com',
-  headers: {
-    'Authorization': 'Bearer YOUR_TOKEN' // Optional
-  },
-  timeout: 10000 // Optional (default: 10000ms)
-})
-
-// Record an answer and get the next item
-const result = await client.recordAnswer({
-  userId: 'user123',
-  skillId: 'math',
-  itemId: 'item456',
-  score: 0.8,
-  timestamp: Date.now()
-})
-
-console.log('Updated ability:', result.theta)
-console.log('Next item:', result.nextItem)
-```
-
-### Configuration
-
-#### IrtClientConfig
-
-```typescript
-interface IrtClientConfig {
-  baseUrl: string                      // API server base URL (required)
-  headers?: Record<string, string>     // Custom headers (e.g., auth tokens)
-  timeout?: number                     // Request timeout in ms (default: 10000)
-}
-```
-
-### API Methods
-
-#### recordAnswer()
-
-Record a user's response and get the next recommended item.
-
-```typescript
-async recordAnswer(params: RecordAnswerRequest): Promise<RecordAnswerResponse>
-```
-
-**Parameters:**
-```typescript
-interface RecordAnswerRequest {
-  userId: string          // User identifier
-  skillId: string         // Skill identifier
-  itemId: string          // Item identifier
-  score: number           // Response score [0,1] (0=wrong, 1=correct)
-  timestamp: number       // When response occurred (ms)
-  updateOptions?: Partial<UpdateOptions>      // Override learning rates
-  selectionOptions?: Partial<NextItemOptions> // Override selection behavior
-}
-```
-
-**Returns:** Updated ability (theta), standard error (se), next item, and updated states.
-
-**Example:**
-```typescript
-const result = await client.recordAnswer({
-  userId: 'alice',
-  skillId: 'geometry',
-  itemId: 'q100',
-  score: 1.0,
-  timestamp: Date.now()
-})
-
-console.log(`Ability: ${result.theta.toFixed(2)} ± ${result.se.toFixed(2)}`)
-if (result.nextItem) {
-  console.log(`Next question: ${result.nextItem.id}`)
-}
-```
-
-#### recordMultiSkillAnswers()
-
-Record multiple skill scores that came from a single multi-skill item. This is useful when one interaction yields separate sub-skill scores (e.g., integrated tasks that grade both reading and writing).
-
-```typescript
-async recordMultiSkillAnswers(
-  params: RecordMultiSkillAnswersRequest,
-): Promise<RecordMultiSkillAnswersResponse>
-```
-
-**Parameters:**
-
-```typescript
-interface RecordMultiSkillAnswersRequest {
-  userId: string
-  itemId: string
-  timestamp?: number
-  updateOptions?: Partial<UpdateOptions>
-  skillScores: Array<{
-    skillId: string
-    score: number // [0,1]
-    updateOptions?: Partial<UpdateOptions>
-  }>
-}
-```
-
-**Returns:** Array of per-skill updates with theta, SE, updated user/item snapshots.
-
-**Example:**
-
-```typescript
-const multi = await client.recordMultiSkillAnswers({
-  userId: 'alice',
-  itemId: 'essay-22',
-  skillScores: [
-    { skillId: 'reading', score: 0.9 },
-    { skillId: 'writing', score: 0.6 },
-  ],
-})
-
-multi.results.forEach((entry) => {
-  console.log(entry.skillId, entry.theta, entry.se)
-})
-```
-
-#### recordAnswerOnly()
-
-Record a user's response without requesting the next recommended item (useful when you already control sequencing).
-
-```typescript
-async recordAnswerOnly(params: RecordAnswerRequest): Promise<RecordAnswerOnlyResponse>
-```
-
-```typescript
-await client.recordAnswerOnly({
-  userId: 'alice',
-  skillId: 'geometry',
-  itemId: 'q100',
-  score: 1.0,
-  timestamp: Date.now()
-})
-```
-
-#### selectNextItem()
-
-Get the next recommended item without recording a response.
-
-```typescript
-async selectNextItem(params: SelectNextItemRequest): Promise<SelectNextItemResponse>
-```
-
-#### resetUser() / resetItem()
-
-Reset all Redis-backed skill state for a user or item.
-
-```typescript
-async resetUser(userId: string): Promise<ResetUserResponse>
-async resetItem(itemId: string): Promise<ResetItemResponse>
-```
-
-#### bulkUpdateUser() / bulkUpdateItem()
-
-Bulk cold-start/backfill helpers that update **only** user skills or **only** item parameters.
-
-```typescript
-async bulkUpdateUser(
-  userId: string,
-  events: BulkUpdateEvent[],
-  updateOptions?: Partial<UpdateOptions>
-): Promise<BulkUpdateResponse>
-
-async bulkUpdateItem(
-  itemId: string,
-  events: BulkUpdateEvent[],
-  updateOptions?: Partial<UpdateOptions>
-): Promise<BulkUpdateResponse>
-```
-
-#### getUserState() / getUserStates()
-
-Get current user ability estimates.
-
-```typescript
-async getUserState(userId: string, skillId: string): Promise<UserStateResponse>
-async getUserStates(userId: string): Promise<UserStatesResponse>
-```
-
-#### getItemState() / getItemStates()
-
-Get item parameters and metadata.
-
-```typescript
-async getItemState(itemId: string, skillId: string): Promise<ItemStateResponse>
-async getItemStates(itemId: string): Promise<ItemStatesResponse>
-```
-
-#### deleteUser() / deleteItem()
-
-Delete a user (and their skill states) or an item (and all per-skill calibrations). These are mainly for integration tests and fixture cleanup.
-
-```typescript
-async deleteUser(userId: string): Promise<DeleteUserResponse>
-async deleteItem(itemId: string): Promise<DeleteItemResponse>
-```
-
-#### health()
-
-Check API server health status.
-
-```typescript
-async health(): Promise<HealthResponse>
-```
-
-See `examples/sdk-usage.ts` for complete working examples.
-
-### Error Handling
-
-All methods throw errors for network failures, HTTP errors, timeouts, and invalid responses.
-
-```typescript
-try {
-  const result = await client.recordAnswer({...})
-  // Handle success
-} catch (error) {
-  if (error instanceof Error) {
-    console.error('API error:', error.message)
-    if (error.message.includes('timeout')) {
-      // Retry logic
-    }
-  }
-}
-```
-
-### Best Practices
-
-1. **Reuse client instances** - Create one client and reuse it
-2. **Use timestamps** - Always provide client-side timestamps for accurate analytics
-3. **Handle errors gracefully** - Show user-friendly messages on errors
-4. **Check for null items** - The API may return `null` if no suitable item is available
-
-```typescript
-const result = await client.selectNextItem({...})
-if (result.nextItem) {
-  // Show item to user
-} else {
-  // No more items available
-}
-```
-
----
-
-## Backend Server Setup
-
-The backend server is **not published** to npm. It runs as a service on Aliyun Function Compute.
-
-### Features
-
-- RESTful IRT API backed by **Redis (online state)** and **Postgres via Prisma** (durable via `/api/irt/sync`)
-- Aliyun FC lifecycle hooks (`/initialize`, `/pre-stop`)
-- Graceful shutdown and health checks
-
-### Development Setup
-
-```bash
-# From repo root
-npm install
-
-# Create .env file with:
-# REDIS_URL=redis://... (or rediss://...)
-# REDIS_DB=2
-# DATABASE_URL=postgres://user:pass@host:port/db
-
-# Run dev server
-npm run --workspace @more-ink/irt-edge dev
-
-# Seed data
-npm run --workspace @more-ink/irt-edge seed
-```
-
-### Backend Environment Variables
-
-```bash
-# Aliyun Function Compute
-ALIYUN_ACCESS_KEY="YOUR_ALIYUN_ACCESS_KEY"
-ALIYUN_SECRET_ACCESS_KEY="YOUR_ALIYUN_SECRET_KEY"
-
-# Database (PostgreSQL via Prisma)
-DATABASE_URL="postgres://user:pass@host:port/db?schema=public"
-# If using PgBouncer / pooled connections, also set DIRECT_URL for Prisma CLI commands
-# DIRECT_URL="postgres://user:pass@host:port/db?schema=public"
-
-# Feishu (Lark) Integration
-FEISHU_APP_ID="YOUR_FEISHU_APP_ID"
-FEISHU_APP_SECRET="YOUR_FEISHU_APP_SECRET"
-FEISHU_CHAT_ID="YOUR_FEISHU_CHAT_ID"
-
-# Redis (primary online store)
-REDIS_URL="redis://localhost:6379"
-REDIS_DB=2
-
-# Debug mode for Function Compute
-DEBUG_FC="true"
-
-# Server port (optional, default: 9000)
-PORT=9000
-```
-
-See `src/index.ts` for default IRT engine parameters (learning rates, selection options).
-
-### API Endpoints
-
-**IRT Operations:**
-- `POST /api/irt/answer` - Record response and get next item
-- `POST /api/irt/answer-multi` - Record multiple skill responses for one item
-- `POST /api/irt/sync` - Persist dirty Redis state to Postgres (cron-triggered)
-- `POST /api/irt/next-item` - Get next item without recording response
-- `POST /api/irt/users/:userId/reset` - Reset user skills in Redis
-- `POST /api/irt/items/:itemId/reset` - Reset item skills in Redis
-- `POST /api/irt/bulk-update-user/:userId` - Bulk update user skills (user-only)
-- `POST /api/irt/bulk-update-item/:itemId` - Bulk update item parameters (item-only)
-- `DELETE /api/irt/users/:userId` - Delete a user and all skill states
-- `DELETE /api/irt/items/:itemId` - Delete an item and its per-skill calibrations
-- `GET /api/irt/health` - Health check
-
-**Aliyun FC Lifecycle:**
-- `POST /initialize` - Instance startup (verifies Prisma DB and Redis connection)
-- `GET /pre-stop` - Instance shutdown (closes Prisma DB and Redis)
-
-**System:**
-- `GET /` - Service info
-
----
-
-## Cold-start Guidance
-
-When you have **no prior data** (no user θ, no item a/b), the recommended order for scale is:
-
-1) **Item cold-start** using a default θ (e.g., θ=0).  
-2) **User cold-start** using the calibrated item a/b.  
-3) **Optional**: run item cold-start again to refine a/b.
-
-Why this order: item sets are typically small and fixed, while user sets are large and segmented. A quick first-pass item calibration (with θ=0) reduces downstream work before user backfill.
-
-Reset and cold-start operations clear **Redis** only. Postgres is treated as a backup store and may retain stale rows until fresh updates overwrite them.
-
-### Bulk Update Constraints
-
-- Maximum **10k events** per request (over limit returns 400).
-- `timestamp` is **required** and events are processed in ascending time order.
-- `score` must be in `[0, 1]` (invalid events are skipped with errors).
-- Errors are reported per event; valid events still proceed.
-- Only a **single global** `updateOptions` is supported per bulk request.
-
----
-
-## Backend Deployment (Aliyun FC)
-
-Deploy the backend server to Aliyun FC:
-
-```bash
-# From root (recommended)
-npm run dp
-
-# Or from package dir
-npm run --workspace @more-ink/irt-edge deploy
-```
-
-### How Deployment Works
-
-Deployment now runs directly from the package root with npm-installed `node_modules` (no flattening step needed):
-1. Run `npm run --workspace @more-ink/irt-edge deploy` (runs `prisma generate`, then `build`, then `fc-deploy` from the package root)
-2. Upload from the package root; `node_modules` already contains real files.
-
-Ensure `DATABASE_URL` (and `DIRECT_URL` if pooling) is set in the function env.
-
----
-
-## SDK Publishing (npm)
-
-Publish the SDK to npm (backend code stays private):
-
-```bash
-# From repo root (recommended)
-npm run pub
-
-# Or from package directory
-cd packages/irt-edge
-npm run publish:sdk
-
-# Or using npm directly
-npm publish --access public
-```
-
-### What Gets Published
-
-**Published to npm:**
-- ✅ `sdk/` - Compiled SDK code (~40KB unpacked)
-- ✅ `README.md`, `CHANGELOG.md` - Documentation
-- ✅ `examples/` - Usage examples
-- ✅ `package.json` - Package metadata
-
-**NOT published (stays private):**
-- ❌ Backend server code (`src/index.ts`, `routes.ts`, `storage/`)
-- ❌ Scripts and tests (`scripts/`, `tests/`)
-- ❌ Config files (`.env`, `tsconfig.json`, etc.)
-- ❌ Backend build output (`dist/`)
-
-The `.npmignore` file ensures only SDK files are published.
-
-### Publishing Checklist
-
-Before publishing:
-
-1. **Version Management**
-   - Update version in `package.json` (follow [semver](https://semver.org/))
-   - Update `CHANGELOG.md` with changes
-
-2. **Code Quality**
-   - Build SDK: `npm run --workspace @more-ink/irt-edge build:sdk`
-   - Run tests: `npm run --workspace @more-ink/irt-edge test`
-   - Check TypeScript: `tsc -p tsconfig.sdk.json --noEmit`
-
-3. **Verify Package**
-   - Dry-run: `npm pack --dry-run`
-   - Check package size (<50KB)
-   - Verify only SDK files included
-
-4. **Publish**
-   - `npm run pub` (auto-builds before publishing)
-
-5. **Post-Publishing**
-   - Verify on npm: https://www.npmjs.com/package/@more-ink/irt-edge
-   - Tag release: `git tag v1.0.0 && git push origin v1.0.0`
-   - Create GitHub release
-
-### Test Installation
-
-```bash
-mkdir /tmp/test-irt-sdk && cd /tmp/test-irt-sdk
-npm init -y
-npm install @more-ink/irt-edge @more-ink/irt-core
-node -e "const { IrtClient } = require('@more-ink/irt-edge'); console.log('OK')"
-```
-
----
-
-## Package Scripts
-
-### Development & Backend
-- `npm run --workspace @more-ink/irt-edge dev` - Run dev server with hot reload
-- `npm run --workspace @more-ink/irt-edge build` - Build backend server to `dist/`
-- `npm run --workspace @more-ink/irt-edge start` - Start production backend server
-- `npm run --workspace @more-ink/irt-edge seed` - Seed Redis with test data
-- `npm run --workspace @more-ink/irt-edge deploy` - Deploy backend to Aliyun FC
-
-### SDK Publishing
-- `npm run --workspace @more-ink/irt-edge build:sdk` - Build SDK to `sdk/`
-- `npm run --workspace @more-ink/irt-edge publish:sdk` - Build and publish SDK to npm
-- `npm run pub` - Shortcut for `npm run --workspace @more-ink/irt-edge publish:sdk` (from root)
-
-### Testing
-- `npm run --workspace @more-ink/irt-edge test` - Run test suite
-- `npm run --workspace @more-ink/irt-edge test:watch` - Run tests in watch mode
-
----
-
-## Architecture
-
-```
-
----
-
-irt-edge/
-├── src/
-│   ├── sdk/              # ✅ SDK source (published)
-│   │   ├── types.ts      # Type definitions
-│   │   ├── client.ts     # IrtClient class
-│   │   └── index.ts      # Public exports
-│   ├── index.ts          # ❌ Backend server (not published)
-│   ├── routes.ts         # ❌ Backend routes
-│   └── storage/          # ❌ Backend storage layer
-├── sdk/                  # ✅ Compiled SDK (published)
-├── dist/                 # ❌ Backend build (not published)
-├── examples/             # ✅ SDK examples (published)
-├── tsconfig.json         # Backend build config
-└── tsconfig.sdk.json     # SDK build config
-```
-
-## License
-
-Proprietary - All Rights Reserved
+# @more-ink/irt-edge
+
+**Two packages in one:**
+1. **SDK** - Lightweight API client for JavaScript/TypeScript frontends (published to npm)
+2. **Backend Server** - Production HTTP API server built with Hono for Aliyun Function Compute (not published)
+
+---
+
+## Table of Contents
+
+- [SDK Usage (Frontend)](#sdk-usage-frontend)
+  - [Installation](#installation)
+  - [Quick Start](#quick-start)
+  - [Configuration](#configuration)
+  - [API Methods](#api-methods)
+  - [Error Handling](#error-handling)
+  - [Best Practices](#best-practices)
+- [Backend Server Setup](#backend-server-setup)
+- [Backend Deployment](#backend-deployment-aliyun-fc)
+- [SDK Publishing](#sdk-publishing-npm)
+- [Package Scripts](#package-scripts)
+
+---
+
+## SDK Usage (Frontend)
+
+### Installation
+
+```bash
+npm install @more-ink/irt-edge @more-ink/irt-core
+# or
+yarn add @more-ink/irt-edge @more-ink/irt-core
+```
+
+**Note:** `@more-ink/irt-core` is a peer dependency that provides type definitions.
+
+### Quick Start
+
+```typescript
+import { IrtClient } from '@more-ink/irt-edge'
+
+const client = new IrtClient({
+  namespace: 'exam-a',
+  baseUrl: 'https://your-api.example.com',
+  headers: {
+    'Authorization': 'Bearer YOUR_TOKEN' // Optional
+  },
+  timeout: 10000 // Optional (default: 10000ms)
+})
+
+// Record an answer and get the next item
+const result = await client.recordAnswer({
+  userId: 'user123',
+  skillId: 'math',
+  itemId: 'item456',
+  score: 0.8,
+  timestamp: Date.now()
+})
+
+console.log('Updated ability:', result.theta)
+console.log('Next item:', result.nextItem)
+```
+
+### Configuration
+
+#### IrtClientConfig
+
+```typescript
+interface IrtClientConfig {
+  namespace: string                    // Required namespace (exam type)
+  baseUrl: string                      // API server base URL (required)
+  headers?: Record<string, string>     // Custom headers (e.g., auth tokens)
+  timeout?: number                     // Request timeout in ms (default: 10000)
+}
+```
+
+The SDK sends the namespace as `X-IRT-Namespace` on every request; the server rejects calls without it.
+
+### API Methods
+
+#### recordAnswer()
+
+Record a user's response and get the next recommended item.
+
+```typescript
+async recordAnswer(params: RecordAnswerRequest): Promise<RecordAnswerResponse>
+```
+
+**Parameters:**
+```typescript
+interface RecordAnswerRequest {
+  userId: string          // User identifier
+  skillId: string         // Skill identifier
+  itemId: string          // Item identifier
+  score: number           // Response score [0,1] (0=wrong, 1=correct)
+  timestamp: number       // When response occurred (ms)
+  updateOptions?: Partial<UpdateOptions>      // Override learning rates
+  selectionOptions?: Partial<NextItemOptions> // Override selection behavior
+}
+```
+
+**Returns:** Updated ability (theta), standard error (se), next item, and updated states.
+
+**Example:**
+```typescript
+const result = await client.recordAnswer({
+  userId: 'alice',
+  skillId: 'geometry',
+  itemId: 'q100',
+  score: 1.0,
+  timestamp: Date.now()
+})
+
+console.log(`Ability: ${result.theta.toFixed(2)} ± ${result.se.toFixed(2)}`)
+if (result.nextItem) {
+  console.log(`Next question: ${result.nextItem.id}`)
+}
+```
+
+#### recordMultiSkillAnswers()
+
+Record multiple skill scores that came from a single multi-skill item. This is useful when one interaction yields separate sub-skill scores (e.g., integrated tasks that grade both reading and writing).
+
+```typescript
+async recordMultiSkillAnswers(
+  params: RecordMultiSkillAnswersRequest,
+): Promise<RecordMultiSkillAnswersResponse>
+```
+
+**Parameters:**
+
+```typescript
+interface RecordMultiSkillAnswersRequest {
+  userId: string
+  itemId: string
+  timestamp?: number
+  updateOptions?: Partial<UpdateOptions>
+  skillScores: Array<{
+    skillId: string
+    score: number // [0,1]
+    updateOptions?: Partial<UpdateOptions>
+  }>
+}
+```
+
+**Returns:** Array of per-skill updates with theta, SE, updated user/item snapshots.
+
+**Example:**
+
+```typescript
+const multi = await client.recordMultiSkillAnswers({
+  userId: 'alice',
+  itemId: 'essay-22',
+  skillScores: [
+    { skillId: 'reading', score: 0.9 },
+    { skillId: 'writing', score: 0.6 },
+  ],
+})
+
+multi.results.forEach((entry) => {
+  console.log(entry.skillId, entry.theta, entry.se)
+})
+```
+
+#### recordAnswerOnly()
+
+Record a user's response without requesting the next recommended item (useful when you already control sequencing).
+
+```typescript
+async recordAnswerOnly(params: RecordAnswerRequest): Promise<RecordAnswerOnlyResponse>
+```
+
+```typescript
+await client.recordAnswerOnly({
+  userId: 'alice',
+  skillId: 'geometry',
+  itemId: 'q100',
+  score: 1.0,
+  timestamp: Date.now()
+})
+```
+
+#### selectNextItem()
+
+Get the next recommended item without recording a response.
+
+```typescript
+async selectNextItem(params: SelectNextItemRequest): Promise<SelectNextItemResponse>
+```
+
+#### resetUser() / resetItem()
+
+Reset all Redis-backed skill state for a user or item.
+
+```typescript
+async resetUser(userId: string): Promise<ResetUserResponse>
+async resetItem(itemId: string): Promise<ResetItemResponse>
+```
+
+#### bulkUpdateUser() / bulkUpdateItem()
+
+Bulk cold-start/backfill helpers that update **only** user skills or **only** item parameters.
+
+```typescript
+async bulkUpdateUser(
+  userId: string,
+  events: BulkUpdateEvent[],
+  updateOptions?: Partial<UpdateOptions>
+): Promise<BulkUpdateResponse>
+
+async bulkUpdateItem(
+  itemId: string,
+  events: BulkUpdateEvent[],
+  updateOptions?: Partial<UpdateOptions>
+): Promise<BulkUpdateResponse>
+```
+
+#### getUserState() / getUserStates()
+
+Get current user ability estimates.
+
+```typescript
+async getUserState(userId: string, skillId: string): Promise<UserStateResponse>
+async getUserStates(userId: string): Promise<UserStatesResponse>
+```
+
+#### getItemState() / getItemStates()
+
+Get item parameters and metadata.
+
+```typescript
+async getItemState(itemId: string, skillId: string): Promise<ItemStateResponse>
+async getItemStates(itemId: string): Promise<ItemStatesResponse>
+```
+
+#### deleteUser() / deleteItem()
+
+Delete a user (and their skill states) or an item (and all per-skill calibrations). These are mainly for integration tests and fixture cleanup.
+
+```typescript
+async deleteUser(userId: string): Promise<DeleteUserResponse>
+async deleteItem(itemId: string): Promise<DeleteItemResponse>
+```
+
+#### health()
+
+Check API server health status.
+
+```typescript
+async health(): Promise<HealthResponse>
+```
+
+See `examples/sdk-usage.ts` for complete working examples.
+
+### Error Handling
+
+All methods throw errors for network failures, HTTP errors, timeouts, and invalid responses.
+
+```typescript
+try {
+  const result = await client.recordAnswer({...})
+  // Handle success
+} catch (error) {
+  if (error instanceof Error) {
+    console.error('API error:', error.message)
+    if (error.message.includes('timeout')) {
+      // Retry logic
+    }
+  }
+}
+```
+
+### Best Practices
+
+1. **Reuse client instances** - Create one client and reuse it
+2. **Use timestamps** - Always provide client-side timestamps for accurate analytics
+3. **Handle errors gracefully** - Show user-friendly messages on errors
+4. **Check for null items** - The API may return `null` if no suitable item is available
+
+```typescript
+const result = await client.selectNextItem({...})
+if (result.nextItem) {
+  // Show item to user
+} else {
+  // No more items available
+}
+```
+
+---
+
+## Backend Server Setup
+
+The backend server is **not published** to npm. It runs as a service on Aliyun Function Compute.
+
+### Features
+
+- RESTful IRT API backed by **Redis (online state)** and **Postgres via Prisma** (durable via `/api/irt/sync`)
+- Aliyun FC lifecycle hooks (`/initialize`, `/pre-stop`)
+- Graceful shutdown and health checks
+
+### Development Setup
+
+```bash
+# From repo root
+npm install
+
+# Create .env file with:
+# REDIS_URL=redis://... (or rediss://...)
+# REDIS_DB=2
+# DATABASE_URL=postgres://user:pass@host:port/db
+
+# Run dev server
+npm run --workspace @more-ink/irt-edge dev
+
+# Seed data
+npm run --workspace @more-ink/irt-edge seed
+```
+
+### Backend Environment Variables
+
+```bash
+# Aliyun Function Compute
+ALIYUN_ACCESS_KEY="YOUR_ALIYUN_ACCESS_KEY"
+ALIYUN_SECRET_ACCESS_KEY="YOUR_ALIYUN_SECRET_KEY"
+
+# Database (PostgreSQL via Prisma)
+DATABASE_URL="postgres://user:pass@host:port/db?schema=public"
+# If using PgBouncer / pooled connections, also set DIRECT_URL for Prisma CLI commands
+# DIRECT_URL="postgres://user:pass@host:port/db?schema=public"
+
+# Feishu (Lark) Integration
+FEISHU_APP_ID="YOUR_FEISHU_APP_ID"
+FEISHU_APP_SECRET="YOUR_FEISHU_APP_SECRET"
+FEISHU_CHAT_ID="YOUR_FEISHU_CHAT_ID"
+
+# Redis (primary online store)
+REDIS_URL="redis://localhost:6379"
+REDIS_DB=2
+
+# Debug mode for Function Compute
+DEBUG_FC="true"
+
+# Server port (optional, default: 9000)
+PORT=9000
+```
+
+See `src/index.ts` for default IRT engine parameters (learning rates, selection options).
+
+### API Endpoints
+
+**IRT Operations:**
+- `POST /api/irt/answer` - Record response and get next item
+- `POST /api/irt/answer-multi` - Record multiple skill responses for one item
+- `POST /api/irt/sync` - Persist dirty Redis state to Postgres (cron-triggered)
+- `POST /api/irt/next-item` - Get next item without recording response
+- `POST /api/irt/users/:userId/reset` - Reset user skills in Redis
+- `POST /api/irt/items/:itemId/reset` - Reset item skills in Redis
+- `POST /api/irt/bulk-update-user/:userId` - Bulk update user skills (user-only)
+- `POST /api/irt/bulk-update-item/:itemId` - Bulk update item parameters (item-only)
+- `DELETE /api/irt/users/:userId` - Delete a user and all skill states
+- `DELETE /api/irt/items/:itemId` - Delete an item and its per-skill calibrations
+- `GET /api/irt/health` - Health check
+
+**Aliyun FC Lifecycle:**
+- `POST /initialize` - Instance startup (verifies Prisma DB and Redis connection)
+- `GET /pre-stop` - Instance shutdown (closes Prisma DB and Redis)
+
+**System:**
+- `GET /` - Service info
+
+---
+
+## Cold-start Guidance
+
+When you have **no prior data** (no user θ, no item a/b), the recommended order for scale is:
+
+1) **Item cold-start** using a default θ (e.g., θ=0).  
+2) **User cold-start** using the calibrated item a/b.  
+3) **Optional**: run item cold-start again to refine a/b.
+
+Why this order: item sets are typically small and fixed, while user sets are large and segmented. A quick first-pass item calibration (with θ=0) reduces downstream work before user backfill.
+
+Reset and cold-start operations clear **Redis** only. Postgres is treated as a backup store and may retain stale rows until fresh updates overwrite them.
+
+### Bulk Update Constraints
+
+- Maximum **10k events** per request (over limit returns 400).
+- `timestamp` is **required** and events are processed in ascending time order.
+- `score` must be in `[0, 1]` (invalid events are skipped with errors).
+- Errors are reported per event; valid events still proceed.
+- Only a **single global** `updateOptions` is supported per bulk request.
+
+---
+
+## Backend Deployment (Aliyun FC)
+
+Deploy the backend server to Aliyun FC:
+
+```bash
+# From root (recommended)
+npm run dp
+
+# Or from package dir
+npm run --workspace @more-ink/irt-edge deploy
+```
+
+### How Deployment Works
+
+Deployment now runs directly from the package root with npm-installed `node_modules` (no flattening step needed):
+1. Run `npm run --workspace @more-ink/irt-edge deploy` (runs `prisma generate`, then `build`, then `fc-deploy` from the package root)
+2. Upload from the package root; `node_modules` already contains real files.
+
+Ensure `DATABASE_URL` (and `DIRECT_URL` if pooling) is set in the function env.
+
+---
+
+## SDK Publishing (npm)
+
+Publish the SDK to npm (backend code stays private):
+
+```bash
+# From repo root (recommended)
+npm run pub
+
+# Or from package directory
+cd packages/irt-edge
+npm run publish:sdk
+
+# Or using npm directly
+npm publish --access public
+```
+
+### What Gets Published
+
+**Published to npm:**
+- ✅ `sdk/` - Compiled SDK code (~40KB unpacked)
+- ✅ `README.md`, `CHANGELOG.md` - Documentation
+- ✅ `examples/` - Usage examples
+- ✅ `package.json` - Package metadata
+
+**NOT published (stays private):**
+- ❌ Backend server code (`src/index.ts`, `routes.ts`, `storage/`)
+- ❌ Scripts and tests (`scripts/`, `tests/`)
+- ❌ Config files (`.env`, `tsconfig.json`, etc.)
+- ❌ Backend build output (`dist/`)
+
+The `.npmignore` file ensures only SDK files are published.
+
+### Publishing Checklist
+
+Before publishing:
+
+1. **Version Management**
+   - Update version in `package.json` (follow [semver](https://semver.org/))
+   - Update `CHANGELOG.md` with changes
+
+2. **Code Quality**
+   - Build SDK: `npm run --workspace @more-ink/irt-edge build:sdk`
+   - Run tests: `npm run --workspace @more-ink/irt-edge test`
+   - Check TypeScript: `tsc -p tsconfig.sdk.json --noEmit`
+
+3. **Verify Package**
+   - Dry-run: `npm pack --dry-run`
+   - Check package size (<50KB)
+   - Verify only SDK files included
+
+4. **Publish**
+   - `npm run pub` (auto-builds before publishing)
+
+5. **Post-Publishing**
+   - Verify on npm: https://www.npmjs.com/package/@more-ink/irt-edge
+   - Tag release: `git tag v1.0.0 && git push origin v1.0.0`
+   - Create GitHub release
+
+### Test Installation
+
+```bash
+mkdir /tmp/test-irt-sdk && cd /tmp/test-irt-sdk
+npm init -y
+npm install @more-ink/irt-edge @more-ink/irt-core
+node -e "const { IrtClient } = require('@more-ink/irt-edge'); console.log('OK')"
+```
+
+---
+
+## Package Scripts
+
+### Development & Backend
+- `npm run --workspace @more-ink/irt-edge dev` - Run dev server with hot reload
+- `npm run --workspace @more-ink/irt-edge build` - Build backend server to `dist/`
+- `npm run --workspace @more-ink/irt-edge start` - Start production backend server
+- `npm run --workspace @more-ink/irt-edge seed` - Seed Redis with test data
+- `npm run --workspace @more-ink/irt-edge deploy` - Deploy backend to Aliyun FC
+
+### SDK Publishing
+- `npm run --workspace @more-ink/irt-edge build:sdk` - Build SDK to `sdk/`
+- `npm run --workspace @more-ink/irt-edge publish:sdk` - Build and publish SDK to npm
+- `npm run pub` - Shortcut for `npm run --workspace @more-ink/irt-edge publish:sdk` (from root)
+
+### Testing
+- `npm run --workspace @more-ink/irt-edge test` - Run test suite
+- `npm run --workspace @more-ink/irt-edge test:watch` - Run tests in watch mode
+
+---
+
+## Architecture
+
+```
+
+---
+
+irt-edge/
+├── src/
+│   ├── sdk/              # ✅ SDK source (published)
+│   │   ├── types.ts      # Type definitions
+│   │   ├── client.ts     # IrtClient class
+│   │   └── index.ts      # Public exports
+│   ├── index.ts          # ❌ Backend server (not published)
+│   ├── routes.ts         # ❌ Backend routes
+│   └── storage/          # ❌ Backend storage layer
+├── sdk/                  # ✅ Compiled SDK (published)
+├── dist/                 # ❌ Backend build (not published)
+├── examples/             # ✅ SDK examples (published)
+├── tsconfig.json         # Backend build config
+└── tsconfig.sdk.json     # SDK build config
+```
+
+## License
+
+Proprietary - All Rights Reserved