v2 Realtime fallback + v2-gpu Qwen default + Meili on + docs

[hunnibear]

PR: v2 Supabase Realtime DNS fallback + v2‑GPU Qwen reranker default + Meili enabled

Summary

• Fixes intermittent "Name or service not known" on Supabase Realtime in hi-rag-gateway-v2 by auto‑deriving a host‑gateway websocket URL when a host‑only DNS name leaks into SUPABASE_REALTIME_URL.
• Sets Qwen reranker as default for hi-rag-gateway-v2-gpu and exposes env overrides.
• Enables Meilisearch lexical scoring by default via pmoves/.env.local.
• Cleans up Neo4j deprecation by replacing exists(e.type) with e.type IS NOT NULL (v2 and legacy v1 gateways).
• Documents the Firefly external stack bootstrap, persists compose defaults (app key, volume, timezone), and records n8n webhook smoke evidence for finance + health flows.

Changes

• Code: pmoves/services/hi-rag-gateway-v2/app.py
  • Adds _hostname_resolves() and container‑aware _derive_realtime_url() fallback to ws://host.docker.internal:54321/realtime/v1/websocket using SUPA_REST_INTERNAL_URL/SUPA_REST_URL.
  • Updates Neo4j warm query to CASE WHEN e.type IS NOT NULL THEN e.type ELSE 'UNK' END.
• Code: pmoves/services/hi-rag-gateway/gateway.py
  • Same Neo4j exists() → IS NOT NULL change.
• Compose: pmoves/docker-compose.yml
  • v2‑GPU: default reranker → Qwen/Qwen3-Reranker-4B (overridable).
• Env: pmoves/.env.local
  • Adds robust defaults for Supabase REST/Realtime and sets USE_MEILI=true, Qwen reranker flags, plus Firefly/N8N tokens for local smokes.
• Docs: pmoves/docs/LOCAL_DEV.md
  • Notes fallback behavior and explicit override.
• Docs: pmoves/docs/PMOVES.AI PLANS/WGER - Firefly iii compose -integrations/firefly/Integration Plan_ Firefly bootstrap.md
  • Step-by-step Firefly bring-up, key generation, token issuance, and CHIT hand-off guidance.
• Evidence: pmoves/docs/logs/2025-10-19_*.txt, pmoves/docs/logs/2025-10-20_external_integrations.txt.
• Compose: pmoves/docker-compose.external.yml
  • Shares Firefly defaults (APP_KEY env, trusted proxies, named volume) and ensures data persistence across restarts.

Rationale

• api.supabase.internal resolves on the host/CLI network, not inside the app network. The fallback ensures v2 remains resilient and subscribes without manual restarts.
• Qwen reranker is the target default for GPU path per recent validation, and Meili improves lexical grounding compared to rapidfuzz-only fallback.
• Firefly/Wger/Jellyfin are first-class integrations; documenting the bootstrap path and default compose env makes the external workspace reproducible for future smokes.

Validation

• v2 startup now shows:
  • Supabase realtime geometry listener started (url=ws://host.docker.internal:54321/realtime/v1/websocket)
  • Subscribed to Supabase realtime geometry.cgp.v1 channel
• Logs: see pmoves/docs/logs/2025-10-19_v2_realtime_fix.txt.
• GPU smoke: make smoke-gpu OK; Qwen smoke uses make smoke-qwen-rerank.
• External integrations: FIREFLY_PORT=8081 make -C pmoves up-external-firefly plus set -a && source pmoves/.env && source pmoves/.env.local && set +a && make -C pmoves up-n8n followed by the finance/health webhook curls in pmoves/docs/logs/2025-10-20_external_integrations.txt (HTTP 200 with n8n success logs).
• Neo4j: no Statement.SyntaxError for exists(variable.property).

Local CI

• Please run on your host:
  • make smoke
  • make smoke-gpu
  • Optionally: make smoke-rerank and make retrieval-eval-smoke

Rollout / Config

• Ensure pmoves/.env.local exists with:
  • SUPA_REST_URL=http://host.docker.internal:54321/rest/v1
  • SUPA_REST_INTERNAL_URL=http://host.docker.internal:54321/rest/v1
  • SUPABASE_REALTIME_URL=ws://host.docker.internal:54321/realtime/v1/websocket
  • USE_MEILI=true
  • RERANK_MODEL=Qwen/Qwen3-Reranker-4B (v2‑GPU)
  • Firefly tokens (FIREFLY_APP_KEY, FIREFLY_ACCESS_TOKEN) and optional AGENT_ZERO_EVENTS_TOKEN for webhook smokes

Next

• If desired, make Meili default on directly in compose (instead of env) and wire retrieval-eval artifact capture in CI.
• Expand Firefly docs with managed Postgres overrides once we connect to production stores.

Summary by CodeRabbit

• New Features

  • Added GPU-enabled gateway variants alongside CPU versions
  • Implemented Supabase Realtime DNS fallback for container environments
  • Enabled Meilisearch lexical scoring by default
  • Set Qwen reranker as default for GPU deployments
  • Introduced new orchestration targets for flexible stack startup

• Bug Fixes

  • Fixed Neo4j query syntax issues
  • Improved hostname resolution for container environments

• Documentation

  • Added comprehensive service guides and configuration documentation
  • Expanded smoke test and local development guidance
  • Updated make target references and port mappings

[coderabbitai]

Walkthrough

The PR introduces comprehensive GPU gateway support (v1/v2), automatic Supabase Realtime DNS fallback for container environments, Qwen reranker defaults for GPU paths, Meilisearch lexical scoring enablement, Neo4j query deprecation fixes, and new orchestration targets. Compose configurations, Makefiles, service implementations, and documentation are updated throughout.

Changes

Cohort / File(s)	Summary
Configuration & Environment pmoves/.compose_config.yaml, pmoves/.supabase.env, README.md	Added new Compose config file with pmoves service stub and Supabase environment file with service credentials. Updated root README bootstrap guidance to place env overrides in pmoves/.env.local instead of repo root.
Orchestration Makefile pmoves/Makefile	Introduced 12+ new make targets: up (combined data/workers/v2), up-gpu-gateways, recreate-v2/recreate-v2-gpu, up-open-notebook/down-open-notebook, up-both-gateways/up-legacy-both, smoke-gpu, smoke-hirag-v1, smoke-qwen-rerank. Enhanced health-check logic for multi-port gateway discovery and GPU/v1 validation. Updated ps formatting and logs to include all gateway variants.
Compose Service Definitions pmoves/docker-compose.yml, pmoves/docker-compose.open-notebook.yml	Major service rewiring: changed hi-rag-gateway port to 8089, updated SUPA_REST_URL defaults to host.docker.internal:54321/rest/v1, added extra_hosts entries, introduced GPU variants (hi-rag-gateway-gpu, hi-rag-gateway-v2-gpu) with resource reservations, enabled Meilisearch/reranker by default on GPU paths, marked pmoves network as external. Updated open-notebook port mappings (8502→8503, 5055→5056).
Gateway v2 Service Implementation pmoves/services/hi-rag-gateway-v2/app.py, pmoves/services/hi-rag-gateway-v2/Dockerfile.gpu	Added Realtime URL derivation with host-gateway fallback when DNS resolution fails; new _hostname_resolves() check. Introduced RERANK_MODEL_LABEL env var for reporting overrides and new /hirag/admin/reranker/model/label endpoint. Added SUPABASE_REST_INTERNAL_URL for container-aware URL rewriting. Enabled SMOKE_ALLOW_ADMIN_STATS bypass for local tests. Fixed Neo4j NULL handling in warm dictionary refresh. Updated stats endpoint signature to accept optional request context. GPU Dockerfile now sets PYTHONPATH and copies libs/ directory.
Gateway v1 Service Implementation pmoves/services/hi-rag-gateway/gateway.py	Introduced CrossEncoder-based reranking workflow controlled by RERANK_ENABLE, RERANK_MODEL, RERANK_TOPN, RERANK_K env vars. Lazy-loads reranker with CUDA/CPU device selection and error handling. Integrates reranking into search flow post-retrieval. Fixed Neo4j NULL type handling in warm dictionary query. Maintains backward-compatible fallback if reranking disabled or fails.
Publisher Metrics pmoves/services/publisher/publisher.py	Simplified GET /metrics endpoint to always return JSON with 200 response; /metrics.prom now conditionally serves Prometheus payload or 404 when disabled.
Database Schema & RLS pmoves/supabase/initdb/00_pmoves_schema.sql, pmoves/supabase/initdb/09_geometry_rls.sql	Replaced arbitrary $$ delimiters with named $SQL$ delimiters for consistency. Added nested exception handling for vector index creation with ivfflat→hnsw fallback. Changed pmoves_ui role from NOPRIVILEGE to NOLOGIN. Converted unconditional RLS policy creation to idempotent DO block with IF NOT EXISTS checks against pg_policies.
Local Development Documentation pmoves/README.md, pmoves/docs/LOCAL_DEV.md, pmoves/docs/SMOKETESTS.md	Added hi-rag-gateway-v2 runtime notes (Realtime DNS fallback, Meilisearch enablement, Qwen GPU defaults). Expanded port mapping table for CPU/GPU variants of v1/v2 gateways. Updated startup instructions to use make up and make up-legacy-both. Added Realtime DNS fallback behavior explanation. Updated smoke test commands to reference new make targets and multi-port discovery.
New Service Documentation pmoves/docs/services/{meilisearch,minio,neo4j,qdrant,open-notebook}/README.md, pmoves/docs/services/hi-rag-gateway*/README.md	Added comprehensive service guides documenting compose config, ports, environment variables, dependencies, and make targets. Documented split of v1 into CPU/GPU variants with port and rerank differences.
Operations & Planning Documentation pmoves/docs/MAKE_TARGETS.md, pmoves/docs/NEXT_STEPS.md, pmoves/docs/SESSION_IMPLEMENTATION_PLAN.md, pmoves/docs/PMOVES.AI\ PLANS/ROADMAP.md, pmoves/docs/PR_DRAFT_REALTIME_FALLBACK_QWEN.md	New MAKE_TARGETS.md documents all make target behaviors and defaults. Updated NEXT_STEPS.md with completed M2 items (DNS fallback, Qwen GPU, Meilisearch). Added SESSION_IMPLEMENTATION_PLAN session log with concrete task tracking. Marked three M2 items complete in ROADMAP.md. Added PR draft notes documenting fallback derivation, Neo4j fix, and Qwen defaults.
Smoke Test Logs pmoves/docs/logs/2025-10-19_*.txt	Added 6 smoke test result files documenting execution traces for CPU, GPU, Qwen reranker, and combined workflows, including status indicators and diagnostic guidance for model mismatch scenarios.
Stray File pmoves/NUL	Contains shell error output "/bin/sh: 1: where: not found" (appears to be accidental artifact).

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant Gateway as hi-rag-gateway-v2
    participant SupaRealtime as Supabase Realtime
    participant DNS as Container DNS

    Client->>Gateway: Initialize app
    activate Gateway
    Gateway->>Gateway: Check SUPABASE_REALTIME_URL configured
    
    alt URL configured
        Gateway->>DNS: _hostname_resolves(realtime_url)?
        alt Resolves inside container
            DNS-->>Gateway: ✓ Resolvable
            Gateway->>SupaRealtime: Use configured URL
        else Does not resolve (host-only DNS)
            DNS-->>Gateway: ✗ Not resolvable
            Gateway->>Gateway: _derive_realtime_url()
            Note over Gateway: Parse SUPA_REST_INTERNAL_URL<br/>Rewrite host.docker.internal<br/>Construct ws://....:54321/realtime/v1/websocket
            Gateway->>SupaRealtime: Use derived ws:// URL
        end
    else Not configured
        Gateway->>Gateway: Fallback to default REST base
        Gateway->>SupaRealtime: Use constructed realtime URL
    end
    
    deactivate Gateway

Loading

sequenceDiagram
    participant Client
    participant Gateway as hi-rag-gateway
    participant Retrieval as Retrieval Engine
    participant CrossEncoder as CrossEncoder Reranker
    participant Results as Results

    Client->>Gateway: POST /hirag/query
    activate Gateway
    
    Gateway->>Retrieval: run_query(query_text)
    activate Retrieval
    Retrieval->>Retrieval: Retrieve top-N candidates
    Retrieval-->>Gateway: candidates[]
    deactivate Retrieval
    
    alt RERANK_ENABLE=true
        Gateway->>CrossEncoder: Load reranker (lazy-init)
        activate CrossEncoder
        Note over CrossEncoder: CUDA/CPU device selection<br/>Model: RERANK_MODEL env var
        CrossEncoder-->>Gateway: Reranker ready
        deactivate CrossEncoder
        
        loop For each candidate
            Gateway->>CrossEncoder: score(query, candidate_text)
            CrossEncoder-->>Gateway: rerank_score
        end
        
        Gateway->>Gateway: Sort by rerank_score DESC<br/>Take top RERANK_K results
    else RERANK_ENABLE=false
        Gateway->>Gateway: Use original retrieval scores<br/>Take top K results
    end
    
    Gateway-->>Client: Results with scores
    deactivate Gateway

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

The PR spans multiple service implementations with new logic (Realtime DNS fallback, CrossEncoder reranking, GPU support), significant orchestration changes (12+ new make targets), database schema updates with error-handling patterns, and heterogeneous service rewiring across docker-compose. While many documentation and log changes are homogeneous, the code changes require separate reasoning per service and careful verification of multi-gateway interactions, environment variable plumbing, and fallback behaviors.

Poem

🐰 Hops of joy through Docker lanes,
GPU gateways break the chains,
DNS fallbacks dance with grace,
Realtime flows to their place,
Qwen rerankers rank so true,
Multi-gateways—what's not to do? ✨

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Free

📥 Commits

Reviewing files that changed from the base of the PR and between 0b93846 and 6d62621.

📒 Files selected for processing (38)

• README.md (1 hunks)
• pmoves/.compose_config.yaml (1 hunks)
• pmoves/.supabase.env (1 hunks)
• pmoves/Makefile (7 hunks)
• pmoves/NUL (1 hunks)
• pmoves/README.md (1 hunks)
• pmoves/docker-compose.open-notebook.yml (1 hunks)
• pmoves/docker-compose.yml (10 hunks)
• pmoves/docs/LOCAL_DEV.md (3 hunks)
• pmoves/docs/MAKE_TARGETS.md (1 hunks)
• pmoves/docs/NEXT_STEPS.md (3 hunks)
• pmoves/docs/PMOVES.AI PLANS/ROADMAP.md (1 hunks)
• pmoves/docs/PR_DRAFT_REALTIME_FALLBACK_QWEN.md (1 hunks)
• pmoves/docs/SESSION_IMPLEMENTATION_PLAN.md (1 hunks)
• pmoves/docs/SMOKETESTS.md (3 hunks)
• pmoves/docs/logs/2025-10-19_full_smokes_host.txt (1 hunks)
• pmoves/docs/logs/2025-10-19_make_smokes.txt (1 hunks)
• pmoves/docs/logs/2025-10-19_make_smokes_host.txt (1 hunks)
• pmoves/docs/logs/2025-10-19_qwen_and_gpu_smoke.txt (1 hunks)
• pmoves/docs/logs/2025-10-19_qwen_gpu_smoke.txt (1 hunks)
• pmoves/docs/logs/2025-10-19_qwen_smoke.txt (1 hunks)
• pmoves/docs/logs/2025-10-19_smokes_run.txt (1 hunks)
• pmoves/docs/logs/2025-10-19_v2_realtime_fix.txt (1 hunks)
• pmoves/docs/logs/2025-10-19_verify_full_run.txt (1 hunks)
• pmoves/docs/services/README.md (1 hunks)
• pmoves/docs/services/hi-rag-gateway-v2/README.md (2 hunks)
• pmoves/docs/services/hi-rag-gateway/README.md (2 hunks)
• pmoves/docs/services/meilisearch/README.md (1 hunks)
• pmoves/docs/services/minio/README.md (1 hunks)
• pmoves/docs/services/neo4j/README.md (1 hunks)
• pmoves/docs/services/open-notebook/README.md (1 hunks)
• pmoves/docs/services/qdrant/README.md (1 hunks)
• pmoves/services/hi-rag-gateway-v2/Dockerfile.gpu (2 hunks)
• pmoves/services/hi-rag-gateway-v2/app.py (5 hunks)
• pmoves/services/hi-rag-gateway/gateway.py (6 hunks)
• pmoves/services/publisher/publisher.py (1 hunks)
• pmoves/supabase/initdb/00_pmoves_schema.sql (4 hunks)
• pmoves/supabase/initdb/09_geometry_rls.sql (2 hunks)

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}