🔴CLOSED: Week 3 : KiranaAI (Text2Cypher + Text2SQL AI Agent for Kirana Stores - India) - 🇮🇳

⚽GraphAcademy Cup Community Challenge
, , ,
1

:trophy: GraphAcademy Cup Submission

Topic Title Format:
Week 3: KiranaAI — Text2Cypher + Text2SQL AI Agent for Kirana Stores - India

GraphAcademy Cup Team Profile Link

Team Profile Link: India | GraphAcademy Cup

GraphAcademy Public Profile Username

Public Profile Username: guna

:warning: Anonymous GraphAcademy profiles are not eligible for weekly LEGO prizes.

Country

Country: India

GraphAcademy Course Completed

Course Name:

Project Name

KiranaAI — Conversational AI Agent for Indian Kirana Store Owners using Text2Cypher + Text2SQL

Description

India has over 12 million kirana (neighborhood grocery) stores. Every owner knows their business intuitively — but depends on a "technical person" to run reports. A relational database gives sales totals and stock counts, but it cannot reveal how customers, products, credit, and suppliers are connected. Those connections are graph problems.

A few days ago I got an email about the Week 2 GraphAcademy Cup results. That same day I gave a guest lecture on Text2SQL at my undergraduate college. Driving back, one question came to mind: does Text2Cypher exist? I found the Neo4j blog, and the idea clicked — Text2SQL and Text2Cypher are both products of the LLM + ReAct agent pattern era . Both let a non-technical person query a database with plain language. But they solve fundamentally different problems.

KiranaAI is a Tenglish (Telugu + English, Roman script) conversational agent that routes each owner question to the right database automatically:

Graph Value — why Neo4j is the intelligence layer:

  • "Atta tho paatu em adugutaaru customers?" → OFTEN_WITH co-purchase traversal + stock check from SQLite = full recommendation

  • "Evaru evaru udhar teeyaali?" → Customer → OWES → Khata traversal + credit ranking

  • "Basmati Rice ekkadi nundi vastaundi?" → Product → SUPPLIED_BY → Supplier one-hop traversal

No SQL JOIN chain expresses these naturally. Two-line Cypher does. And Text2Cypher translates the owner's Tenglish question to that Cypher automatically — no graph knowledge required.

Architecture:

Owner Question (Tenglish — Telugu + English, Roman script)
                        │
                        ▼
           ┌─────────────────────────┐
           │       DeepSeek LLM      │
           │  (LangGraph ReAct Agent)│
           └────────────┬────────────┘
                        │ decides which tool(s)
         ┌──────────────┴──────────────┐
         │                             │
         ▼                             ▼
┌──────────────────┐     ┌─────────────────────────┐
│  neo4j_search    │     │       sql_query         │
│  (Text2Cypher    │     │       (SQLite)          │
│  → Neo4j Aura)   │     │                         │
│                  │     │  Inventory, Sales,      │
│  PURCHASED       │     │  Billing, Stock alerts  │
│  OWES → Khata    │     └────────────┬────────────┘
│  OFTEN_WITH      │                  │
│  SUPPLIED_BY     │                  │
│  REFERRED_BY     │                  │
└────────┬─────────┘                  │
         └─────────────┬──────────────┘
                       │
                       ▼
          ┌────────────────────────┐
          │   create_visualization │
          │      (Plotly charts)   │
          └────────────┬───────────┘
                       │
                       ▼
        Answer in Tenglish
        + Interactive Neo4j Graph (pyvis)
        + Plotly Chart (when numeric)

What Did You Learn?

a) The Graph Data Model

I modelled the kirana store as a knowledge graph where every business relationship is a first-class edge:


(Customer)-\[:PURCHASED {times, last_date}\]->(Product)

(Customer)-\[:OWES\]->(Khata {balance})

(Product)-\[:OFTEN_WITH {strength}\]->(Product)

(Product)-\[:SUPPLIED_BY\]->(Supplier)

(Customer)-\[:REFERRED_BY\]->(Customer)

This is what the Cypher Fundamentals and Neo4j Fundamentals courses made click for me — designing relationships as edges (not foreign keys) changes what questions you can answer in one query. MATCH (c:Customer)-\[r:OWES\]->(k:Khata) RETURN c, r, k ORDER BY k.balance DESC does what would take a 3-table SQL JOIN plus an ORDER BY.

b) Text2Cypher with GraphCypherQAChain from langchain-neo4j

The neo4j_search tool accepts only plain-language questions — the agent never writes Cypher. Inside the tool:

  1. Neo4jGraph(enhanced_schema=True) fetches the live schema with property examples → LLM stops guessing node labels

  2. The question + schema + 14 verified few-shot Cypher examples go into GraphCypherQAChain

3. LLM generates Cypher grounded in the real schema

4. The same Cypher re-runs via the raw Neo4j driver to capture Node and Relationship objects for the interactive pyvis graph

Without the few-shot examples, the LLM invented complex WITH aggregation blocks the graph couldn't serve. 14 tested patterns made generation reliable.

c) Two auto-generated Cypher queries that show what Text2Cypher enables

Question: "Atta tho paatu em adugutaaru?" (What to suggest alongside Atta?)


MATCH (p1:Product)-\[r:OFTEN_WITH\]->(p2:Product)

WHERE p1.name CONTAINS 'Atta'

RETURN p1, r, p2

ORDER BY r.strength DESC

The agent also called sql_query for stock levels and merged both answers — without being told to.

Question: "Evaru evaru udhar teeyaali?" (Who owes money?)


MATCH (c:Customer)-\[r:OWES\]->(k:Khata)

RETURN c, r, k

ORDER BY k.balance DESC

Both queries rendered as interactive force-directed graphs — automatically.

d) Key architectural insight

Graph + Relational together is more powerful than either alone. Neo4j handles relationships and patterns. SQLite handles counts, totals, and filtering. The LangGraph ReAct agent decides which database — or both — to query for each question. That decision is the intelligence.

Screenshot

Query 1 — "Atta tho paatu em adugutaaru customers, aa items stock lo unnaya?"

(What to suggest to Atta buyers — are those items in stock?)

This question requires both databases: Neo4j for co-purchase relationships, SQLite for stock levels. The agent decides this on its own.

Query 2 — "Evaru evaru udhar teeyaali, enta baaki undi?"

(Who all need to pay their credit — how much is pending?)

A pure graph traversal question. The OWES relationship between Customer and Khata nodes holds the answer.

Repository / Demo Link

GitHub / Demo URL (Optional): GitHub - chakka-guna-sekhar-venkata-chennaiah/kirana-ai-agent · GitHub

Additional Notes

The Tenglish persona matters: millions of Telugu kirana owners think and speak in Telugu+English Roman script — not Hindi, not pure English. "Naadu stock chala takkuvaiga undi!" lands differently than "Stock is low." The agent responds the same way a knowledgeable neighbour would.

The system is schema-aware at runtime — Neo4jGraph fetches the live graph schema before each query, so the Text2Cypher layer adapts automatically if the graph evolves. No hardcoded schema strings in the prompt.

My background with knowledge graphs came from postgraduate studies and professional work. Revisiting Cypher through GraphAcademy with a real project to build made every concept land differently than studying it in isolation. The moment Text2Cypher turned a Tenglish question into a working MATCH query against live Neo4j Aura was when it all made sense.

Next: local LLM support (Ollama) for full offline operation, and a WhatsApp bot interface — since most kirana owners already use WhatsApp all day.

:white_check_mark: Submission Checklist

Before submitting, confirm that:

  • I am participating in the GraphAcademy Cup.

  • I included my Team Profile Link.

  • I included my GraphAcademy Public Profile Username.

  • My profile is public and eligible for prize verification.

  • My project is related to concepts learned in GraphAcademy.

:scroll: Contest Reminder

:wrapped_gift: One LEGO prize winner will be selected every week during the GraphAcademy Cup.

:scroll: Terms & Conditions:

:red_question_mark: FAQ:

2

@Ari_Neo4j I have a doubt as follows:-
Public Profile Username: means the user name that is displayed on certificates or the username that is dispalyed in the community or somethign else?

Thank you
Guna.