Skip to content

feat: deploy-week-4 infrastructure + frontend reconnection #49

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
Number531 merged 3 commits into from
Mar 16, 2026
Merged

feat: deploy-week-4 infrastructure + frontend reconnection #49

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ba9c2d9
feat: multimodal artifact embedding — cross-modal text-to-image chart…
Number531 Mar 16, 2026
88ca1bf
fix: harden artifact embedding for live pipeline stability
Number531 Mar 16, 2026
68b9abd
feat: deploy-week-4 frontend reconnection + deploy testing docs
Number531 Mar 16, 2026
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
68 changes: 68 additions & 0 deletions super-legal-mcp-refactored/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,74 @@

All notable changes to the Super Legal MCP Server are documented in this file.

## [4.11.0] - 2026-03-15

### Added — Multimodal Artifact Embedding (Cross-Modal Chart Search)

Multimodal vector embeddings for chart PNG artifacts via Gemini `gemini-embedding-2-preview`, enabling cross-modal search where text queries retrieve visually and semantically relevant chart images. Extends the existing embedding infrastructure (v4.9.0) into the shared 3072-dimensional vector space. Gated behind the same `EMBEDDING_PERSISTENCE` flag — no new feature flag required.

#### Schema — `artifact_embeddings` Table

| Change | File | Impact |
|--------|------|--------|
| **New table `artifact_embeddings`** — `artifact_id` FK → `report_artifacts(id)` ON DELETE CASCADE, `session_id` FK → `sessions(id)` ON DELETE CASCADE, `embedding vector(3072)`, unique constraint on `artifact_id` | `postgres.js` | One embedding per artifact, auto-cleaned on cascade delete |
| **Session index** — `idx_artifact_emb_session` on `session_id` | `postgres.js` | Fast session-scoped queries |
| **HNSW index** — `idx_artifact_emb_hnsw` with cosine ops (non-fatal if pgvector < 0.7.0, falls back to sequential scan) | `postgres.js` | Approximate nearest-neighbor search at scale |
| **DDL split** — HNSW creation separated from table DDL with try/catch | `postgres.js` | Graceful degradation on older pgvector versions (2000-dim cap) |

#### Embedding Service — 3 New Exports

| Function | File | Purpose |
|----------|------|---------|
| **`embedImage(imageBuffer, mimeType, description)`** | `embeddingService.js` | Gemini multimodal embedding via `inlineData` (base64 PNG + text description) → 3072-dim vector |
| **`embedAndStoreArtifact(artifactId, sessionId, imageBuffer, mimeType, fileName)`** | `embeddingService.js` | Embed + UPSERT into `artifact_embeddings`. Description auto-derived from filename (strip extension, replace hyphens/underscores with spaces) |
| **`searchArtifacts(queryEmbedding, { limit, threshold, sessionId })`** | `embeddingService.js` | Cosine similarity search on `artifact_embeddings` with optional session scoping. Returns `file_name`, `mime_type`, `description`, `artifact_id`, `session_key`, `similarity` |

#### Artifact Persistence — Fire-and-Forget Embedding

| Change | File | Impact |
|--------|------|--------|
| **`persistArtifact()` returns artifact ID** — added `RETURNING id` to INSERT | `artifactPersistence.js` | Backward-compatible — callers that ignore the return value are unaffected |
| **`persistSessionArtifacts()` chart loop** — fire-and-forget `setImmediate` embedding for `image/png` when `EMBEDDING_PERSISTENCE=true` | `artifactPersistence.js` | Batch session backfill auto-embeds charts |
| **`persistChartArtifact()` single chart** — same fire-and-forget pattern | `artifactPersistence.js` | Live code execution charts auto-embedded |
| **`featureFlags` import** — static import of `featureFlags` from config | `artifactPersistence.js` | Gate embedding behind existing flag |

#### REST API — New Endpoint

| Endpoint | File | Purpose |
|----------|------|---------|
| **`GET /api/db/search-artifacts?q=...&limit=10&threshold=0.3&session_id=UUID`** | `dbFrontendRouter.js` | Text-to-image semantic search across chart artifacts. Same validation pattern as `/api/db/search-semantic` (query length, UUID format, limit/threshold bounds) |

#### Server Startup — Ordering Fix

| Change | File | Impact |
|--------|------|--------|
| **`ensureArtifactSchema()` before `ensureEmbeddingSchema()`** | `claude-sdk-server.js` | `artifact_embeddings` FK references `report_artifacts` — schema must exist first. Without this fix, server startup would fail with `EMBEDDING_PERSISTENCE=true` |

#### Backfill Script

| Script | Purpose |
|--------|---------|
| **`scripts/backfill-artifact-embeddings.mjs`** | Queries `report_artifacts` for `image/png` rows without embeddings, calls `embedAndStoreArtifact()` synchronously. Supports `--session=KEY`, `--dry-run`. No race condition (unlike fire-and-forget path) |

#### Test Suites

| Suite | Tests | File | Coverage |
|-------|-------|------|----------|
| **Integration (fabricated vectors)** | 15 | `artifact-embedding-integration.test.js` | Schema, CRUD, UPSERT, CASCADE (artifact + session), FK integrity, similarity search (ordering, threshold, limit, session scope), module import, performance |
| **Cloud SQL + Gemini (live)** | 7 | `artifact-embedding-cloud-sql.test.js` | Gemini multimodal smoke, cross-modal similarity, full pipeline round-trip, idempotent UPSERT, text-to-image search |

#### Backfill Results (2026-03-15)

| Session | Artifacts Persisted | Charts Embedded | Queries Tested | Precision@1 |
|---------|--------------------|-----------------|----|------------|
| `2026-03-13-1773426614` | 109 (pre-existing) | 37 of 43 (6 empty files skipped) | 13 | 100% |
| `2026-03-07-1772900028` | 78 | 6 of 6 | 3 | 100% |

**Migration**: None required. Schema changes are purely additive (`CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`). Startup ordering fix is backward-compatible. Existing sessions retain current data; chart embeddings populate on next `persistChartArtifact()` call or via backfill script.

---

## [4.10.0] - 2026-03-14

### Added — Agent Observability Replay (Session Reload)
Expand Down
57 changes: 53 additions & 4 deletions super-legal-mcp-refactored/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,7 @@ node index.js
- **Interleaved thinking**: Beta header retained for Sonnet 4.5 backward compatibility via `SDK_MODEL` env override.
- **1M context**: Enabled via `context-1m-2025-08-07` beta on the orchestrator; inherited by all subagents.
- **Effort control**: Supported on Sonnet 4.6, Opus 4.5/4.6. Not supported on Sonnet 4.5 (beta header is inert).
- **SDK versions**: `@anthropic-ai/sdk` 0.78.0, `@anthropic-ai/claude-agent-sdk` 0.2.47, `zod` 4.3.6
- **SDK versions**: `@anthropic-ai/sdk` 0.78.0, `@anthropic-ai/claude-agent-sdk` 0.2.70, `zod` 4.3.6
- **Rollback**: Set `SDK_MODEL=claude-sonnet-4-5-20250929` to revert orchestrator instantly (env override, no code change).

### Prompt Architecture — Split Prompts (v3.2.0)
Expand Down Expand Up @@ -309,7 +309,7 @@ Hook wrapping chain (outermost → innermost):

**All 8 hook types**: SessionStart, SessionEnd, PreToolUse, PostToolUse, SubagentStart, SubagentStop, PreCompact, PostToolUseFailure.

#### Schema (12 tables, 30+ indexes)
#### Schema (19 tables, 30+ indexes)

| Table | Purpose | Key Feature |
|-------|---------|-------------|
Expand All @@ -327,6 +327,11 @@ Hook wrapping chain (outermost → innermost):
| `sections` | Memo section metadata | Word count, footnotes, phases, subsections |
| `remediation_tasks` | Remediation task tracking | Wave, priority, validation checks |
| `remediation_wave_summary` | Remediation wave aggregation | Task count, completed, failed |
| `report_artifacts` | Binary PDF/DOCX/PNG deliverables (BYTEA) | Category, MIME, UPSERT dedup |
| `report_embeddings` | Report chunk vector embeddings (3072-dim) | HNSW cosine index, session-scoped |
| `citation_embeddings` | Citation vector embeddings (future use) | HNSW cosine index |
| `artifact_embeddings` | Chart image multimodal embeddings (3072-dim) | Cross-modal text→image search (v4.11.0) |
| `users` | Authentication (email/password) | bcrypt hashes, role-based |

**Dual-write guarantee**: original handler always runs first; DB write is additive in try/catch. If DB fails, local file is already written.

Expand All @@ -351,11 +356,52 @@ npm start # Schema auto-created on first boo

**Rollback**: `HOOK_DB_PERSISTENCE=false` in `.env` — instant disable, zero behavior change. Specification at `docs/pending-updates/hookDBBridge-spec.md` (v2.5).

### Embedding Persistence — Semantic Search (v4.9.0, multimodal v4.11.0)

Vector embeddings for report content and chart images via Gemini `gemini-embedding-2-preview` + pgvector, enabling natural-language search across all persisted memoranda, deliverables, and chart artifacts. Reports are chunked by `##` headers, batch-embedded (3072 dimensions), and stored in `report_embeddings` with HNSW indexing for fast cosine similarity search. Chart PNGs are multimodal-embedded into a shared vector space, enabling cross-modal text-to-image retrieval.

#### How It Works

```
Report INSERT (hookDBBridge)
→ setImmediate (fire-and-forget, non-blocking)
→ chunkByHeaders (split markdown by ## headers, max 8192 chars/chunk)
→ embedDocuments (Gemini batch embedding, RETRIEVAL_DOCUMENT task type)
→ transactional DELETE + batch INSERT into report_embeddings

Chart PNG persist (artifactPersistence)
→ persistArtifact (RETURNING id)
→ setImmediate (fire-and-forget, non-blocking, image/png only)
→ embedImage (Gemini multimodal: text description + inlineData base64)
→ UPSERT into artifact_embeddings
```

#### Search Endpoints

```
GET /api/db/search-semantic?q=antitrust+merger+review&limit=10&threshold=0.3&session_id=UUID
GET /api/db/search-artifacts?q=revenue+chart&limit=10&threshold=0.3&session_id=UUID
```

`search-semantic` returns ranked report chunks with `chunk_content`, `chunk_header`, `report_key`, `report_type`, `session_key`, and `similarity` score (0–1).

`search-artifacts` returns ranked chart artifacts with `file_name`, `mime_type`, `description`, `artifact_id`, `session_key`, and `similarity` score (0–1). Text queries retrieve visually relevant chart images via cross-modal embedding.

#### Feature Flags

| Flag | Default | Effect When OFF |
|------|---------|-----------------|
| `EMBEDDING_PERSISTENCE` | `false` | All embedding code paths skipped — zero behavior change |

**Dependencies:** Requires `HOOK_DB_PERSISTENCE=true`, `GEMINI_API_KEY` (or `GOOGLE_API_KEY`), and PostgreSQL with pgvector extension.

**Rollback**: `EMBEDDING_PERSISTENCE=false` in `.env` — instant disable, zero behavior change. Database retains previously embedded data.

### Database-Frontend Integration — Session History (v3.10.0)

Bridges the hookDBBridge write layer to the dashboard ([Issue #19](https://github.com/Number531/Legal-API/issues/19)). Page refresh no longer means blank slate — past sessions are loaded from PostgreSQL with full phase progress, timeline reconstruction, and report metadata.

#### REST API (15 read-only endpoints)
#### REST API (16 read-only endpoints)

| Endpoint | Purpose | Key Feature |
|----------|---------|-------------|
Expand All @@ -370,6 +416,8 @@ Bridges the hookDBBridge write layer to the dashboard ([Issue #19](https://githu
| `GET /api/db/sessions/:key/sections` | Section-level view | Word count, footnotes, phases |
| `GET /api/db/sessions/:key/remediation` | Remediation dashboard | Tasks, waves, computed metrics |
| `GET /api/db/search` | Full-text search | GIN FTS index on report content |
| `GET /api/db/search-semantic` | Semantic vector search (reports) | Cosine similarity via pgvector (v4.9.0) |
| `GET /api/db/search-artifacts` | Semantic vector search (chart images) | Cross-modal text→image via Gemini multimodal (v4.11.0) |
| `GET /api/analytics/sessions/quality` | Session quality comparison | Score, cost, duration trends |
| `GET /api/analytics/agents/performance` | Agent leaderboard | Duration, gate pass rate |
| `GET /api/analytics/cost/trends` | Weekly cost/quality trends | DATE_TRUNC aggregation |
Expand Down Expand Up @@ -553,7 +601,8 @@ When a specialist report includes a `## Code Execution Metadata` section (genera
| `FILES_API_CHART_EXTRACTION` | ❌ Optional | Set to `true` to download chart PNGs from code execution containers via Files API instead of base64-via-stdout (default: `false`) |
| `CHART_PERSISTENCE` | ❌ Optional | Set to `true` to persist chart PNGs to disk and enable chart-to-document pipeline with figure numbering (default: `false`) |
| `OPENAI_API_KEY` | ❌ Optional | OpenAI API key for GPT-5 orchestrator mode |
| `GEMINI_API_KEY` | ❌ Optional | Google Gemini API key for optional filter layer |
| `GEMINI_API_KEY` | ❌ Optional | Google Gemini API key — used for embedding persistence (`EMBEDDING_PERSISTENCE=true`) vector search |
| `EMBEDDING_PERSISTENCE` | ❌ Optional | Set to `true` to enable Gemini vector embeddings for report semantic search (default: `false`). Requires `HOOK_DB_PERSISTENCE=true` and `GEMINI_API_KEY`. |

### API Rate Limits

Expand Down
Loading