Upadeshaka (Guru Guide)¶

Scope¶

Upadeshaka is the dharmic guidance assistant. It must:

Convert user problems and life situations into dharmic guidance with appropriate rituals, vratas, japa, seva, and lifestyle recommendations.
Provide a ritual intensity spectrum: quick japa, home puja, community yajna, temple seva.
Ensure contextual sensitivity: add disclaimers for health/education/finance/legal queries, never substitute professional advice.
Enforce regional and sampradāya correctness: Advaita, Vaishnava, Shaiva, Shakta, Smarta.
Personalize by age, gotra, household context, and region, while respecting privacy and consent.
Handle open-ended queries (e.g., "How to overcome anxiety?") and specific requests (e.g., "Suggest a puja for career growth").
Offer authentic scriptural grounding with source citations (śāstra, purāṇa, itihāsa, smṛti).
Connect users to vetted human priests/gurus when needed for custom sankalpa.
Deliver progressive curriculum: daily mantra, weekly reading, monthly vrata.
Provide seva/donation pathways for Gurukul or temple involvement.
Support multimodal UX (text/voice) with only Telugu and English; transliteration fallback.
Include a dedicated Telugu parser (NLU/slot filling) and Telugu converser (dialog generation) for native-quality understanding and expression.

Conversational Orchestrator — AI: Chatbot Agent
Manages dialogue state, tool‑calling, and tiered suggestions.
- NLU & Slot Filling — AI: Model
  Intent classification (AskGuidance, AskMantra, Donation, ConnectPriest) and entity extraction (topic, age, region, sampradāya, gotra).
- Telugu Parser — AI: Model
  Telugu-specific tokenization, morphology, intent/entity extraction; handles code-mix and dialects.
- Telugu Converser — AI: Model
  Response generation in Telugu; register control (devotional vs casual), script/IAST transliteration, and voice output compatibility.
Guidance Planner — AI: Tool‑using Agent
Maps problem contexts to ritual/upāya sets across intensity spectrum; validates appropriateness.
- Timely Ritual Scheduler and Reminder
  Suggests daily/weekly/monthly practices; integrates with calendar service for reminders.
Personalization & Ranking — AI: Model
Adjusts ritual sets based on user context, preferences, and prior history.
Policy/Guardrails — AI: Classification Model
Ensures safe, dharmic‑aligned, and disclaimer‑protected outputs.
MCP Tooling Layer — AI: MCP Server
Exposes ritual, scripture, priest, donation tools in a typed, discoverable interface.

Ritual Knowledge Service — API + KB (RAG)
Structured repository of ritual specifications, vratas, mantras, references, variants.
Scripture Reference Service — API + DB
Curated citations with versions, translations, commentaries.
Priest Directory — API + DB
Vetted priests/gurus, region, lineage, expertise, honorarium rules.
Privacy backed profile Service — API + DB
User region, gotra, sampradāya, household context, history.
Calendar/Events Service — API + MCP
Panchang/festival calendar integration.
UI/Clients — Web/App
Chat surface, ritual guidance visualization, donation/connection flows.
Telemetry/Analytics — Pipeline + Warehouse
Track guidance acceptance, escalation rate, donation conversion.
AuthN/AuthZ & Compliance — Services
User identity, consent flags, compliance with charitable donation law.
LLM and AI Evaluation Bench — AI: Eval Framework
Automated and manual evaluation of NLU, planning, personalization, and end‑to‑end flows.

tool.guruSuggest(topic, age, region?, sampradāya?, gotra?) → {rituals[], vratas[], japa[], seva[], cautions[], citations[]}
tool.askMantra(mantra_type, duration) → {text, audio_uri}
tool.connectPriest(topic, time_window) → {priests[]}
tool.donate(program_id, amount) → {receipt}
tool.getScriptureCitation(query) → {sources[]}

Ritual(id, name, type{japa, puja, yajna, seva}, deity, festival?, steps_uri, intensity, regional_variant, sampradāya, citations[])
User(id, region, sampradāya, gotra, household_ctx, age, prefs{})
GuidanceHistory(user_id, topic, rituals[], dt, accepted?)
Priest(id, name, lineage, expertise[], region, availability, honorarium_rules)
DonationProgram(id, gurukul_id, description, split_rules%)
Citation(id, scripture, ref, translation_uri, commentary_uri)