Sajid1974/Socratic_QA_GenAI_Tutor

Socratic Q/A Generative AI Tutoring System

A production-ready modular repository for guided reasoning tutoring that emphasizes Socratic questioning, conceptual evaluation, and tiered hinting instead of direct answers.

System Overview

This system is designed for research and deployment on Hugging Face Spaces (CPU) with:

• —Frontend: Gradio
• —LLM Inference: GROQ API (llama3-70b-8192)
• —Knowledge Retrieval: Local FAISS vector store with sentence-transformers embeddings
• —Document Support: Digital and scanned PDFs via parser + OCR

Pedagogical Behavior

The tutor is policy-bound to:

• —Avoid direct answers and full worked solutions
• —Ask guiding Socratic prompts
• —Provide scaffolded hints (levels 0–3)
• —Diagnose misconceptions and understanding levels
• —Log session-level analytics for research

Repository Structure

/app.py
/requirements.txt
/README.md

/agents
   socratic_agent.py
   evaluation_agent.py
   orchestration_agent.py
   ingestion_agent.py

/engines
   rag_engine.py
   hint_policy_engine.py
   misconception_engine.py

/utils
   pdf_parser.py
   ocr_engine.py
   embedding_indexer.py
   prompt_templates.py
   confidence_scorer.py

/data
   vector_store/

/outputs
   session_logs.json

Architecture Diagram

flowchart TD
    A[Upload PDFs] --> B[Ingestion Agent]
    B --> C{Digital or Scanned?}
    C -->|Digital| D[PDF Parser]
    C -->|Scanned| E[OCR Engine]
    D --> F[Chunk + Embed]
    E --> F
    F --> G[FAISS Vector Store]

    H[Student Query] --> I[RAG Engine]
    G --> I
    I --> J[Orchestration Agent]
    J --> K[Hint Policy Engine]
    J --> L[Misconception Engine]
    I --> M[Socratic Agent via GROQ]
    K --> M
    L --> M
    M --> N[Socratic Response]

    H --> O[Evaluation Agent]
    N --> O
    O --> P[Confidence Scorer]
    P --> Q[Session Logs]

End-to-End Flow

1. 1.Upload PDFs
2. 2.Parse digital text + OCR scanned pages
3. 3.Chunk text by concept and embed
4. 4.Store in FAISS local vector index
5. 5.Accept student query
6. 6.Retrieve top-k relevant chunks
7. 7.Apply orchestration policy (intent + difficulty + hint style)
8. 8.Generate Socratic LLM output
9. 9.Evaluate conceptual quality and mastery score
10. 10.Persist logs in outputs/session_logs.json

Deployment (Hugging Face Spaces)

1) Create Space

• —Create a new Gradio Space on Hugging Face.
• —Set repository files to this project structure.

2) Add dependencies

Use requirements.txt as provided.

3) Configure GROQ key

In Space settings → Variables and secrets:

• —Key: GROQ_API_KEY
• —Value: your free GROQ API key

4) Run

app.py launches Gradio at startup. The app stores vectors in data/vector_store and session logs in outputs/session_logs.json.

GROQ Setup

1. 1.Create an account at https://console.groq.com
2. 2.Generate an API key
3. 3.Export locally for testing:

export GROQ_API_KEY="your_key_here"
python app.py

Local Development

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.py

Notes for CPU Spaces

• —all-MiniLM-L6-v2 is lightweight enough for CPU use.
• —OCR quality depends on Poppler + Tesseract availability in runtime.
• —If OCR system binaries are unavailable, digital PDF parsing still works.
• —Multi-session support is implemented with per-session IDs and append-only logs.

Research Logging Schema

Each turn logs:

• —query
• —generated Socratic response
• —hint level and routing policy
• —misconception status/type
• —evaluation metrics and mastery score
• —confidence estimate
• —learning mode
• —timestamp and session ID

This supports longitudinal analysis of conceptual growth and hint efficacy.