{"id":51547240,"url":"https://github.com/iamvisheshsrivastava/graphrag-lab","last_synced_at":"2026-07-09T19:31:07.700Z","repository":{"id":364268001,"uuid":"1267174674","full_name":"iamvisheshsrivastava/graphrag-lab","owner":"iamvisheshsrivastava","description":"Domain-specific knowledge graph for automotive parking requirements with verifiable GraphRAG queries - SAE L2 ADAS parking functions (APA, RPA, Summon). FastAPI + React + Cytoscape.js.","archived":false,"fork":false,"pushed_at":"2026-07-06T19:41:25.000Z","size":101,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-06T20:14:50.975Z","etag":null,"topics":["adas","fastapi","graphrag","iso-26262","knowledge-graph","ontology","parking","react","requirements-engineering","sae-j3016"],"latest_commit_sha":null,"homepage":"https://graphrag-lab.vercel.app","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iamvisheshsrivastava.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-12T09:41:05.000Z","updated_at":"2026-07-06T19:41:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/iamvisheshsrivastava/graphrag-lab","commit_stats":null,"previous_names":["iamvisheshsrivastava/graphrag-lab"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/iamvisheshsrivastava/graphrag-lab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamvisheshsrivastava%2Fgraphrag-lab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamvisheshsrivastava%2Fgraphrag-lab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamvisheshsrivastava%2Fgraphrag-lab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamvisheshsrivastava%2Fgraphrag-lab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iamvisheshsrivastava","download_url":"https://codeload.github.com/iamvisheshsrivastava/graphrag-lab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamvisheshsrivastava%2Fgraphrag-lab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35311290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-09T02:00:07.329Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adas","fastapi","graphrag","iso-26262","knowledge-graph","ontology","parking","react","requirements-engineering","sae-j3016"],"created_at":"2026-07-09T19:31:02.939Z","updated_at":"2026-07-09T19:31:07.688Z","avatar_url":"https://github.com/iamvisheshsrivastava.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GraphRAG — Automotive Requirements Knowledge Graph\n\nA research tool for building **LLM-powered, domain-specific knowledge graphs** from automotive requirements text and querying them using **Graph-Retrieval-Augmented-Generation (GraphRAG)**.\n\nTargets ADAS and parking function requirements (SAE Level 2) with full traceability, consistency verification, natural language querying, and persistent graph storage via Neo4j AuraDB.\n\nBuilt as a portfolio project supporting a PhD application in AI-based GraphRAG for automotive functions.\n\n---\n\n## Live Demo\n\n| Layer | URL |\n|---|---|\n| Frontend (Vercel) | https://graphrag-lab.vercel.app |\n| Backend API (Render) | https://graphrag-lab-api.onrender.com |\n| API Docs (Swagger) | https://graphrag-lab-api.onrender.com/docs |\n\n\u003e **Note:** The backend runs on Render's free tier and may take ~50 seconds to wake from cold start.\n\n---\n\n## Architecture\n\n```\ngraphrag-lab/\n├── backend/\n│   ├── main.py                       # FastAPI app entrypoint + CORS config\n│   ├── .python-version               # Pins Python 3.11.0 for Render\n│   ├── models/schemas.py             # Pydantic data models\n│   ├── services/\n│   │   ├── ontology.py               # Automotive parking ontology (concepts, relations, rules)\n│   │   ├── llm_extractor.py          # LLM-based entity + relation extraction (gemini-2.5-flash)\n│   │   ├── graph_builder.py          # KG construction: LLM extraction → ontology backbone\n│   │   ├── neo4j_service.py          # Neo4j AuraDB persistence + Cypher query runner\n│   │   └── rag_engine.py             # GraphRAG = BFS traversal + LLM generation\n│   ├── routers/\n│   │   ├── requirements.py           # CRUD + batch verification endpoints\n│   │   ├── graph.py                  # Build, inspect, Neo4j status endpoints\n│   │   └── query.py                  # GraphRAG query + Cypher passthrough endpoints\n│   └── data/\n│       └── sample_requirements.json  # 18 rich ADAS parking requirements (SYS/APA/RPA/SUM/SEN/HMI/VER)\n│\n└── frontend/\n    ├── src/\n    │   ├── App.jsx                   # Root layout + routing\n    │   ├── components/\n    │   │   ├── Sidebar.jsx           # Navigation (6 tabs)\n    │   │   ├── RequirementsPanel.jsx # Load sample data or upload JSON/CSV\n    │   │   ├── GraphViewer.jsx       # Cytoscape.js interactive graph canvas\n    │   │   ├── QueryPanel.jsx        # GraphRAG natural language query + answer\n    │   │   ├── VerificationPanel.jsx # Rule-based ISO 26262 / SAE J3016 checks\n    │   │   ├── TraceabilityPanel.jsx # Upstream/downstream dependency explorer\n    │   │   └── CypherConsole.jsx     # Live Cypher query editor against Neo4j AuraDB\n    │   └── lib/api.js                # Axios API client + all endpoint wrappers\n    └── package.json\n```\n\n---\n\n## Features\n\n### 1. LLM-Based Knowledge Graph Construction\n\nGraph building is a two-step pipeline:\n\n**Step 1 — LLM extraction** (`llm_extractor.py`)\n- Sends the full requirements batch to `google/gemini-2.5-flash` via OpenRouter in a single structured prompt\n- Returns strict JSON: `{\"entities\": [...], \"relations\": [...]}`\n- Temperature = 0.0 for near-deterministic output\n- Entity types: `sensor | function | concept | actor | safety_level | standard | system`\n- Relation types: `mentions | depends_on | derives_from | implements | governed_by | conflicts_with | refines | part_of | uses | connected_to`\n- Falls back to keyword matching if no API key is set\n\n**Step 2 — Ontology backbone** (`graph_builder.py`)\n- Merges LLM output with deterministic ontology edges defined in `ontology.py`\n- Scans requirement text for explicit cross-references (e.g. `APA-001`) and adds `depends_on` edges\n- Validates DAG property; topological ordering enables certifiable dependency analysis\n\n### 2. Neo4j AuraDB Integration\n\n- After every graph build, the full graph is persisted to Neo4j AuraDB via Cypher `MERGE`\n- Node labels: `:Requirement` and `:Entity`\n- In-memory NetworkX DiGraph is used for fast BFS traversal during GraphRAG retrieval\n- Neo4j failure is non-blocking — API response is not affected if Neo4j is down\n\n### 3. Cypher Console\n\n- Live query editor in the UI with 6 example Cypher queries pre-loaded\n- Shows Neo4j connection status + node count badge\n- Results rendered as a sortable table (columns + rows)\n- Ctrl+Enter to run — calls `POST /query/cypher` on the backend\n\n### 4. GraphRAG Query Engine\n\n- Top-k node retrieval by TF-IDF-style keyword scoring against the graph\n- BFS context expansion (depth 2) around seed nodes\n- Graph context serialized into the LLM prompt alongside the question\n- Answer is grounded in cited graph nodes — every response includes the traversal path\n- Model: `google/gemini-2.5-flash` via OpenRouter\n\n### 5. Requirements Input\n\n- **Load sample dataset** — 18 rich automotive requirements covering SYS, APA, RPA, SUM, SEN, HMI, VER domains\n- **Upload your own** — supports `.json` (array of requirement objects) and `.csv` files\n\n### 6. Verification Engine\n\nRule-based, deterministic checks (no LLM required):\n- SAE L2 requirements must include a driver monitoring obligation\n- Safety requirements must reference an ISO 26262 ASIL level\n- Performance requirements must contain quantitative thresholds\n- Ambiguous language detection (`appropriate`, `adequate`, `as needed`, `if possible`, …)\n\n### 7. Traceability Matrix\n\n- Per-requirement upstream and downstream link explorer\n- Link types: `depends_on`, `derives_from`, `implements`, `conflicts_with`\n- Output suitable for ISO 26262 Part 8 traceability evidence\n\n---\n\n## Quick Start\n\n### Backend\n\n```bash\ncd backend\npython -m venv .venv \u0026\u0026 source .venv/bin/activate   # Windows: .venv\\Scripts\\activate\npip install -r requirements.txt\ncp .env.example .env   # add your keys\nuvicorn main:app --reload --port 8000\n```\n\nAPI docs: http://localhost:8000/docs\n\n### Frontend\n\n```bash\ncd frontend\nnpm install\nnpm run dev\n```\n\nUI: http://localhost:5173\n\n### Walkthrough\n\n1. **Requirements** → **Load Sample Dataset** (18 ADAS parking requirements)\n2. **Knowledge Graph** → **Generate Graph** (LLM extracts entities + relations)\n3. Click any node to inspect its properties and ontology links\n4. **GraphRAG Query** → ask natural language questions; see the traversal path used\n5. **Verification** → run ISO 26262 / SAE J3016 consistency checks\n6. **Traceability** → explore upstream/downstream dependency chains\n7. **Cypher Console** → run live Cypher queries against Neo4j AuraDB\n\n---\n\n## Environment Variables\n\nCreate `backend/.env`:\n\n```env\n# Required for LLM-based graph extraction and GraphRAG queries\nOPENROUTER_API_KEY=sk-or-v1-...\n\n# Optional: override the model (default: google/gemini-2.5-flash)\nOPENROUTER_MODEL=google/gemini-2.5-flash\n\n# Required for Neo4j AuraDB persistence and Cypher Console\nNEO4J_URI=neo4j+s://xxxxxxxx.databases.neo4j.io\nNEO4J_USERNAME=neo4j\nNEO4J_PASSWORD=your-password\n\n# Or use OpenAI directly (model switches to gpt-4o automatically)\nOPENAI_API_KEY=sk-...\n```\n\nThe root endpoint (`GET /`) reports `\"llm_enabled\": true / false` and `\"llm_provider\": \"openrouter\" | \"openai\" | \"none\"`.\n\nWithout any API key, the system falls back to keyword-based graph extraction and template-based query answers — fully functional for offline/demo use.\n\n---\n\n## Model Choice\n\n| Model | Provider | Cost | Used for |\n|---|---|---|---|\n| `google/gemini-2.5-flash` | OpenRouter | ~$0.15/1M tokens | Graph extraction + GraphRAG queries |\n| `gpt-4o` | OpenAI | ~$2.50/1M tokens | Auto-selected if only `OPENAI_API_KEY` is set |\n\nAt typical demo usage (10 graph builds + 50 queries), total cost ≈ **$0.01–0.02**.\n\n---\n\n## Design Decisions\n\n| Decision | Rationale |\n|---|---|\n| LLM extraction at temperature=0.0 | Near-deterministic graph structure; consistent across runs |\n| Ontology backbone merged after LLM | Guarantees domain concepts are always present regardless of LLM output |\n| Dual storage: NetworkX + Neo4j | NetworkX for fast in-process BFS; Neo4j for durable Cypher queries |\n| Rule-based verification (no ML) | Certifiable, auditable evidence for ISO 26262 functional safety |\n| Cytoscape.js for visualization | Handles large graphs client-side; no server render needed |\n| OpenRouter as LLM gateway | Single API key accesses 100+ models; easy model switching via env var |\n| Render free tier + Vercel CDN | Zero-cost hosting for portfolio demo |\n\n---\n\n## Roadmap\n\n- [x] LLM-based entity + relation extraction\n- [x] Neo4j AuraDB integration for persistent Cypher-queryable graph storage\n- [x] Cypher Console in UI\n- [x] File upload for custom requirements (JSON / CSV)\n- [ ] Reload graph from Neo4j on service restart (currently requires manual rebuild)\n- [ ] SHACL / SPARQL constraint validation layer\n- [ ] Export to ReqIF format for integration with DOORS / Polarion\n- [ ] Multi-document ingestion (PDF, DOCX, Excel requirement sheets)\n- [ ] Conflict detection via constraint propagation and SAT solving\n- [ ] Docker Compose for one-command local deployment\n\n---\n\n## References\n\n- SAE J3016: *Taxonomy and Definitions for Terms Related to Driving Automation Systems* (2021)\n- ISO 26262: *Road vehicles — Functional safety* (2018)\n- ISO 21448: *Road vehicles — Safety of the Intended Functionality (SOTIF)* (2022)\n- Edge, D. et al. (2024). *From Local to Global: A Graph RAG Approach to Query-Focused Summarization.* arXiv:2404.16130\n- Baader, F. et al. (2003). *The Description Logic Handbook.* Cambridge University Press.\n- Pan, J.Z. et al. (2023). *Unifying Large Language Models and Knowledge Graphs: A Roadmap.* IEEE TKDE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamvisheshsrivastava%2Fgraphrag-lab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiamvisheshsrivastava%2Fgraphrag-lab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamvisheshsrivastava%2Fgraphrag-lab/lists"}