Status: Work In Progress (Personal Exploratory PoC)

Lucid Lineage GraphRAG MCP

Lucid Lineage is a personal proof-of-concept (PoC) and exploratory project demonstrating the practical application of agentic AI and Knowledge GraphRAG (Retrieval-Augmented Generation) technology. It explores how an autonomous orchestration framework can map mock infrastructure dependencies and evaluate data boundary anomalies within a simulated sandbox environment.

Project Summary

This project evaluates how a Neo4j knowledge graph can be paired with LLM-driven reasoning to trace simulated data flows and analyze mock compliance constraints (such as illustrative GDPR, SOX, or CCPA frameworks). It leverages a LangChain-orchestrated reasoning agent to traverse an experimental graph database, test deterministic graph-querying tools, and log simulated audit findings back into the database for analysis.

Codebase Guide

The project serves as an exploratory GraphRAG architecture pattern: a LangChain agent (backed by Google Gemini) reasons over a mock Neo4j knowledge graph, interacts with deterministic graph tools, and logs simulated findings back to the graph environment. At runtime, a presentation entry point calls run_trace(), which lets the agent evaluate and select appropriate graph tools; those tools execute parameterized Cypher through a singleton driver against the Neo4j instance.

app.py / main.py   →   run_trace()          →   Gemini selects tools
(presentation)         (src/agent.py)            │
                                                 src/graph_tools.py  →  src/db.py  →  Neo4j Aura

A core principle is single-source-of-truth: all Cypher lives in src/graph_tools.py (shared by the agent and the MCP server); all model configuration lives in src/llm.py (shared by the UI and the CLI).

Presentation layer

• app.py — Streamlit web UI ("Forensic Workspace"): manages session state, the access-control sidebar (IAM role / clearance boundary), chat rendering, and per-prompt calls to run_trace().
• main.py — CLI "Forensic Terminal": builds the live agent and loops over audit queries → run_trace() → prints results (with a Windows UTF-8 console guard).

Orchestration layer

• src/agent.py — The core. Defines the six LangChain @tool wrappers, the Neo4j-backed chat memory (get_graph_memory / save_graph_memory, including primitive-serialization normalization), and run_trace() — the main pipeline (bounded history → role/clearance-aware prompt → create_tool_calling_agent + AgentExecutor with iteration/time caps → normalized, persisted answer). Falls back to a mock response when no LLM is supplied.
• src/llm.py — LLM factory & provider toggle: builds either Google Gemini (gemini-3.5-flash) or OpenAI (gpt-4o-mini), selected via LLM_PROVIDER in .env (or the DEFAULT_PROVIDER constant). Single source of truth for model config.

Data access layer

• src/graph_tools.py — The unified Cypher query layer; all Neo4j business logic. Six tools: asset-lineage trace, co-location "blast radius", compliance-boundary check, write audit finding, retrieve past findings, and the cross-boundary leak scan. All queries are parameterized (injection-safe).
• src/db.py — Thread-safe singleton Neo4j driver (bounded connection pool + acquisition timeout), plus connectivity verification and graceful shutdown.
• src/graph_admin.py — Graph administration & health: reseeds the graph from the canonical Cypher, detects drift from the seeded baseline (SHA-256 fingerprint), and computes the dashboard security "traffic light".

Tool bridging & observability

• src/mcp_server.py — FastMCP server exposing the same six tools via the Model Context Protocol, so external MCP clients use identical Cypher and schema.
• src/telemetry.py — OpenTelemetry instrumentation; the trace_tool decorator records spans, non-secret arguments, latency, and success/failure for run_trace and each graph tool.
• src/__init__.py — Package docstring / module map.

Data & persistence

• data/init_graph.cypher — Enterprise graph seed script: compliance boundaries, compute nodes, data assets, service accounts, their lineage relationships, and intentional compliance violations used as test fixtures.
• seed_db.py — Loads and executes data/init_graph.cypher to provision or reset the graph.

Diagnostics

• check_env.py — Verifies Neo4j Aura connectivity and authentication from .env.
• check_models.py — Lists the Gemini models the configured API key can access.

Testing & validation

• TESTCASES.md — The three canonical scenarios (each a primary + follow-up query).
• eval/run_testcases.py — Automated harness that runs the scenarios (primary + follow-up on a shared session to exercise memory) and captures responses, tools invoked, timing, and errors.
• TESTCASES_LOG.md — Audit log of test-run results (pass/fail status and any trace errors).

Infrastructure as Code (planned deployment — see ARCHITECTURE.md, Milestone C)

• infra/main.tf — Terraform: Vertex AI endpoint, a (mock) Neo4j host, and a Cloud Run service for the Streamlit UI (region europe-west2 for sovereignty).
• infra/iam.tf — Terraform: zero-trust IAM — custom agent role, service account, and role bindings.
• infra/variables.tf — Terraform input variables (project_id, region, streamlit_service_name).

Configuration & documentation

• .env — Secrets/config: Neo4j credentials, GOOGLE_API_KEY, PROJECT_ID (gitignored).
• requirements.txt — Python dependencies, aligned to the code's actual direct imports.
• ARCHITECTURE.md: Core system architecture, target state, and graph schema.
• CLAUDE.md: System instructions for the Claude Code autonomous agent (rules, priorities, working-directory confinement).
• CLEANUP_LOG.md: Housekeeping audit trail (what was reviewed/removed and why).

Graph schema (quick reference)

• Nodes: Data_Asset, Compute_Node, Compliance_Boundary, Service_Account, Audit_Finding (plus Session / Message for chat memory).
• Edges: STORED_ON, REPLICATED_TO, GOVERNED_BY, HAS_ACCESS, HAS_AUDIT_RECORD.

Setup Instructions

Create a .env file in the root directory:

NEO4J_URI=neo4j+s://<your-db-id>.databases.neo4j.io
NEO4J_USER=neo4j
NEO4J_PASSWORD=<your-password>
GOOGLE_API_KEY=<your-gemini-api-key>

Then install dependencies, seed the graph, and launch:

pip install -r requirements.txt
python seed_db.py            # provision / reset the Neo4j graph
streamlit run app.py         # web UI   (or:  python main.py  for the CLI)

Verify connectivity at any time with python check_env.py and python check_models.py.