Skip to content

README.md

Latest commit

 

History

History
320 lines (219 loc) · 8.13 KB

README.md

File metadata and controls

320 lines (219 loc) · 8.13 KB

🧠 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

QueryCortex 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

📜 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.