GovCortexAI (V2 Plan)

Governed analytics agent with dual-chat comparison:

• Memory OFF: same agent asked the same question in two lanes, can diverge in approach/style.
• Memory ON: same agent uses approved notebook memory and should converge to the canonical answer.

This document describes the planned V2 architecture. V2 is not implemented yet.

V2 Current Implementation Slice

Implemented now:

• src_v2/api/main.py: dual-lane V2 API with:
  • POST /api/v2/chat/turn
  • POST /api/v2/chat/turns/dual
  • GET /api/v2/chat/events/{session_id}/{lane_id}
  • GET /api/v2/chat/stream/{session_id}/{lane_id}
  • GET /api/v2/chat/session/{session_id}
  • GET /api/v2/library/cells
  • GET /api/v2/library/notebooks
  • GET /api/v2/library/notebooks/{template_id}
  • GET /api/v2/library/examples
  • POST /api/v2/library/evaluate-lane (mock accuracy + pending approval persistence)
• src_v2/orchestrator/react_agent.py: mode-gated ReAct turn runner.
• src_v2/orchestrator/tools.py: schema explorer, guarded SQL runner, notebook runner, python runner.
• src_v2/ui/Home.py: side-by-side dual-lane Streamlit UI with unified live timeline, cell status labels, and evaluate/send workflow.
• src_v2/ui/pages/1_Memory_Library.py: separate Memory Library page for approved notebook/cell memory and pending approvals.

Supporting scripts:

• scripts/seed_v2_demo_cells.py: seed additional approved V2 demo cells.
• scripts/check_composio_snowflake.py: verify Composio Snowflake connected account.
• scripts/test_v2_showcase_flows.py: validate OFF divergence and ON convergence flow.

Run V2

API (port 8002)

py -m uvicorn src_v2.api.main:app --host 0.0.0.0 --port 8002

UI

streamlit run src_v2/ui/Home.py

Required Env For Composio Snowflake

COMPOSIO_API_KEY=...
SNOWFLAKE_DATABASE=GOVCORTEX
SNOWFLAKE_SCHEMA=PUBLIC

Verify Composio Wiring

curl http://localhost:8002/api/v2/tools/status

Seed V2 Demo Cells

venv\Scripts\python.exe scripts\seed_v2_demo_cells.py

Run Showcase Flow Check

venv\Scripts\python.exe scripts\test_v2_showcase_flows.py

Why This Rework

Current implementation does not match demo goals:

• Not a true multi-turn ReAct chat experience.
• No reliable streaming across intermediate tool steps.
• Notebook memory is not treated as executable, approved workflow memory.
• Weak guardrails for analytics-safe data access patterns.

V2 Product Behavior

Core UX

• Two side-by-side chats for the same question.
• Same agent in both lanes.
• Toggle memory mode:
  • OFF: notebook memory tools disabled.
  • ON: notebook memory tools enabled.

Expected Demo Outcome

• Memory OFF:
  • Both lanes run independently.
  • Same question can produce different reasoning paths and answer styles.
• Memory ON:
  • Agent checks approved notebook workflows.
  • Both lanes should return consistent canonical outputs.

Planned Architecture

Agent Runtime

• CrewAI-based ReAct orchestration.
• Persistent multi-turn session context per lane.
• Tool action stream shown live in UI.

Tooling

• schema_explorer: discover tables/columns only.
• sql_runner: guarded SQL execution with preview limits.
• python_runner: controlled Python transforms over query previews.
• notebook_runner: execute approved notebook cells with inputs and return previews.

Notebook Memory

• Notebook memory is executable, not only retrieval text.
• Notebook templates include input cell + ordered SQL/Python cells.
• Agent can pass inputs to notebook templates and use returned previews.

Guardrails

• No unrestricted table dumps.
• Block SELECT * unless explicitly safe and limited.
• Enforce row preview limits.
• Prefer aggregated analytics queries over raw extraction.

API and Streaming (Planned)

• FastAPI V2 endpoints under /api/v2.
• SSE stream for lane-level events:
  • intent parsed
  • schema explored
  • tool called
  • notebook step executed
  • partial findings
  • final answer

Planned Repo Layout

src_v2/
  api/
  agents/
  orchestrator/
  models/
  ui/
    pages/
docs/
  requirements.md
  technical.md
  implementation_plan.md

V2 Status

• Documentation: in progress.
• Implementation: not started.
• Existing V1 code: kept as-is for reference.

Next Step

Implementation will start from docs-defined contracts:

• dual-lane session model
• mode-gated tools
• notebook execution interface
• streaming event protocol