📊 GenQ Analytics

Transform raw datasets into intelligent, interactive reports powered by NVIDIA NIM or local AI.

Features • 📄 Sample Report • Quick Start • Architecture • Configuration • Contributing

---

✨ Features

• 🤖 AI-Powered Analysis — Upload any CSV/Excel dataset and get a structured analytical report generated by NVIDIA NIM or local Ollama.
• 💬 Context-Aware Chat — An interactive chat panel lets you ask follow-up questions about your data. The AI is grounded in your specific report, preventing hallucinations.
• 📈 Meaningful Visualizations — Automatically generates semantically relevant charts (bar, line, scatter, heatmap) based on the actual structure and relationships within your data.
• 📄 PDF Export — Export polished, chart-embedded PDF reports with a single click.
• 📚 Report Library — Browse, view, and manage all previously generated reports from a dedicated library page.
• 🔒 Provider Control — Use NVIDIA NIM for stronger hosted models, or switch back to Ollama for local-only processing.
• 🛡️ Extreme Reliability — Built-in exponential backoff for API network failures, 3-attempt code/JSON recovery loops, and secure sandboxed Python execution.

---

🚀 Quick Start

Prerequisites

Requirement	Version	Notes
Python	3.12+	Download
Node.js	18+	Download
NVIDIA API key	Active	Required for NVIDIA NIM mode
Ollama	Latest	Optional local fallback

1. Clone the Repository

git clone https://github.com/nisargpatel1906/genq-analytics.git
cd genq-analytics

2. Configure an AI Provider

The app supports NVIDIA NIM and Ollama. NVIDIA is the recommended provider for the model catalog in NVIDIA_Models_Guide.pdf.

LLM_PROVIDER=nvidia
LLM_MODE=agentic
LLM_FALLBACK_PROVIDER=ollama
LLM_MAX_REGENERATION_ROUNDS=3
NVIDIA_API_KEY=your_nvapi_key_here
NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1

# Defaults selected from NVIDIA_Models_Guide.pdf
LLM_DOMAIN_MODEL=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning
LLM_ANALYSIS_MODEL=nvidia/nemotron-3-super-120b-a12b
LLM_VISUAL_MODEL=nvidia/nemotron-3-super-120b-a12b
LLM_REPORT_MODEL=nvidia/llama-3.3-nemotron-super-49b-v1.5
LLM_REVIEW_MODEL=nvidia/llama-3.3-nemotron-super-49b-v1.5
LLM_CHAT_MODEL=nvidia/llama-3.3-nemotron-super-49b-v1.5

For local fallback, set LLM_PROVIDER=ollama.

Optional: Pull an Ollama Model

Make sure Ollama is running, then pull a model:

# Recommended (fast, fits on most GPUs)
ollama pull gemma4

# Alternatives
ollama pull llama3.1
ollama pull mistral

LLM_PROVIDER=ollama
OLLAMA_MODEL=gemma4:12b
OLLAMA_URL=http://localhost:11434

3. Set Up the Backend

cd backend

# Create and activate a virtual environment
python -m venv venv
.\venv\Scripts\activate        # Windows
# source venv/bin/activate     # macOS/Linux

# Install dependencies
pip install -r requirements.txt

# Configure environment
copy .env.example .env
# Edit .env and set NVIDIA_API_KEY, or switch LLM_PROVIDER=ollama

4. Set Up the Frontend

cd frontend
npm install

5. Launch the Application

From the project root, run the one-click launcher:

# Windows
start.bat

Or start each server manually:

# Terminal 1 - Backend (from /backend)
python -m uvicorn main:app --reload --port 8000

# Terminal 2 - Frontend (from /frontend)
npm run dev

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

---

🏗️ Architecture

genq-analytics/
├── backend/                    # FastAPI Python backend
│   ├── app/
│   │   ├── api/                # Endpoints for chat, export, CRUD, upload
│   │   └── db.py               # SQLite-backed persistent report store
│   ├── services/
│   │   ├── agent_graph.py      # Multi-agent state machine and orchestration
│   │   ├── agent_prompts.py    # LLM system prompts and instructions
│   │   ├── analyzer.py         # Main analysis pipeline manager
│   │   ├── code_executor.py    # Safe Python sandbox for visualization
│   │   └── llm.py              # LLM network wrapper with transient retries
│   ├── main.py                 # FastAPI application entry point
│   └── requirements.txt
│
├── frontend/                   # React + Vite + TypeScript frontend
│   ├── src/
│   │   ├── pages/
│   │   │   ├── Dashboard.tsx   # Main dashboard with AI chat panel
│   │   │   ├── Report.tsx      # Report viewer with charts
│   │   │   ├── Library.tsx     # Report library browser
│   │   │   └── Upload.tsx      # Dataset upload UI
│   │   ├── components/
│   │   │   ├── layout/         # Navbar, Footer
│   │   │   └── ui/             # Badge, Button primitives
│   │   └── store/
│   │       └── useChartStore.ts # Zustand chart state management
│   └── package.json
│
├── docker-compose.yml          # Docker orchestration
├── start.bat                   # Windows one-click launcher
└── README.md

How It Works

In agentic mode, the Data Profiler, Analytics Agent, Visualization Agent, and Report Writer run in sequence. The Quality Auditor then scores factual accuracy, chart relevance, and report quality. Rejected work is routed back only to the responsible agent and its dependents, with a maximum of three automatic regeneration rounds.

User uploads CSV/Excel
        ↓
  Backend parses file with Pandas
        ↓
  Data Profiler maps schema, statistics, quality, and domain
        ↓
  Analytics Agent produces evidence-backed findings
        ↓
  Visualization Agent creates validated chart specifications
        ↓
  Report Writer and Quality Auditor finalize the report
        ↓
  Report stored in reports.db (SQLite)
        ↓
  Frontend renders charts, agent stages, and audit score
        ↓
  User chats with report via /api/reports/{id}/chat

---

⚙️ Configuration

Backend (backend/.env)

# Provider selection
LLM_PROVIDER=nvidia          # nvidia or ollama
LLM_MODE=agentic             # agentic or single
LLM_FALLBACK_PROVIDER=ollama # optional fallback if NVIDIA fails
LLM_MAX_REGENERATION_ROUNDS=3

# NVIDIA NIM configuration
NVIDIA_API_KEY=your_key_here
NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
LLM_DOMAIN_MODEL=nvidia/nemotron-3-nano-omni-30b-a3b-reasoning
LLM_ANALYSIS_MODEL=nvidia/nemotron-3-super-120b-a12b
LLM_VISUAL_MODEL=nvidia/nemotron-3-super-120b-a12b
LLM_REPORT_MODEL=nvidia/llama-3.3-nemotron-super-49b-v1.5
LLM_REVIEW_MODEL=nvidia/llama-3.3-nemotron-super-49b-v1.5
LLM_CHAT_MODEL=nvidia/llama-3.3-nemotron-super-49b-v1.5

# Ollama fallback
OLLAMA_MODEL=gemma4:12b
OLLAMA_URL=http://localhost:11434

Frontend (frontend/.env or root .env)

VITE_API_URL=http://localhost:8000  # Backend API URL
VITE_APP_NAME=GenQ Analytics

Note: See .env.example files in each directory for all available options with descriptions.

---

🐳 Docker (Optional)

docker compose up -d --build

This starts the backend (port 8000), frontend (port 3000), and a Redis container (for async task queues). The SQLite database and data are safely persisted in Docker volumes across restarts. For NVIDIA mode, set NVIDIA_API_KEY in backend/.env; for Ollama mode, keep Ollama running on the host.

---

📡 API Reference

Method	Endpoint	Description
POST	/api/upload	Upload a CSV/Excel file for analysis
GET	/api/reports	List all generated reports
GET	/api/reports/{id}	Get a specific report's full data
DELETE	/api/reports/{id}	Delete a report
POST	/api/reports/{id}/chat	Send a chat message in report context
GET	/api/llm/status	Show configured domain, analysis, visual, report, review, and chat models
GET	/api/reports/{id}/export	Export report as PDF

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Commit your changes: git commit -m 'feat: add some feature'
4. Push to the branch: git push origin feature/your-feature-name
5. Open a Pull Request

Please make sure your code follows the existing style and that the backend and frontend both run without errors.

---

📄 License

This project is licensed under the GNU General Public License v3.0 — see the LICENSE file for details.

In short: you are free to use, modify, and distribute this software, but any derivative work must also be released under the GPL v3.

---

🙏 Acknowledgements

• NVIDIA NIM - For OpenAI-compatible hosted model inference.
• Ollama — For making local LLM inference simple and accessible.
• FastAPI — High-performance Python web framework.
• Recharts — Composable charting library for React.
• ReportLab — PDF generation for Python.

---

Built with ❤️ · Report a Bug · Request a Feature