{"id":31559565,"url":"https://github.com/samowolabi/chatrag-knowledge-graph","last_synced_at":"2026-04-15T07:35:26.180Z","repository":{"id":315914706,"uuid":"1061240703","full_name":"samowolabi/chatrag-knowledge-graph","owner":"samowolabi","description":"Intelligent RAG system with knowledge graphs. Processes documents → extracts entities \u0026 relationships → stores in Neo4j → enables semantic search \u0026 AI-powered Q\u0026A with citations. 🔗 Where documents become knowledge graphs. Advanced RAG system that turns your files into an intelligent, queryable knowledge base.","archived":false,"fork":false,"pushed_at":"2025-09-21T22:52:52.000Z","size":1593,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-05T01:54:44.193Z","etag":null,"topics":["graphrag","knowledge-graph","llm-agent","neo4j"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samowolabi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2025-09-21T14:27:01.000Z","updated_at":"2025-10-03T18:06:21.000Z","dependencies_parsed_at":"2025-09-21T16:28:02.768Z","dependency_job_id":"e5918a90-ad5f-4c76-ba6c-f56704705a50","html_url":"https://github.com/samowolabi/chatrag-knowledge-graph","commit_stats":null,"previous_names":["samowolabi/chatrag-knowledge-graph"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/samowolabi/chatrag-knowledge-graph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samowolabi%2Fchatrag-knowledge-graph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samowolabi%2Fchatrag-knowledge-graph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samowolabi%2Fchatrag-knowledge-graph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samowolabi%2Fchatrag-knowledge-graph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samowolabi","download_url":"https://codeload.github.com/samowolabi/chatrag-knowledge-graph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samowolabi%2Fchatrag-knowledge-graph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31831846,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T07:17:56.427Z","status":"ssl_error","status_checked_at":"2026-04-15T07:17:30.007Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["graphrag","knowledge-graph","llm-agent","neo4j"],"created_at":"2025-10-05T01:54:10.923Z","updated_at":"2026-04-15T07:35:26.174Z","avatar_url":"https://github.com/samowolabi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ChatRAG Knowledge Graph\n\n[![GitHub Repository](https://img.shields.io/badge/GitHub-chatrag--knowledge--graph-blue?logo=github)](https://github.com/samowolabi/chatrag-knowledge-graph)\n[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Neo4j](https://img.shields.io/badge/Neo4j-008CC1?logo=neo4j\u0026logoColor=white)](https://neo4j.com/)\n[![OpenAI](https://img.shields.io/badge/OpenAI-412991?logo=openai\u0026logoColor=white)](https://openai.com/)\n\n🧠 **Intelligent RAG system with knowledge graphs.** Processes documents → extracts entities \u0026 relationships → stores in Neo4j → enables semantic search \u0026 AI-powered Q\u0026A with citations.\n\nA comprehensive **Retrieval-Augmented Generation (RAG)** system that ingests documents, creates knowledge graphs, and provides intelligent querying capabilities using OpenAI embeddings and Neo4j graph database.\n\n## 🏗️ Architecture Overview\n\n```\nDocuments → Ingestion Pipeline → Neo4j Graph → Query Pipeline → AI Responses\n    ↓              ↓                ↓              ↓           ↓\n   PDF/TXT    Text Extraction   Chunks +      Semantic    Generated\n   Files      + Chunking       Entities +    Search +     Answers\n                               Relations     Graph RAG    with Sources\n```\n\n## 📋 Table of Contents\n\n- [Features](#-features)\n- [Repository Structure](#-repository-structure)\n- [System Architecture](#-system-architecture)\n- [Prerequisites](#-prerequisites)\n- [Installation](#-installation)\n- [Configuration](#-configuration)\n- [Data Ingestion Pipeline](#-data-ingestion-pipeline)\n- [Query Pipeline](#-query-pipeline)\n- [API Endpoints](#-api-endpoints)\n- [Usage Examples](#-usage-examples)\n- [Testing with Postman](#-testing-with-postman)\n- [Architecture Details](#-architecture-details)\n- [Troubleshooting](#-troubleshooting)\n\n## ✨ Features\n\n### 📊 Data Ingestion\n- **Multi-format document parsing** (PDF, TXT, DOC)\n- **Intelligent text chunking** using LangChain\n- **OpenAI embeddings generation** for semantic search\n- **Entity and relationship extraction** using AI\n- **Neo4j graph storage** for complex relationships\n\n### 🔍 Query System\n- **Semantic search** using vector similarity\n- **RAG (Retrieval-Augmented Generation)** with source citation\n- **Graph traversal** for entity relationships\n- **Hybrid search** combining semantic and keyword matching\n\n## 📁 Repository Structure\n\n```\nchatrag-knowledge-graph/\n├── src/\n│   ├── config/\n│   │   └── environment.ts          # Environment configuration\n│   ├── controllers/\n│   │   ├── ingestDataController.ts # Document ingestion endpoints\n│   │   └── queryDataController.ts  # Query and search endpoints\n│   ├── routes/\n│   │   ├── graphRagRoutes.ts       # Ingestion API routes\n│   │   └── queryRoutes.ts          # Query API routes\n│   ├── services/\n│   │   ├── graphService.ts         # Neo4j graph operations\n│   │   ├── langchainService.ts     # Text chunking with LangChain\n│   │   ├── neo4jService.ts         # Neo4j database connection\n│   │   ├── openaiService.ts        # OpenAI API integration\n│   │   └── textExtractor.ts        # Document parsing (PDF/TXT)\n│   ├── utils/\n│   │   ├── chunkText.ts           # Text processing utilities\n│   │   └── jsonToObjectParser.ts  # JSON parsing utilities\n│   └── index.ts                   # Express server entry point\n├── ChatRAG API.postman_collection.json  # Postman test collection\n├── package.json                   # Dependencies and scripts\n├── tsconfig.json                 # TypeScript configuration\n├── nodemon.json                  # Development server config\n└── README.md                     # This file\n```\n\n## 🏗️ System Architecture\n\n### High-Level Architecture\n\n```mermaid\ngraph TB\n    A[Documents] --\u003e B[Text Extractor]\n    B --\u003e C[LangChain Chunker]\n    C --\u003e D[OpenAI Embeddings]\n    D --\u003e E[Neo4j Graph DB]\n    \n    F[User Query] --\u003e G[OpenAI Embedding]\n    G --\u003e H[Neo4j Vector Search]\n    H --\u003e I[Graph Service]\n    I --\u003e J[OpenAI RAG]\n    J --\u003e K[AI Response with Citations]\n    \n    E --\u003e H\n```\n\n### Component Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                        Express.js Server                        │\n├─────────────────────────────────────────────────────────────────┤\n│                          Routes Layer                           │\n│  ┌─────────────────────┐    ┌─────────────────────────────────┐ │\n│  │   graphRagRoutes    │    │        queryRoutes              │ │\n│  │   (Ingestion)       │    │       (Search \u0026 RAG)           │ │\n│  └─────────────────────┘    └─────────────────────────────────┘ │\n├─────────────────────────────────────────────────────────────────┤\n│                       Controllers Layer                         │\n│  ┌─────────────────────┐    ┌─────────────────────────────────┐ │\n│  │ ingestDataController│    │   queryDataController          │ │\n│  │ • extractText       │    │   • semanticSearch             │ │\n│  │ • breakTextIntoChunks│   │   • ragQuery                   │ │\n│  │ • generateEmbeddings│    │   • (future: hybridSearch)     │ │\n│  │ • storeInGraph      │    │                                │ │\n│  │ • fullPipeline      │    │                                │ │\n│  └─────────────────────┘    └─────────────────────────────────┘ │\n├─────────────────────────────────────────────────────────────────┤\n│                        Services Layer                           │\n│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────┐ │\n│  │ textExtractor│ │langchainSvc  │ │ openaiService│ │graphSvc │ │\n│  │ • parsePDF   │ │ • splitText  │ │ • embedText  │ │• search │ │\n│  │ • parseTXT   │ │ • chunkText  │ │ • chatCompl  │ │• store  │ │\n│  │ • parseDoc   │ │              │ │ • embedBatch │ │• entity │ │\n│  └──────────────┘ └──────────────┘ └──────────────┘ └─────────┘ │\n│                              ┌──────────────┐                   │\n│                              │ neo4jService │                   │\n│                              │ • connection │                   │\n│                              │ • queries    │                   │\n│                              │ • transactions│                  │\n│                              └──────────────┘                   │\n├─────────────────────────────────────────────────────────────────┤\n│                         Data Layer                              │\n│              ┌─────────────────────────────────────┐            │\n│              │           Neo4j Graph Database       │            │\n│              │  ┌─────────────┐  ┌─────────────────┐│            │\n│              │  │   Chunks    │  │    Entities     ││            │\n│              │  │ • content   │  │ • name/type     ││            │\n│              │  │ • embedding │  │ • description   ││            │\n│              │  │ • metadata  │  │ • properties    ││            │\n│              │  └─────────────┘  └─────────────────┘│            │\n│              │           Relationships              │            │\n│              │         • CONTAINS                   │            │\n│              │         • RELATES_TO                 │            │\n│              │         • Custom types               │            │\n│              └─────────────────────────────────────┘            │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n### Service Responsibilities\n\n| Service | Purpose | Key Methods |\n|---------|---------|-------------|\n| **textExtractor** | Document parsing | `parseDocument()`, `extractMetadata()` |\n| **langchainService** | Text processing | `splitText()`, `createChunks()` |\n| **openaiService** | AI operations | `embedText()`, `chatCompletion()`, `embedTextsBatch()` |\n| **neo4jService** | Database layer | `executeQuery()`, `initialize()`, `testConnection()` |\n| **graphService** | Graph operations | `semanticSearchChunks()`, `storeExtractedNodesAndRelationships()` |\n\n## 🛠️ Prerequisites\n\n- **Node.js** 18+\n- **Neo4j Database** 4.0+ (with optional GDS library)\n- **OpenAI API Key**\n- **TypeScript** knowledge\n\n## 📦 Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/samowolabi/chatrag-knowledge-graph.git\ncd chatrag-knowledge-graph\n\n# Install dependencies\nnpm install\n\n# Set up environment variables\ncp .env.example .env\n```\n\n## ⚙️ Configuration\n\nCreate a `.env` file with the following variables:\n\n```env\n# Server Configuration\nPORT=3000\n\n# OpenAI Configuration\nOPENAI_API_KEY=your_openai_api_key_here\n\n# Neo4j Configuration\nNEO4J_URI=neo4j://localhost:7687\nNEO4J_USERNAME=neo4j\nNEO4J_PASSWORD=your_neo4j_password\n\n# Optional: Neo4j AuraDB (cloud)\n# NEO4J_URI=neo4j+s://your-instance.databases.neo4j.io\n```\n\n## 📥 Data Ingestion Pipeline\n\nThe ingestion system processes documents through multiple stages:\n\n### Pipeline Stages\n\n1. **Text Extraction** → Parse documents into structured text\n2. **Text Chunking** → Split content into manageable pieces\n3. **Embedding Generation** → Create vector representations\n4. **Chunk Storage** → Save chunks with embeddings to Neo4j\n5. **Entity Extraction** → Identify entities and relationships using AI\n6. **Graph Construction** → Store entities and relationships in Neo4j\n\n### Available Endpoints\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/graphrag/extract-text` | POST | Parse documents (PDF/TXT/DOC) |\n| `/graphrag/break-text` | POST | Split text into chunks |\n| `/graphrag/embed-chunks-with-openai` | POST | Generate embeddings |\n| `/graphrag/store-chunks-embeddings-graph` | POST | Store chunks in Neo4j |\n| `/graphrag/extract-document-nodes-relationships-graph` | POST | Extract entities/relationships |\n| `/graphrag/store-extracted-nodes-relationships-graph` | POST | Store graph data |\n| `/graphrag/process-document-pipeline` | POST | **Full end-to-end processing** |\n\n### Individual Steps Usage\n\n#### 1. Extract Text from Document\n```bash\ncurl -X POST http://localhost:3000/graphrag/extract-text \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"filePath\": \"/path/to/document.pdf\",\n    \"type\": \"pdf\"\n  }'\n```\n\n#### 2. Break Text into Chunks\n```bash\ncurl -X POST http://localhost:3000/graphrag/break-text \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"text\": \"Your document content here...\"\n  }'\n```\n\n#### 3. Generate Embeddings\n```bash\ncurl -X POST http://localhost:3000/graphrag/embed-chunks-with-openai \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"chunks\": [\n      {\"id\": \"chunk_1\", \"content\": \"First chunk content\"},\n      {\"id\": \"chunk_2\", \"content\": \"Second chunk content\"}\n    ]\n  }'\n```\n\n#### 4. Store Chunks with Embeddings\n```bash\ncurl -X POST http://localhost:3000/graphrag/store-chunks-embeddings-graph \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"chunks\": [\n      {\n        \"id\": \"chunk_1\",\n        \"content\": \"Content here\",\n        \"embedding\": [0.1, 0.2, 0.3, ...]\n      }\n    ]\n  }'\n```\n\n#### 5. Full Pipeline (Recommended)\n```bash\ncurl -X POST http://localhost:3000/graphrag/process-document-pipeline \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"filePath\": \"/path/to/document.pdf\",\n    \"type\": \"pdf\"\n  }'\n```\n\n## 🔍 Query Pipeline\n\nThe query system provides multiple ways to retrieve and generate responses:\n\n### Available Query Types\n\n| Endpoint | Method | Purpose |\n|----------|--------|---------|\n| `/query/semantic` | POST | Vector similarity search |\n| `/query/rag` | POST | AI-generated answers with sources |\n\n### Query Examples\n\n#### Semantic Search\nFind similar content using vector embeddings:\n\n```bash\ncurl -X POST http://localhost:3000/query/semantic \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": \"artificial intelligence applications\",\n    \"limit\": 5\n  }'\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"query\": \"artificial intelligence applications\",\n    \"results\": [\n      {\n        \"id\": \"chunk_1\",\n        \"content\": \"AI applications in healthcare include...\",\n        \"similarity\": 0.89,\n        \"score\": 0.89\n      }\n    ],\n    \"count\": 5\n  }\n}\n```\n\n#### RAG Query\nGet AI-generated answers with source citations:\n\n```bash\ncurl -X POST http://localhost:3000/query/rag \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": \"What are the benefits of machine learning?\",\n    \"limit\": 3,\n    \"includeContext\": true\n  }'\n```\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"query\": \"What are the benefits of machine learning?\",\n    \"answer\": \"Based on the provided context, machine learning offers several key benefits [1][2]: automation of complex tasks, pattern recognition in large datasets...\",\n    \"sources\": [\n      {\n        \"id\": \"chunk_1\",\n        \"content\": \"Machine learning enables automated...\",\n        \"similarity\": 0.92,\n        \"sourceNumber\": 1\n      }\n    ],\n    \"metadata\": {\n      \"chunksRetrieved\": 3,\n      \"avgSimilarity\": 0.87\n    }\n  }\n}\n```\n\n## 🚀 Quick Start\n\n### 1. Start the Server\n```bash\nnpm run dev\n```\n\n### 2. Ingest Your First Document\n```bash\ncurl -X POST http://localhost:3000/graphrag/process-document-pipeline \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"filePath\": \"/path/to/your/document.pdf\",\n    \"type\": \"pdf\"\n  }'\n```\n\n### 3. Query Your Data\n```bash\ncurl -X POST http://localhost:3000/query/rag \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": \"What is this document about?\",\n    \"limit\": 5\n  }'\n```\n\n## 📊 Neo4j Graph Schema\n\n### Node Types\n- **Chunk**: Document fragments with embeddings\n- **Entity**: Extracted entities (PERSON, ORGANIZATION, LOCATION, CONCEPT)\n\n### Relationship Types\n- **CONTAINS**: Document contains entities\n- **RELATES**: Entity relationships\n- **Custom types**: Based on extracted relationships\n\n### Example Cypher Queries\n```cypher\n// View all chunks\nMATCH (c:Chunk) RETURN c LIMIT 10\n\n// Find entities of a specific type\nMATCH (e:PERSON) RETURN e.name, e.description\n\n// Explore relationships\nMATCH (a)-[r]-\u003e(b) RETURN a.name, type(r), b.name LIMIT 10\n```\n\n## 🧪 Testing with Postman\n\n### Import Collection\n1. **Download**: [`ChatRAG API.postman_collection.json`](./ChatRAG%20API.postman_collection.json)\n2. **Import to Postman**: File → Import → Upload the JSON file\n3. **Set Environment**: Update `base_url` variable to `http://localhost:3000`\n\n### Available Test Collections\n\nThe Postman collection includes comprehensive tests for:\n\n#### **📥 Ingestion Endpoints**\n- ✅ Health Check\n- ✅ Extract Text from Document  \n- ✅ Break Text into Chunks\n- ✅ Generate Embeddings\n- ✅ Store Chunks \u0026 Embeddings\n- ✅ Extract Entities \u0026 Relationships\n- ✅ Store Graph Data\n- ✅ **Full Pipeline Test** (End-to-end)\n\n#### **🔍 Query Endpoints**\n- ✅ Semantic Search\n- ✅ RAG Query with Citations\n- ✅ (Future: Hybrid Search, Entity Search)\n\n### Test Sequence\n1. **Health Check** → Verify server is running\n2. **Full Pipeline** → Process a sample document\n3. **Semantic Search** → Test vector search\n4. **RAG Query** → Test AI response generation\n\n### Sample Test Data Included\n- Realistic document content examples\n- Pre-configured embeddings for testing\n- Entity/relationship samples\n- Various query examples\n\n## 🔧 Architecture Details\n\n### Request/Response Flow\n\n#### Ingestion Flow\n```\n1. POST /graphrag/process-document-pipeline\n   ↓\n2. ingestDataController.processDocumentPipeline()\n   ↓\n3. textExtractor.parseDocument() → Document object\n   ↓\n4. langchainService.splitText() → Text chunks\n   ↓\n5. openaiService.embedTextsBatch() → Vector embeddings\n   ↓\n6. graphService.storeBatchChunksWithEmbeddings() → Neo4j storage\n   ↓\n7. graphService.extractEntitiesAndRelationshipsFromText() → AI extraction\n   ↓\n8. graphService.storeExtractedNodesAndRelationships() → Graph relationships\n```\n\n#### Query Flow\n```\n1. POST /query/rag\n   ↓\n2. queryDataController.ragQuery()\n   ↓\n3. openaiService.embedText() → Query embedding\n   ↓\n4. graphService.semanticSearchChunks() → Similar chunks\n   ↓\n5. Build context from retrieved chunks\n   ↓\n6. openaiService.chatCompletion() → AI response\n   ↓\n7. Return answer with source citations\n```\n\n### Core Services\n\n#### TextExtractor Service\n- **Purpose**: Multi-format document parsing\n- **Formats**: PDF, TXT, DOC files\n- **Methods**: \n  - `parseDocument(filePath, type)` - Main parsing method\n  - `extractMetadata()` - Document metadata extraction\n- **Dependencies**: pdf-parse, fs\n\n#### LangChain Service\n- **Purpose**: Intelligent text chunking\n- **Features**: Configurable chunk size, overlap handling\n- **Methods**:\n  - `splitText(text)` - Split text into chunks\n  - `createChunks()` - Create chunk objects with IDs\n- **Dependencies**: LangChain TextSplitter\n\n#### OpenAI Service\n- **Purpose**: AI operations and embeddings\n- **Models**: text-embedding-ada-002, gpt-4\n- **Methods**:\n  - `embedText(text)` - Single text embedding\n  - `embedTextsBatch(texts[])` - Batch embedding processing\n  - `chatCompletion(messages, options)` - AI response generation\n- **Features**: Automatic retry, error handling, batch optimization\n\n#### Neo4j Service\n- **Purpose**: Database connection and query execution\n- **Features**: Connection pooling, transaction management\n- **Methods**:\n  - `initialize()` - Database setup\n  - `executeQuery(query, params)` - Query execution\n  - `testConnection()` - Health check\n- **Configuration**: Supports local and AuraDB cloud instances\n\n#### Graph Service\n- **Purpose**: High-level graph operations\n- **Features**: Vector search, entity management, relationship handling\n- **Methods**:\n  - `semanticSearchChunks(embedding, limit)` - Vector similarity search\n  - `storeExtractedNodesAndRelationships()` - Graph data storage\n  - `extractEntitiesAndRelationshipsFromText()` - AI-powered extraction\n- **Fallbacks**: Manual cosine similarity if GDS not available\n\n### Data Models\n\n#### Chunk Model\n```typescript\ninterface Chunk {\n  id: string;\n  content: string;\n  embedding: number[];\n  metadata: Record\u003cstring, any\u003e;\n}\n```\n\n#### Entity Model\n```typescript\ninterface GraphEntity {\n  id: string;\n  name: string;\n  type: string; // PERSON, ORGANIZATION, LOCATION, CONCEPT\n  description: string;\n  properties: Record\u003cstring, any\u003e;\n}\n```\n\n#### Relationship Model\n```typescript\ninterface GraphRelationship {\n  id: string;\n  source: string;\n  target: string;\n  type: string; // RELATES_TO, WORKS_FOR, etc.\n  description: string;\n  properties: Record\u003cstring, any\u003e;\n}\n```\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n#### Neo4j Connection Failed\n```bash\n# Check Neo4j status\nneo4j status\n\n# Start Neo4j\nneo4j start\n\n# Verify credentials in .env file\n```\n\n#### OpenAI API Errors\n```bash\n# Verify API key\necho $OPENAI_API_KEY\n\n# Check API quota and billing\n```\n\n#### Vector Search Issues\nIf GDS functions fail, the system automatically falls back to manual cosine similarity calculation.\n\n#### Memory Issues with Large Documents\n- Reduce chunk size in LangChain configuration\n- Process documents in smaller batches\n- Increase Node.js memory limit: `node --max-old-space-size=4096`\n\n### Debug Mode\n```bash\n# Enable detailed logging\nDEBUG=* npm run dev\n```\n\n### Health Check\n```bash\ncurl http://localhost:3000/\n```\n\n## 📈 Performance Optimization\n\n### Neo4j Optimization\n```cypher\n// Create vector index for faster similarity search\nCREATE VECTOR INDEX chunk_embeddings FOR (c:Chunk) ON (c.embedding)\nOPTIONS {indexConfig: {`vector.dimensions`: 1536, `vector.similarity_function`: 'cosine'}}\n\n// Create text index for keyword search\nCREATE TEXT INDEX chunk_content FOR (c:Chunk) ON (c.content)\n```\n\n### Batch Processing\n- Process documents in batches of 10-50 chunks\n- Use Promise.all for parallel embedding generation\n- Implement pagination for large query results\n\n## 🤝 Contributing\n\n### Development Setup\n```bash\n# Clone the repository\ngit clone https://github.com/samowolabi/chatrag-knowledge-graph.git\ncd chatrag-knowledge-graph\n\n# Install dependencies\nnpm install\n\n# Set up environment\ncp .env.example .env\n\n# Start development server\nnpm run dev\n```\n\n### Adding New Features\n\n#### Adding New Query Types\n1. Implement controller in `src/controllers/queryDataController.ts`\n2. Add route in `src/routes/queryRoutes.ts`\n3. Update Postman collection\n4. Update this README\n\n#### Adding New Document Types\n1. Extend `textExtractor` service in `src/services/textExtractor.ts`\n2. Update type definitions\n3. Test with sample documents\n4. Add tests to Postman collection\n\n#### Adding New Services\n1. Create service file in `src/services/`\n2. Implement proper error handling\n3. Add to dependency injection in controllers\n4. Document in README architecture section\n\n### Code Style\n- TypeScript strict mode\n- Async/await pattern\n- Proper error handling with try/catch\n- Descriptive variable and function names\n- JSDoc comments for public methods\n\n### Pull Request Process\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Implement changes with proper testing\n4. Update documentation (README, Postman collection)\n5. Commit changes (`git commit -m 'Add amazing feature'`)\n6. Push to branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **OpenAI** for powerful embeddings and language models\n- **Neo4j** for graph database capabilities  \n- **LangChain** for text processing utilities\n- **TypeScript** community for excellent tooling\n\n---\n\n**Repository**: [https://github.com/samowolabi/chatrag-knowledge-graph](https://github.com/samowolabi/chatrag-knowledge-graph)\n\n**Happy querying! 🚀**\n\nFor support, please check the [troubleshooting section](#-troubleshooting) or create an issue in the repository.# chatrag-knowledge-graph\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamowolabi%2Fchatrag-knowledge-graph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamowolabi%2Fchatrag-knowledge-graph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamowolabi%2Fchatrag-knowledge-graph/lists"}