Acadence AI

AI-Powered Academic Intelligence Platform with Adaptive Hybrid + Agentic RAG

Acadence AI is a multi-tenant AI-powered academic automation platform designed for large-scale educational datasets. It combines adaptive Hybrid RAG, intelligent agents, SQL-grounded reasoning, semantic retrieval, and automation workflows to deliver accurate, grounded, and conversational insights over academic records in real time.

The platform keeps each tenant's data, logs, and agent activity isolated so multiple institutions can use the same deployment without seeing each other's records.

Built for real-world educational institutions, the platform enables teachers, students, parents, and administrators to query complex academic datasets naturally while minimizing hallucinations through database-verified responses and grounded retrieval pipelines.

---

Core Features

Adaptive Hybrid + Agentic RAG

Intelligent Query Orchestration

• Adaptive LLM-driven query planning
• Hybrid SQL + semantic retrieval orchestration
• Multi-step reasoning workflows
• Context reranking and validation
• Conversational multi-turn memory
• Hallucination prevention pipeline
• Database-grounded response generation
• Rule-based routing and intent handling as a fallback reliability layer
• Safe fallback execution for low-confidence or ambiguous queries

---

Intelligent Academic Querying

Supports natural language questions such as:

• "Who are the top 10 students?"
• "Compare semester 4 toppers with semester 5 performance"
• "Which students are underperforming in DSA?"
• "Summarize class performance trends"
• "Which students improved the most?"

The system dynamically determines whether the query requires:

• SQL retrieval
• semantic retrieval (FAISS or pgvector)
• hybrid retrieval
• analytics reasoning
• multi-step orchestration

---

Key Capabilities

Large-Scale Tabular Data Processing

• Handles massive academic datasets
• Multi-column student result processing
• CSV, Excel, and PDF ingestion
• Schema normalization and validation
• Duplicate detection and cleaning

SQL-Grounded AI

• LLM dynamically generates SQL queries
• PostgreSQL acts as the source of truth
• Rankings, analytics, filtering, and aggregations are database verified
• Prevents fabricated academic values

Semantic Retrieval

• Vector retrieval (FAISS or pgvector)
• Context-aware semantic search
• Similarity-based chunk retrieval
• Reranking for high-confidence context selection

Intelligent Agents

• Query planning agents
• Retrieval orchestration agents
• Analytics reasoning workflows
• Email automation agents
• Multi-step reasoning pipelines

Email Automation

• Automated academic workflow processing
• Gmail attachment ingestion
• Automated report generation
• Notification workflows

---

Architecture

User Query
    ↓
LLM Query Planner
    ↓
Dynamic Tool Selection

IF structured:
→ SQL generation
→ PostgreSQL execution
→ verified structured data

IF semantic:
→ FAISS or `pgvector` retrieval
→ reranker
→ grounded context

IF hybrid:
→ SQL + semantic retrieval
→ context fusion
→ reranking

→ grounded LLM response

Tech Stack

Layer	Technology
Frontend	React, Vite, Tailwind CSS
Backend	FastAPI, Python
Database	PostgreSQL
Semantic Retrieval	Postgres (pgvector) [default] / FAISS (optional)
AI Layer	Gemini / LLM
Parsing	LlamaParse, Pandas
Automation	Gmail Automation
Cloud	GCP, Cloud Storage
Vector Embeddings	Sentence Transformers
Orchestration	Agentic RAG Workflows

---

Quick Start

Prerequisites

• Python 3.9+ (3.11 recommended)
• Node.js 18+ and npm/yarn
• PostgreSQL 12+ running and reachable via DATABASE_URL
• (Optional) Elasticsearch and Redis for advanced features

1. Clone the Repository

git clone https://github.com/3015pavan/Acadence-Ai.git
cd Acadence-Ai

2. Configure the Environment

Create a .env file in the repository root and set the required variables:

DATABASE_URL=postgresql://user:password@localhost:5432/acadence_ai_db
AUTH_SECRET=change-me-in-production
BOOTSTRAP_ADMIN_EMAIL=admin@example.com
BOOTSTRAP_ADMIN_PASSWORD=change-me
GCP_GEMINI_KEY=your_api_key_here
GEMINI_MODEL=gemini-2.5-flash
GEMINI_THINKING_LEVEL=low
GMAIL_SERVICE_ACCOUNT_JSON=path/to/credentials.json
ELASTICSEARCH_URL=http://localhost:9200
ACCESS_TOKEN_TTL_SECONDS=1800
REFRESH_TOKEN_TTL_SECONDS=1209600

3. Install Dependencies

# Backend
python -m venv .venv
.venv\Scripts\activate
python -m pip install -r requirements.txt

# Frontend
cd frontend
npm install

4. Apply Database Migrations

cd ..
alembic upgrade head

5. Start Services

Backend

cd backend
python -m uvicorn main:app --reload --host 127.0.0.1 --port 8000

Frontend

cd frontend
npm run dev

Email Agent (Optional)

python backend/agents/email_agent.py

6. Verify the App

• Health: GET /health at http://127.0.0.1:8000/health
• Docs: http://127.0.0.1:8000/docs
• Frontend: http://127.0.0.1:5173

---

Getting Started: Two Paths

Path 1: Web Interface (Manual Upload)

Perfect for testing, ad-hoc analysis, and interactive exploration.

1. Navigate to http://127.0.0.1:5173
2. Go to Upload Page and drop an Excel or PDF file
3. View Dashboard with instant analytics
4. Use Query Chat for natural language questions

Path 2: Email Automation (Hands-Free Processing)

Perfect for institutions with regular result batches.

1. Setup Gmail Integration (see Email Automation Setup)
2. Start the email agent: python backend/agents/email_agent.py
3. Send result files to the monitored Gmail address
4. Agent automatically:
   • ✅ Detects emails with attachments
   • ✅ Processes .xlsx and .pdf files
   • ✅ Generates PDF analysis reports
   • ✅ Replies with insights and download links

---

API Reference

Query Endpoint

POST /analytics/query
Content-Type: application/json

{
  "query": "Who are the top 5 performers?",
  "file_ids": [],           # Empty = all datasets
  "history": []             # Chat history (optional)
}

Response:

{
  "intent": "CONTEXTUAL_ANSWER",
  "answer": "The top performers are...",
  "students": [
    {"name": "Student A", "sgpa": 9.2},
    {"name": "Student B", "sgpa": 9.0}
  ],
  "meta": {
    "confidence": 0.95,
    "citations": ["Student A: SGPA 9.2", "Student B: SGPA 9.0"]
  }
}

Core Endpoints

# List all datasets
GET /analytics/datasets

# Upload file
POST /upload/file
Content-Type: multipart/form-data

# Delete dataset (cleanup)
DELETE /analytics/datasets/{dataset_id}

# Rebuild search index
POST /analytics/reindex

---

Query Examples

Your Question	Intent Type	Result
Who are the toppers?	SQL_QUERY	Database-verified list with SGPA
Students with A+ but failed	HYBRID	SQL + semantic analysis
Average SGPA in DSA subject	SQL_AGGREGATION	Database computed statistic
Result of Abir in DSA	SQL_LOOKUP	Database-verified record
Pass rate by semester	SQL_ANALYTICS	Cross-tabulated summary
Summarize this class	SEMANTIC + ANALYTICS	LLM narrative with DB-grounded insights
Who needs support?	HYBRID	At-risk identification with reasoning

---

Configuration

Environment Variables (.env)

# Database Connection
DATABASE_URL=postgresql://user:password@localhost:5432/acadence_ai_db

# LLM Configuration (Google Gemini)
GCP_GEMINI_KEY=your_api_key_here
GEMINI_MODEL=gemini-2.5-flash
GEMINI_THINKING_LEVEL=low

# Gmail Integration (Optional)
GMAIL_SERVICE_ACCOUNT_JSON=path/to/credentials.json
GMAIL_INBOX_CHECK_INTERVAL=300  # seconds

# Multi-tenant configuration
# An example tenant-aware variable: when running a single-instance multi-tenant deployment,
# tenants are represented in the database. Per-tenant storage paths and tokens are namespaced
# by `owner_user_id` or `tenant_id` (e.g. `backend/storage/gmail_tokens/tenant_<id>.json`).
# No global token files are used in production; ensure your deployment scripts create
# per-tenant directories with correct permissions.

# Search Backends (Optional)
ELASTICSEARCH_URL=http://localhost:9200
REDIS_URL=redis://localhost:6379

# API Configuration
API_PORT=8000
FRONTEND_URL=http://127.0.0.1:5173

---

Email Automation Setup

Automate your entire student results processing pipeline — From inbox to insights in minutes.

Step 1: Create Google Cloud Service Account

1. Go to Google Cloud Console
2. Create a new project (or use existing)
3. Create a new service account
4. Download private key as JSON (credentials.json)
5. Place in project root

Step 2: Enable Gmail API

1. In Google Cloud Console, search for "Gmail API"
2. Click Enable
3. Go to Service Account details
4. Grant access to your Gmail address

Step 3: Configure Environment

GMAIL_SERVICE_ACCOUNT_JSON=./credentials.json
GMAIL_INBOX_CHECK_INTERVAL=300

Step 4: Start Email Agent

python backend/agents/email_agent.py

Note: the email agent uses per-tenant token files and per-tenant job ids (e.g. email-agent-poll-<tenant_id>). If running multiple tenants on one host, ensure the agent is started in a way that isolates per-tenant tokens and storage directories (or run separate agent processes per tenant).

Email Processing Workflow

📧 Incoming Email
   ↓
📎 Detect Attachment (.xlsx, .pdf)
   ↓
⚙️ Parse & Validate Data
   ↓
📊 Generate PDF Report
   ↓
💾 Store Results & Index
   ↓
✉️ Auto-Reply with Link

---

Performance & Scaling

• FAISS / pgvector Indexing: ~1M vectors, <100ms search latency (depends on storage and infra)
• Elasticsearch: Full-text search over 100K+ documents
• PostgreSQL: Sub-50ms indexed queries on 10K+ records
• LLM Response Time: ~2-5s (including context retrieval)
• Cache Hit Rate: 70%+ for repeated queries with Redis
• Concurrent Users: Tested with 50+ concurrent connections

---

Reliability & Evaluation

The platform includes production-grade evaluation and monitoring pipelines for:

• Hallucination Rate
• Query Accuracy
• Recall@K
• Precision@K
• Groundedness Score
• Faithfulness Score
• SQL Execution Accuracy
• Retrieval Precision
• Multi-turn Context Accuracy
• Workflow Success Rate
• End-to-End Latency

---

Testing

Smoke Tests (Quick Validation)

# Start backend first, then:
python tools/smoke_test_query.py "Summarize this class"

Query Validation Suite

python TEST_QUERIES_VALIDATION.py

Integration Tests

pip install -r requirements.txt
pytest -v

Evaluation Report

python tools/evaluate.py

---

Use Cases

Teachers

• Analyze student performance
• Identify weak students
• Compare semester trends
• Generate reports automatically

Students

• Query marks and analytics
• Understand performance trends
• Track academic progress

Parents

• Monitor student performance
• View attendance and results
• Understand strengths and weaknesses

Institutions

• Automate result processing
• Generate analytics dashboards
• Enable AI-driven academic intelligence

---

Documentation

Learn More

• 📚 Project Structure: See backend/ and frontend/ directories
• 🔌 API Endpoints: Full docs in backend/routes/
• ⚙️ Query Engine: Core logic in backend/services/query_engine.py
• 🤖 LLM Integration: See backend/services/intelligence.py
• 📧 Email Agent: Details in backend/agents/email_agent.py

---

Roadmap

• Multimodal RAG support
• Predictive analytics
• Real-time streaming ingestion
• Advanced analytics agents
• Personalized academic recommendations
• Distributed vector search
• Role-aware reasoning pipelines
• Multi-language support

---

Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request with description

Development Setup

git clone https://github.com/3015pavan/Acadence_Ai.git 
cd agent_edata
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -r requirements.txt

---

Support & Troubleshooting

Common Issues

"LLM Provider not responding"

# Check your API key
echo $GCP_GEMINI_KEY  # Should show your Gemini API key

# Test the connection
python -c "from backend.services.intelligence import _llm_chat_json"

"Database connection failed"

# Verify PostgreSQL is running
psql -U user -d acadence_ai_db -c "SELECT 1"

# Check DATABASE_URL in .env is correct

"No results found for query"

# Ensure files are uploaded
curl http://127.0.0.1:8000/analytics/datasets

# Check dashboard for parse errors

Get Help

• 📖 Check Documentation
• 🐛 Open an Issue
• 💬 Start a Discussion

---

Why Acadence AI?

Unlike traditional rule-based academic chatbots, Acadence AI uses adaptive Hybrid + Agentic RAG to dynamically reason over structured and semantic academic data. The system is designed to answer arbitrary natural language questions over large academic datasets while maintaining grounded, verifiable, and reliable responses.

---

Performance Goals

• Low hallucination rate
• High retrieval precision
• SQL-grounded correctness
• Adaptive query handling
• Production-grade scalability
• Real-time conversational analytics

---

Author

Pavan Reddy

Building production-grade AI systems focused on adaptive RAG architectures, intelligent agents, semantic retrieval, automation workflows, and grounded AI reasoning over large-scale datasets.

---

Acadence AI — AI-Powered Academic Intelligence Platform

Have questions? Open an Issue | Start a Discussion | Email Us

⭐ If Acadence AI helps you, please star us on GitHub! ⭐ Star

---