smart_brain 0.1.2 → 0.3.0

data/docs/media_memory_schema.md

@@ -0,0 +1,271 @@
+# 媒体记忆：契约与数据模型设计（阶段 0 定稿）
+
+> 状态：**P0-P3、数据完整性修复和真实端到端验证已实现**（2026-08-14）
+> 范围：smart_brain 在 SmartRAG 文本资源记忆之外，扩展 image / audio / video 等媒体记忆的契约与数据模型。
+> 本文档是阶段 1–4 实现的对照依据。
+
+## 1. 设计目标与原则
+
+1. **载体复用，不加表**：媒体记忆 = 结构化元数据（存 `source_documents.metadata` JSONB）+ 可检索文本（存 `source_sections`）。现有文本链路零改动。
+2. **两个正交维度**：`source_type`（来源：url/file/manual）与 `media_type`（内容类别：image/audio/video/document/other）互不干扰，不能合并。
+3. **向后兼容**：`add_document` 行为不变；`retrieve` 无 `media_type` 过滤时行为不变；证据结构字段只增不改。
+4. **可降级**：LLM/whisper 依赖缺失时，仅存技术元数据 + 文件名/标签，仍有价值且不报错。
+
+## 2. 媒体类型清单（`media_type` 枚举）
+
+| 值 | 含义 | 覆盖内容 | 专用入口 |
+|---|---|---|---|
+| `image` | 图片 | jpg/png/gif/webp/heic | `add_image` |
+| `audio` | 音频 | mp3/wav/m4a/flac/ogg | `add_audio` |
+| `video` | 视频 | mp4/mkv/mov/webm | `add_video` |
+| `document` | 文档类 | pdf/docx/xlsx/pptx/md/txt/html/csv/json 等（即现有 `add_document` 全部覆盖面，**text 并入 document**） | `add_document` |
+| `other` | 无法识别 | — | `add_media` 兜底 |
+
+- 枚举值：`image / audio / video / document / other`。
+- `add_document` 语义不变，仅显式归类为 `media_type: "document"`。
+- 命名以产品语义为准，不与 IANA 的 `application` 对齐。
+
+### 2.1 类型推断规则（`add_media(media_type: :auto)` 时）
+
+1. 扩展名映射表优先（`.jpg/.png` → image，`.mp3/.wav` → audio，`.mp4/.mov` → video，其余文档扩展名 → document）；
+2. 无法从扩展名判断时用 `file` 命令 MIME 兜底；
+3. 仍无法识别 → `other`。
+
+## 3. 数据模型：`metadata` JSONB schema
+
+在现有 `extract_metadata` 产物（`file_path/file_size/file_type/created_at/modified_at` + 用户覆盖）之上，新增三个键：
+
+```json
+{
+  "media_type": "image",
+  "media": {
+    "format": "jpeg",
+    "width": 1920,
+    "height": 1080,
+    "dpi": 72,
+    "color_mode": "RGB",
+    "orientation": "landscape",
+    "exif": { "datetime": "2026-07-01T10:00:00Z", "camera_model": "X", "gps": { "lat": 31.2, "lon": 121.5 } },
+    "duration_ms": null,
+    "bitrate_bps": null,
+    "sample_rate_hz": null,
+    "channels": null,
+    "codec": null,
+    "fps": null,
+    "audio_codec": null
+  },
+  "semantic": {
+    "description": "产品发布会现场白板照片",
+    "captions": ["画面中央是需求流程图，标题为 Q3 路线图"],
+    "tags": ["发布会", "白板", "路线图"]
+  },
+  "content": "（截断后的转写/描述摘要，见 3.3）"
+}
+```
+
+### 3.1 设计要点（已确认决策）
+
+- **D1（通过）**：`media` 是**单一对象、三态共用、类型特有字段置 null**。检索与展示代码无需按类型分支。
+- **D2（通过）**：`media_type` 在**顶层冗余**一份，`metadata->>'media_type'` 可直接查询/过滤，不用剥 `media` 对象。
+- **D3（通过）**：`title` **只进 `document.title` 列**，不进 `semantic`，避免双写不一致。
+- **D4（通过）**：`metadata.content` 存**截断后的转写/描述摘要**，全文只进 `sections`。
+
+### 3.2 `media` 字段说明
+
+| 字段 | 适用 | 说明 |
+|---|---|---|
+| `format` | 全部 | 实际格式（jpeg/mp3/mp4/…），来自解析 |
+| `width` / `height` | image/video | 像素尺寸；其他类型 null |
+| `dpi` | image | 分辨率；其他类型 null |
+| `color_mode` | image | RGB/CMYK/灰度等 |
+| `orientation` | image/video | landscape/portrait，可推导可不存 |
+| `exif` | image | 可选：拍摄时间、相机、GPS；无则 `{}` |
+| `duration_ms` | audio/video | 时长（毫秒） |
+| `bitrate_bps` | audio/video | 码率（bps），解析不到则 null |
+| `sample_rate_hz` | audio | 采样率 |
+| `channels` | audio | 声道数 |
+| `codec` | audio/video | 编码（h264/mp3/…） |
+| `fps` | video | 帧率 |
+| `audio_codec` | video | 视频内音轨编码 |
+
+### 3.3 `semantic` 字段说明
+
+- `description`：用户或 LLM 提供的整体描述（可 null）。
+- `captions`：LLM 生成的描述/字幕句（数组，可空）。图片为画面描述，音频/视频为转写字幕句。
+- `tags`：用户标签（数组，可空）。
+
+## 4. 写侧 API 契约
+
+### 4.1 SmartRAG 层（真实执行者）
+
+```ruby
+rag.add_image(source, options = {})    # media_type 固定 "image"
+rag.add_audio(source, options = {})    # 固定 "audio"
+rag.add_video(source, options = {})    # 固定 "video"
+rag.add_document(source, options = {}) # 现有，显式归类 media_type: "document"
+rag.add_media(source, options = {})    # media_type: :auto | "image" | "audio" | "video" | "document"
+```
+
+`options` 统一字典（全可选，命名对齐现有 `add_document` 的 options）：
+
+- `title:` / `description:` / `author:` / `tags:` → 语义元数据
+- `media_type:` → 仅 `add_media` 使用
+- `llm_caption: true` → 图片/视频帧生成描述（默认开，依赖缺失降级）
+- `transcribe: true` → 音频/视频转写（默认开，依赖缺失降级）
+- `generate_embeddings:` / `generate_tags:` → 透传现有 `save_sections` 选项
+- `metadata: {}` → 用户覆盖（现有约定：merge 进 extract_metadata 结果）
+- `source_type:` / `source_uri:` / `url:` → 透传现有 `create_or_update_document`
+
+统一返回结构：
+
+```ruby
+{
+  document_id: 123,
+  media_type: "image",
+  status: "success",             # "success" | "unsupported"
+  section_count: 3,
+  metadata: { media: {...}, semantic: {...} },  # 入库后回读的元数据
+  warnings: ["whisper 未安装，跳过音频转写"]      # 降级说明
+}
+```
+
+### 4.2 smart_brain 适配层（三个客户端统一契约）
+
+```ruby
+add_document(source, options = {})   # 新增（现有客户端只有 retrieve）
+add_image(source, options = {})
+add_audio(source, options = {})
+add_video(source, options = {})
+add_media(source, options = {})
+```
+
+- `DirectClient` → 转发 `@rag`
+- `HttpClient` → `POST /v1/media`；本地文件走 multipart，URL 走 JSON。服务端 extractor 由 SmartRAG `HttpApp` 注入。
+- `NullClient` → `{status: "unsupported", warnings: ["smart_rag client not configured; add_media ignored"]}`（fail closed，与现有 retrieve 降级风格一致）
+
+### 4.3 smart_brain 门面（阶段 4 薄封装）
+
+```ruby
+SmartBrain.add_image(source:, options: {})
+SmartBrain.add_audio(source:, options: {})
+SmartBrain.add_video(source:, options: {})
+SmartBrain.add_media(source:, options: {})
+```
+
+- **不绑定 session**：媒体资源是全局资源记忆（归 SmartRAG 库），不属于某个对话会话。
+- 导入动作是否记入 EventStore → 列为后续增强点，不纳入本契约。
+
+## 5. 读侧 / 检索契约
+
+### 5.1 过滤（RetrievalPlan → SmartRAG filters）
+
+```ruby
+plan[:filters] = { media_type: "image" }        # 或 ["image", "audio"]
+```
+
+- 单值或数组皆可（对齐现有 `source_type` 的 `Array()` 归一化风格）。
+- 实现落在 `candidate_passes_filters?` 新增分支：从 `candidate[:metadata][:media_type]` 取值比较。
+- 不带此过滤时行为不变。
+
+### 5.2 证据透传（EvidencePack）
+
+- **不新增 `kind`**：仍是 `resource_section`（媒体检索命中的就是转写/描述文本块）。
+- `metadata` 透传 `media_type` + `media` + `semantic`，`source_type`/`title`/`snippet` 字段语义不变。
+- 现有 merger/composer 消费代码无需改动（它们只读 title/snippet/metadata）。
+
+## 6. 完整示例（评审用）
+
+### 6.1 image
+
+```json
+{
+  "media_type": "image",
+  "media": { "format": "jpeg", "width": 1920, "height": 1080, "dpi": 72, "color_mode": "RGB",
+             "orientation": "landscape", "exif": {}, "duration_ms": null, "codec": null,
+             "bitrate_bps": null, "sample_rate_hz": null, "channels": null, "fps": null, "audio_codec": null },
+  "semantic": { "description": "产品发布会白板", "captions": ["画面中央是需求流程图，标题为 Q3 路线图"], "tags": [] },
+  "content": "需求流程图：Q3 路线图……（LLM 描述摘要）"
+}
+```
+
+### 6.2 audio
+
+```json
+{
+  "media_type": "audio",
+  "media": { "format": "mp3", "duration_ms": 1870000, "bitrate_bps": 128000, "sample_rate_hz": 44100,
+             "channels": 2, "codec": "mp3", "width": null, "height": null, "dpi": null,
+             "color_mode": null, "orientation": null, "exif": {}, "fps": null, "audio_codec": null },
+  "semantic": { "description": null, "captions": ["……转写句子 1", "……转写句子 2"], "tags": ["会议"] },
+  "content": "大家好，今天我们讨论 Q3 路线图……（转写摘要）"
+}
+```
+
+### 6.3 video
+
+```json
+{
+  "media_type": "video",
+  "media": { "format": "mp4", "duration_ms": 452000, "width": 1920, "height": 1080, "fps": 30,
+             "codec": "h264", "audio_codec": "aac", "bitrate_bps": null, "sample_rate_hz": null,
+             "channels": null, "dpi": null, "color_mode": null, "orientation": "landscape",
+             "exif": {} },
+  "semantic": { "description": null, "captions": ["第 1 帧：界面加载中……", "字幕：点击导入按钮"], "tags": [] },
+  "content": "字幕与帧描述摘要……"
+}
+```
+
+## 7. 存储影响
+
+- 文档级媒体信息继续使用 `source_documents.metadata` JSONB。
+- 第二批 MVP 为 `source_sections` 增加 `metadata` JSONB + GIN，用于保存视频片段的 `start_ms/end_ms/frame_timestamp_ms/extraction_kind`。
+- 可选优化（不阻塞）：如需高频 `media_type` 过滤可加表达式索引，但 JSONB GIN 对 `@>` 与 key 路径已覆盖，**建议先不加**。
+
+## 8. 边界 / 非目标（明确不做）
+
+- 不新建表、不改现有文本链路、不新增 `source_type` 值（如 `"media"`）——`source_type` 语义保持。
+- 不做视频语义理解（仅字幕/帧描述/OCR）。
+- 不做对象存储/大文件托管（文件仍走本地路径/URL）。
+- 初始 MVP 不做权限/配额控制；P3 已补充 Bearer principal、任务/文档隔离和数据库配额。
+- 不把导入动作记入 EventStore（列为后续增强）。
+
+## 9. 决策点结论（已确认）
+
+| 决策点 | 结论 |
+|---|---|
+| D1 media 对象形态 | 单一对象 + null 填充（通过） |
+| D2 media_type 顶层冗余 | 冗余（通过） |
+| D3 title 归属 | 只进 `document.title` 列，不进 semantic（通过） |
+| D4 metadata.content | 存截断摘要，全文进 sections（通过） |
+| D5 llm_caption / transcribe 默认 | 默认开，缺依赖降级 + warnings（通过） |
+| D6 文档类枚举值 | `document`（非 application），`add_document` 即专用入口（通过） |
+| D6a text 归类 | 并入 `document`（通过） |
+| D7 smart_brain 门面 | 阶段 4 做薄封装（通过） |
+| D8 枚举命名 | 产品语义为准，不与 IANA 对齐（通过） |
+| D9 filters[:media_type] | 单值 + 数组（通过） |
+
+## 10. 后续阶段对照
+
+- **阶段 1**：SmartRAG `MediaMetadataExtractor`（image/audio/video 技术元数据解析，Python bridge，可降级）。
+- **阶段 2**：媒体内容可检索化（图片描述/OCR、音频转写、视频音轨转写和关键帧描述已支持通过 extractor callable 接入）。
+- **阶段 3**：SmartRAG `add_image/add_audio/add_video/add_media` API（复用 `create_document` 管线）。
+- **阶段 4**：smart_brain 适配层写 API（三客户端）+ HTTP JSON/multipart 协议 + `filters[:media_type]` 检索过滤 + 门面封装（已完成）。
+- **阶段 5**：测试、文档、示例（`examples/media_memory.rb`）。
+
+## 11. P1 / P2 生产能力补充
+
+- **P1**：内置 OCR/视觉/转写适配器、时间戳切片、场景检测、安全限制、本地内容寻址存储、PostgreSQL 异步队列和 worker。
+- **P2**：任务分页与状态过滤、取消与人工重试、过期 `processing` 恢复、终态保留期清理、队列统计及健康检查。失败的异步上传在清理期内保留，以支持人工重试。
+- `media_jobs` 由迁移 013 创建，迁移 014 增加恢复和清理所需的组合索引。
+- **P3**：迁移 015 增加 heartbeat lease、按 principal 隔离的幂等键、`media_objects` / `media_object_references` 引用管理和数据库配额计数。内容存储支持本地 CAS 与可选 S3/MinIO；HTTP 可启用 Bearer 认证和调用方配额。
+- **数据完整性修复**：迁移 016 为文档增加 `principal` owner，并用 `media_jobs.staging_media_object_id` 显式保护 queued/processing/failed 任务的源对象。同步导入在语义提取前登记零引用对象，失败后可由 GC 回收；检索、读取、列表、删除和统计按认证 principal 隔离。
+- **幂等冲突检测**：迁移 017 为任务增加非空 `request_fingerprint`，并为历史任务回填 SHA-256 指纹。指纹由 operation、source 和递归规范化后的可序列化 options 组成；同 principal/幂等键/指纹返回原任务，同 principal/幂等键但指纹不同则返回 HTTP 409 `idempotency_conflict`。不同 principal 可复用同一键。
+- **检索纵深隔离**：认证 principal 先转换为 PostgreSQL 中拥有的 document ID 白名单并下推搜索，再对后端返回候选逐条复核 owner。HTTP Bearer 认证失败返回 401，检索结果不公开内部 principal 过滤字段。
+- **真实 MinIO E2E**：显式启用的集成规格验证两个独立 S3 client 实例间的字节一致性、异步 worker 对 `s3://` URI 的物化、引用计数、解除引用后的真实删除，以及 retained failed job 对 staging 对象的 GC 保护。
+
+### 11.1 升级和调用方约束
+
+1. 部署新队列代码前，先将 SmartRAG 数据库迁移到 017；新列为 `NOT NULL`，绕过队列直接写 `media_jobs` 的内部工具也必须写入有效指纹。
+2. 网络重试必须复用原幂等键和完全相同的业务载荷。若 source、operation 或 options 改变，应创建新幂等键，不能把 409 当作成功去重。
+3. SmartBrain `HttpClient` 将 SmartRAG HTTP 409 包装为 `status: "failed"` 和 warning；`DirectClient` 直接传播 `MediaJobQueue::IdempotencyConflict`。业务层应分别检查结果状态或捕获异常。
+4. MinIO/S3 多实例部署必须使用所有 worker 均可访问的 endpoint、bucket 和 prefix。任务保留期结束并被 prune 后，零引用 staging 对象才允许被 GC。

data/docs/memory_types.md

@@ -0,0 +1,278 @@
+## 1. 目的
+
+MemoryTypes 用于把“对话与工具事件中可沉淀的长期信息”结构化，解决：
+- 记忆污染（把闲聊当长期事实）
+- 冲突不可控（同一事实多版本）
+- 检索不可用（只存全文，无法聚合/过滤/关联）
+- 无法解释（不知道这条记忆来自哪里）
+
+本规范定义：
+- 记忆类型（type）
+- key 规则（如何唯一标识一条记忆）
+- value 形态（建议的 JSON）
+- 写入门控与冲突合并策略（最低要求）
+
+---
+
+## 2. 总体存储模型（建议）
+
+### 2.1 memory_items（结构化）
+字段建议：
+- `id`
+- `type`
+- `key`
+- `value_json`
+- `confidence`（0..1）
+- `status`（active|superseded|retracted）
+- `source_turn_id`
+- `source_message_id`（可选）
+- `evidence_refs`（可选：document_id/section_id/url）
+- `updated_at`
+
+### 2.2 memory_chunks（可检索文本）
+- `id`
+- `memory_item_id`
+- `text`（用于 FTS/embedding）
+- `embedding`
+- `tsv`
+- `meta_json`（包含 type/key、版本、语言等）
+
+> 规则：memory_items 是真相；memory_chunks 是派生索引内容，可重建。
+
+---
+
+## 3. 类型清单（v0.1）
+
+v0.1 约定以下类型（type）：
+
+### 3.1 profile（用户/主体画像）
+- 含义：稳定身份信息（职业、背景、组织、长期角色）
+- key 规则：`profile:<subject>`  
+  - subject 常用：`user`（默认）、或 `agent`（多主体时）
+- value_json 示例：
+```json
+{
+  "subject": "user",
+  "facts": [
+    {"k": "role", "v": "Executive Secretary General of ...", "since": "2024-05-17"}
+  ]
+}
+```
+
+* 写入门控：只有明确陈述且稳定的信息才写入；不确定内容写入 events，不写 profile。
+
+### 3.2 preferences（偏好与约束）
+
+* 含义：写作风格、工具偏好、语言偏好、预算偏好等
+* key 规则：`pref:<scope>:<name>`
+
+  * scope：`writing|coding|tools|ui|other`
+* value_json 示例：
+
+```json
+{
+  "scope": "writing",
+  "name": "tone",
+  "value": "focused and exacting",
+  "priority": 0.8
+}
+```
+
+* 冲突策略：同 key 新值覆盖旧值（旧值 status=superseded），保留历史版本。
+
+### 3.3 goals（长期目标）
+
+* 含义：项目目标、学习目标、长期规划
+* key 规则：`goal:<project_or_topic>:<name>`
+* value_json 示例：
+
+```json
+{
+  "project": "SmartBrain",
+  "name": "local_first_memory_runtime",
+  "description": "Build ...",
+  "status": "active"
+}
+```
+
+### 3.4 tasks（任务与待办）
+
+* 含义：可追踪的任务项（含状态流转）
+* key 规则：`task:<project>:<task_id>`（task_id 可为 uuid 或 slug）
+* value_json 示例：
+
+```json
+{
+  "project": "SmartBot",
+  "task_id": "brain_runtime_mvp",
+  "title": "Integrate SmartBrain into SmartBot loop",
+  "status": "todo|doing|done|blocked",
+  "due": "2026-03-01",
+  "notes": ["..."]
+}
+```
+
+* 重要：tasks 应当支持状态更新（commit_turn 时识别“已完成/阻塞”）。
+
+### 3.5 decisions（决策与承诺）
+
+* 含义：已经决定的方案、选择、不可逆约束
+* key 规则：`decision:<project>:<topic>`
+* value_json 示例：
+
+```json
+{
+  "project": "SmartRAG",
+  "topic": "retrieve_api_contract",
+  "decision": "Add retrieve(plan) returning EvidencePack",
+  "rationale": "Contract-based integration with SmartBrain",
+  "made_at": "2026-02-20"
+}
+```
+
+### 3.6 entities（实体）
+
+* 含义：对话中出现的重要实体（人/组织/项目/仓库/文件/URL 域名等）
+* key 规则：`entity:<kind>:<canonical>`
+
+  * kind：`person|org|repo|file|url|topic|other`
+* value_json 示例：
+
+```json
+{
+  "kind": "repo",
+  "canonical": "zhuangbiaowei/smart_rag",
+  "aliases": ["smart_rag"],
+  "attrs": {"host": "github.com"}
+}
+```
+
+* 备注：entities 通常配合 entity_mentions 表用于关联检索。
+
+### 3.7 events（重要事件）
+
+* 含义：可被未来引用的关键事件（发布、会议、里程碑、异常）
+* key 规则：`event:<project_or_scope>:<date>:<slug>`
+* value_json 示例：
+
+```json
+{
+  "scope": "SmartBrain",
+  "date": "2026-02-20",
+  "title": "Decided to split memory runtime into SmartBrain",
+  "impact": "architecture"
+}
+```
+
+### 3.8 cases（案例/经验片段）
+
+* 含义：某次任务的输入—过程—输出—结果，可复用
+* key 规则：`case:<domain>:<slug_or_id>`
+* value_json 示例：
+
+```json
+{
+  "domain": "rag_debug",
+  "problem": "...",
+  "solution": "...",
+  "outcome": "works",
+  "artifacts": [{"type":"doc","ref":"..."}]
+}
+```
+
+### 3.9 patterns（模式/规则）
+
+* 含义：从多个案例/对话中归纳出的可复用策略
+* key 规则：`pattern:<domain>:<name>`
+* value_json 示例：
+
+```json
+{
+  "domain": "context_composing",
+  "name": "slot_based_composition",
+  "rule": "system core -> summary -> recent -> evidence -> user",
+  "confidence": 0.7
+}
+```
+
+---
+
+## 4. key 设计规则（必须遵守）
+
+1. **稳定性**：同一事实应映射到同一 key（便于更新与去重）
+2. **可读性**：key 应可读可排查（不全是 uuid）
+3. **可扩展**：允许引入 scope/domain/project 前缀
+4. **可多主体**：必要时将 subject 纳入 key（profile/user vs profile/agent）
+
+---
+
+## 5. 写入门控（Retention Gate）最低要求
+
+SmartBrain 在 commit_turn 时必须执行门控：
+
+* 必写（高价值）：
+
+  * tool_call 结果（尤其是产出 artifact、变更状态）
+  * refs（文件/URL）及其摘要/元信息
+  * decisions（明确决策）
+  * tasks（新增/更新/完成）
+* 条件写（中价值）：
+
+  * preferences（明确偏好、可稳定复用）
+  * goals（明确长期目标）
+  * entities/events（出现频繁或被强调的实体/事件）
+* 不写入长期记忆（仅存 event）：
+
+  * 闲聊、情绪性内容、一次性无复用信息
+  * 模糊推测、未确认事实
+
+---
+
+## 6. 冲突合并策略（最低要求）
+
+### 6.1 覆盖型（overwrite）
+
+适用：preferences/goals/tasks（同 key 新值应覆盖旧值）
+
+* 旧值标记：`status = superseded`
+* 保留历史版本（便于回滚/审计）
+
+### 6.2 多版本并存（versioned）
+
+适用：profile（谨慎）、decisions/events（应保留历史）
+
+* 以时间或版本号区分（在 value_json 中存 `version` 或 `made_at`）
+* compose 时默认选最新/最高置信
+
+### 6.3 撤回（retracted）
+
+适用：用户明确否认的事实
+
+* 将旧条目标记 `status = retracted`
+* 新条目可写入修正事实（同 key 或新 key）
+
+---
+
+## 7. memory_chunks 文本化规则（用于检索）
+
+为了让 FTS/embedding 有用，每个 memory_item 应生成一个或多个 chunk 文本：
+
+* 第一行：`[type:key]`（用于定位）
+* 主体：对 value_json 的可读摘要
+* 可附：来源/时间/项目
+
+示例（preferences）：
+
+```
+[preferences:pref:writing:tone]
+User prefers a focused and exacting tone for technical documents.
+Updated at: 2026-02-20
+```
+
+---
+
+## 8. 版本与兼容
+
+* v0.1：类型集合与 key 规则为最低一致性要求
+* 可新增 type，但必须遵守 key 规则
+* 破坏性变更（重命名 type/key 规则）需要 major 版本与迁移策略