@mera-vansh/ms-gtr

Hindu Gotra-Pravara knowledge retrieval for genealogical AI applications.

@mera-vansh/ms-gtr is a zero-dependency, zero-database retrieval engine for Hindu lineage (Gotra-Pravara) knowledge. Drop it into any Node.js application to answer genealogy questions in 9 Indian languages without calling an external API or database.

The library ships 105 Gotra records covering 69 Brahmin lineages and 36 non-Brahmin communities (Rajput, Jat, Agarwal, Maratha, Yadav), with multilingual names, Pravara chains, Sutra traditions, regional community assignments, and Puranic origin stories. All records are read-only and safe to share across requests.

Key Capabilities

• Natural language queries — ask in any Indian script or Romanised English
• Community-aware retrieval — filter by Brahmin tradition, Kshatriya lineage, Vaishya clan, and more
• Phonetic matching — finds gotras even with common spelling variants (वशिष्ठ / वसिष्ठ, bhardwaj / bharadvaja)
• Multilingual context output — response labels localised to the detected language (Hindi, Telugu, Tamil, Kannada, Malayalam, Marathi, Bengali, Sanskrit)
• LLM-ready context — .context string formatted for direct injection into an LLM system prompt
• Prefix autocomplete — type-ahead over Gotra names, Devanagari forms, aliases, and community names
• Stateful feedback loop — promote or demote individual Gotras based on user signals
• Serialisable state — export and restore the full engine as plain JSON

Installation

npm install @mera-vansh/ms-gtr
# or
pnpm add @mera-vansh/ms-gtr

Requirements: Node.js ≥ 22

Quick Start

import { GTR } from "@mera-vansh/ms-gtr";

const gtr = new GTR();

// Query in any language or script
const res = gtr.call({ query: "gautama gotra brahmin south india" });

console.log(res.context);        // LLM-ready context block
console.log(res.candidates[0]);  // top match with score and explanation
console.log(res.detectedLang);   // "en", "hi", "te", etc.

Knowledge Base

| | | |---|---| | Brahmin lineages | 69 (Pancha Gauda + Pancha Dravida traditions) | | Non-Brahmin communities | 36 (8 Rajput, 10 Jat, 10 Agarwal, 5 Maratha, 3 Yadav) | | Total Gotras | 105 | | Root Rishis (Saptarishi) | 7 | | Ganas | 18 | | Sutra traditions | Apastamba, Baudhayana, Hiranyakeshi, Gobhila, Jaimini, Asvalayana, Smriti | | Multilingual names | Hindi, Telugu, Tamil, Kannada, Malayalam, Marathi, Bengali, Sanskrit | | Source | Baudhayana Srauta Sutra (~600 BCE) |

API

new GTR(options?)

const gtr = new GTR({ defaultTopK: 5 });

| Option | Type | Default | Description | |---|---|---|---| | defaultTopK | number | 5 | Default number of candidates returned per query |

gtr.call(req): GTRResponse

Queries the knowledge base in natural language. Accepts any Indian script or Romanised English. Automatically detects the language, applies community and region reasoning, and returns ranked candidates with an LLM-ready context string.

// English query
gtr.call({ query: "kashyapa gotra apastamba" });

// Hindi query
gtr.call({ query: "गौतम गोत्र" });

// Telugu query
gtr.call({ query: "గౌతమ గోత్రం" });

// Filter by community
gtr.call({ query: "gotra", filters: { community: "Jat" } });

// Filter by Sutra tradition
gtr.call({ query: "bharadvaja", filters: { sutra: "apastamba" } });

// Filter by region
gtr.call({ query: "brahmin gotra", filters: { region: "south" } });

// Limit results
gtr.call({ query: "vasishtha", topK: 1 });

Request fields:

| Field | Type | Description | |---|---|---| | query | string | Natural language question in any script | | topK | number? | Max candidates to return (default: defaultTopK) | | lang | LangCode? | Override auto-detected language for context labels | | filters.gana | GanaId? | Restrict to a Gana | | filters.sutra | SutraId? | Restrict to a Sutra tradition | | filters.region | RegionId? | "north" | "south" | "east" | "west" | "deccan" | | filters.community | string? | Substring match against community names |

Response shape:

interface GTRResponse {
  query:        string;           // original query
  detectedLang: LangCode | null;  // detected language ("hi", "te", "ta", etc.)
  candidates:   GTRCandidate[];   // ranked matches
  context:      string;           // LLM-ready context block
  metadata: {
    totalGotras:  number;         // total indexed records
    searchTimeMs: number;         // retrieval time in ms
  };
}

interface GTRCandidate {
  gotra:         GotraEntry;      // the matched Gotra record
  score:         number;          // relevance score [0, 1]
  matchedTokens: string[];        // query tokens that matched
  explanation:   string;          // human-readable match summary
}

gtr.suggest(prefix, maxResults?): GotraEntry[]

Type-ahead autocomplete over Gotra ids, Devanagari names, aliases, regional names, and community names.

gtr.suggest("gaut");        // → [{ id: "gautama", devanagari: "गौतम", ... }]
gtr.suggest("गौ");          // → [{ id: "gautama", ... }]
gtr.suggest("Jat", 5);      // → Jat community gotras
gtr.suggest("Tamil", 10);   // → Tamil Brahmin gotras
gtr.suggest("kash", 3);     // → kashyapa + related

Note: An empty prefix ("") returns up to maxResults entries from the full knowledge base — useful for showing initial suggestions before the user types. Pass maxResults: 0 to suppress this.

gtr.feedback(id, signal)

Adjusts how a Gotra ranks in future queries based on whether the result was useful.

gtr.feedback("gautama", { type: "positive" }); // promote in future results
gtr.feedback("gautama", { type: "negative" }); // demote in future results
gtr.feedback("gautama", { type: "neutral" });  // no change

// Attach a correction for downstream review
gtr.feedback("gautama", {
  type: "positive",
  correction: { region: ["south"] },
});

Note: Calling feedback() with an unknown ID is a silent no-op. Use gtr.has(id) first if you need to detect mis-typed IDs.

gtr.ingest(docs) / gtr.add(doc)

Adds custom supplementary documents to the retrieval store. Useful for enriching the knowledge base with application-specific text without modifying the built-in records.

gtr.add({
  id: "custom-note-gautama",
  text: "Our family registers list Gautama as the primary gotra in Kashi.",
  gotraId: "gautama",   // optional: associates with an existing GotraEntry
});

gtr.ingest([
  { id: "note-1", text: "Kashyapa gotra families in Mysore region" },
  { id: "note-2", text: "Vasishtha branch in Kerala documented since 12th c." },
]);

Attempting to add a document with an ID that already exists is a silent no-op (the original record is preserved).

gtr.optimize()

Applies queued correction patches to the engine state. Call this after a batch of feedback() calls that include corrections.

gtr.feedback("kashyapa", {
  type: "positive",
  correction: { region: ["south"] },
});
gtr.optimize(); // applies and clears correction queue

gtr.export() / gtr.import(state)

Persist and restore the full engine state (retrieval weights + corrections) as plain JSON.

// Save to database or disk
const state = gtr.export();
await db.collection("gtr_state").replaceOne(
  { _id: "v1" },
  { _id: "v1", ...state },
  { upsert: true }
);

// Restore in a new process or on startup
const saved = await db.collection("gtr_state").findOne({ _id: "v1" });
const gtr2 = new GTR();
if (saved) gtr2.import(saved);

gtr.size() / gtr.has(id)

gtr.size();              // total indexed records (105 built-in + any custom docs)
gtr.has("gautama");      // → true
gtr.has("unknown_id");   // → false

Application Examples

Genealogy chatbot with LLM

import { GTR } from "@mera-vansh/ms-gtr";

const gtr = new GTR();

async function answer(userQuestion: string) {
  const res = gtr.call({ query: userQuestion, topK: 3 });

  // Inject the structured context directly into your LLM
  const llmResponse = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: [
      {
        role: "system",
        content: "You are an expert on Hindu genealogy and lineage traditions.",
      },
      {
        role: "user",
        content: `${res.context}\n\nQuestion: ${userQuestion}`,
      },
    ],
  });

  // Boost the top result for future queries
  if (res.candidates[0]) {
    gtr.feedback(res.candidates[0].gotra.id, { type: "positive" });
  }

  return llmResponse.choices[0]!.message.content;
}

await answer("What is the pravara of the Bharadwaj gotra?");
await answer("गौतम गोत्र का मूल ऋषि कौन है?");
await answer("What sutra does Kaundinya gotra follow?");

Community-specific gotra lookup

import { GTR } from "@mera-vansh/ms-gtr";

const gtr = new GTR();

// All Iyer (Tamil Brahmin) gotras
const iyer = gtr.call({
  query: "iyer gotra",
  filters: { community: "Tamil Brahmin (Iyer)" },
  topK: 10,
});
iyer.candidates.forEach(c =>
  console.log(c.gotra.id, c.gotra.devanagari, c.gotra.sutra)
);

// Agarwal community gotras
const agarwal = gtr.call({
  query: "agarwal gotra",
  filters: { community: "Agarwal" },
  topK: 10,
});

// Rajput gotras in north India
const rajput = gtr.call({
  query: "rajput kshatriya",
  filters: { community: "Rajput Kshatriya", region: "north" },
  topK: 5,
});

Multilingual search with autocomplete

import { GTR } from "@mera-vansh/ms-gtr";

const gtr = new GTR();

// Show suggestions as user types
function onInput(prefix: string) {
  return gtr.suggest(prefix, 8).map(g => ({
    id: g.id,
    label: g.devanagari,
    communities: g.communities ?? [],
  }));
}

// Handle full query submission in any language
function onSearch(query: string) {
  const res = gtr.call({ query });
  return {
    lang: res.detectedLang,
    results: res.candidates.map(c => ({
      name: c.gotra.devanagari,
      rishi: c.gotra.rootRishi.name,
      pravaras: c.gotra.pravaras.map(p => p.name),
      sutra: c.gotra.sutra,
      score: c.score,
    })),
  };
}

onInput("kash");     // → [{ id: "kashyapa", label: "कश्यप", ... }]
onSearch("కాశ్యప"); // Telugu → kashyapa
onSearch("ভরদ্বাজ"); // Bengali → bharadvaja

Marriage compatibility assistant

import { GTR } from "@mera-vansh/ms-gtr";

const gtr = new GTR();

function checkCompatibility(queryA: string, queryB: string) {
  const a = gtr.call({ query: queryA, topK: 1 }).candidates[0]?.gotra;
  const b = gtr.call({ query: queryB, topK: 1 }).candidates[0]?.gotra;

  if (!a || !b) return { found: false };

  const sameGotra = a.id === b.id;
  const pravarasA = new Set(a.pravaras.map(p => p.name));
  const sharedPravaras = b.pravaras
    .map(p => p.name)
    .filter(name => pravarasA.has(name));

  return {
    found: true,
    gotraA: a.devanagari,
    gotraB: b.devanagari,
    sameGotra,
    sharedPravaras,
    // Traditional rule: different gotra with no shared pravaras
    traditionallyCompatible: !sameGotra && sharedPravaras.length === 0,
  };
}

checkCompatibility("gautama", "kashyapa");
// → { sameGotra: false, sharedPravaras: [], traditionallyCompatible: true }

checkCompatibility("gautama", "gautama");
// → { sameGotra: true, traditionallyCompatible: false }

Persistent state across server restarts

import { GTR } from "@mera-vansh/ms-gtr";
import { writeFileSync, readFileSync, existsSync } from "fs";

const STATE_FILE = "./gtr-state.json";

function loadEngine(): GTR {
  const gtr = new GTR();
  if (existsSync(STATE_FILE)) {
    gtr.import(JSON.parse(readFileSync(STATE_FILE, "utf8")));
  }
  return gtr;
}

function saveEngine(gtr: GTR): void {
  writeFileSync(STATE_FILE, JSON.stringify(gtr.export(), null, 2));
}

// On server startup
const gtr = loadEngine();

// After each user interaction
gtr.feedback("gautama", { type: "positive" });
saveEngine(gtr);

Direct knowledge base access

import { GOTRAS, GOTRA_MAP, GANAS, GANA_MAP } from "@mera-vansh/ms-gtr";

// Browse all gotras
GOTRAS.forEach(g => console.log(g.id, g.devanagari, g.sutra));

// Direct lookup by id
const gautama = GOTRA_MAP["gautama"];
console.log(gautama?.pravaras.map(p => p.name)); // ["Angirasa", "Ayasya", "Gautama"]
console.log(gautama?.communities);               // ["Brahmin (general)", ...]

// Browse ganas
GANAS.forEach(g => console.log(g.id, g.name));

// Direct gana lookup
const gana = GANA_MAP["angirasa"];
console.log(gana?.progenitor.name); // "Angirasa"

TypeScript Types

import type {
  GTROptions,       // { defaultTopK?: number }
  GTRRequest,       // { query, topK?, lang?, filters? }
  GTRResponse,      // { query, detectedLang, candidates, context, metadata }
  GTRCandidate,     // { gotra, score, matchedTokens, explanation }
  GTRFilters,       // { gana?, sutra?, region?, community? }
  GotraEntry,       // full Gotra record shape
  GanaEntry,        // Gana (clan group) record
  RishiRef,         // { name, devanagari, aliases }
  FeedbackSignal,   // { type: "positive"|"negative"|"neutral", correction? }
  SerialGTRState,   // exported state shape
  LangCode,         // "hi" | "sa" | "te" | "ta" | "kn" | "ml" | "mr" | "bn" | ...
  GanaId,           // "angirasa" | "kashyapa" | "vasishtha" | ...
  SutraId,          // "apastamba" | "baudhayana" | "smriti" | ...
  RegionId,         // "north" | "south" | "east" | "west" | "deccan"
  GotraDocument,    // custom document shape for ingest/add
  SutraRule,        // sutra rule record
} from "@mera-vansh/ms-gtr";

License

GPL-3.0 © dwivna