planning phase

.cursorindexingignore

@@ -0,0 +1,3 @@
+
+# Don't index SpecStory auto-save files, but allow explicit context inclusion via @ references
+.specstory/**

.specstory/.gitignore

@@ -0,0 +1,2 @@
+# SpecStory explanation file
+/.what-is-this.md

.specstory/clickup-tasks/todo.md

@@ -0,0 +1,505 @@
+Intelligent Graph-Based SQL Federation Middleware - Requirements
+Project Overview
+A Docker-containerized middleware system that uses graph analytics to intelligently federate queries across multiple relational databases, translating natural language questions into coordinated SQL queries.
+Example problem to solve: 
+An LLM asks to find all the customers connected to a specific drug and pull pricing information. This request may need to be queried from 3 different databases. Therefore, our intelligent middleware system reads the different schemas from federated sources and designs a plan to retrieve the information for the user-LLM asking the question.
+
+
+
+Epic 1: Database Connection Management
+Feature 1.1: Multi-Database Connection Registry
+As a system administrator
+ I want to configure and manage connections to multiple relational databases
+ So that the middleware can access federated data sources
+Story 1.1.1: Secure Credential Storage
+Acceptance Criteria:
+System reads database credentials from encrypted key files
+Supports username/password authentication
+Credentials stored outside container (mounted volume)
+Support for multiple database types (PostgreSQL, MySQL, SQL Server, Oracle)
+Connection string validation on startup
+Story 1.1.2: Connection Health Monitoring
+Acceptance Criteria:
+System validates connections on initialization
+Periodic health checks (configurable interval)
+Logs connection failures with descriptive errors
+Automatic retry logic with exponential backoff
+Status endpoint to query connection health
+Story 1.1.3: MCP Protocol Support (Optional/Future)
+Acceptance Criteria:
+Support Model Context Protocol connections as alternative to direct DB access
+Fallback to direct connection if MCP unavailable
+Configuration flag to toggle MCP vs direct connection
+
+Epic 2: Schema Discovery & Graph Representation
+Feature 2.1: Automatic Schema Ingestion
+As a data architect
+ I want to automatically discover and index database schemas
+ So that the system understands available data structures
+Story 2.1.1: Schema Metadata Extraction
+Acceptance Criteria:
+Extract table names, column names, data types
+Identify primary keys and foreign keys
+Capture indexes and constraints
+Store table/column descriptions if available in DB metadata
+Support incremental schema updates
+Story 2.1.2: Cross-Database Relationship Discovery
+Acceptance Criteria:
+Identify implicit relationships between tables across databases
+Use naming conventions to suggest relationships (e.g., customer_id fields)
+Allow manual relationship definition/override
+Store relationship confidence scores
+Feature 2.2: Knowledge Graph Construction
+As a system architect
+ I want to represent database schemas as a knowledge graph
+ So that the LLM can understand data relationships and query planning
+Story 2.2.1: Graph Schema Storage
+Acceptance Criteria:
+Nodes represent: databases, tables, columns, relationships
+Edges represent: contains, references, foreign_key relationships
+Graph stored in embedded graph database (Neo4j, TigerGraph, or similar)
+Node properties include: data types, cardinality estimates, usage frequency
+Story 2.2.2: Semantic Annotations
+Acceptance Criteria:
+Support manual annotation of tables/columns with business terms
+Tag tables with domains (e.g., "customer", "pricing", "product")
+Associate synonyms with columns (e.g., "client" → "customer")
+Store sample values for key columns to aid LLM understanding
+Story 2.2.3: Graph Query API
+Acceptance Criteria:
+RESTful API to query graph structure
+Support graph traversal queries (find path between entities)
+Return subgraphs relevant to query keywords
+Export graph in standard formats (GraphML, JSON-LD)
+
+Epic 3: Human-in-the-Loop Configuration
+Feature 3.1: Connection Management Interface
+As a database administrator
+ I want to manage database connections and priorities
+ So that I can control which data sources are used
+Story 3.1.1: Connection CRUD Operations
+Acceptance Criteria:
+API endpoints to add/edit/remove database connections
+Update credentials without system restart
+Enable/disable connections without deletion
+Validation of connection parameters before saving
+Story 3.1.2: Table Priority Configuration
+Acceptance Criteria:
+Assign priority scores to tables (1-10 scale)
+Mark certain tables as "preferred" for specific query types
+Set cost/latency estimates per database
+Configure table deprecation warnings
+Feature 3.2: Schema Annotation Interface
+As a data steward
+ I want to annotate and enrich schema metadata
+ So that query planning is more accurate
+Story 3.2.1: Business Glossary Management
+Acceptance Criteria:
+Add/edit business descriptions for tables and columns
+Define domain tags and categories
+Specify which tables contain authoritative data
+Mark PII/sensitive columns with special flags
+Story 3.2.2: Relationship Override
+Acceptance Criteria:
+Manually define cross-database relationships
+Override auto-discovered relationships
+Specify join conditions between tables
+Document rationale for manual relationships
+
+Epic 4: Intelligent Query Planning
+Feature 4.1: Natural Language Query Understanding
+As a user LLM
+ I want to send natural language queries
+ So that I can retrieve data without writing SQL
+Story 4.1.1: Query Intent Classification
+Acceptance Criteria:
+Parse incoming natural language query
+Extract entities (customers, drugs, pricing, etc.)
+Identify required data attributes
+Classify query type (lookup, aggregation, join, etc.)
+Return confidence score for understanding
+Story 4.1.2: Entity-to-Schema Mapping
+Acceptance Criteria:
+Map query entities to graph nodes (tables/columns)
+Use semantic annotations and business glossary
+Leverage embeddings for fuzzy matching
+Return top-k candidate mappings with confidence scores
+Feature 4.2: Federated Query Plan Generation
+As a query planner
+ I want to generate optimal execution plans across databases
+ So that queries are efficient and accurate
+Story 4.2.1: Graph-Based Query Decomposition
+Acceptance Criteria:
+Use graph traversal to find paths between required entities
+Identify which databases contain needed data
+Decompose complex queries into sub-queries per database
+Minimize cross-database joins
+Generate dependency graph of sub-queries
+Story 4.2.2: Query Optimization
+Acceptance Criteria:
+Consider table priorities in plan selection
+Estimate query costs (latency, data volume)
+Choose optimal join strategies
+Apply predicate pushdown where possible
+Generate multiple candidate plans with cost estimates
+Story 4.2.3: Execution Plan Explainability
+Acceptance Criteria:
+Generate human-readable explanation of query plan
+Show which databases will be queried
+Explain why certain tables were chosen
+Visualize query execution flow
+Include estimated execution time
+
+Epic 5: Query Execution & Result Compilation
+Feature 5.1: Distributed Query Execution
+As a query executor
+ I want to execute SQL across multiple databases
+ So that I can retrieve federated results
+Story 5.1.1: Parallel Sub-Query Execution
+Acceptance Criteria:
+Execute independent sub-queries in parallel
+Respect query dependencies (wait for required data)
+Handle connection pooling per database
+Set per-query timeouts
+Collect execution metrics (time, rows returned)
+Story 5.1.2: Error Handling & Fallbacks
+Acceptance Criteria:
+Gracefully handle query failures
+Provide partial results if some queries fail
+Suggest alternative queries on failure
+Log detailed error information
+Implement circuit breaker pattern for failing databases
+Feature 5.2: Result Integration & Formatting
+As a result processor
+ I want to combine and format query results
+ So that the user LLM receives coherent answers
+Story 5.2.1: Cross-Database Join Processing
+Acceptance Criteria:
+Perform in-memory joins on results from different databases
+Support common join types (inner, left, outer)
+Handle data type mismatches gracefully
+Optimize memory usage for large result sets
+Story 5.2.2: LLM-Powered Result Synthesis
+Acceptance Criteria:
+Use LLM to format raw results into natural language answers
+Generate summary statistics where appropriate
+Create structured JSON responses with metadata
+Include data provenance (which DB each piece came from)
+Handle null/missing values intelligently
+Story 5.2.3: Response Caching
+Acceptance Criteria:
+Cache query results with TTL
+Use query fingerprint for cache key
+Support cache invalidation on schema changes
+Configurable cache size limits
+Cache hit/miss metrics
+
+Epic 6: System Infrastructure & DevOps
+Feature 6.1: Docker Containerization
+As a DevOps engineer
+ I want to deploy the system as a Docker container
+ So that it's portable and easy to manage
+Story 6.1.1: Container Build & Configuration
+Acceptance Criteria:
+Dockerfile with multi-stage build
+Environment-based configuration
+Volume mounts for credentials and graph storage
+Health check endpoint
+Minimal base image (security hardened)
+Story 6.1.2: Docker Compose Setup
+Acceptance Criteria:
+Compose file with middleware + graph DB
+Network configuration for service communication
+Persistent volumes for data
+Easy local development setup
+Environment variable templates
+Feature 6.2: Observability & Monitoring
+As a system operator
+ I want to monitor system performance and health
+ So that I can ensure reliability
+Story 6.2.1: Structured Logging
+Acceptance Criteria:
+JSON-formatted logs
+Log levels: DEBUG, INFO, WARN, ERROR
+Request tracing with correlation IDs
+Performance timing logs
+Sensitive data redaction
+Story 6.2.2: Metrics & Instrumentation
+Acceptance Criteria:
+Prometheus-compatible metrics endpoint
+Track: query latency, error rates, cache hits
+Database connection pool metrics
+Graph query performance metrics
+Export metrics in OpenTelemetry format
+
+Epic 7: API & Integration Layer
+Feature 7.1: RESTful Query API
+As a client LLM
+ I want to submit queries via REST API
+ So that I can integrate with the middleware
+Story 7.1.1: Query Submission Endpoint
+Acceptance Criteria:
+POST /api/v1/query endpoint
+Accept natural language query in request body
+Return JSON response with results and metadata
+Support synchronous and async query modes
+Include request ID for tracking
+Story 7.1.2: Query Status & Results Retrieval
+Acceptance Criteria:
+GET /api/v1/query/{request_id}/status
+GET /api/v1/query/{request_id}/results
+Webhook callback support for async queries
+Streaming results for large datasets
+Pagination support
+Feature 7.2: Administrative API
+As a system administrator
+ I want to manage system configuration via API
+ So that I can automate operations
+Story 7.2.1: Schema Management Endpoints
+Acceptance Criteria:
+POST /api/v1/databases (register new database)
+PUT /api/v1/databases/{id}/refresh (update schema)
+GET /api/v1/graph/search (query knowledge graph)
+POST /api/v1/annotations (add semantic annotations)
+Story 7.2.2: System Control Endpoints
+Acceptance Criteria:
+GET /health (readiness and liveness)
+GET /metrics (Prometheus metrics)
+POST /cache/clear
+GET /api/v1/connections/test
+
+Example Workflow: Drug-Customer-Pricing Query
+Scenario
+Query: "Find all customers connected to drug 'Aspirin' and pull pricing information"
+System Flow:
+Query Understanding:
+
+
+Entities identified: "customers", "drug: Aspirin", "pricing"
+Intent: Multi-entity lookup with join
+Graph Traversal:
+
+
+Find path: Customer → Prescription → Drug → Pricing
+Identify tables: pharma_db.customers, orders_db.prescriptions, pharma_db.drugs, pricing_db.drug_prices
+Query Plan:
+
+
+Query 1 (pharma_db): SELECT drug_id FROM drugs WHERE name = 'Aspirin'
+Query 2 (orders_db): SELECT customer_id FROM prescriptions WHERE drug_id = ?
+Query 3 (pharma_db): SELECT * FROM customers WHERE id IN (?)
+Query 4 (pricing_db): SELECT * FROM drug_prices WHERE drug_id = ?
+Execution:
+
+
+Execute Query 1, get drug_id = 12345
+Execute Query 2 & 4 in parallel using drug_id
+Execute Query 3 using customer_ids from Query 2
+Result Synthesis:
+
+
+LLM combines results into natural language response
+Includes customer names, order details, and pricing
+Cites source databases in response
+
+Non-Functional Requirements
+Performance
+Query response time < 5 seconds for 80% of queries
+Support concurrent query execution (10+ simultaneous queries)
+Graph traversal queries < 100ms
+Security
+Encrypted credential storage (AES-256)
+TLS for all external API communications
+Role-based access control for admin APIs
+SQL injection prevention
+Audit logging of all query executions
+Scalability
+Horizontal scaling of query executors
+Support for 100+ database connections
+Handle schemas with 1000+ tables
+Process result sets up to 100k rows
+Reliability
+99.5% uptime target
+Graceful degradation on partial failures
+Automatic retry on transient errors
+Data consistency validation
+
+Technical Stack Recommendations
+Language: Python 3.11+ (for LLM integration, data processing)
+Graph Database: Neo4j Community Edition or Apache AGE
+API Framework: FastAPI
+Database Drivers: SQLAlchemy (multi-DB support)
+LLM Integration: LangChain or direct API calls
+Caching: Redis
+Containerization: Docker + Docker Compose
+Monitoring: Prometheus + Grafana
+
+
+
+
+—---
+
+
+Epic 8: Streamlit Demonstration Interface
+Feature 8.1: Simple Single-Page Query Demo
+As a product demonstrator
+ I want to showcase the middleware capabilities through a simple web interface
+ So that stakeholders can see the federated query system in action
+
+Story 8.1.1: Single-Page Query Interface
+Acceptance Criteria:
+Single page Streamlit app with three main sections:
+Query Input (top)
+Execution Visualization (middle)
+Results Display (bottom)
+Text area for natural language query input
+"Execute Query" button
+Dropdown with 3-4 example queries for quick testing
+Clean, minimal design with clear visual separation between sections
+Example Queries:
+"Find all customers connected to drug 'Aspirin' and pull pricing information"
+"Show me customers who have purchased drugs over $500"
+"List all prescriptions for customer 'John Smith' with pricing"
+
+Story 8.1.2: Middleware Execution Visualization
+Acceptance Criteria:
+Display execution progress in real-time with simple status indicators
+Show 4 key phases as they happen:
+🔍 Understanding Query - Show identified entities (customers, drug: Aspirin, pricing)
+🗺️ Finding Tables - Display which tables will be used (e.g., "3 tables across 3 databases")
+⚙️ Executing Queries - Show databases being queried with loading animation
+✅ Compiling Results - Brief status before showing results
+Each phase appears sequentially with checkmark when complete
+Simple text descriptions, no complex visualizations
+Total execution time displayed at the end
+Visual Example:
+Execution Status:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✓ Understanding Query (0.2s)
+  Entities: customers, drug (Aspirin), pricing
+  
+✓ Finding Tables (0.3s)
+  Located 3 tables across 3 databases
+  • pharma_db.customers
+  • orders_db.prescriptions  
+  • pricing_db.drug_prices
+  
+✓ Executing Queries (1.8s)
+  Queried: pharma_db → orders_db → pricing_db
+  
+✓ Compiling Results (0.4s)
+  Retrieved 47 records
+
+Total Time: 2.7s
+
+
+Story 8.1.3: Results Display
+Acceptance Criteria:
+Display results in two formats:
+Summary: Natural language answer (2-3 sentences from LLM)
+Data Table: Clean dataframe showing the retrieved data
+Table includes:
+Customer names
+Drug information
+Pricing details
+Database source indicator (subtle badge or column)
+Show row count and key statistics (e.g., "47 customers found, avg price: $24.50")
+Download CSV button below the table
+Results are paginated if more than 50 rows
+Example Output:
+📊 Summary:
+Found 47 customers who have been prescribed Aspirin. The pricing 
+ranges from $5.99 to $15.99 depending on dosage and pharmacy.
+
+Results (47 rows):
+┌──────────────┬────────────┬──────────┬──────────┐
+│ Customer     │ Drug       │ Price    │ Source   │
+├──────────────┼────────────┼──────────┼──────────┤
+│ John Smith   │ Aspirin    │ $12.99   │ pharma   │
+│ Jane Doe     │ Aspirin    │ $15.99   │ pharma   │
+│ ...          │ ...        │ ...      │ ...      │
+└──────────────┴────────────┴──────────┴──────────┘
+
+[Download CSV]
+
+
+Story 8.1.4: Basic Configuration Display
+Acceptance Criteria:
+Sidebar shows simple connection status
+List of connected databases with status indicators (🟢/🔴)
+Total table count per database
+No edit functionality needed - just display
+Collapsible sidebar to maximize screen space
+Sidebar Content:
+📂 Connected Databases
+
+🟢 pharma_db
+   3 tables
+
+🟢 orders_db  
+   2 tables
+
+🟢 pricing_db
+   1 table
+
+
+Story 8.1.5: Error Handling
+Acceptance Criteria:
+Display friendly error messages if queries fail
+Show which phase failed and basic reason
+Suggest trying example queries if custom query fails
+Include basic troubleshooting hint (e.g., "Check database connections")
+Error doesn't break the interface - user can try another query
+
+Technical Implementation
+Streamlit App Structure
+streamlit_app/
+├── app.py                  # Single main file (~200-300 lines)
+├── middleware_client.py    # API calls to middleware
+├── requirements.txt
+└── config.py              # Database connection display config
+
+Simple API Integration
+# Query submission
+POST /api/v1/query
+{
+  "query": "Find all customers connected to drug 'Aspirin'..."
+}
+
+# Response includes execution phases and results
+{
+  "request_id": "abc123",
+  "phases": [
+    {"name": "understanding", "duration_ms": 200, "details": {...}},
+    {"name": "planning", "duration_ms": 300, "details": {...}},
+    {"name": "execution", "duration_ms": 1800, "details": {...}},
+    {"name": "synthesis", "duration_ms": 400, "details": {...}}
+  ],
+  "results": {
+    "summary": "Found 47 customers...",
+    "data": [...],
+    "row_count": 47
+  }
+}
+
+Key Dependencies
+streamlit>=1.28.0
+requests>=2.31.0
+pandas>=2.1.0
+
+
+Acceptance Criteria for Epic 8
+[ ] Single page Streamlit app runs in Docker container
+[ ] User can input natural language queries
+[ ] Example queries work correctly
+[ ] Execution phases display sequentially with timing
+[ ] Results show as summary + data table
+[ ] Database connection status visible in sidebar
+[ ] Download CSV functionality works
+[ ] Error messages are clear and helpful
+[ ] Complete demo runs in < 5 seconds
+[ ] UI is clean and uncluttered
+[ ] Successfully demonstrates federated query across 3 databases
+
+Total Scope: One simple page, ~300 lines of code, focused entirely on demonstrating the core capability with minimal complexity.

README.md

@@ -1,4 +1,5 @@
 # Graph-Driven Agentic System MVP
+"Keep your data where it is but we will treat it like a graph for you and solve these problems for you"
 
 ## Overview
 An intelligent agent system that reads instructions from Neo4j, queries PostgreSQL databases, pauses for human review, and maintains a complete audit trail. The system demonstrates agentic workflow orchestration with human-in-the-loop controls.
@@ -27,6 +28,16 @@ An intelligent agent system that reads instructions from Neo4j, queries PostgreS
                     └─────────────┘    └─────────────┘
 ```
 
+###### Any MCP applicaiton/API/Agent can be both a client and a server. Clients and Servers are a logical seperation only, not a physical one. There is an natural idea of chaining/composability between clients and servers. Like a fire bucket chain of context slosh. Use a pydantic graph here as the engine for the orchestrator? I think the point is to create a co-pilot for the analyst that is using graphRAG to inform itself, given the users request, to think in graphRAG before determining how to navigate the MCP tools
+
+
+actually you aren't immediately writeing data to neo4j from the relational DB instead it's about doing graphRAG to curate the proper SQL statements and tool call to make... there maybe tools to do this.
+
+Use MCP inspector and also have an MCP server that automatically checks the logs in the inspector: https://modelcontextprotocol.io/docs/tools/inspector
+
+
+pydantic is key here and now worrying about frontend until demo time
+
 ### Components
 
 - **Neo4j**: Graph database storing workflows, instructions, and execution metadata

agent/main.py

@@ -22,6 +22,24 @@ if "gpt" in LLM_MODEL:
 else:
     llm_client = Anthropic(api_key=LLM_API_KEY)
 
+# Defining the agents
+## Data Procurement Agent
+## Graph Analysis Agent
+## x Agent etc...
+
+# Create Orchestrato with all the agents and their tasks per orchestrator.py file
+orchestrator = Orchestrator(
+    llm_factory=EastridgeAugmentedLLM,
+    available_agents=[
+        DataProcurementAgent(),
+        GraphAnalysisAgent(),
+        xAgent()
+    ],
+    plan_type="full",
+    plan_output_path=Path("output/execution_plan.md"),
+)
+
+
 # Global flag for interrupt handling
 interrupted = False
 

agent/plan.md

@@ -0,0 +1,20 @@
+{
+    "data": {
+        "steps": [
+            {
+                "description": "Procure data from the source",
+                "tasks": {
+                    "description": "Go to the relational database and procure the data we need. (1st find out what we need to procure from the KG/graph db? thus using the knowledge graph to curate the semantics used for the SQL query? dor can we just hard code the queries like mindsDB? or do we use it to instruct/populate these desctiptions for the agent to reference here(is that actually used as system_prompt-input/augmentation?)",
+                    "agent": "data_procurement_agent"
+                }
+            },
+            {
+                "description": "Transform the data into a graph database",
+                "tasks": {
+                    "description": "run analysis on the data and transform it into a graph database",
+                    "agent": "graph_transformation_agent"
+                }
+            }
+        ]
+    }
+}

agent/task.md

@@ -0,0 +1,24 @@
+# overall task you want the agent(s) to accomplish:
+
+# Task title
+
+Do this step by step:
+
+1. 
+2. 
+3. 
+4. 
+5. 
+6. 
+7. 
+8. 
+9. 
+10. 
+
+Create this output in this format:
+
+Save as this file naming convention -
+
+Persona/System_Prompt Insturctions:
+
+Read only access to the relational database.

plan.md

@@ -0,0 +1,66 @@
+# Implementation Plan: Intelligent Graph-Based SQL Federation Middleware (Revised)
+
+This document outlines the revised strategy to implement the target features by integrating valuable assets from the `semantic-query-router` codebase into our existing architecture.
+
+### Overall Strategy
+The core task is to evolve the current single-step agent into a multi-step, GraphRAG-powered orchestrator using LangChain. We will enhance the MCP server with advanced core logic, replace PostgreSQL with a rich life sciences SQLite dataset, and transform the Streamlit monitor into a fully conversational chat UI. The `frontend/` Next.js application will be deprecated.
+
+---
+
+### Phase 1: Integrate New Dataset & Core Logic (Due by Friday, Oct 3rd)
+
+**Goal**: Replace the existing data foundation with the life sciences dataset and upgrade the MCP server with advanced, reusable logic from the `semantic-query-router` project.
+
+-   **Task 1.1: Adopt Life Sciences Dataset**
+    -   Integrate the `generate_sample_databases.py` script into our `ops/scripts/` directory.
+    -   Create a new `make seed-db` command in the `Makefile` to generate the `clinical_trials.db`, `laboratory.db`, and `drug_discovery.db` SQLite files.
+    -   Update `docker-compose.yml` to remove the PostgreSQL service and mount the new `data/` directory for the SQLite databases.
+
+-   **Task 1.2: Enhance MCP Server with Core Logic**
+    -   Create a new `mcp/core/` directory.
+    -   Migrate the advanced logic from `semantic-query-router/src/core/` (`discovery.py`, `graph.py`, `intelligence.py`) into our `mcp/core/` directory.
+    -   Refactor these modules to fit our project structure and standards.
+
+-   **Task 1.3: Create a Dedicated Ingestion Process**
+    -   Create a new script, `ops/scripts/ingest.py`, that uses the new core logic to perform a one-time ingestion of the SQLite database schemas into Neo4j.
+    -   Create a `make ingest` command in the `Makefile` to run this script. This separates the schema ingestion process from the agent's runtime duties, making the system more modular.
+    -   Remove the schema discovery logic from `agent/main.py`.
+
+---
+
+### Phase 2: Rebuild Agent with LangChain (Due by Tuesday, Oct 7th)
+
+**Goal**: Re-architect the agent from a simple script into a robust LangChain-powered orchestrator that leverages the enhanced MCP server.
+
+-   **Task 2.1: Refactor Agent to use LangChain**
+    -   Overhaul `agent/main.py` to implement the `AgentExecutor` pattern from `langchain_integration.py`.
+    -   Define a formal agent prompt that instructs the LLM on how to use the available tools to answer questions.
+
+-   **Task 2.2: Implement Custom LangChain Tools**
+    -   Create a new `agent/tools.py` file.
+    -   Implement custom LangChain tools that make authenticated REST API calls to our enhanced MCP server.
+    -   The tools will include: `SchemaSearchTool`, `JoinPathFinderTool`, and `QueryExecutorTool`. These tools will act as clients to the powerful logic we integrated into the MCP in Phase 1.
+
+-   **Task 2.3: Update Agent's Main Loop**
+    -   Modify the agent's main loop to delegate tasks to the LangChain `AgentExecutor` instead of handling instructions directly. The agent's primary role will now be to orchestrate the LangChain agent and log the results.
+
+---
+
+### Phase 3: Build the Chat UI & Finalize (Due by Thursday, Oct 9th)
+
+**Goal**: Replace the basic Streamlit monitor with a full-featured conversational chat interface and complete the final integration for the demo.
+
+-   **Task 3.1: Implement Conversational Chat UI**
+    -   Replace the entire contents of `streamlit/app.py` with the conversational UI logic from `semantic-query-router/src/chat_app.py`.
+    -   Adapt the UI to work with our project's MCP REST API (instead of WebSocket) for submitting questions and fetching results.
+
+-   **Task 3.2: Integrate Demo-Specific Features**
+    -   Ensure the new Streamlit UI includes the required demo features:
+        -   Display of execution phases (e.g., "Searching Schema," "Finding Join Path," "Executing Query").
+        -   A final results view that shows both the natural language summary from the agent and a clean data table (Pandas DataFrame) of the raw results.
+        -   A "Download CSV" button for the results table.
+        -   A sidebar that displays the connection status of the Neo4j and SQLite databases.
+
+-   **Task 3.3: Final Integration and Testing**
+    -   Perform end-to-end testing of the full workflow: from asking a question in the Streamlit app to the agent's orchestration and the final result display.
+    -   Clean up any unused files and finalize the `README.md` with updated instructions.