🌐 Marathi WordNet & Indic GraphRAG Platform

An enterprise-grade Semantic Knowledge Graph, Rule-Based Morphological Analyzer, and Indic GraphRAG Engine built for the Marathi language (83M+ speakers). The platform bridges symbolic lexical semantics and generative AI, eliminating Large Language Model (LLM) hallucinations through deterministic multi-hop graph retrieval and ontological grounding.

---

📌 Executive Summary & Key Highlights

• 🕸️ Rich 12-Relation Knowledge Graph: Ingested 1,002 curated Marathi lemmas and 1,428+ semantic relations across 10+ core domains (Agriculture, Medicine/Body, Professions, Emotions, Nature, Actions, Food).
• 🔤 Morphological Disambiguation Engine: Sub-millisecond suffix-stripping engine with Unicode NFC normalization and oblique stem transformation (शेतकऱ्यांनी $\to$ शेतकरी), strictly validated against Neo4j to guarantee 0% false-positive candidate generation.
• 📐 Graph-Native Semantic Similarity: Pushes down the Wu-Palmer (WUP) metric directly into Cypher queries, computing Least Common Subsumer (LCS) tree depths over taxonomy hierarchies without in-memory BFS/DFS bottlenecks.
• 🤖 Indic GraphRAG & Agentic Tool Layer: Python autonomous agent exposing WordNet APIs via OpenAPI tool schemas to ground LLM generation in factual knowledge graphs.
• 🎨 Modern Interactive UI: React 19 + Vite frontend featuring dual Dictionary & Semantic Compare modes, dynamic context example parsing (Meaning | उदा: Example), and visual relationship exploration.
• 🐳 Cloud-Ready & Secure Containerization: Multi-stage Docker build running non-root Alpine JRE with orchestrated Docker Compose healthchecks.

---

🏗️ System Architecture

+------------------------------------------------------------------------------------+
|                                   CLIENT LAYER                                     |
|         +---------------------------+         +----------------------------+       |
|         |    React 19 / Vite UI     |         |   Indic GraphRAG Agent     |       |
|         | (Dictionary & Comparison) |         | (Autonomous Tool-Calling)  |       |
+---------+-------------+-------------+---------+-------------+--------------+-------+
                        |                                     |
                        | REST / JSON                         | REST / JSON
                        v                                     v
+------------------------------------------------------------------------------------+
|                        SPRING BOOT 3.2.3 REST API LAYER                            |
|                                                                                    |
|   +------------------------------------+   +-----------------------------------+   |
|   |          WordController            |   |         WordNetController         |   |
|   |  GET /api/words/lookup/{word}      |   |  POST /api/wordnet/bulk           |   |
|   |  GET /api/words/morphology/{word}  |   |  POST /api/wordnet/relation       |   |
|   |  GET /api/words/similarity         |   |  DELETE /api/wordnet/clearAll     |   |
|   +-----------------+------------------+   +-----------------+-----------------+   |
+---------------------|----------------------------------------|---------------------+
                      v                                        v
+------------------------------------------------------------------------------------+
|                             CORE ENGINE / SERVICE LAYER                            |
|                                                                                    |
|   +------------------------------------+   +-----------------------------------+   |
|   |         MorphologyService          |   |         SimilarityService         |   |
|   |  - Unicode NFC Normalization       |   |  - Least Common Subsumer (LCS)    |   |
|   |  - Longest-Suffix Strip Rule Engine|   |  - Cypher-Native Wu-Palmer Score  |   |
|   |  - Database Validation Gate        |   |  - Path Distance Resolution       |   |
|   +-----------------+------------------+   +-----------------+-----------------+   |
+---------------------|----------------------------------------|---------------------+
                      v                                        v
+------------------------------------------------------------------------------------+
|                        DATA ACCESS LAYER & GRAPH STORAGE                           |
|                                                                                    |
|   +----------------------------------------------------------------------------+   |
|   |       Spring Data Neo4j (SDN) & Neo4j 5.18.0 Labeled Property Graph        |   |
|   |                                                                            |   |
|   |   (:Word) ---[:VARIANT_OF]---> (:Lemma) ---[:BELONGS_TO]---> (:Synset)    |   |
|   |                                                                  |  |      |   |
|   |   [:IS_A / :PART_OF / :CAUSATION / :TROPONYM / :ANTONYM] <-------+  +-->   |   |
|   +----------------------------------------------------------------------------+   |
+------------------------------------------------------------------------------------+

---

🧩 Ontological Relationship Types

The knowledge graph supports 12 comprehensive linguistic relation types:

Relationship	Type	Linguistic Description	Example in Marathi WordNet
SYNONYM	Lexical/Sense	Interchangeable concepts	पाणी $\leftrightarrow$ जल / नीर
ANTONYM	Lexical	Direct conceptual opposites	प्रकाश $\leftrightarrow$ अंधार
HYPERNYM (IS_A)	Taxonomic	Broader / Superordinate category	शेतकरी $\to$ व्यवसाय करणारी व्यक्ती
HYPONYM	Taxonomic	More specific sub-category	शेतकरी $\to$ बागायतदार / अल्पभूधारक शेतकरी
MERONYM (PART_OF)	Mereological	Part-of relationship	हायड्रोजन $\to$ पाणी
HOLONYM	Mereological	Whole containing the part	झाड $\to$ फांदी
TROPONYM	Event/Action	Specific manner of doing an action	नांगरणी $\to$ शेती
ENTAILMENT	Logical	Truth of X necessitates Y	घोरणे $\to$ झोपणे
CAUSATION (AFFECTS)	Dynamic	Action causing state transition	पाऊस $\to$ पीक वाढ
ATTRIBUTE	Descriptive	Inherent qualitative property	सूर्य $\to$ उष्णता
DERIVED_FORM	Morphological	Grammatical root derivation	नांगरणे $\to$ नांगरणी
DOMAIN	Contextual	Topical/Disciplinary classification	शेती $\to$ कृषी विज्ञान

---

⚡ Quickstart & Local Deployment

Prerequisites

• Docker & Docker Compose OR
• Java 17+ (JDK), Maven 3.8+, Node.js 18+, Python 3.10+, and Neo4j 5.x.

---

Option A: One-Click Docker Compose (Recommended)

# Clone the repository
git clone https://github.com/your-username/marathi-wordnet.git
cd marathi-wordnet

# Start Neo4j and Spring Boot backend
docker-compose up --build -d

• Backend API: http://localhost:8080
• Neo4j Browser: http://localhost:7474 (Auth: neo4j / password)

---

Option B: Local Development Setup

1. Start Neo4j Database

Ensure Neo4j is running on bolt://localhost:7687 with credentials configured in src/main/resources/application.properties.

2. Run Spring Boot Backend

mvn clean spring-boot:run

The server will start on port 8081 (or 8080 depending on application.properties).

3. Ingest Comprehensive Dataset

curl -X POST http://localhost:8081/api/wordnet/ingest-local/marathi_wordnet_comprehensive.json

4. Run Frontend (React 19 + Vite)

cd ui
npm install
npm run dev

Access UI at http://localhost:5173.

5. Run Indic GraphRAG Agent Demo

cd agent
pip install -r requirements.txt
python graphrag_agent.py

---

📡 API Reference

1. Dictionary Lookup (with Morphological Resolution)

GET /api/words/lookup/{word}

Example Request: GET /api/words/lookup/पाण्याचे

{
  "lemma": "पाणी",
  "synsets": [
    {
      "id": "SN_1002",
      "definition": "एक रंगहीन, गंधहीन द्रव पदार्थ जो जीवनासाठी आवश्यक आहे | उदा: पाणी हेच जीवन आहे.",
      "pos": "noun",
      "words": ["पाणी", "जल", "नीर", "तोय"],
      "relations": [
        { "type": "HYPERNYM", "target": "द्रव_पदार्थ", "weight": 1.0 },
        { "type": "MERONYM", "target": "हायड्रोजन", "weight": 0.9 },
        { "type": "RELATED_TO", "target": "नदी", "weight": 0.85 }
      ]
    }
  ]
}

2. Semantic Similarity Score (Wu-Palmer Metric)

GET /api/words/similarity?w1=शेतकरी&w2=नांगरणी

{
  "word1": "शेतकरी",
  "word2": "नांगरणी",
  "similarityScore": 0.892
}

3. Morphological Breakdown

GET /api/words/morphology/शेतकऱ्यांना

{
  "inputWord": "शेतकऱ्यांना",
  "normalizedForm": "शेतकऱ्यांना",
  "resolvedLemma": "शेतकरी",
  "candidates": ["शेतकरी"],
  "directMatch": false
}

---

🧠 Tech Stack & Engineering Decisions

Component	Technology	Rationale
Backend Framework	Java 17, Spring Boot 3.2.3, Spring Data Neo4j	High-concurrency RESTful service with native graph object mapping.
Graph Database	Neo4j 5.18 (Community Edition)	$O(1)$ index-free adjacency enables millisecond-level multi-hop taxonomic traversals without SQL join explosions.
Algorithm Engine	Cypher-Pushdown Wu-Palmer	Computes Least Common Subsumers directly in Neo4j, avoiding memory transfer of large graph subtrees to Java heap.
Morphology	Custom Rule Engine + Unicode NFC	Fast, rule-based suffix-stripping tailored for Indic oblique stems, validated strictly against Neo4j nodes.
Agent / GraphRAG	Python, Requests, Indic Prompts	Decoupled agentic layer providing OpenAPI tool schemas for deterministic LLM grounding.
Frontend	React 19, Vite, Lucide Icons	Responsive UI with real-time graph exploration and context parsing.
DevOps	Multi-Stage Dockerfile, Docker Compose	Alpine JRE runtime with non-root user execution (appuser) and container memory limit management.

---

📄 License

This project is open-source and available under the MIT License.