lucasw89/STCourses
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(ai): contract requests 3-5 settled in v1.1

Browse Source 
Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
Lucas Winther
2026-10-30 20:37:33 +01:00
co-authored by Claude Opus 5.5
parent 5c63f17cff
commit 260f7b52c8
1 changed files with 13 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contract-requests/ai.md
+13
View File
@@ -35,17 +35,30 @@ provider keeps each response's raw content blocks (thinking with signature, text
and replays them unchanged. Proposal: `ChatMessage.toolCalls?: { id, name, input }[]` and an opaque
`providerData?: unknown` the provider can round-trip.
**Settled in v1.1 (`feat/v11-ai`):** `ChatMessage.toolCalls?: ToolCall[]` and `providerData?: unknown` are in
`@stc/contracts`, and providers may yield `{ providerData }` once per turn. The assistant loop appends one assistant
message per model turn. Anthropic returns `{ anthropic: <raw blocks> }` and replays it verbatim (no in-memory map);
OpenAI maps `toolCalls` to `tool_calls`.
## 4. Per-course mentor toggle in `ai_settings`
The frozen key is `(scope, owner_id)` with one `mentor_off` column, so a per-course toggle cannot be a row. The flag
lives in the user row's `config_json.mentorOff[courseId]`; `mentor_off` stays 0 (reserved for "off everywhere").
Proposal: add `course_id TEXT NOT NULL DEFAULT ''` to the key, or a small `ai_mentor_prefs(user_id, course_id, off)` table.
**Settled in v1.1:** table `ai_mentor_prefs(user_id, course_id, off, updated_at)` from
`packages/feature-ai/migrations/0002_ai_mentor_prefs.sql`. `upgradeAiData` (src/upgrade.ts) copies v1
`config_json.mentorOff` toggles once (marker `ai_data_v11` in `schema_migrations`).
## 5. Citations on `ai_messages`
`ai_messages` has no column for an assistant message's sources. They are stored as an extra row with role `sources`
(JSON) right after the assistant row and folded back when reading. Proposal: `ai_messages.meta_json TEXT`.
**Settled in v1.1:** column `ai_messages.citations_json` from `0001_ai_message_citations.sql`, which also folds v1
`sources` rows into the assistant row before them. (MCP `env`/`headers` are now encrypted at rest too, masked in the
admin API.)
## 6. Derived text cache layout (shared with WP-B)
Retrieval reads the importer's layout: