@more-ink/irt-edge 2.1.0 → 2.1.2

package/README.md

@@ -89,7 +89,7 @@ interface RecordAnswerRequest {
   skillId: string         // Skill identifier
   itemId: string          // Item identifier
   score: number           // Response score [0,1] (0=wrong, 1=correct)
-  timestamp?: number      // When response occurred (ms)
+  timestamp: number       // When response occurred (ms)
   updateOptions?: Partial<UpdateOptions>      // Override learning rates
   selectionOptions?: Partial<NextItemOptions> // Override selection behavior
 }
@@ -184,6 +184,33 @@ Get the next recommended item without recording a response.
 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.
@@ -263,7 +290,7 @@ The backend server is **not published** to npm. It runs as a service on Aliyun F
 
 ### Features
 
-- RESTful IRT API backed by **PostgreSQL via Prisma** (Redis route kept only for diagnostics)
+- 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
 
@@ -274,8 +301,9 @@ The backend server is **not published** to npm. It runs as a service on Aliyun F
 npm install
 
 # Create .env file with:
-# UPSTASH_REDIS_REST_URL=https://...
-# UPSTASH_REDIS_REST_TOKEN=...
+# 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
@@ -301,8 +329,8 @@ FEISHU_APP_ID="YOUR_FEISHU_APP_ID"
 FEISHU_APP_SECRET="YOUR_FEISHU_APP_SECRET"
 FEISHU_CHAT_ID="YOUR_FEISHU_CHAT_ID"
 
-# Optional legacy Redis diagnostics route
-REDIS_URL=""
+# Redis (primary online store)
+REDIS_URL="redis://localhost:6379"
 REDIS_DB=2
 
 # Debug mode for Function Compute
@@ -319,20 +347,47 @@ See `src/index.ts` for default IRT engine parameters (learning rates, selection
 **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 diag route if configured)
-- `GET /pre-stop` - Instance shutdown (closes Prisma DB and Redis if used)
+- `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:
@@ -447,6 +502,9 @@ node -e "const { IrtClient } = require('@more-ink/irt-edge'); console.log('OK')"
 ## Architecture
 
 ```
+
+---
+
 irt-edge/
 ├── src/
 │   ├── sdk/              # ✅ SDK source (published)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@more-ink/irt-edge",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "IRT Edge API client SDK for JavaScript/TypeScript frontends.",
   "main": "sdk/index.js",
   "types": "sdk/index.d.ts",
@@ -32,12 +32,9 @@
     "layer:clean": "rm -rf .layer",
     "layer:deps": "bash scripts/layer-deps.sh"
   },
-  "peerDependencies": {
-    "@more-ink/irt-core": "^1.2.0"
-  },
   "dependencies": {
     "@hono/node-server": "^1.19.6",
-    "@more-ink/irt-core": "^1.2.0",
+    "@more-ink/irt-core": "^1.2.2",
     "@prisma/adapter-pg": "^7.1.0",
     "@prisma/client": "^7.1.0",
     "dayjs": "^1.11.19",
@@ -48,9 +45,9 @@
     "undici": "^7.0.1"
   },
   "devDependencies": {
-    "prisma": "^7.1.0",
     "@larksuiteoapi/node-sdk": "^1.55.0",
     "@upstash/redis": "^1.35.7",
-    "fc-deploy": "^1.2.9"
+    "fc-deploy": "^1.2.9",
+    "prisma": "^7.1.0"
   }
-}
+}