🧠 QueryCortex

An Agentic AI Platform for Deep Reasoning over Data & Documents

---

🚀 Overview

QueryCortex is a production-grade agentic AI orchestration platform designed to perform deep reasoning, intent understanding, and autonomous decision-making across:

• 📊 Structured data (SQL databases)
• 📄 Unstructured knowledge (PDFs, documents)
• 🔐 Role-aware enterprise environments

Unlike traditional chatbots, QueryCortex thinks before it answers.
It plans execution paths, validates reasoning, selects tools dynamically, and ensures responses are complete, explainable, and safe.

💡 Built for real-world systems where AI must operate across data silos, security boundaries, and business logic.

---

📑 Table of Contents

• System Architecture
• Core Capabilities
• Agentic Intelligence Layer
• Database Intelligence
• Observability & Auditability
• Timezone Handling
• Technology Stack
• Prerequisites
• Installation
• Configuration
• Running the Application
• Database Schema Overview
• Document Processing Pipeline
• Security & Compliance
• Video Walkthroughs
• License
• Contact

---

🗺️ System Architecture

QueryCortex uses a multi-agent reasoning architecture where each user query flows through an intelligent decision layer.

Depending on intent and context, the system dynamically selects:

• 📄 Semantic document reasoning (Vector-based RAG)
• 🗄️ Schema-aware SQL execution
• 🔁 Hybrid multi-hop reasoning pipelines

This ensures transparent, auditable AI workflows, not black-box responses.

---

✨ Core Capabilities

🔐 Secure Authentication & Stateful Sessions

• OAuth2-compliant authentication
• JWT-based access tokens (30-minute expiry)
• Secure logout with server-side invalidation
• Full session lifecycle tracking

👥 Role-Based Access Control (RBAC)

• Fine-grained authorization at query & document level
• Role-scoped default knowledge bases via ROLE_PDFS
• Strict isolation between roles and datasets

📄 Intelligent Document Intelligence (NLP + RAG)

• Role-aware PDF ingestion
• Semantic chunking and embeddings
• High-recall vector search with grounding
• Auto-loading of default documents at startup

---

🧠 Agentic Intelligence Layer

QueryCortex is not a simple chatbot — it is an agent-driven reasoning system.

🧩 Core Agents

• Intent Detection Agent

  • Deep NLP-based intent classification
  • Distinguishes analytical, informational, and operational queries

• Auto-Thinking Planning Agent

  • Decomposes complex queries into steps
  • Plans optimal execution order

• Routing & Strategy Agent

  • Selects SQL, RAG, or Hybrid execution
  • Prevents unsafe or invalid query paths

• Query Completion Checker

  • Ensures answers are complete and grounded
  • Prevents hallucinations and partial responses

• Reasoning Validator

  • Verifies alignment between intent, execution, and output

---

📊 Database Intelligence

• PostgreSQL-backed persistence layer
• SQLAlchemy ORM with schema introspection
• Safe, explainable SQL execution
• Natural-language-to-SQL reasoning with result interpretation

---

🧾 Observability & Auditability

• Full query execution history
• Latency and execution-time metrics
• Login metadata capture (IP, OS, browser, device)
• Secure logging with zero secret exposure

---

🌍 Timezone Handling

• All timestamps standardized to Asia/Kolkata
• Automatic handling of legacy offset-naive records

---

🏗️ Technology Stack

Layer	Technologies
Backend API	FastAPI
Authentication	OAuth2 · JWT
Database	PostgreSQL · SQLAlchemy
NLP & RAG	Vector Stores · Semantic Search
Agentic AI	Planning Agents · Reasoning Agents
Frontend	Vue 3 · Vite · TypeScript
Security	RBAC · CORS · Bcrypt

---

📦 Prerequisites

• Python ≥ 3.8
• PostgreSQL ≥ 12
• Node.js (Vite compatible)
• npm / pnpm

---

⚙️ Installation

1️⃣ Clone Repository

git clone https://github.com/shib1111111/QueryCortex
cd QueryCortex

2️⃣ Create Virtual Environment

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

3️⃣ Install Backend Dependencies

pip install -r requirements.txt

4️⃣ Frontend Setup

cd frontend
npm install

---

🔧 Configuration

Backend .env

DB_URI=postgresql://username:password@localhost:5432/querycortex
JWT_SECRET_KEY=your-secret-key
ANTHROPIC_API_KEY=your-anthropic-api-key

Frontend .env

VITE_BASE_URL=http://localhost:8080

Best Practices

• Generate JWT secret using: os.urandom(32).hex()
• Default role documents auto-load via ROLE_PDFS

---

▶️ Running the Application

Backend

uvicorn app:app --host 0.0.0.0 --port 8080

➡ API: http://localhost:8080

Frontend

cd frontend
npm run dev

➡ UI: http://localhost:5173

---

🗄️ Database Schema Overview

• User – identity and role metadata
• UserSession – token lifecycle management
• UserLog – authentication environment data
• Documents – role-based PDFs
• ChatHistory – reasoning trace & timing

---

📄 Document Processing Pipeline

1. Role-based PDF upload
2. Secure storage at ROOT_DIR/dataset/pdfs/<role>
3. Embedding generation
4. Semantic retrieval during agent execution

---

🔐 Security & Compliance

• JWT-secured endpoints
• Bcrypt password hashing
• Strict CORS enforcement
• Automatic session expiration
• No sensitive data in logs

---

🎥 Video Walkthroughs

• Agentic AI Architecture https://youtu.be/mWcpJCHRmog

• End-to-End System Demo https://youtu.be/E_-fb--rXds

---

📜 License

Released under the MIT License. See LICENSE for details.

---

📬 Contact

Shib Kumar 📧 shibkumarsaraf05@gmail.com 🐙 GitHub: https://github.com/shib1111111

---

⭐ If QueryCortex aligns with your vision for intelligent systems, consider starring the repository.