smart_brain 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8680f123a98c14a68780c2ef0ec315e5f2a45446c2692cc81a8fed527ecafb7
-  data.tar.gz: 8f782644dbe7202bd8cfe51660b88d0f5ff9c855e1d7fb3bf121e7286975bfe2
+  metadata.gz: 79a975252d1cd55bc21928851ba6c2e250ad7d6a87d26d659c025da5e18836d6
+  data.tar.gz: 4a5cff31efd5d411dd14e8100561a2ab6fd04678801eeb283f493261329a73c6
 SHA512:
-  metadata.gz: 5f7ce80bf28a81ae4d4775ace5566b007b1c80ecc02413f15609f190207ddd46776f0fa3c45e7295447adce748f406baa0622e38566b741a8bf02a13e9388342
-  data.tar.gz: 2ee106f092c37f5d8d96c821b9b4d1fc0995e476d545fa57dd051234eea2e244942c9593523e90024b6c648b0024c74fa805a3881ff08d2ffee6e2fcbcdfe1ea
+  metadata.gz: '01534922911c9446056dc33859bec7cb6818593a08ab59d5194beb4fb1877a104cf59535309ccf66015a4d8ac199c9bfd47d6480331a12872642dbe53d39b6cf'
+  data.tar.gz: 711502b6b7435e057669580b174c03425a03ccfd5f38c4d57f79307b6ec7a37e95ec6ee6090a3da36a25b435b9ed3d13ee89e9d4008206030a1cf0addb90820c

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.3.0 - 2026-08-14
+
+- Add document, image, audio, and video memory ingestion through the public runtime facade.
+- Add asynchronous media job enqueue, status, listing, cancellation, retry, and queue statistics APIs.
+- Add media metadata extraction with graceful partial-result fallbacks.
+- Add multipart-capable SmartRAG HTTP transport with scoped retrieval and media operations.
+- Propagate media-type resource filters into SmartRAG retrieval plans.
+- Keep null, direct, and HTTP SmartRAG adapters behaviorally aligned for optional deployments.
+- Require SmartRAG 0.2 for the media, principal-isolation, and durable-job contracts.
+
 ## 0.2.0 - 2026-08-03
 
 - Add domain-isolated global, project, expert, task, and legacy session memory scopes.

data/README.en.md

@@ -33,6 +33,7 @@ The repository now includes a runnable v0.1 flow with:
 - `config/brain.yml`: policy config
 - `example.rb`: SmartBrain + SmartAgent + SmartPrompt + SmartRAG demo
 - `docs/`: design and protocol documents
+- `docs/media_memory_schema.md`: media-memory contract, production controls, and SmartRAG migration requirements (Chinese)
 
 ## Installation
 
@@ -98,6 +99,17 @@ client = SmartBrain::Adapters::SmartRag::HttpClient.new(transport: transport, ti
 SmartBrain.configure(smart_rag_client: client)
 ```
 
+For the built-in SmartRAG HTTP API, configure the remote endpoint and Bearer token directly:
+
+```ruby
+client = SmartBrain::Adapters::SmartRag::HttpClient.for_url(
+  base_url: 'http://127.0.0.1:9393',
+  timeout_seconds: 30,
+  headers: { 'Authorization' => "Bearer #{ENV.fetch('SMARTRAG_TOKEN')}" }
+)
+SmartBrain.configure(smart_rag_client: client)
+```
+
 ### 3) DirectClient (used in `example.rb`)
 
 ```ruby
@@ -111,6 +123,27 @@ client = SmartBrain::Adapters::SmartRag::DirectClient.new(rag: rag)
 SmartBrain.configure(smart_rag_client: client)
 ```
 
+## Media Queue Production Contract
+
+SmartBrain delegates image, audio, and video persistence to SmartRAG. Before deploying the current queue code, migrate the **SmartRAG database** through `017_add_media_job_request_fingerprint`; running `smart_brain migrate` does not apply SmartRAG migrations. Migrations 015 and 016 add leases, shared S3/MinIO object lifecycle, staging protection, and principal-owned documents. Migration 017 backfills and requires a canonical SHA-256 request fingerprint.
+
+Use a stable idempotency key for asynchronous retries:
+
+```ruby
+job = SmartBrain.enqueue_media(
+  source: '/data/product-demo.mp4',
+  options: { media_type: 'video', idempotency_key: 'product-demo-v1' }
+)
+```
+
+For the same authenticated principal, repeating the same operation, source, and canonicalized options returns the original job with `deduplicated: true`. Reusing the key with a different payload returns SmartRAG HTTP `409` and `code: "idempotency_conflict"`. Keep both the original key and payload for network retries; generate a new key when the business payload changes.
+
+`HttpClient` converts a non-2xx response into a SmartBrain result with `status: "failed"`; an idempotency conflict is visible in `warnings` as `SmartRAG HTTP 409`. `DirectClient` propagates `SmartRAG::Core::MediaJobQueue::IdempotencyConflict` to the caller.
+
+Authenticated SmartRAG retrieval uses defense in depth: it pushes the principal's PostgreSQL-owned document IDs into search and rechecks returned candidates before emitting evidence. Invalid Bearer tokens return 401. For multi-instance workers, configure a shared S3 or MinIO endpoint, bucket, and prefix; retained failed jobs protect their staging objects until pruning.
+
+SmartRAG's opt-in real integration suites verify MinIO cross-instance storage and deletion, asynchronous worker materialization, failed-job GC protection, Bearer-token tenant isolation, HTTP 409 behavior, and concurrent idempotency races. See the SmartRAG README section "Real storage and isolation verification" for environment variables and commands.
+
 ## `example.rb` (Updated)
 
 The example demonstrates the real loop:

data/README.md

@@ -35,6 +35,23 @@ SmartBrain 把 Agent 的可用信息分为两类，分工明确：
 
 ## 安装
 
+### 从 RubyGems 安装（推荐给最终用户）
+
+```bash
+gem install smart_brain
+```
+
+装完即可用，默认零外部依赖（memory 后端 + stub LLM）：
+
+```bash
+smart_brain --version
+smart_brain status
+```
+
+完整安装/配置/可选能力（PostgreSQL 持久化、Ollama/OpenAI LLM、SmartRAG 资源检索）见 **[`docs/installation.md`](docs/installation.md)**。
+
+### 从源码开发
+
 ```bash
 bundle install
 ```
@@ -256,6 +273,7 @@ docs/
   context_package.md                        # ContextPackage 协议
   retrieval_plan.md                         # RetrievalPlan 协议
   evidence_pack.md                          # EvidencePack 协议
+  media_memory_schema.md                    # 媒体记忆契约、生产能力和迁移约束
 spec/
   spec_helper.rb
   commit_turn_spec.rb                       # commit_turn 单元测试
@@ -367,7 +385,22 @@ SmartBrain.configure  # 无需额外配置
 
 ### 2) HttpClient（HTTP 远程）
 
-通过自定义 transport lambda 调用远端 SmartRAG 服务，支持超时降级。
+通过 SmartRAG HTTP 服务调用远端资源库，支持 JSON URL 导入、multipart 文件上传和超时降级：
+
+```ruby
+client = SmartBrain::Adapters::SmartRag::HttpClient.for_url(
+  base_url: 'http://127.0.0.1:9393',
+  timeout_seconds: 30,
+  headers: { 'Authorization' => "Bearer #{ENV.fetch('SMARTRAG_TOKEN')}" }
+)
+SmartBrain.configure(smart_rag_client: client)
+
+SmartBrain.add_video(source: '/data/demo.mp4', options: { tags: ['demo'] })
+```
+
+本地路径自动使用 multipart 上传，HTTP/HTTPS source 使用 JSON URL 导入。OCR、视觉描述和转写 callable 不能跨进程序列化，必须配置在远端 SmartRAG `HttpApp` 的 `extractors:` 中。
+
+也可以继续通过自定义 transport lambda 集成其他协议：
 
 ```ruby
 transport = lambda do |plan, timeout_seconds:|
@@ -407,6 +440,99 @@ SmartBrain.configure(smart_rag_client: client)
 
 Mapper 返回的 `filters` 会作为 `scope_filters` 发送给 SmartRAG。业务 scope 存在时，后端必须返回 `scope_filter_applied: true`；mapper 缺失、映射失败或后端未确认时，adapter 默认 fail closed，丢弃资源证据并在 `warnings` 和 `explain.ignored_fields` 中说明原因。
 
+## 多媒体记忆（MVP）
+
+SmartBrain 通过 SmartRAG 保存图片、音频和视频的技术元数据，并把描述、OCR 或转写文本作为普通 section 建立全文及向量索引：
+
+```ruby
+SmartBrain.add_image(
+  source: '/data/whiteboard.jpg',
+  options: {
+    title: 'Q3 路线图白板',
+    tags: ['roadmap'],
+    image_describer: ->(path) { vision_client.describe(path) },
+    ocr_extractor: ->(path) { ocr_client.extract(path) }
+  }
+)
+
+SmartBrain.add_audio(
+  source: '/data/weekly-meeting.wav',
+  options: {
+    tags: ['meeting'],
+    audio_transcriber: ->(path) { whisper_client.transcribe(path) }
+  }
+)
+
+SmartBrain.add_video(
+  source: '/data/product-demo.mp4',
+  options: {
+    tags: ['demo'],
+    # start/end 使用秒；也可以返回 start_ms/end_ms。
+    video_transcriber: ->(audio_path) {
+      whisper_client.transcribe(audio_path, timestamps: true)
+      # => { segments: [{ text: '打开设置', start: 5.0, end: 9.0 }] }
+    },
+    frame_describer: ->(frame_path, timestamp_ms) {
+      vision_client.describe(frame_path, timestamp_ms: timestamp_ms)
+    },
+    frame_interval_seconds: 30,
+    max_frames: 12
+  }
+)
+```
+
+`add_media` 会根据扩展名和 MIME 类型自动判断类型；`add_image`、`add_audio`、`add_video` 固定类型。Pillow 或 ffprobe 缺失、语义提取器未配置或调用失败时，导入仍会保存文件名、标签和可获得的技术元数据，返回 `status: "partial"` 及 `warnings`。
+
+按媒体类型限制资源检索：
+
+```ruby
+SmartBrain.compose_context(
+  session_id: 'demo',
+  user_message: '查资料：路线图白板上写了什么？',
+  resource_filters: { media_type: ['image'] }
+)
+```
+
+SmartRAG 的 P1 配置可启用本地内容寻址存储（SHA-256 去重），并内置 OpenAI-compatible 图片描述/音频转写与可选 Tesseract OCR。未启用内容存储时仍保存原文件路径或 URL。
+
+异步导入和状态查询：
+
+```ruby
+job = SmartBrain.enqueue_media(
+  source: '/data/long-demo.mp4',
+  options: { media_type: 'video', tags: ['demo'] }
+)
+status = SmartBrain.media_job(job_id: job[:job_id])
+
+failed = SmartBrain.media_jobs(status: 'failed', limit: 20)
+SmartBrain.retry_media_job(job_id: failed[:jobs].first[:id])
+SmartBrain.cancel_media_job(job_id: job[:job_id]) # 仅 queued 状态可取消
+queue = SmartBrain.media_job_statistics
+```
+
+HTTP 客户端会发送 `options.async=true`，服务端返回 202；SmartRAG worker 负责消费 PostgreSQL `media_jobs` 队列。P2 支持任务分页/状态过滤、取消、人工重试、卡死任务恢复、保留期清理和健康指标。默认 `NullClient` 对写入和任务查询返回 `unsupported`。
+
+P3 支持按调用方隔离的幂等入队。HTTP 模式可把幂等键放在 options 中；服务端也接受标准请求头 `Idempotency-Key`：
+
+```ruby
+job = SmartBrain.enqueue_media(
+  source: '/data/long-demo.mp4',
+  options: { media_type: 'video', idempotency_key: 'demo-video-v1' }
+)
+```
+
+部署当前版本前，SmartRAG 数据库必须执行到迁移 `017_add_media_job_request_fingerprint`。该迁移为历史任务回填规范化 SHA-256 请求指纹，并将指纹列设为必填。同一 principal 下，用相同幂等键重复提交相同 operation、source 和 options，会返回原任务并标记 `deduplicated: true`；相同键对应不同 source 或 options 时，SmartRAG 返回 HTTP `409` 和 `code: "idempotency_conflict"`。嵌套 Hash 的键顺序以及 symbol/string 键不影响指纹，数组顺序仍有意义。
+
+`HttpClient` 会将该 409 转成 SmartBrain 的失败结果：`status: "failed"`，并在 `warnings` 中包含 `SmartRAG HTTP 409`。调用方应保持原载荷和原幂等键进行网络重试；业务载荷发生变化时必须生成新键。`DirectClient` 进程内调用时，SmartRAG 的 `MediaJobQueue::IdempotencyConflict` 会直接向上传播。
+
+多实例部署应把 SmartRAG `media.content_store.provider` 配置成 `s3`，可连接 AWS S3 或 MinIO。P3 worker 使用 heartbeat 租约避免长任务被错误恢复，并维护媒体对象引用计数和零引用垃圾回收。HTTP Bearer token 可继续通过 `HttpClient.for_url(headers: ...)` 设置。
+
+SmartRAG 迁移 016 将认证 principal 写入文档 owner，并把它应用到检索、文档读取/列表/删除和统计。HTTP 检索会把 principal 对应的文档 ID 下推给搜索后端，并在生成 EvidencePack 前根据 PostgreSQL owner 再次过滤候选；即使后端忽略 `document_ids`，也不能返回其他租户证据。failed 任务保留期间，其 staging 对象不会被 GC 删除，人工重试仍可读取原始媒体；同步导入在后续处理失败时留下的零引用对象可被 GC 回收。
+
+SmartRAG 提供显式启用的真实集成测试。`SMARTRAG_MINIO_E2E=1` 的 MinIO 用例覆盖跨实例上传/下载、异步 worker 读取 `s3://` staging URI、对象引用和真实 GC 删除；`media_tenant_isolation_spec.rb` 与 `media_p3_spec.rb` 覆盖 Bearer 多租户检索、非法 token、幂等 409 和并发唯一键竞争。具体环境变量和命令见 SmartRAG README 的 “Real storage and isolation verification”。
+
+视频的转写片段和关键帧描述分别保存为 section。检索命中后，EvidencePack 的 `metadata` 会包含 `extraction_kind`、`start_ms`、`end_ms` 或 `frame_timestamp_ms`，调用方可据此跳转到视频位置。视频处理依赖 `ffmpeg`；缺失时导入降级为 `partial`。
+
 ## 运行示例
 
 ### example.rb

data/docs/installation.md

@@ -0,0 +1,198 @@
+# SmartBrain 安装与配置指南（面向最终用户）
+
+本指南面向通过 RubyGems 安装 SmartBrain 的用户。读完并照做后即可直接使用，
+无需克隆源码或维护开发环境。
+
+## 1. 安装
+
+要求 Ruby >= 3.0，已安装 RubyGems：
+
+```bash
+gem install smart_brain
+```
+
+验证安装：
+
+```bash
+smart_brain --version     # 打印版本号
+smart_brain status        # 打印运行时诊断（默认 memory 后端）
+```
+
+如果 `smart_brain` 命令不在 PATH 里，检查 RubyGems 的 bin 目录（`gem env` 里的
+`EXECUTABLE DIRECTORY`）并把它加入 `PATH`。
+
+## 2. 开箱即用（零外部依赖）
+
+默认配置（打包在 gem 内的 `config/brain.yml`）：
+
+- 存储后端：`memory`（进程内，重启即丢，适合开发/试用）
+- LLM：`stub`（确定性、零网络，摘要走模板、重排走词法）
+- 资源 RAG：未挂载（`NullClient`，资源证据为空）
+
+因此装完什么都不用配就能跑：
+
+```ruby
+require 'smart_brain'
+
+SmartBrain.configure
+
+SmartBrain.commit_turn(
+  session_id: 'demo',
+  turn_events: {
+    messages: [
+      { role: 'user', content: '记住：默认数据库是 Postgres。' },
+      { role: 'assistant', content: '已记录。' }
+    ],
+    decisions: [{ key: 'decision:storage', decision: '默认用 Postgres' }]
+  }
+)
+
+context = SmartBrain.compose_context(session_id: 'demo', user_message: '继续并总结关键结论')
+puts context[:working_summary]
+puts context[:evidence].size
+puts context.dig(:debug, :trace)   # => { context_id, request_id, plan_id }
+```
+
+## 3. 配置方式
+
+SmartBrain 的配置优先级（从高到低）：
+
+1. **环境变量**（最推荐，尤其面向进程/容器/agent 工具）
+2. **自定义配置文件**：`SmartBrain.configure(config_path: '/path/to/brain.yml')`，
+   CLI 用 `--config PATH` 或环境变量 `SMARTBRAIN_CONFIG`
+3. **gem 内置默认值**：`config/brain.yml`
+
+> 内置 `config/brain.yml` 位于 gem 安装目录内，**不要直接修改它**（升级会被覆盖）。
+> 需要自定义时，复制一份到自己的目录，改完再用 `config_path` / `--config` 指向它。
+
+### 3.1 环境变量速查
+
+| 变量 | 作用 | 默认 |
+|---|---|---|
+| `SMARTBRAIN_BACKEND` | `memory` / `postgres` | `memory` |
+| `SMARTBRAIN_DB_HOST` | Postgres 主机 | `127.0.0.1` |
+| `SMARTBRAIN_DB_PORT` | Postgres 端口 | `5432` |
+| `SMARTBRAIN_DB_NAME` | Postgres 数据库 | `smart_brain_development` |
+| `SMARTBRAIN_DB_USER` | Postgres 用户 | `smart_brain` |
+| `SMARTBRAIN_DB_PASSWORD` | Postgres 密码 | `smart_brain` |
+| `SMARTBRAIN_LLM_PROVIDER` | `stub` / `ollama` / `openai` | `stub` |
+| `SMARTBRAIN_LLM_MODEL` | 生成式模型名 | 配置文件里的 `model` |
+| `SMARTBRAIN_LLM_BASE_URL` | LLM 端点 | `http://localhost:11434` |
+| `SMARTBRAIN_LLM_API_KEY` | OpenAI 兼容 API key | 空 |
+| `SMARTBRAIN_CONFIG` | 配置文件路径（CLI 用） | 无 |
+
+## 4. 可选能力（按需开启）
+
+### 4.1 持久化（PostgreSQL）
+
+跨进程/重启保留记忆，并启用 `memory_chunks` 全文检索：
+
+```bash
+# 一次性：建角色与库（以 postgres 超级用户执行）
+sudo -u postgres createuser -d smart_brain
+sudo -u postgres psql -c "ALTER USER smart_brain PASSWORD 'smart_brain';"
+sudo -u postgres createdb -O smart_brain smart_brain_development
+```
+
+然后：
+
+```bash
+export SMARTBRAIN_BACKEND=postgres
+export SMARTBRAIN_DB_NAME=smart_brain_development
+smart_brain migrate      # 幂等建表（也可省略：postgres 后端启动时会自动 migrate）
+smart_brain status       # 应显示 backend=postgres
+```
+
+### 4.2 真 LLM 摘要与重排（Ollama）
+
+默认 `stub` 不联网。切到本地 Ollama 后，`working_summary` 走真摘要、Fusion 走
+LLM-as-judge 重排：
+
+```bash
+ollama serve &            # 起 ollama
+ollama pull qwen3         # 注意：需要「生成式」模型（qwen3/llama2），不是 qwen3-embedding
+export SMARTBRAIN_LLM_PROVIDER=ollama
+export SMARTBRAIN_LLM_MODEL=qwen3
+```
+
+OpenAI 兼容端点（silicon_flow 等）：
+
+```bash
+export SMARTBRAIN_LLM_PROVIDER=openai
+export SMARTBRAIN_LLM_BASE_URL=https://api.siliconflow.cn/v1
+export SMARTBRAIN_LLM_API_KEY=sk-...
+export SMARTBRAIN_LLM_MODEL=Qwen/Qwen3-8B
+```
+
+> 说明：`qwen3-embedding` 只能算向量，不能做文本生成；摘要/重排必须用生成式聊天模型。
+
+### 4.3 资源 RAG（SmartRAG）
+
+SmartBrain 默认不依赖 SmartRAG（资源证据为空）。需要文档/网页/代码库检索时：
+
+```bash
+gem install smart_rag
+```
+
+再按需挂载进程内直连或 HTTP 适配器（见
+[`user_guide.md §12`](user_guide.md) 与 README）：
+
+```ruby
+require 'smart_rag'
+require 'smart_brain/adapters/smart_rag/direct_client'
+
+rag = SmartRAG::SmartRAG.new(...)   # 需配置 PostgreSQL + LLM + embedding
+client = SmartBrain::Adapters::SmartRag::DirectClient.new(rag: rag)
+SmartBrain.configure(smart_rag_client: client)
+```
+
+## 5. 使用方式
+
+安装后同一套能力可通过四种方式调用（共享同一个 `Server::Service` 门面）：
+
+```bash
+# 1) CLI 一次性命令
+smart_brain commit --data '{"session_id":"demo","turn_events":{"messages":[{"role":"user","content":"用 Postgres"}],"decisions":[{"key":"decision:db","decision":"用 Postgres"}]}}'
+smart_brain compose --data '{"session_id":"demo","user_message":"持久化方案？"}'
+smart_brain search --data '{"session_id":"demo","query":"Postgres"}'
+
+# 2) HTTP API（Puma）
+smart_brain serve --host 0.0.0.0 --port 9292
+curl -s localhost:9292/status
+curl -XPOST localhost:9292/commit -H 'Content-Type: application/json' -d '{...}'
+
+# 3) MCP（接 Claude Code / Cursor，19 个工具）
+smart_brain mcp
+
+# 4) Ruby 库（嵌入自己的 Agent 进程）
+#    require 'smart_brain'; SmartBrain.configure; SmartBrain.commit_turn(...)
+```
+
+> **注意 CLI 一次性命令与后端的关系**：`smart_brain commit/search/compose` 每次都是独立进程。
+> 默认 `memory` 后端只存在进程内，所以「先 commit 再 search」在**同一条命令里看不到**（第二次是全新进程）。
+> 要用 CLI 跨命令持久化，请先切 `SMARTBRAIN_BACKEND=postgres` 并 `smart_brain migrate`。
+> MCP 和 HTTP serve 是长驻进程，进程存续期内 memory 后端也能跨调用记住；跨重启仍需 postgres。
+
+MCP 接入配置示例见 [`mcp.md`](mcp.md)；完整 API 与治理能力见
+[`user_guide.md`](user_guide.md)。
+
+## 6. 常见问题
+
+- **`smart_brain: command not found`**：把 `gem env` 显示的 EXECUTABLE DIRECTORY 加入 `PATH`。
+- **`cannot load such file -- sequel/extensions/pgvector`**：见 README「常见问题」；不影响核心使用。
+- **Postgres 连接失败**：检查 `SMARTBRAIN_DB_*` 是否与建库时一致，先 `smart_brain migrate`。
+- **切 ollama 后摘要还是模板**：确认 `SMARTBRAIN_LLM_PROVIDER=ollama` 且模型是生成式（非 embedding）。
+- **要不要装 `smart_rag`**：只有需要资源 RAG 时才装；纯对话记忆场景完全不需要。
+
+## 7. 从源码开发/运行测试（可选）
+
+仅在需要改代码或跑测试时：
+
+```bash
+git clone https://github.com/zhuangbiaowei/smart_brain
+cd smart_brain
+bundle install
+bundle exec rspec                                   # memory 后端
+SMARTBRAIN_PG=1 bundle exec rspec                   # 含 PostgreSQL 集成
+SMARTBRAIN_LLM=1 bundle exec rspec spec/smoke_ollama_spec.rb   # 真实 Ollama 冒烟
+```