🔮 Poornima Oracle — Campus RAG Assistant & AI Co-Pilot

Poornima Oracle is a next-generation, RAG-powered intelligent campus co-pilot and automated document retrieval system engineered for the Poornima Group of Colleges — covering Poornima University (PU), Poornima College of Engineering (PCE), and Poornima Institute of Engineering & Technology (PIET).

It grounds conversational AI in verified institutional knowledge, official circulars, exam schedules, and academic calendars with real-time SSE streaming, dual-tier cloud fallback resilience, autonomous tool calling via the Model Context Protocol (MCP), and an installable Progressive Web App (PWA).

• ✨ Core Capabilities
• 🏗️ System Architecture
• 📁 Project Structure
• 🚀 Quick Start
• ⚙️ Environment Configuration
• 🔌 API Reference
• 📜 Available Scripts
• 🧪 Testing & Diagnostics
• 🌐 Deployment
• 📄 License & Authors

• Automated Notice Crawler (services/crawler/notice-sync.js):
  • Poornima University (PU): Directly accesses the Firestore REST API (poornima-5c202) for Angular client-rendered notices, announcements, and calendars.
  • Poornima College of Engineering (PCE) & PIET: Scrapes server-rendered HTML portals using Cheerio with full metadata extraction.
• Deep PDF Circular Extraction (services/crawler/pdf-extractor.js): Downloads and parses attached official PDF notices, circulars, and fee guidelines with pdf-parse, chunking tabular data and text for semantic vector indexing.
• Pinecone Vector Database: Multi-namespace vector indexing (__default__ for institutional documents, notices for real-time circulars) with 768-dimensional embeddings via Google gemini-embedding-001.
• Scheduled Synchronization: Built-in automated cron runner (30 0 * * * — 6:00 AM IST) and authenticated on-demand admin trigger (POST /api/sync-notices).

• Zero-Failure Architecture: Automatic routing when knowledge base coverage is low (score < 0.35), Gemini returns an out-of-scope refusal, or primary API keys hit rate limits (429 / 503).
• Tier 1 Fallback: OpenRouter Free API (utilizing meta-llama/llama-3.3-70b-instruct:free or equivalent zero-cost LLMs).
• Tier 2 Fallback: Hosted Remote Ollama Cloud API (e.g. nemotron-3-nano:30b).
• Client-Provided Key Overrides: Supports x-openrouter-key, x-ollama-key, and x-ollama-host request headers.

• MCP Integration (@modelcontextprotocol/sdk): Configurable MCP servers defined in mcp-servers.json for structured external tools (SQLite, GitHub, and custom SSE servers).
• Native Tool Dispatcher (services/tool-dispatcher.js):
  • 🔍 Web Search: Real-time external campus intelligence using DuckDuckGo (zero-key fallback) or Tavily Search API.
  • 🌐 Web Scraper: Real-time content fetching and HTML markdown extraction with Cheerio.
  • 🏛️ Portal Inspector: Direct extraction of live official campus portals.
  • ⏰ Date/Time Calculator: Accurate calculations for exam countdowns, registration cutoffs, and event dates.

• Dynamic Calendar Engine (services/calendar-service.js): Tracks university & college exams, assignment submissions, fee payment cutoffs, holidays, and campus fests.
• Frontend Countdown Cards (src/js/components/calendarWidget.js): Collapsible, responsive widget showing upcoming deadlines with badge indicators and campus-based filtering (PU, PCE, PIET, ALL).
• Context Injection: Calendar deadlines are automatically fed into the LLM system prompt for accurate temporal awareness.

• Installable Application: Service Worker (sw.js) and Web App Manifest (manifest.json) allow installation as a native desktop or mobile app on Android, iOS, Windows, and macOS.
• Offline Reliability: Cache-first asset strategy with offline fallback page and offline status badge indicator.
• Locally Vendored Assets: Icons and UI libraries vendored locally to guarantee zero external CDN dependency breakages.

• Profile Store (src/js/profile/profileStore.js): Students and faculty can configure their institution (PU, PCE, PIET), department, year, semester, and section to receive personalized answers.
• Voice & Audio Interface: Integrated Web Speech API for speech-to-text queries and natural text-to-speech response playback.
• Chat History & Export: Export chat sessions directly into Markdown, JSON, or plain text formats.
• Security: Hardened with Helmet HTTP security headers, CORS origin whitelisting, Express Rate Limiting, and XSS input sanitization.

                                  +---------------------------------------+
                                  |         User Browser / PWA            |
                                  |   (Speech I/O | Profile | Calendar)   |
                                  +---------------------------------------+
                                                     |
                                            SSE / HTTP Requests
                                                     v
                                  +---------------------------------------+
                                  |          Express 4.21 Server          |
                                  | (Helmet | RateLimiter | In-Memory LRU)|
                                  +---------------------------------------+
                                                     |
             +--------------------+------------------+--------------------+--------------------+
             |                    |                                       |                    |
             v                    v                                       v                    v
  +--------------------+  +--------------------------------+  +--------------------+  +--------------------+
  | Pinecone Vector DB |  |      Google Gemini 2.0         |  |   Dual Fallback    |  |    MCP Manager     |
  |  (768-dim Vectors) |  |   (gemini-2.0-flash Core)      |  |     Router         |  | & Tool Dispatcher  |
  |                    |  +--------------------------------+  |                    |  |                    |
  | Namespaces:        |                  |                   | - OpenRouter (Llama|  | - Web Search (DDG) |
  | - __default__      |                  | (low score/429)   |   3.3 70B Free)    |  | - Web Scraper      |
  | - notices          |                  +------------------>| - Ollama Cloud API |  | - Portal Inspector |
  +--------------------+                                      +--------------------+  | - Datetime Calc    |
             ^                                                                        +--------------------+
             |
  +------------------------------------------------+
  |    Automated Notice Ingestion Pipeline         |
  |   (Firestore REST / Cheerio / pdf-parse)       |
  |   - Cron Job (Daily at 6:00 AM IST)            |
  |   - Admin Endpoint: POST /api/sync-notices     |
  +------------------------------------------------+

Poornima-Oracle/
├── .github/
│   └── workflows/
│       └── static.yml              # GitHub Actions static Pages deployment
├── services/
│   ├── calendar-service.js         # Academic calendar & events aggregation
│   ├── fallback-router.js          # Dual-tier OpenRouter/Ollama fallback engine
│   ├── mcp-manager.js              # Model Context Protocol server connector
│   ├── tool-dispatcher.js          # Native tools (search, scraper, datetime)
│   ├── crawler/
│   │   ├── notice-sync.js          # PU Firestore & PCE/PIET portal crawler
│   │   └── pdf-extractor.js        # Circular download & PDF parser
│   └── tools/
│       ├── datetime-calculator.js  # Date arithmetic for deadlines
│       ├── portal-inspector.js     # Live campus website parser
│       ├── web-scraper.js          # Cheerio web scraper
│       └── web-search.js           # DuckDuckGo / Tavily search
├── src/
│   └── js/
│       ├── app.js                  # Main client application orchestration
│       ├── config.js               # Frontend configuration & API routes
│       ├── state.js                # Client state management
│       ├── components/
│       │   └── calendarWidget.js   # Collapsible countdown calendar widget
│       ├── profile/
│       │   └── profileStore.js     # Student profile & college selection store
│       ├── pwa/
│       │   └── installPrompt.js    # PWA install banner & lifecycle
│       └── utils/
│           └── chatExport.js       # Conversation export (MD / JSON / Text)
├── index.html                      # Single-page application entry
├── server.js                       # Express server, RAG orchestration, API routes
├── sw.js                           # Progressive Web App service worker
├── manifest.json                   # PWA manifest specifications
├── mcp-servers.json                # External MCP server definitions
├── styles.css                      # Compiled Tailwind CSS styles
├── tailwind.config.js              # Tailwind styling configuration
├── test-calendar-service.js        # Unit test suite for calendar queries
├── test-pdf-extractor.js           # Unit test suite for PDF parsing
├── test-pinecone.js                # Pinecone connectivity & namespace verification
├── package.json                    # Project dependencies & npm scripts
└── .env.example                    # Environment variable documentation template

• Node.js: v18.0.0 or higher
• Pinecone Account: app.pinecone.io
• Google AI Studio Key: aistudio.google.com

git clone https://github.com/sunnydev07/Poornima-Oracle.git
cd Poornima-Oracle
npm install

Copy the configuration template:

cp .env.example .env

Populate your .env with your API credentials (refer to the Configuration section).

# Verify syntax across all modules
npm run check

# Start the local development server
npm run dev

Open http://localhost:3001 in your browser.

GET /api/health

Returns system readiness, vector database configuration, active fallback providers, connected MCP servers, uptime, and memory usage.

POST /api/chat
Content-Type: application/json

Streams responses using Server-Sent Events (SSE).

Request Body:

{
  "message": "When are the mid-term examinations for B.Tech Semester 4?",
  "history": [
    { "role": "user", "text": "Hi" },
    { "role": "model", "text": "Hello! How can I assist you with Poornima campus information today?" }
  ],
  "profile": {
    "college": "PU",
    "department": "Computer Science",
    "year": "2nd Year",
    "semester": "Semester 4"
  }
}

GET /api/calendar?campus=PU&category=exam&daysAhead=60&limit=15

Retrieves structured academic events, examination schedules, submission deadlines, and holidays.

• Query Parameters:
  • campus: PU, PCE, PIET, or ALL (default: ALL)
  • category: all, exam, submission, fee, holiday, event
  • daysAhead: Integer days to look ahead (default: 90)
  • limit: Max items to return (1–100, default: 25)

GET /api/test-models

Validates Gemini API key credentials and tests available model candidates (gemini-2.0-flash, gemini-1.5-flash, etc.).

POST /api/sync-notices
x-admin-key: <your_ADMIN_API_KEY>
Content-Type: application/json

{
  "dryRun": false
}

Triggers the live portal crawler and PDF circular extractor to vectorize and upsert new announcements into Pinecone.

POST /api/feedback
Content-Type: application/json

{
  "messageId": "msg_123456",
  "rating": 1,
  "comment": "Accurate details regarding exam timings."
}

Verify all subsystem components prior to production deployment:

# 1. Test syntax integrity
npm run check

# 2. Test Pinecone vector database connection
npm run test:pinecone

# 3. Test PDF parser on official circulars
npm run test:pdf

# 4. Test calendar filtering engine
npm run test:calendar

The static frontend is configured with a GitHub Actions workflow in .github/workflows/static.yml. Every push to main automatically deploys the frontend directly to GitHub Pages.

The backend can be hosted on Render, Railway, Google Cloud Run, or any Linux VPS:

# Production start via PM2
npm run start:prod

# Check logs
pm2 logs poornima-oracle

Make sure to set the environment variables in your hosting dashboard and configure CORS_ORIGIN to match your frontend domain.

Distributed under the MIT License. See LICENSE for details.

Developed with ❤️ by Sunny Kumar Dev for the students, faculty, and administration of the Poornima Group of Colleges.