smart_brain 0.2.0 → 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/retrieval_plan.md

@@ -110,6 +110,7 @@ RetrievalPlan 是一个 JSON/Ruby Hash 对象（可序列化入日志）。
   "tag_ids": ["..."],
   "topic_ids": ["..."],
   "source_type": ["url","file","manual","memory_snapshot"],
+  "media_type": ["image","audio","video","document","other"],
   "source_uri_prefix": ["https://...", "file://..."],
   "language": ["zh","en"],
   "time_range": { "from": "2026-01-01T00:00:00Z", "to": "2026-02-20T00:00:00Z" }
@@ -120,6 +121,7 @@ RetrievalPlan 是一个 JSON/Ruby Hash 对象（可序列化入日志）。
 
 * `document_ids/tag_ids/topic_ids`：知识库内过滤
 * `source_type`：资源类型过滤（建议 SmartRAG 支持）
+* `media_type`：媒体内容类型过滤；接受单值或数组
 * `source_uri_prefix`：按 URI 前缀过滤（适合域名/路径范围）
 * `language`：语言过滤（可选）
 * `time_range`：时间过滤（可按 documents.created_at 或 sections.created_at 实现）
@@ -228,4 +230,4 @@ RetrievalPlan 是一个 JSON/Ruby Hash 对象（可序列化入日志）。
 
 * v0.1：新增字段只能“可选”，不得破坏现有字段含义
 * v0.x：执行方必须忽略未知字段并在 explain 中声明（可选）
-* v1.0：如需破坏性变更，另起 major 版本并提供迁移说明
+* v1.0：如需破坏性变更，另起 major 版本并提供迁移说明

data/docs/user_guide.md

@@ -539,6 +539,7 @@ SMARTBRAIN_LLM=1 bundle exec rspec spec/smoke_ollama_spec.rb   # 真实 Ollama
 
 ## 18. 进阶文档
 
+- 安装与配置（最终用户）：`docs/installation.md`
 - 设计与契约：`docs/smartbrain_design.md`、`docs/policies.md`、`docs/memory_types.md`
 - 策略与治理：`docs/retrieval_plan.md`、`docs/evidence_pack.md`、`docs/context_package.md`
 - MCP 接入：`docs/mcp.md`

data/examples/07_media_memory.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'smart_brain'
+require 'smart_rag'
+require 'smart_brain/adapters/smart_rag/direct_client'
+
+rag = SmartRAG::SmartRAG.new(
+  database: {
+    adapter: 'postgresql',
+    host: ENV.fetch('SMARTBRAIN_RAG_DB_HOST', '127.0.0.1'),
+    port: ENV.fetch('SMARTBRAIN_RAG_DB_PORT', '5432').to_i,
+    database: ENV.fetch('SMARTBRAIN_RAG_DB_NAME', 'smart_rag_development'),
+    user: ENV.fetch('SMARTBRAIN_RAG_DB_USER', 'rag_user'),
+    password: ENV.fetch('SMARTBRAIN_RAG_DB_PASSWORD', 'rag_pwd')
+  }
+)
+SmartBrain.configure(
+  smart_rag_client: SmartBrain::Adapters::SmartRag::DirectClient.new(rag: rag)
+)
+
+image_result = SmartBrain.add_image(
+  source: ARGV.fetch(0),
+  options: {
+    title: 'Imported image',
+    tags: ['image'],
+    # Replace this callable with the vision/OCR provider used by your app.
+    image_describer: ->(_path) { 'A user-provided image description' }
+  }
+)
+puts image_result
+
+if ARGV[1]
+  video_result = SmartBrain.add_video(
+    source: ARGV[1],
+    options: {
+      title: 'Imported video',
+      video_transcriber: lambda do |_audio_path|
+        { segments: [{ text: 'Example timestamped transcript', start: 0.0, end: 5.0 }] }
+      end,
+      frame_describer: ->(_frame_path, timestamp_ms) { "Video frame at #{timestamp_ms} ms" },
+      frame_interval_seconds: 30,
+      max_frames: 6
+    }
+  )
+  puts video_result
+end
+
+context = SmartBrain.compose_context(
+  session_id: 'media-demo',
+  user_message: '查资料：这张图片里有什么？',
+  resource_filters: { media_type: 'image' }
+)
+puts context[:evidence]

data/lib/smart_brain/adapters/smart_rag/direct_client.rb

@@ -34,10 +34,51 @@ module SmartBrain
           }
         end
 
+        def add_document(source, options = {}) = write(:add_document, source, options)
+        def add_media(source, options = {}) = write(:add_media, source, options)
+        def add_image(source, options = {}) = write(:add_image, source, options)
+        def add_audio(source, options = {}) = write(:add_audio, source, options)
+        def add_video(source, options = {}) = write(:add_video, source, options)
+        def enqueue_media(source, options = {}) = write(:enqueue_media, source, options)
+
+        def media_job(job_id)
+          rag.media_job(job_id) || { status: 'not_found', job_id: job_id, warnings: ['media job not found'] }
+        rescue StandardError => e
+          { status: 'failed', job_id: job_id, warnings: ["smart_rag direct media_job failed: #{e.message}"] }
+        end
+
+        def media_jobs(status: nil, limit: 20, offset: 0)
+          rag.media_jobs(status: status, limit: limit, offset: offset)
+        end
+
+        def cancel_media_job(job_id) = rag.cancel_media_job(job_id)
+        def retry_media_job(job_id) = rag.retry_media_job(job_id)
+        def media_job_statistics = rag.media_job_statistics
+
         private
 
         attr_reader :rag, :scope_mapper, :fail_closed
 
+        def write(operation, source, options)
+          normalize_write_result(rag.public_send(operation, source, options), operation)
+        rescue StandardError => e
+          {
+            status: 'failed',
+            media_type: operation.to_s.delete_prefix('add_'),
+            section_count: 0,
+            warnings: ["smart_rag direct #{operation} failed: #{e.message}"]
+          }
+        end
+
+        def normalize_write_result(response, operation)
+          result = response.is_a?(Hash) ? response.dup : {}
+          result[:status] ||= 'success'
+          result[:media_type] ||= operation.to_s.delete_prefix('add_') unless operation == :add_media
+          result[:section_count] ||= 0
+          result[:warnings] = Array(result[:warnings])
+          result
+        end
+
         def normalize_pack(response, request_id:)
           pack = response.is_a?(Hash) ? response : {}
           {

data/lib/smart_brain/adapters/smart_rag/http_client.rb

@@ -8,13 +8,70 @@ module SmartBrain
       class HttpClient
         include ScopeFilter
 
-        def initialize(transport:, timeout_seconds: 2, scope_mapper: nil, fail_closed: true)
+        def initialize(transport:, write_transport: nil, job_transport: nil, job_list_transport: nil,
+                       job_mutation_transport: nil, job_statistics_transport: nil,
+                       timeout_seconds: 2, scope_mapper: nil, fail_closed: true)
           @transport = transport
+          @write_transport = write_transport
+          @job_transport = job_transport
+          @job_list_transport = job_list_transport
+          @job_mutation_transport = job_mutation_transport
+          @job_statistics_transport = job_statistics_transport
           @timeout_seconds = timeout_seconds
           @scope_mapper = scope_mapper
           @fail_closed = fail_closed
         end
 
+        def self.for_url(base_url:, timeout_seconds: 30, headers: {}, scope_mapper: nil, fail_closed: true)
+          require_relative 'http_transport'
+          http_transport = HttpTransport.new(base_url: base_url, headers: headers)
+          new(
+            transport: http_transport.method(:retrieve),
+            write_transport: http_transport.method(:write),
+            job_transport: http_transport.method(:media_job),
+            job_list_transport: http_transport.method(:media_jobs),
+            job_mutation_transport: http_transport.method(:mutate_media_job),
+            job_statistics_transport: http_transport.method(:media_job_statistics),
+            timeout_seconds: timeout_seconds,
+            scope_mapper: scope_mapper,
+            fail_closed: fail_closed
+          )
+        end
+
+        def add_document(source, options = {}) = write(:add_document, source, options)
+        def add_media(source, options = {}) = write(:add_media, source, options)
+        def add_image(source, options = {}) = write(:add_image, source, options)
+        def add_audio(source, options = {}) = write(:add_audio, source, options)
+        def add_video(source, options = {}) = write(:add_video, source, options)
+        def enqueue_media(source, options = {}) = write(:add_media, source, options.merge(async: true))
+
+        def media_job(job_id)
+          return { status: 'unsupported', job_id: job_id, warnings: ['smart_rag job transport not configured'] } unless job_transport
+          result = job_transport.call(job_id, timeout_seconds: timeout_seconds)
+          result[:warnings] = Array(result[:warnings])
+          result
+        rescue Timeout::Error
+          { status: 'failed', job_id: job_id, warnings: ['smart_rag media_job timeout'] }
+        rescue StandardError => e
+          { status: 'failed', job_id: job_id, warnings: ["smart_rag media_job failed: #{e.message}"] }
+        end
+
+        def media_jobs(status: nil, limit: 20, offset: 0)
+          call_job_transport(job_list_transport, { status: status, limit: limit, offset: offset }, fallback: { jobs: [], total: 0 })
+        end
+
+        def cancel_media_job(job_id)
+          call_job_mutation(job_id, :cancel)
+        end
+
+        def retry_media_job(job_id)
+          call_job_mutation(job_id, :retry)
+        end
+
+        def media_job_statistics
+          call_job_transport(job_statistics_transport, fallback: { counts: {}, total: 0 })
+        end
+
         def retrieve(plan)
           started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           scoped_plan, required, ignored, warnings = prepare_scoped_plan(plan)
@@ -38,7 +95,52 @@ module SmartBrain
 
         private
 
-        attr_reader :transport, :timeout_seconds, :scope_mapper, :fail_closed
+        attr_reader :transport, :write_transport, :job_transport, :job_list_transport,
+                    :job_mutation_transport, :job_statistics_transport, :timeout_seconds,
+                    :scope_mapper, :fail_closed
+
+        def call_job_transport(callable, argument = nil, fallback:)
+          return fallback.merge(status: 'unsupported', warnings: ['smart_rag job transport not configured']) unless callable
+          result = argument ? callable.call(argument, timeout_seconds: timeout_seconds) : callable.call(timeout_seconds: timeout_seconds)
+          result[:warnings] = Array(result[:warnings])
+          result
+        rescue StandardError => e
+          fallback.merge(status: 'failed', warnings: ["smart_rag media job request failed: #{e.message}"])
+        end
+
+        def call_job_mutation(job_id, action)
+          return { status: 'unsupported', job_id: job_id,
+                   warnings: ['smart_rag job transport not configured'] } unless job_mutation_transport
+          result = job_mutation_transport.call(job_id, action, timeout_seconds: timeout_seconds)
+          result[:warnings] = Array(result[:warnings])
+          result
+        rescue StandardError => e
+          { status: 'failed', job_id: job_id,
+            warnings: ["smart_rag media job request failed: #{e.message}"] }
+        end
+
+        def write(operation, source, options)
+          return unsupported_write(operation) unless write_transport
+
+          raw = write_transport.call(
+            { operation: operation, source: source, options: options },
+            timeout_seconds: timeout_seconds
+          )
+          result = raw.is_a?(Hash) ? raw.dup : {}
+          result[:status] ||= 'success'
+          result[:section_count] ||= 0
+          result[:warnings] = Array(result[:warnings])
+          result
+        rescue Timeout::Error
+          { status: 'failed', section_count: 0, warnings: ["smart_rag #{operation} timeout"] }
+        rescue StandardError => e
+          { status: 'failed', section_count: 0, warnings: ["smart_rag #{operation} failed: #{e.message}"] }
+        end
+
+        def unsupported_write(operation)
+          { status: 'unsupported', section_count: 0,
+            warnings: ["smart_rag write transport not configured; #{operation} ignored"] }
+        end
 
         def build_pack(raw:, request_id:, took_ms:)
           ignored = []

data/lib/smart_brain/adapters/smart_rag/http_transport.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/multipart'
+require 'json'
+
+module SmartBrain
+  module Adapters
+    module SmartRag
+      class HttpTransport
+        EXTRACTOR_OPTIONS = %i[
+          audio_transcriber video_transcriber image_describer frame_describer ocr_extractor
+        ].freeze
+
+        def initialize(base_url:, headers: {})
+          @connection = Faraday.new(url: base_url, headers: headers) do |faraday|
+            faraday.request :multipart
+            faraday.request :url_encoded
+            faraday.adapter Faraday.default_adapter
+          end
+        end
+
+        def retrieve(plan, timeout_seconds:)
+          response = connection.post('/v1/retrieve') do |request|
+            request.options.timeout = timeout_seconds
+            request.headers['Content-Type'] = 'application/json'
+            request.body = JSON.generate(plan: serializable(plan))
+          end
+          parse_response(response)
+        end
+
+        def write(payload, timeout_seconds:)
+          options = payload.fetch(:options, {})
+          reject_callable_options!(options)
+          source = payload.fetch(:source).to_s
+
+          response = if File.file?(source)
+                       upload_file(payload[:operation], source, options, timeout_seconds)
+                     else
+                       write_source(payload[:operation], source, options, timeout_seconds)
+                     end
+          parse_response(response)
+        end
+
+        def media_job(job_id, timeout_seconds:)
+          response = connection.get("/v1/media/jobs/#{Integer(job_id)}") do |request|
+            request.options.timeout = timeout_seconds
+          end
+          parse_response(response)
+        end
+
+        def media_jobs(params, timeout_seconds:)
+          response = connection.get('/v1/media/jobs', params) { |request| request.options.timeout = timeout_seconds }
+          parse_response(response)
+        end
+
+        def mutate_media_job(job_id, action, timeout_seconds:)
+          response = connection.post("/v1/media/jobs/#{Integer(job_id)}/#{action}") do |request|
+            request.options.timeout = timeout_seconds
+          end
+          parse_response(response)
+        end
+
+        def media_job_statistics(timeout_seconds:)
+          response = connection.get('/v1/media/jobs/stats') { |request| request.options.timeout = timeout_seconds }
+          parse_response(response)
+        end
+
+        private
+
+        attr_reader :connection
+
+        def upload_file(operation, source, options, timeout_seconds)
+          connection.post('/v1/media') do |request|
+            request.options.timeout = timeout_seconds
+            request.body = {
+              operation: operation.to_s,
+              options: JSON.generate(serializable(options)),
+              file: Faraday::Multipart::FilePart.new(source, mime_type(source), File.basename(source))
+            }
+          end
+        end
+
+        def write_source(operation, source, options, timeout_seconds)
+          connection.post('/v1/media') do |request|
+            request.options.timeout = timeout_seconds
+            request.headers['Content-Type'] = 'application/json'
+            request.body = JSON.generate(
+              operation: operation.to_s, source: source, options: serializable(options)
+            )
+          end
+        end
+
+        def reject_callable_options!(options)
+          unsupported = EXTRACTOR_OPTIONS.select do |key|
+            value = options[key] || options[key.to_s]
+            value.respond_to?(:call) || value.respond_to?(:extract)
+          end
+          return if unsupported.empty?
+
+          raise ArgumentError,
+                "HTTP media ingestion cannot serialize extractors: #{unsupported.join(', ')}; configure them on SmartRAG"
+        end
+
+        def serializable(value)
+          case value
+          when Hash
+            value.each_with_object({}) { |(key, item), result| result[key] = serializable(item) }
+          when Array
+            value.map { |item| serializable(item) }
+          when Symbol
+            value.to_s
+          else
+            value
+          end
+        end
+
+        def parse_response(response)
+          body = JSON.parse(response.body, symbolize_names: true)
+          return body if response.success?
+
+          raise "SmartRAG HTTP #{response.status}: #{body[:error] || response.reason_phrase}"
+        rescue JSON::ParserError
+          raise "SmartRAG HTTP #{response.status}: invalid JSON response"
+        end
+
+        def mime_type(path)
+          extension = File.extname(path).downcase
+          {
+            '.jpg' => 'image/jpeg', '.jpeg' => 'image/jpeg', '.png' => 'image/png',
+            '.wav' => 'audio/wav', '.mp3' => 'audio/mpeg', '.mp4' => 'video/mp4',
+            '.pdf' => 'application/pdf', '.txt' => 'text/plain', '.md' => 'text/markdown'
+          }.fetch(extension, 'application/octet-stream')
+        end
+      end
+    end
+  end
+end