1 line
18 KiB
JSON
1 line
18 KiB
JSON
{"repo": "aditya10045/conversational-analytics", "files": {"README.md": {"693ba52d99a3a23553096f4e3a1350e9a8616e9f": {"t": 1785746483.4766066, "n": 4079, "h": "672468685d939a4d", "c": "# Conversational Analytics\n\nAI-powered conversational analytics platform that converts natural language questions into SQL, generates business insights, and visualizes data through interactive dashboards.\n\n## Overview\n\nConversational Analytics enables users to explore business data using natural language instead of writing SQL manually.\n\nThe application uses a two-pass LLM architecture:\n\n1. **Pass 1 – SQL Generation**\n\n * Converts user questions into SQL queries.\n * Produces explanations and chart recommendations.\n\n2. **Pass 2 – Insight Generation**\n\n * Analyzes query results.\n * Generates business insights and summaries.\n\nThe platform includes SQL validation guardrails, read-only database access, interactive charts, and a modern chat-based user interface.\n\n---\n\n## Features\n\n* Natural Language → SQL conversion\n* AI-generated business insights\n* Interactive data visualizations\n* SQL query transparency\n* Read-only database architecture\n* Table-level access controls\n* SQL validation using sqlglot\n* Semantic caching support\n* OpenRouter and Groq model integration\n* Responsive Next.js frontend\n* FastAPI backend\n\n---\n\n## Architecture\n\nUser Question\n\n↓\n\nLLM Pass 1 (Text-to-SQL)\n\n↓\n\nSQL Validation & Guardrails\n\n↓\n\nPostgreSQL Database\n\n↓\n\nLLM Pass 2 (Insight Generation)\n\n↓\n\nCharts + Insights + Results\n\n---\n\n## Tech Stack\n\n### Frontend\n\n* Next.js\n* React\n* TypeScript\n* Tailwind CSS\n* Recharts\n\n### Backend\n\n* FastAPI\n* SQLAlchemy\n* Pydantic\n* Psycopg\n* sqlglot\n\n### AI Layer\n\n* OpenRouter\n* Groq\n* DeepSeek Models\n* Qwen Models\n\n### Database\n\n* PostgreSQL\n\n---\n\n## Project Structure\n\n```text\nconversational-analytics/\n│\n├── backend/\n│ ├── app/\n│ ├── requirements.txt\n│ ├── Dockerfile\n│ └── analytics.db\n│\n├── frontend/\n│ ├── app/\n│ ├── components/\n│ ├── lib/\n│ ├── package.json\n│ └── Dockerfile\n│\n├── sample_data/\n│ └── init.sql\n│\n├── .env.example\n└── README.md\n```\n\n---\n\n## Environment Setup\n\n### Backend\n\nCreate a `.env` file inside `backend/`.\n\nExample:\n\n```env\nOPENROUTER_API_KEY=your_api_key\n\nSQL_LLM_MODEL=deepseek/deepseek-chat-v3\n\nINSIGHT_LLM_MODEL=deepseek/deepseek-chat-v3\n\nINSIGHT_LLM_PROVIDER=openrouter\nINSIGHT_LLM_BASE_URL=https://openrouter.ai/api/v1\n\nDATABASE_URL=postgresql+psycopg://username:password@localhost:5432/analytics\n\nALLOWED_TABLES=sales_summary,orders,customers,revenue_by_region\n```\n\n### Frontend\n\nCreate a `.env` file inside `frontend/`.\n\n```env\nNEXT_PUBLIC_API_BASE_URL=http://localhost:8000/api/v1\n```\n\n---\n\n## Local Installation\n\n### Backend\n\n```bash\ncd backend\n\npython -m venv .venv\n\npip install -r requirements.txt\n\nuvicorn app.main:app --reload\n```\n\nBackend runs at:\n\n```text\nhttp://localhost:8000\n```\n\n---\n\n### Frontend\n\n```bash\ncd frontend\n\nnpm install\n\nnpm run dev\n```\n\nFrontend runs at:\n\n```text\nhttp://localhost:3000\n```\n\n---\n\n## Sample Questions\n\n* Which region generated the highest revenue?\n* Show monthly revenue trends for the last six months.\n* Compare customer segments by sales performance.\n* Which products contributed most to revenue growth?\n* Show revenue distribution by region.\n\n---\n\n## Security Guardrails\n\nThe platform implements multiple protections:\n\n* Read-only database access\n* Table whitelist enforcement\n* SQL AST validation\n* Blocked DDL/DML operations\n* Query timeout limits\n* Automatic row limits\n* Restricted schema access\n\nUnsupported operations include:\n\n* INSERT\n* UPDATE\n* DELETE\n* DROP\n* ALTER\n* TRUNCATE\n\n---\n\n## Demo Data\n\nThis repository includes a sample analytics database populated with fictional business data for demonstration and development purposes.\n\nNo real customer or production data is included.\n\n---\n\n## Future Improvements\n\n* Authentication and role-based access control\n* Dashboard sharing\n* Query history\n* Export to CSV and Excel\n* Multi-database support\n* Advanced chart recommendations\n* RAG-based business knowledge integration\n\n---\n\n## Author\n\nAditya S\n\nBuilt as part of an AI-powered analytics and business intelligence learning project demonstrating LLM-based Text-to-SQL workflows, insight generation, and interactive data visualization.\n"}, "7fd598a58bc37ec284429e7b2e4c89a3e0a8c9db": {"t": 1785764804.734755, "n": 4079, "h": "672468685d939a4d", "c": "# Conversational Analytics\n\nAI-powered conversational analytics platform that converts natural language questions into SQL, generates business insights, and visualizes data through interactive dashboards.\n\n## Overview\n\nConversational Analytics enables users to explore business data using natural language instead of writing SQL manually.\n\nThe application uses a two-pass LLM architecture:\n\n1. **Pass 1 – SQL Generation**\n\n * Converts user questions into SQL queries.\n * Produces explanations and chart recommendations.\n\n2. **Pass 2 – Insight Generation**\n\n * Analyzes query results.\n * Generates business insights and summaries.\n\nThe platform includes SQL validation guardrails, read-only database access, interactive charts, and a modern chat-based user interface.\n\n---\n\n## Features\n\n* Natural Language → SQL conversion\n* AI-generated business insights\n* Interactive data visualizations\n* SQL query transparency\n* Read-only database architecture\n* Table-level access controls\n* SQL validation using sqlglot\n* Semantic caching support\n* OpenRouter and Groq model integration\n* Responsive Next.js frontend\n* FastAPI backend\n\n---\n\n## Architecture\n\nUser Question\n\n↓\n\nLLM Pass 1 (Text-to-SQL)\n\n↓\n\nSQL Validation & Guardrails\n\n↓\n\nPostgreSQL Database\n\n↓\n\nLLM Pass 2 (Insight Generation)\n\n↓\n\nCharts + Insights + Results\n\n---\n\n## Tech Stack\n\n### Frontend\n\n* Next.js\n* React\n* TypeScript\n* Tailwind CSS\n* Recharts\n\n### Backend\n\n* FastAPI\n* SQLAlchemy\n* Pydantic\n* Psycopg\n* sqlglot\n\n### AI Layer\n\n* OpenRouter\n* Groq\n* DeepSeek Models\n* Qwen Models\n\n### Database\n\n* PostgreSQL\n\n---\n\n## Project Structure\n\n```text\nconversational-analytics/\n│\n├── backend/\n│ ├── app/\n│ ├── requirements.txt\n│ ├── Dockerfile\n│ └── analytics.db\n│\n├── frontend/\n│ ├── app/\n│ ├── components/\n│ ├── lib/\n│ ├── package.json\n│ └── Dockerfile\n│\n├── sample_data/\n│ └── init.sql\n│\n├── .env.example\n└── README.md\n```\n\n---\n\n## Environment Setup\n\n### Backend\n\nCreate a `.env` file inside `backend/`.\n\nExample:\n\n```env\nOPENROUTER_API_KEY=your_api_key\n\nSQL_LLM_MODEL=deepseek/deepseek-chat-v3\n\nINSIGHT_LLM_MODEL=deepseek/deepseek-chat-v3\n\nINSIGHT_LLM_PROVIDER=openrouter\nINSIGHT_LLM_BASE_URL=https://openrouter.ai/api/v1\n\nDATABASE_URL=postgresql+psycopg://username:password@localhost:5432/analytics\n\nALLOWED_TABLES=sales_summary,orders,customers,revenue_by_region\n```\n\n### Frontend\n\nCreate a `.env` file inside `frontend/`.\n\n```env\nNEXT_PUBLIC_API_BASE_URL=http://localhost:8000/api/v1\n```\n\n---\n\n## Local Installation\n\n### Backend\n\n```bash\ncd backend\n\npython -m venv .venv\n\npip install -r requirements.txt\n\nuvicorn app.main:app --reload\n```\n\nBackend runs at:\n\n```text\nhttp://localhost:8000\n```\n\n---\n\n### Frontend\n\n```bash\ncd frontend\n\nnpm install\n\nnpm run dev\n```\n\nFrontend runs at:\n\n```text\nhttp://localhost:3000\n```\n\n---\n\n## Sample Questions\n\n* Which region generated the highest revenue?\n* Show monthly revenue trends for the last six months.\n* Compare customer segments by sales performance.\n* Which products contributed most to revenue growth?\n* Show revenue distribution by region.\n\n---\n\n## Security Guardrails\n\nThe platform implements multiple protections:\n\n* Read-only database access\n* Table whitelist enforcement\n* SQL AST validation\n* Blocked DDL/DML operations\n* Query timeout limits\n* Automatic row limits\n* Restricted schema access\n\nUnsupported operations include:\n\n* INSERT\n* UPDATE\n* DELETE\n* DROP\n* ALTER\n* TRUNCATE\n\n---\n\n## Demo Data\n\nThis repository includes a sample analytics database populated with fictional business data for demonstration and development purposes.\n\nNo real customer or production data is included.\n\n---\n\n## Future Improvements\n\n* Authentication and role-based access control\n* Dashboard sharing\n* Query history\n* Export to CSV and Excel\n* Multi-database support\n* Advanced chart recommendations\n* RAG-based business knowledge integration\n\n---\n\n## Author\n\nAditya S\n\nBuilt as part of an AI-powered analytics and business intelligence learning project demonstrating LLM-based Text-to-SQL workflows, insight generation, and interactive data visualization.\n"}, "08752d6a798fdfebce1b8f9c893fb4046532aa55": {"t": 1785764806.0681076, "n": 4102, "h": "9896f33f90df36c4", "c": "# Conversational Analytics\n\nAI-powered conversational analytics platform that converts natural language questions into SQL, generates business insights, and visualizes data through interactive dashboards.\n\n## Overview\n\nConversational Analytics enables users to explore business data using natural language instead of writing SQL manually.\n\nThe application uses a two-pass LLM architecture:\n\n1. **Pass 1 – SQL Generation**\n\n * Converts user questions into SQL queries.\n * Produces explanations and chart recommendations.\n\n2. **Pass 2 – Insight Generation**\n\n * Analyzes query results.\n * Generates business insights and summaries.\n\nThe platform includes SQL validation guardrails, read-only database access, interactive charts, and a modern chat-based user interface.\n\n---\n\n## Features\n\n* Natural Language → SQL conversion\n* AI-generated business insights\n* Interactive data visualizations\n* SQL query transparency\n* Read-only database architecture\n* Table-level access controls\n* SQL validation using sqlglot\n* Semantic caching support\n* OpenRouter and Groq model integration\n* Responsive Next.js frontend\n* FastAPI backend\n\n---\n\n## Architecture\n\nUser Question\n\n↓\n\nLLM Pass 1 (Text-to-SQL)\n\n↓\n\nSQL Validation & Guardrails\n\n↓\n\nPostgreSQL Database\n\n↓\n\nLLM Pass 2 (Insight Generation)\n\n↓\n\nCharts + Insights + Results\n\n---\n\n## Tech Stack\n\n### Frontend\n\n* Next.js\n* React\n* TypeScript\n* Tailwind CSS\n* Recharts\n\n### Backend\n\n* FastAPI\n* SQLAlchemy\n* Pydantic\n* Psycopg\n* sqlglot\n\n### AI Layer\n\n* OpenRouter\n* Groq\n* DeepSeek Models\n* Qwen Models\n\n### Database\n\n* PostgreSQL\n\n---\n\n## Project Structure\n\n```text\nconversational-analytics/\n│\n├── backend/\n│ ├── app/\n│ ├── requirements.txt\n│ ├── Dockerfile\n│ └── analytics.db\n│\n├── frontend/\n│ ├── app/\n│ ├── components/\n│ ├── lib/\n│ ├── package.json\n│ └── Dockerfile\n│\n├── sample_data/\n│ └── init.sql\n│\n├── docker-compose.yml\n├── .env.example\n└── README.md\n```\n\n---\n\n## Environment Setup\n\n### Backend\n\nCreate a `.env` file inside `backend/`.\n\nExample:\n\n```env\nOPENROUTER_API_KEY=your_api_key\n\nSQL_LLM_MODEL=deepseek/deepseek-chat-v3\n\nINSIGHT_LLM_MODEL=deepseek/deepseek-chat-v3\n\nINSIGHT_LLM_PROVIDER=openrouter\nINSIGHT_LLM_BASE_URL=https://openrouter.ai/api/v1\n\nDATABASE_URL=postgresql+psycopg://username:password@localhost:5432/analytics\n\nALLOWED_TABLES=sales_summary,orders,customers,revenue_by_region\n```\n\n### Frontend\n\nCreate a `.env` file inside `frontend/`.\n\n```env\nNEXT_PUBLIC_API_BASE_URL=http://localhost:8000/api/v1\n```\n\n---\n\n## Local Installation\n\n### Backend\n\n```bash\ncd backend\n\npython -m venv .venv\n\npip install -r requirements.txt\n\nuvicorn app.main:app --reload\n```\n\nBackend runs at:\n\n```text\nhttp://localhost:8000\n```\n\n---\n\n### Frontend\n\n```bash\ncd frontend\n\nnpm install\n\nnpm run dev\n```\n\nFrontend runs at:\n\n```text\nhttp://localhost:3000\n```\n\n---\n\n## Sample Questions\n\n* Which region generated the highest revenue?\n* Show monthly revenue trends for the last six months.\n* Compare customer segments by sales performance.\n* Which products contributed most to revenue growth?\n* Show revenue distribution by region.\n\n---\n\n## Security Guardrails\n\nThe platform implements multiple protections:\n\n* Read-only database access\n* Table whitelist enforcement\n* SQL AST validation\n* Blocked DDL/DML operations\n* Query timeout limits\n* Automatic row limits\n* Restricted schema access\n\nUnsupported operations include:\n\n* INSERT\n* UPDATE\n* DELETE\n* DROP\n* ALTER\n* TRUNCATE\n\n---\n\n## Demo Data\n\nThis repository includes a sample analytics database populated with fictional business data for demonstration and development purposes.\n\nNo real customer or production data is included.\n\n---\n\n## Future Improvements\n\n* Authentication and role-based access control\n* Dashboard sharing\n* Query history\n* Export to CSV and Excel\n* Multi-database support\n* Advanced chart recommendations\n* RAG-based business knowledge integration\n\n---\n\n## Author\n\nAditya S\n\nBuilt as part of an AI-powered analytics and business intelligence learning project demonstrating LLM-based Text-to-SQL workflows, insight generation, and interactive data visualization.\n"}, "442d7e864da1c14b10a32a8de485ec365c3b5f10": {"t": 1785764807.4897845, "n": 4331, "h": "81bc9a6e0911de7f", "c": "# Conversational Analytics MVP (Open-Source Models + SQL Warehouse)\n\nThis project is a full-stack MVP for conversational analytics using a **two-pass Text-to-SQL architecture** with open-source models.\n\n- Pass 1 (SQL generation): coder model (OpenRouter)\n- Pass 2 (insight generation): reasoning model (Groq/OpenRouter)\n- Backend: FastAPI + SQLAlchemy + sqlglot guardrails\n- Frontend: Next.js + Tailwind + Recharts\n\n## What Changed\n\nThe stack is now optimized for your open-source model strategy:\n\n- Replaced Claude-only integration with **OpenAI-compatible provider routing**\n- Added **separate model/provider config for each pass**\n- Added **JSON schema structured output enforcement** (`response_format: json_schema`) with automatic fallback for unsupported routes\n- Kept strict SQL validation/security boundary in middleware\n\n## Two-Pass Flow\n\n1. User asks a question in chat UI\n2. Backend sends schema + business rules + question to pass-1 model\n3. Pass-1 model returns strict JSON: `sql`, `explanation`, `chart_recommendation`\n4. Backend validates SQL (`sqlglot`) and executes read-only query\n5. Backend sends SQL + result rows + aggregates to pass-2 model\n6. Pass-2 model returns structured business insights JSON\n7. Frontend renders narrative, SQL, chart, and table\n\n## Security Guardrails\n\n- Read-only DB user (`analytics_ro`)\n- Table whitelist (`ALLOWED_TABLES`)\n- SQL AST validation with `sqlglot`\n- Rejects:\n - comments\n - semicolons\n - multi-statements\n - DDL/DML (INSERT/UPDATE/DELETE/DROP/ALTER/TRUNCATE/...)\n - unknown tables\n- Auto-adds `LIMIT` if absent\n- Query timeout via `SET LOCAL statement_timeout`\n\n## Model Routing Configuration\n\nUse separate API routes/models per pass:\n\n- **Pass 1 (SQL):** OpenRouter + `qwen/qwen-2.5-coder-32b-instruct` (default)\n- **Pass 2 (Insights):** Groq + `openai/gpt-oss-120b` (default)\n\nYou can swap models without code changes using env vars.\n\n## Environment Variables\n\n### Root `.env`\n\n```bash\nOPENROUTER_API_KEY=your_openrouter_api_key\nGROQ_API_KEY=your_groq_api_key\n```\n\n### Backend `backend/.env`\n\nCopy from [backend/.env.example](C:\\Users\\adity\\Documents\\Codex\\2026-05-28\\think-like-an-expert-llm-solution\\backend\\.env.example).\n\nImportant fields:\n\n- `SQL_LLM_BASE_URL` (default `https://openrouter.ai/api/v1`)\n- `SQL_LLM_MODEL`\n- `SQL_LLM_API_KEY` (or `OPENROUTER_API_KEY`)\n- `INSIGHT_LLM_BASE_URL` (default `https://api.groq.com/openai/v1`)\n- `INSIGHT_LLM_MODEL`\n- `INSIGHT_LLM_API_KEY` (or `GROQ_API_KEY`)\n- `LLM_USE_JSON_SCHEMA=true`\n- `DATABASE_URL`\n- `ALLOWED_TABLES`\n\n### Frontend `frontend/.env`\n\n```bash\nNEXT_PUBLIC_API_BASE_URL=http://localhost:8000/api/v1\n```\n\n## Run with Docker\n\n1. Copy root env:\n\n```bash\ncp .env.example .env\n```\n\n2. Add keys to `.env`\n\n3. Start:\n\n```bash\ndocker compose up --build\n```\n\n4. Open:\n\n- Frontend: [http://localhost:3000](http://localhost:3000)\n- Backend health: [http://localhost:8000/api/v1/health](http://localhost:8000/api/v1/health)\n\n## Run Locally\n\n### Backend\n\n```bash\ncd backend\npython -m venv .venv\n.\\.venv\\Scripts\\Activate.ps1\npip install -r requirements.txt\ncopy .env.example .env\nuvicorn app.main:app --reload --port 8000\n```\n\n### Frontend\n\n```bash\ncd frontend\nnpm install\ncopy .env.example .env\nnpm run dev\n```\n\n## Sample Questions\n\n- Which regions had highest growth last quarter?\n- Show monthly revenue trend by region for the last 6 months.\n- Which customer segment has the strongest gross margin?\n- Compare quarter-over-quarter margin change by region.\n\n## Key Files\n\n- API dependency wiring: [backend/app/api/dependencies.py](C:\\Users\\adity\\Documents\\Codex\\2026-05-28\\think-like-an-expert-llm-solution\\backend\\app\\api\\dependencies.py)\n- Open-source LLM integration: [backend/app/llm/open_source_service.py](C:\\Users\\adity\\Documents\\Codex\\2026-05-28\\think-like-an-expert-llm-solution\\backend\\app\\llm\\open_source_service.py)\n- SQL guardrails: [backend/app/utils/sql_validator.py](C:\\Users\\adity\\Documents\\Codex\\2026-05-28\\think-like-an-expert-llm-solution\\backend\\app\\utils\\sql_validator.py)\n- Orchestrator: [backend/app/services/orchestrator.py](C:\\Users\\adity\\Documents\\Codex\\2026-05-28\\think-like-an-expert-llm-solution\\backend\\app\\services\\orchestrator.py)\n- Seeded demo schema/data: [sample_data/init.sql](C:\\Users\\adity\\Documents\\Codex\\2026-05-28\\think-like-an-expert-llm-solution\\sample_data\\init.sql)\n"}}}} |