Skip to content

feat(submodule): add PMOVES-Spark-VSS and integration handoff #2277

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
POWERFULMOVES merged 1 commit into from
Jul 29, 2026
Merged

feat(submodule): add PMOVES-Spark-VSS and integration handoff #2277

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .gitmodules
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -362,3 +362,7 @@
url = https://github.com/POWERFULMOVES/Pmoves-pretext.git
branch = PMOVES.AI-Edition-Hardened
ignore = all
[submodule "PMOVES-Spark-VSS"]
path = PMOVES-Spark-VSS
url = https://github.com/POWERFULMOVES/PM-Spark-video-search-and-summarization.git
branch = main

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Add a main-branch exception to the policy gate

When the documented local release checks run, make -C pmoves submodule-branch-policy-check rejects this new entry because pmoves/mk/preflight.mk permits main only for PMOVES-ClawZ; the resulting failure explicitly lists PMOVES-Spark-VSS -> main. Since the overlay says this fork intentionally has no hardened branch, add PMOVES-Spark-VSS=main to SUBMODULE_BRANCH_ALLOW rather than leaving the new submodule in permanent violation of the gate.

AGENTS.md reference: pmoves/AGENTS.md:L38-L39

Useful? React with 👍 / 👎.

Comment on lines +365 to +368

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Register the submodule with scheduled updates

On the weekly schedule, and on manual runs with the submodule filter left blank, .github/workflows/submodule-update-check.yml only iterates the four hardcoded entries in TRACKED_SUBMODULES (lines 33-40). Because this new tracked submodule is absent from that list, its main gitlink will never receive the automated update checks or bump PRs; add its name:path:branch triple or derive the list directly from .gitmodules.

Useful? React with 👍 / 👎.

1 change: 1 addition & 0 deletions PMOVES-Spark-VSS
Open in desktop
Submodule PMOVES-Spark-VSS added at 7640d9
6 changes: 6 additions & 0 deletions pmoves/docs/AGENTS/AGNOTE4482PHI.t1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1273,3 +1273,9 @@ The pipeline reports success because its validation scope is too narrow. Neither
<!-- GRAPHITI_MARK: KIMI-SPARK::HF-MCP-REVIEW-TRIAGE::2026-07-29 -->

<!-- GRAPHITI_MARK: KIMI-SPARK::HF-MCP-SERVER-WIRING::2026-07-29 -->

- `2026-07-29T02:17:00Z` RELEASE `KIMI-SPARK` scope: **PR #2276 merged to main** (admin-merge). Head `232cc91a6` lands hf-mcp-server compose wiring, real MCP transport, localhost bind, doc parity, and agent-teams registration. All required CI checks green; `triage` bot flaked on Claude Code Action init (infra, non-blocking). HF_TOKEN verified in local env via `with-env.sh` after bundle sync. Next lane: PM-Spark VSS submodule + pmoves-vss-agent compose service per handoff doc §Claw opportunity. agent_signature: `ACK::KIMI-SPARK::HF-MCP-MERGED-2026-07-29`.

- `2026-07-29T02:20:00Z` CLAIM `KIMI-SPARK` scope: **SPARK Video Search & Summarization (VSS) integration for Claw and agent mesh.** Submodule `PM-Spark-video-search-and-summarization` as `PMOVES-Spark-VSS/`, add `pmoves-vss-agent` compose service, register in agent_registry + agent-teams + CATALOG, install agentskills.io VSS skills into Claw skill directory, expose VSS orchestrator/analytics tools to PMOVES agents. Worktree: `/tmp/PMOVES.AI-spark-vss`. Branch: `feature/spark-vss-submodule-wiring`. Three-body: delivery=KIMI-SPARK, control=operator/DARKXSIDE (submodule + compose change), memory=this trail + `pmoves/docs/handoffs/SPARK_HF_MCP_SERVER_WIRING_2026-07-28.md` VSS section. agent_signature: `ACK::KIMI-SPARK::SPARK-VSS-CLAIM-2026-07-29`.

@coderabbitai coderabbitai Bot Jul 29, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Add the claim TTL.

The VSS CLAIM includes the branch and scope but omits the required TTL, so other agents cannot determine when the lane expires. Add a TTL consistent with the collision-avoidance protocol.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@pmoves/docs/AGENTS/AGNOTE4482PHI.t1.md` at line 1279, Add the required
collision-avoidance TTL to the VSS CLAIM entry in AGNOTE4482PHI, preserving its
existing branch, scope, worktree, three-body, and agent_signature details. Use
the established claim format and a TTL value consistent with the protocol.

Source: Path instructions


<!-- GRAPHITI_MARK: KIMI-SPARK::SPARK-VSS-CLAIM::2026-07-29 -->
55 changes: 55 additions & 0 deletions pmoves/docs/AGENTS/SUBMODULE_CODEX_HOMES/PMOVES-Spark-VSS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# PMOVES-Spark-VSS

**Submodule:** `PMOVES-Spark-VSS/`
**Repository:** https://github.com/POWERFULMOVES/PM-Spark-video-search-and-summarization.git
**Upstream:** NVIDIA AI Blueprint for Video Search and Summarization
**Branch tracked:** `main` (native PMOVES fork; no upstream `PMOVES.AI-Edition-Hardened` branch)

## Scope

NVIDIA AI Blueprint for Video Search and Summarization (VSS), forked for PMOVES/SPARK. Provides GPU-accelerated vision agents and video analytics:

- **Layer 1 — Real-time video intelligence:** RT-CV detection/tracking, RT-Embed semantic video embeddings, RT-VLM captions/incident detection.
- **Layer 2 — Downstream analytics:** Behavior analytics, alert contextualization, incidents/metrics to Elasticsearch.
- **Layer 3 — Agent & offline processing:** VSS Agent exposes search, summarization, visual Q&A, and clip retrieval via Model Context Protocol (MCP).

## Use this when

- The user wants video understanding, search, summarization, or incident analysis.
- Claw or another PMOVES agent needs to deploy or operate a VSS workflow.
- You are wiring a `pmoves-vss-agent` compose service or exposing VSS tools to the PMOVES MCP mesh.

## PMOVES companions

- **Claw** — install VSS skills into `~/.openclaw-autoclaw/skills/` so Claw can deploy/operate VSS.
- **Agent Zero** — route VSS MCP tools through the agent mesh.
- **NATS** — VSS publishes features/incidents to a message broker; PMOVES can consume these via NATS.
- **MinIO / S3** — VSS uses object storage for clips and snapshots.
- **Elasticsearch** — VSS analytics layer stores incidents, metrics, tracker data.

## Core checks

```bash
# Submodule present and on expected branch
git submodule status PMOVES-Spark-VSS
Comment on lines +32 to +34

@coderabbitai coderabbitai Bot Jul 29, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Use a command that actually verifies the tracked branch.

git submodule status verifies the gitlink revision and dirty state, but not that the checkout is on main.

  • pmoves/docs/AGENTS/SUBMODULE_CODEX_HOMES/PMOVES-Spark-VSS.md#L32-L34: add git -C PMOVES-Spark-VSS branch --show-current or relabel the check as revision/status verification.
  • pmoves/docs/handoffs/SPARK_VSS_INTEGRATION_2026-07-29.md#L107-L109: apply the same correction to the verification section.
📍 Affects 2 files
  • pmoves/docs/AGENTS/SUBMODULE_CODEX_HOMES/PMOVES-Spark-VSS.md#L32-L34 (this comment)
  • pmoves/docs/handoffs/SPARK_VSS_INTEGRATION_2026-07-29.md#L107-L109
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@pmoves/docs/AGENTS/SUBMODULE_CODEX_HOMES/PMOVES-Spark-VSS.md` around lines 32
- 34, Update the verification sections in
pmoves/docs/AGENTS/SUBMODULE_CODEX_HOMES/PMOVES-Spark-VSS.md lines 32-34 and
pmoves/docs/handoffs/SPARK_VSS_INTEGRATION_2026-07-29.md lines 107-109 to verify
the checked-out branch with git -C PMOVES-Spark-VSS branch --show-current, or
relabel the existing git submodule status command as revision/status
verification rather than branch verification.


# VSS skills catalog
ls PMOVES-Spark-VSS/skills/

# Agent service build context
ls PMOVES-Spark-VSS/services/agent/docker/

# Compose profiles in submodule
cat PMOVES-Spark-VSS/deploy/docker/compose.yml
```

## Related parity tokens

- `pmoves/docs/handoffs/SPARK_VSS_INTEGRATION_2026-07-29.md` — integration lane plan
- `pmoves/docs/handoffs/SPARK_HF_MCP_SERVER_WIRING_2026-07-28.md` — prior SPARK handoff that surfaced VSS opportunity
- `.claude/PATTERNS.md` § *MCP / SSE Service Review Patterns*

## Notes

- This submodule is a **developer-side blueprint**, not a single container. Integration into PMOVES compose is a multi-step lane documented in the handoff above.
- Skills are [agentskills.io](https://agentskills.io/specification)-compatible; install location is `~/.openclaw-autoclaw/skills/<skill-name>/` per AGENTS.md skill-path guidance.
2 changes: 1 addition & 1 deletion pmoves/docs/handoffs/SPARK_HF_MCP_SERVER_WIRING_2026-07-28.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,4 +82,4 @@ local video understanding + search + summarization tools.
should set it).
- ~~Add `hf-mcp-server` to `pmoves/config/agent_registry.yaml`.~~ Done.
- ~~Update CATALOG.md to add `:8203 hf-mcp-server`.~~ Done.
- Submodule / wire PM-Spark-VSS for Claw.
- ~~Submodule / wire PM-Spark-VSS for Claw.~~ Claimed — see `pmoves/docs/handoffs/SPARK_VSS_INTEGRATION_2026-07-29.md`.
122 changes: 122 additions & 0 deletions pmoves/docs/handoffs/SPARK_VSS_INTEGRATION_2026-07-29.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
# SPARK VSS Integration — 2026-07-29

> **GRAPHITI_MARK:** SPARK-KIMI::SPARK-VSS-INTEGRATION::2026-07-29
> **Lane:** PM-Spark Video Search & Summarization for Claw / PMOVES agent mesh
> **Status:** foundation landed; compose/service wiring pending
> **Supersedes:** `pmoves/docs/handoffs/SPARK_HF_MCP_SERVER_WIRING_2026-07-28.md` § PM-Spark VSS opportunity

## Context

`PM-Spark-video-search-and-summarization` is the POWERFULMOVES fork of the NVIDIA VSS blueprint. It ships:

- GPU-accelerated video intelligence microservices (detection/tracking, embeddings, VLMs)
- Downstream analytics (behavior analytics, incidents, alerts)
- A VSS Agent layer exposing search/summarization/Q&A/report tools via MCP
- agentskills.io-compatible skills under `skills/` for deploy-time and runtime operations

The goal is to make VSS a first-class PMOVES capability: every agent (Claw, Claude, Kimi, Hermes, NemoClaw) can deploy and operate VSS workflows through the skill catalog, and the VSS Agent can publish/consume events on the PMOVES NATS bus.

## Foundation (this PR)

- [x] Add `PMOVES-Spark-VSS` submodule at repo root, tracking `main`.
- [x] Add `pmoves/docs/AGENTS/SUBMODULE_CODEX_HOMES/PMOVES-Spark-VSS.md` Codex home overlay.
- [x] Update `SPARK_HF_MCP_SERVER_WIRING_2026-07-28.md` to mark VSS lane claimed.
- [x] Update `AGNOTE4482PHI.t1.md` claim/release entries.

## Next steps (future PRs)

### 1. VSS skills available to Claw

Install or symlink the VSS skill directories into Claw's managed skills directory:

```bash
# Per AGENTS.md skill-path guidance
~/.openclaw-autoclaw/skills/
├── vss-deploy-profile/
├── vss-ask-video/
├── vss-search-archive/
├── vss-summarize-video/
├── vss-generate-video-report/
├── vss-query-analytics/
├── vss-manage-alerts/
└── vss-manage-video-io-storage/
```

Each skill is self-contained with `SKILL.md` frontmatter. A `make` target or `pmoves/tools/install_vss_skills.py` script can copy/symlink from `PMOVES-Spark-VSS/skills/` and verify frontmatter.

### 2. `pmoves-vss-agent` compose service

Add a PMOVES-managed service that runs the VSS Agent inside the PMOVES docker network. This is intentionally lightweight for the first pass — the agent container connects to **externally provisioned** VSS backing services (NIM LLM/VLM, VST, Elasticsearch, Redis/Kafka) rather than trying to fold the entire NVIDIA blueprint into `docker-compose.yml`.

Recommended first shape:

| Field | Value |
|-------|-------|
| Service name | `pmoves-vss-agent` |
| Build context | `PMOVES-Spark-VSS/services/agent/` |
| Dockerfile | `docker/Dockerfile` |
Comment on lines +51 to +57

@coderabbitai coderabbitai Bot Jul 29, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Fix the compose build context path.

Because the existing compose file is pmoves/docker-compose.yml and the submodule is at repository root, PMOVES-Spark-VSS/services/agent/ resolves under pmoves/ and will not find the submodule. Use the path relative to the compose file, or explicitly configure the compose project directory.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@pmoves/docs/handoffs/SPARK_VSS_INTEGRATION_2026-07-29.md` around lines 51 -
57, Correct the recommended Docker Compose build context in the integration
documentation so it resolves from pmoves/docker-compose.yml to the
repository-root submodule, rather than nesting PMOVES-Spark-VSS under pmoves.
Update the Build context value to the appropriate relative path, or explicitly
specify the Compose project directory while preserving the existing Dockerfile
location.

| Internal port | `8000` |
| Host port | `8204` (next free after hf-mcp-server `:8203`) |
| Profile | `agents`, `media` |
Comment on lines +58 to +60

@coderabbitai coderabbitai Bot Jul 29, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Resolve the 8204 port allocation before implementation.

The handoff calls 8204 the next free port, but later states that 8200-8299 is already used by HF services. Check the canonical registry/catalog and select a demonstrably free port; otherwise the planned service may collide at startup.

Also applies to: 89-96

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@pmoves/docs/handoffs/SPARK_VSS_INTEGRATION_2026-07-29.md` around lines 58 -
60, Resolve the planned host port in the handoff’s service configuration by
checking the canonical port registry/catalog rather than assuming 8204 is
available. Replace 8204 with a demonstrably free port outside the occupied HF
services range, and update all corresponding references, including the later
port allocation section, while preserving the internal port 8000.

Source: Coding guidelines

| Networks | `pmoves_app`, `pmoves_bus` |
| Env file | `env.tier-media` or new `env.tier-vss` |
| Health | `GET /health` |
| MCP endpoint | `GET /mcp/sse` (verify contract after VSS Agent version) |

Required env (from VSS agent README):

- `HOST_IP`
- `EXTERNAL_IP`
- `INTERNAL_IP`
- `LLM_BASE_URL`
- `VLM_BASE_URL`
- `LLM_NAME`
- `VLM_NAME`
- `VST_INTERNAL_URL`
- `VST_EXTERNAL_URL`
- `VSS_AGENT_PORT`
- `NVIDIA_API_KEY` (if using NIM cloud endpoints)

### 3. Registry / team / catalog parity

Add `pmoves_vss_agent` to:

- `pmoves/config/agent_registry.yaml` — class `media`, health `/health`, MCP SSE endpoint.
- `pmoves/configs/agent-teams.yaml` — team `media`.
- `.claude/CATALOG.md` — host port, health, MCP surface.
- `pmoves/docs/SERVICE_DOCS_MATRIX.md` — service doc index.

### 4. Full VSS stack as optional compose overlay

Longer term, provide a `docker-compose.vss.yml` overlay (or use the submodule's own `deploy/docker/compose.yml`) that brings up the complete VSS profile (`base`, `search`, `lvs`, `alerts`) alongside PMOVES. This depends on:

- GPU host with NVIDIA Container Toolkit and supported driver.
- NIM microservice images (large downloads; require `NVIDIA_API_KEY`).
- Elasticsearch, Redis/Kafka, and MinIO/S3 storage.
- Port ranges that do not collide with PMOVES (`8200-8299` already used by HF services).

## Risks & open questions

- **Hardware:** VSS requires NVIDIA GPU with supported driver (580.x) and Docker Engine < 29.5.0. SPARK node must satisfy this before the full stack can run.
- **Port collision:** VSS default ports may overlap with PMOVES. Need a port-allocation pass before adding the full overlay.
- **Model licensing:** NIM microservices require NVIDIA AI Enterprise or NGC API key.
- **Scope creep:** The submodule is a full blueprint. Keep the first PMOVES integration to agent-only; let the `vss-deploy-profile` skill bring up backing services on demand.

## Verification

```bash
# Submodule present
git submodule status PMOVES-Spark-VSS

# Codex home overlay
ls pmoves/docs/AGENTS/SUBMODULE_CODEX_HOMES/PMOVES-Spark-VSS.md

# VSS skill catalog
ls PMOVES-Spark-VSS/skills/
```

## Related

- Source: https://github.com/POWERFULMOVES/PM-Spark-video-search-and-summarization
- Prior handoff: `pmoves/docs/handoffs/SPARK_HF_MCP_SERVER_WIRING_2026-07-28.md`
- Skill install path: `.claude/PATTERNS.md` § Installing Skills
Loading