forked from sagnik/Project_Velocity
95 lines
9.1 KiB
Markdown
95 lines
9.1 KiB
Markdown
# Oracle Development Status & Transition Blueprint
|
|
|
|
This artifact summarizes the current state, remaining work, and architectural limitations/constraints for the **Project Velocity - The Oracle** module, based on the *Master Architecture and Implementation Artifact (v1.0)*. It is intended to serve as a comprehensive briefing for a coding agent tasked with completing the Oracle implementation.
|
|
|
|
> [!NOTE]
|
|
> **Contextual Awareness**: The current `implementation_plan.md` and `task.md` in the agent's brain directory are mapped to **The Catalyst** (Digital Marketing Agency module), which is a separate product vertical. The Oracle requires an independent set of execution tasks focused completely on the CRM's AI operational intelligence layer.
|
|
|
|
## 1. What Development is Done (Current State in Repo)
|
|
|
|
The repository currently contains the **"visual shell" and technical foundation**, but no production Oracle paths.
|
|
|
|
### Frontend
|
|
- **Polished UI Shell Exists**: `app/src/app/oracle/page.tsx` exists and provides a premium glassmorphic UI, a right-side conversation rail, and a top insight banner.
|
|
- **Mock Data Layer**: The UI uses a single-response mock client (`app/src/lib/oracleQueryClient.ts`) operating on a legacy `OracleQueryResult` contract. It switches between fixed, hardcoded views instead of an extensible, revision-controlled canvas.
|
|
|
|
### Backend
|
|
- **FastAPI / Python Foundation**: A robust FastAPI backend is running (`backend/main.py`), utilizing `asyncpg` for PostgreSQL and JWT-based authentication.
|
|
- **AI Runtime Abstraction Exists**: A production-grade `Nemoclaw` client (`backend/services/nemoclaw_client.py`) is already implemented and currently handles Sentinel's AI needs. This is the abstract LLM planner.
|
|
- **Database Baseline**: `backend/db/schema.sql` possesses the baseline auth and Sentinel schemas, but lacks Oracle's revisioned canvas components.
|
|
- **Placeholders**: `backend/api/routes_oracle.py` and `backend/api/routes_crm.py` exist but are entirely empty.
|
|
|
|
---
|
|
|
|
## 2. What is Remaining (Sprint 1 / MVP Blueprint)
|
|
|
|
The implementation must transition the system from "mocked single-response behavior" into "persistent, branchable, revisioned vertical JSON canvas behavior". This is broken down into Work Packages (WPs):
|
|
|
|
### WP1: Contract Foundation (First Next Step)
|
|
- Create JSON Schemas and API contracts (Section 6 & 13 types: `CanvasPage`, `CanvasComponent`, `PromptExecution`).
|
|
- Deprecate the mock query client; build a typed `oracleApiClient.ts`.
|
|
- Build the `v1` Oracle router skeleton in FastAPI.
|
|
|
|
### WP2: Persistence & DB Core
|
|
- Implement the revision-friendly PostgreSQL database schemas outlined in Section 16.4 (`oracle_canvas_pages`, `oracle_canvas_page_revisions`, `oracle_canvas_components`, `oracle_prompt_executions`).
|
|
|
|
### WP3: Prompt Orchestrator & Data Access
|
|
- Wire up `backend/oracle/prompt_orchestrator.py` to route prompts to `Nemoclaw_client.py`.
|
|
- **Constraint**: Implement strict structured parsing for Nemoclaw's output.
|
|
- Build the `Data Access Gateway` and `Policy Engine` to securely query tenant PostgreSQL data based on the validated LLM plan.
|
|
|
|
### WP4: Frontend Virtualized Canvas
|
|
- Refactor `app/src/app/oracle/page.tsx`.
|
|
- Create a virtualized vertical component scroller (`oracle/components/CanvasViewport.tsx`).
|
|
- Introduce a Component Registry (`oracle/components/ComponentRegistry.tsx`) that translates backend JSON components (e.g., `barChart`, `geoMap`) into React views.
|
|
- Make the prompt rail rely on the execution history instead of mock triggers.
|
|
|
|
### WP5: Collaboration & Merge Model
|
|
- **Jira-Style Branching**: Implement page sharing (Fork creation) instead of live shared edits.
|
|
- Implement Merge Requests, 3-way component diffs, and conflict resolution UI (`MergeReviewDrawer.tsx`).
|
|
|
|
### WP6: Component Catalog & Synthesis
|
|
- Build a catalog of pre-made templates (KPI tiles, pipelines, investor geographic heatmaps).
|
|
- Implement component synthesis: where an LLM generates a brand new visualization template utilizing extracted `styleSignatures` to match the tenant's exact design language.
|
|
|
|
---
|
|
|
|
## 3. Limitations & Constraints Imposed by the Master Artifact
|
|
|
|
The architecture document outlines very strict constraints on *why* parts of the system are deferred and *how* the remaining work must be executed.
|
|
|
|
> [!WARNING]
|
|
> **Strict Implementation Ordering**
|
|
> The system must be built sequentially. **Do not** build the frontend canvas (WP4) or Collaboration (WP5) before the API Contracts (WP1) and Persistence (WP2) are real.
|
|
> *Quoting the document:* "The first concrete move... should be to freeze the current mock Oracle query client... The second move should be to add Oracle page tables... Only after those three foundations exist should the team invest in merge review UI or template synthesis. That order keeps the product grounded in durable state rather than another generation of temporary mocks."
|
|
|
|
### Structural Constraints
|
|
- **No Unrestricted AI Executing SQL**: `Nemoclaw` acts only as a *planner*. It must **never** execute arbitrary SQL or touch connector APIs directly to mitigate hallucination and data leakage. It produces a JSON query plan that is executed strictly by the non-AI *Data Access Gateway*.
|
|
- **No Live Co-Editing**: Overwriting another user's Oracle dashboard live is forbidden. Oracle requires an explicit asynchronous **Fork & Merge** collaboration structure.
|
|
- **Immutable Pages**: Pages are append-only. When the frontend mutates a visualization, it must execute a new commit revision or a rollback revision. It must *never* silently overwrite a past revision log.
|
|
- **Synthesis is Delayed & Isolated**: Auto-promotion of LLM-synthesized UI components is explicitly isolated to the originating tenant for Sprint 1. Global (cross-tenant) sharing of synthesized components is forbidden.
|
|
- **No Uncontrolled Fine-Tuning**: Visual generation must use *exemplar retrieval* (a JSON dictionary `styleSignature`), instead of raw model-weight fine-tuning, to ensure styling remains fully deterministic.
|
|
|
|
### Security / Scope Constraints
|
|
- **Cross-Tenant Blocking**: Because of Hybrid Sovereign deployment architecture, querying across tenants is explicitly rejected and unsupported in this phase.
|
|
- **Connectors**: MVP must rely primarily on internal Velocity PostgreSQL datasets. External CRM connectors are deferred to later phases.
|
|
|
|
---
|
|
|
|
## 4. Oracle Development Status Dashboard
|
|
|
|
| Task Category | Status | Details / Scope | Specific Limitations / Constraints |
|
|
| :--- | :--- | :--- | :--- |
|
|
| **Frontend UI Shell** | ✅ Completed | Premium glassmorphic UI, right-side conversation rail, and top insight banner are all in place (`app/src/app/oracle/page.tsx`). | N/A - Serves as visual foundation. |
|
|
| **Backend Foundation** | ✅ Completed | FastAPI router base, `asyncpg` for PostgreSQL, and JWT authentication flow. | N/A - Foundation only. |
|
|
| **AI Planner Engine** | ✅ Completed | `Nemoclaw` client is operational and abstracted (currently used by Sentinel). | Operates merely as a planner; the LLM cannot execute SQL directly. |
|
|
| **Mock Data Layer** | ⏸️ Deprecated | Legacy `oracleQueryClient.ts` powering single-response fixed views with hardcoded data. | Cannot be used for Phase 2. Must be replaced immediately prior to frontend expansion. |
|
|
| **WP1: Contract Foundation** | ⏳ Remaining | JSON Schemas (`CanvasPage`, `CanvasComponent`) and typed `oracleApiClient.ts`. | **Must be built first.** No UI development can proceed until the API contracts replace the legacy mocks. |
|
|
| **WP2: Persistence & DB Core** | ⏳ Remaining | PostgreSQL schema implementation for `canvas_pages`, `revisions`, `components`, and `executions`. | **Sequential Dependency.** Must be completed immediately after WP1 to ensure all UI actions rely on durable states, avoiding fake in-memory changes. |
|
|
| **WP3: Prompt Orchestrator** | ⏳ Remaining | Wire backend (`prompt_orchestrator.py`) to Nemoclaw for structured JSON retrieval and visualization planning. | **Redaction & Security.** The Data Access Gateway must validate the plan. Nemoclaw is forbidden from directly querying external connectors, preventing data hallucination/leakage. |
|
|
| **WP4: Frontend Canvas** | ⏳ Remaining | Refactor Oracle UI into a virtualized, vertically scrolling JSON canvas with a proper Component Registry. | **No Live Co-Editing.** State changes (mutations) must execute explicit revision commits or rollbacks. Overwriting another user's current view directly is forbidden. |
|
|
| **WP5: Collaboration & Merging** | ⏳ Remaining | Jira-style Share (Fork) workflows, Merge Requests, 3-way component diffs, and review UI. | **Isolated Revisions.** All sharing forces a new branch (Fork). No cross-tenant data sharing is allowed under any circumstance (Hybrid Sovereign constraint). |
|
|
| **WP6: Catalog & Synthesis** | ⏳ Remaining | AI-driven synthesis of custom UI components using extracted tenant styling. | **No Global Promotion.** Auto-promotion of LLM-generated components is isolated to the origin tenant. Uses deterministic `styleSignatures`, avoiding uncontrolled weight fine-tuning. |
|
|
| **WP7: Hardening & Ops** | ⏳ Remaining | Performance testing, telemetry, replay fixtures, and SLA tuning limiters. | Must ensure canvas scrolling maintains 60 FPS up to 5,000 components via strict virtualization limits. |
|
|
|