commit dev

.gitignore

@@ -0,0 +1,2 @@
+*.db
+/graph-agentic-system/neo4j/data

Makefile

@@ -0,0 +1,11 @@
+up:
+	docker-compose up -d
+
+down:
+	docker-compose down
+
+logs:
+	docker-compose logs -f
+
+seed:
+	docker-compose exec mcp python /app/ops/scripts/seed.py

README.md

@@ -0,0 +1,80 @@
+# Agentic Knowledge Graph
+
+A graph-driven agentic system that uses Neo4j as the knowledge graph backend, with MCP server for graph operations, an intelligent agent for workflow execution, and a web interface for interaction.
+
+## Architecture
+
+- **Neo4j**: Knowledge graph database storing workflows, instructions, and metadata
+- **MCP Server**: Single gateway for all Neo4j operations with API key authentication
+- **Agent**: Executes workflows by reading instructions from Neo4j and performing actions
+- **Frontend**: Next.js web interface for user interaction and monitoring
+- **PostgreSQL**: Data source for schema discovery and query execution
+
+## Quick Start
+
+1. **Clone and setup**:
+   ```bash
+   git clone <repository-url>
+   cd 20250922_agentic_kg
+   cp .env.example .env
+   ```
+
+2. **Edit environment variables**:
+   - Update `.env` with your API keys and configuration
+   - Set `LLM_API_KEY` for OpenAI/Claude access
+   - Set `MCP_API_KEYS` for MCP server authentication
+
+3. **Start services**:
+   ```bash
+   make up
+   ```
+
+4. **Check health**:
+   ```bash
+   make neo4j-health
+   make logs
+   ```
+
+## Available Commands
+
+- `make up` - Start all services
+- `make down` - Stop all services  
+- `make logs` - Show service logs
+- `make seed` - Seed database with initial data
+- `make clean` - Stop and remove volumes
+- `make restart` - Restart all services
+- `make neo4j-health` - Check Neo4j health
+
+## Services
+
+- **Neo4j**: http://localhost:7474 (Browser), bolt://localhost:7687 (Bolt)
+- **MCP Server**: http://localhost:3001
+- **Frontend**: http://localhost:3000
+- **PostgreSQL**: localhost:5432
+
+## Development
+
+The system is designed as a monorepo with the following structure:
+
+```
+├── neo4j/          # Neo4j Docker configuration
+├── mcp/            # MCP server implementation
+├── agent/          # Agent implementation
+├── frontend/       # Next.js frontend
+├── postgres/       # PostgreSQL configuration
+├── ops/            # Operations scripts
+└── docker-compose.yml
+```
+
+## Features
+
+- Graph-driven workflow execution
+- Human-in-the-loop pauses for review
+- Natural language to SQL translation
+- Real-time workflow monitoring
+- Graph visualization
+- Audit logging
+
+## Status
+
+🚧 **In Development** - Core infrastructure setup complete, implementing MCP server and agent components.

docker-compose.yml

@@ -0,0 +1,45 @@
+version: '3.8'
+
+services:
+  neo4j:
+    build: ./neo4j
+    ports:
+      - "7474:7474"  # Browser
+      - "7687:7687"  # Bolt
+    environment:
+      - NEO4J_AUTH=neo4j/password
+    volumes:
+      - ./neo4j/data:/data
+    healthcheck:
+      test: ["CMD", "cypher-shell", "-u", "neo4j", "-p", "password", "MATCH (n) RETURN count(n) LIMIT 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  postgres:
+    image: postgres:15
+    container_name: postgres
+    ports:
+      - "5432:5432"
+    environment:
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
+      - POSTGRES_DB=testdb
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+  mcp:
+    build: ./mcp
+    container_name: mcp
+    ports:
+      - "8000:8000"
+    environment:
+      - MCP_PORT=8000
+      - MCP_API_KEYS=dev-key-123,external-key-456
+      - NEO4J_BOLT_URL=bolt://neo4j:7687
+      - NEO4J_AUTH=neo4j/password
+    depends_on:
+      - neo4j
+
+volumes:
+  neo4j_data:
+  postgres_data:

graph-agentic-system/docker-compose.yml

@@ -0,0 +1,29 @@
+version: '3.8'
+
+services:
+  neo4j:
+    image: neo4j:5.15-community
+    container_name: neo4j
+    ports:
+      - "7474:7474"
+      - "7687:7687"
+    environment:
+      - NEO4J_AUTH=-Force{NEO4J_AUTH}
+      - NEO4J_BOLT_URL=-Force{NEO4J_BOLT_URL}
+    volumes:
+      - neo4j_data:/data
+
+  postgres:
+    image: postgres:15
+    container_name: postgres
+    ports:
+      - "5432:5432"
+    environment:
+      - POSTGRES_PASSWORD=-Force{POSTGRES_PASSWORD}
+      - POSTGRES_DB=testdb
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+volumes:
+  neo4j_data:
+  postgres_data:

graph-agentic-system/mcp/Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 8000
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

graph-agentic-system/mcp/main.py

@@ -0,0 +1,62 @@
+from fastapi import FastAPI, Header, HTTPException
+from neo4j import GraphDatabase
+import os
+import json
+from datetime import datetime
+
+app = FastAPI()
+driver = GraphDatabase.driver(
+    os.getenv("NEO4J_BOLT_URL"),
+    auth=("neo4j", os.getenv("NEO4J_AUTH").split("/")[1])
+)
+
+VALID_API_KEYS = os.getenv("MCP_API_KEYS", "").split(",")
+
+@app.get("/health")
+def health():
+    return {"ok": True, "timestamp": datetime.now().isoformat()}
+
+@app.post("/mcp")
+async def execute_tool(request: dict, x_api_key: str = Header(None)):
+    # Verify API key
+    if x_api_key not in VALID_API_KEYS:
+        raise HTTPException(status_code=401, detail="Invalid API key")
+    
+    tool = request.get("tool")
+    params = request.get("params", {})
+    
+    if tool == "get_schema":
+        # Return node labels and relationships
+        with driver.session() as session:
+            result = session.run("CALL db.labels() YIELD label RETURN collect(label) as labels")
+            return {"labels": result.single()["labels"]}
+    
+    elif tool == "query_graph":
+        # Execute parameterized query
+        query = params.get("query")
+        query_params = params.get("parameters", {})
+        with driver.session() as session:
+            result = session.run(query, query_params)
+            return {"data": [dict(record) for record in result]}
+    
+    elif tool == "write_graph":
+        # Structured write operation
+        action = params.get("action")
+        if action == "create_node":
+            label = params.get("label")
+            properties = params.get("properties", {})
+            with driver.session() as session:
+                result = session.run(f"CREATE (n:{label} ) RETURN n", props=properties)
+                return {"created": dict(result.single()["n"])}
+    
+    elif tool == "get_next_instruction":
+        # Get next pending instruction
+        with driver.session() as session:
+            result = session.run("""
+                MATCH (i:Instruction {status: 'pending'})
+                RETURN i ORDER BY i.sequence LIMIT 1
+            """)
+            record = result.single()
+            return {"instruction": dict(record["i"]) if record else None}
+    
+    return {"error": "Unknown tool"}

graph-agentic-system/mcp/requirements.txt

@@ -0,0 +1,4 @@
+fastapi==0.104.0
+uvicorn==0.24.0
+neo4j==5.14.0
+pydantic==2.4.0

graph-agentic-system/neo4j/Dockerfile

@@ -0,0 +1,4 @@
+FROM neo4j:5.23.0
+ENV NEO4J_PLUGINS='["apoc"]'
+ENV NEO4J_apoc_export_file_enabled=true
+ENV NEO4J_apoc_import_file_enabled=true

graph-agentic-system/ops/health/neo4j.ps1

@@ -0,0 +1,2 @@
+docker-compose exec neo4j cypher-shell -u neo4j -p password "MATCH (n) RETURN count(n) LIMIT 1"
+if (1 -eq 0) { echo " Neo4j healthy" }

graph-agentic-system/ops/health/neo4j.sh

@@ -0,0 +1,2 @@
+#!/bin/bash
+docker-compose exec neo4j cypher-shell -u neo4j -p password "MATCH (n) RETURN count(n) LIMIT 1" && echo " Neo4j healthy"

graph-agentic-system/ops/scripts/seed.py

@@ -0,0 +1,83 @@
+import requests
+import json
+
+MCP_URL = "http://localhost:8000/mcp"
+API_KEY = "dev-key-123"
+
+def call_mcp(tool, params=None):
+    response = requests.post(
+        MCP_URL,
+        headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
+        json={"tool": tool, "params": params or {}}
+    )
+    if response.status_code == 200:
+        return response.json()
+    else:
+        print(f"Error: {response.status_code} - {response.text}")
+        return {"error": f"HTTP {response.status_code}: {response.text}"}
+
+# Clear existing data
+print("Clearing existing data...")
+call_mcp("query_graph", {"query": "MATCH (n) DETACH DELETE n"})
+
+# Create demo workflow
+print("Creating workflow...")
+workflow = call_mcp("write_graph", {
+    "action": "create_node",
+    "label": "Workflow",
+    "properties": {
+        "id": "demo-workflow-1",
+        "name": "Entity Resolution Demo",
+        "status": "active",
+        "max_iterations": 10,
+        "current_iteration": 0
+    }
+})
+print(f"Created workflow: {workflow}")
+
+# Create three instructions
+print("Creating instructions...")
+instructions = [
+    {"id": "inst-1", "sequence": 1, "type": "discover_schema", "status": "pending", "pause_duration": 300},
+    {"id": "inst-2", "sequence": 2, "type": "generate_sql", "status": "pending", "pause_duration": 300},
+    {"id": "inst-3", "sequence": 3, "type": "review_results", "status": "pending", "pause_duration": 300}
+]
+
+for inst in instructions:
+    result = call_mcp("write_graph", {
+        "action": "create_node",
+        "label": "Instruction",
+        "properties": inst
+    })
+    print(f"Created instruction: {inst['id']}")
+
+# Create relationships
+print("Creating relationships...")
+call_mcp("query_graph", {
+    "query": "MATCH (w:Workflow {id: 'demo-workflow-1'}), (i:Instruction {id: 'inst-1'}) CREATE (w)-[:HAS_INSTRUCTION]->(i)"
+})
+
+call_mcp("query_graph", {
+    "query": "MATCH (w:Workflow {id: 'demo-workflow-1'}), (i:Instruction {id: 'inst-2'}) CREATE (w)-[:HAS_INSTRUCTION]->(i)"
+})
+
+call_mcp("query_graph", {
+    "query": "MATCH (w:Workflow {id: 'demo-workflow-1'}), (i:Instruction {id: 'inst-3'}) CREATE (w)-[:HAS_INSTRUCTION]->(i)"
+})
+
+# Create instruction chain
+call_mcp("query_graph", {
+    "query": "MATCH (i1:Instruction {id: 'inst-1'}), (i2:Instruction {id: 'inst-2'}) CREATE (i1)-[:NEXT_INSTRUCTION]->(i2)"
+})
+
+call_mcp("query_graph", {
+    "query": "MATCH (i2:Instruction {id: 'inst-2'}), (i3:Instruction {id: 'inst-3'}) CREATE (i2)-[:NEXT_INSTRUCTION]->(i3)"
+})
+
+# Create indexes
+print("Creating indexes...")
+call_mcp("query_graph", {"query": "CREATE INDEX workflow_id IF NOT EXISTS FOR (w:Workflow) ON (w.id)"})
+call_mcp("query_graph", {"query": "CREATE INDEX instruction_id IF NOT EXISTS FOR (i:Instruction) ON (i.id)"})
+call_mcp("query_graph", {"query": "CREATE INDEX instruction_status_seq IF NOT EXISTS FOR (i:Instruction) ON (i.status, i.sequence)"})
+
+print(" Seeding complete!")

mcp/Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 8000
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

mcp/main.py

@@ -0,0 +1,66 @@
+from fastapi import FastAPI, Header, HTTPException
+from neo4j import GraphDatabase
+import os
+import json
+from datetime import datetime
+
+app = FastAPI()
+driver = GraphDatabase.driver(
+    os.getenv("NEO4J_BOLT_URL"),
+    auth=("neo4j", os.getenv("NEO4J_AUTH").split("/")[1])
+)
+
+VALID_API_KEYS = os.getenv("MCP_API_KEYS", "").split(",")
+
+@app.get("/health")
+def health():
+    return {"ok": True, "timestamp": datetime.now().isoformat()}
+
+@app.post("/mcp")
+async def execute_tool(request: dict, x_api_key: str = Header(None)):
+    # Verify API key
+    if x_api_key not in VALID_API_KEYS:
+        raise HTTPException(status_code=401, detail="Invalid API key")
+    
+    tool = request.get("tool")
+    params = request.get("params", {})
+    
+    if tool == "get_schema":
+        # Return node labels and relationships
+        with driver.session() as session:
+            result = session.run("CALL db.labels() YIELD label RETURN collect(label) as labels")
+            return {"labels": result.single()["labels"]}
+    
+    elif tool == "query_graph":
+        # Execute parameterized query
+        query = params.get("query")
+        query_params = params.get("parameters", {})
+        with driver.session() as session:
+            result = session.run(query, query_params)
+            return {"data": [dict(record) for record in result]}
+    
+    elif tool == "write_graph":
+        # Structured write operation
+        action = params.get("action")
+        if action == "create_node":
+            label = params.get("label")
+            properties = params.get("properties", {})
+            with driver.session() as session:
+                result = session.run(f"CREATE (n:{label} $props) RETURN n", {"props": properties})
+                record = result.single()
+                if record:
+                    node = record["n"]
+                    return {"created": dict(node) if hasattr(node, 'items') else {"id": str(node.id), "labels": list(node.labels), "properties": dict(node)}}
+                return {"created": {}}
+    
+    elif tool == "get_next_instruction":
+        # Get next pending instruction
+        with driver.session() as session:
+            result = session.run("""
+                MATCH (i:Instruction {status: 'pending'})
+                RETURN i ORDER BY i.sequence LIMIT 1
+            """)
+            record = result.single()
+            return {"instruction": dict(record["i"]) if record else None}
+    
+    return {"error": "Unknown tool"}

mcp/requirements.txt

@@ -0,0 +1,5 @@
+fastapi==0.104.0
+uvicorn==0.24.0
+neo4j==5.14.0
+pydantic==2.4.0
+requests==2.31.0

neo4j/Dockerfile

@@ -0,0 +1,4 @@
+FROM neo4j:5.23.0
+ENV NEO4J_PLUGINS='["apoc"]'
+ENV NEO4J_apoc_export_file_enabled=true
+ENV NEO4J_apoc_import_file_enabled=true