NQRust-Analytics

Open-Source Analytics Platform with AI-Powered Natural Language Querying

NQRust-Analytics is a comprehensive analytics platform that enables users to query databases using natural language, generate accurate SQL queries, create visualizations, and gain AI-powered insights.

---

✨ Features

Core Capabilities

• Natural Language to SQL: Convert plain English questions into accurate SQL queries
• Multi-Database Support: Connect to various data sources seamlessly
• AI-Powered Insights: Get intelligent analysis and recommendations
• Interactive Visualizations: Auto-generate charts and dashboards
• Semantic Layer: MDL (Modeling Definition Language) for consistent data definitions
• Real-time Analytics: Process and analyze data in real-time

User Management & Collaboration

• User Authentication: Built-in user registration and login with email/password
• OAuth Support: Optional Google and GitHub OAuth integration
• Role-Based Access Control (RBAC): Admin, Editor, and Viewer roles
• Multi-Dashboard Support: Create and manage multiple dashboards per user
• Dashboard Sharing: Share dashboards with other users (view or edit permissions)
• Chat History Sharing: Share conversation threads with team members
• Starred Dashboards: Bookmark frequently used dashboards

Key Benefits

• No SQL Knowledge Required: Business users can query data without technical expertise
• Accurate Results: Semantic layer ensures consistent and governed data access
• Flexible LLM Integration: Support for multiple AI model providers
• Self-Hosted: Full control over your data and infrastructure
• Team Collaboration: Share insights and dashboards across your organization

---

🔌 Supported Data Sources

• Cloud Data Warehouses: Snowflake, BigQuery, Redshift, Azure Synapse
• Relational Databases: PostgreSQL, MySQL, SQL Server, Oracle
• Analytics Engines: DuckDB, Trino, ClickHouse, Athena
• And more: Extensible architecture for custom connectors

---

🤖 Supported LLM Models

• OpenAI (GPT-4, GPT-3.5)
• Azure OpenAI
• Google Gemini (AI Studio & Vertex AI)
• Anthropic Claude (API & Bedrock)
• DeepSeek
• Groq
• Ollama (Local models)
• Databricks

See configuration examples for setup details.

---

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• OpenAI API key (or other LLM provider)
• Minimum 4GB RAM

Installation

1. Clone the repository

   git clone https://github.com/NexusQuantum/NQRust-Analytics.git
   cd NQRust-Analytics

2. Configure environment

   cd docker
   cp .env.example .env

   Edit .env and configure the following:

   • PROJECT_DIR: Set to your local project path
   • OPENAI_API_KEY: Your OpenAI API key (or configure alternative LLM)
   • JWT_SECRET: Required - Set a secure random string for authentication
   • PG_URL: PostgreSQL connection string for the application database
   • OAuth settings (optional): Configure Google/GitHub OAuth if needed

3. Start services

   docker-compose up -d

4. Run database migrations

   # The migrations set up user management, dashboards, and sharing features
   cd ../analytics-ui
   npm install  # or yarn install
   DB_TYPE=pg PG_URL="postgres://analytics:analytics123@localhost:5432/analytics" npx knex migrate:latest

5. Access the application

   • UI: http://localhost:3000
   • API: http://localhost:5556

6. First-time setup

   • Register a new account (first user becomes admin)
   • Or login with OAuth if configured
   • Create your first dashboard and start querying

Development Setup

See individual service README files for detailed development instructions:

• Analytics AI Service
• Analytics UI
• Analytics Launcher

---

📁 Project Structure

NQRust-Analytics/
├── analytics-ai-service/   # AI/LLM service (Python/FastAPI)
├── analytics-ui/           # Web interface (Next.js/React)
├── analytics-launcher/     # CLI launcher (Go)
├── analytics-engine/       # Query engine (submodule)
├── deployment/             # Kubernetes & deployment configs
├── docker/                 # Docker compose files
└── docs/                   # Documentation

---

🏗️ Architecture

Components

1. Analytics UI (Next.js)

   • User interface for data exploration
   • Dashboard creation and management
   • Connection management

2. Analytics AI Service (Python/FastAPI)

   • Natural language processing
   • SQL generation via LLM
   • RAG (Retrieval-Augmented Generation) pipelines

3. Analytics Engine (Rust/Java)

   • Query execution and optimization
   • MDL (Semantic layer) processing
   • Multi-database connectivity

4. Supporting Services

   • Qdrant: Vector database for embeddings
   • PostgreSQL: Metadata storage

Data Flow

User Query (Natural Language)
    ↓
Analytics UI
    ↓
Analytics AI Service (LLM Processing)
    ↓
Analytics Engine (SQL Execution)
    ↓
Data Source
    ↓
Results + Visualizations

---

🛠️ Configuration

LLM Configuration

Edit docker/config.yaml to configure your LLM provider:

llm_provider:
  type: openai  # or azure_openai, gemini, anthropic, etc.
  api_key: ${OPENAI_API_KEY}
  model: gpt-4

Database Connection

Configure data sources through the UI or via API. Supported authentication methods:

• Username/Password
• API Keys
• Service Account (for cloud providers)
• SSH Tunneling

---

📚 Documentation

• Installation Guide
• Configuration Examples
• Contributing Guidelines
• Code of Conduct
• Security Policy

---

🤝 Contributing

We welcome contributions! Here's how to get started:

1. ⭐ Star the repository
2. 🐛 Report bugs via GitHub Issues
3. 💡 Suggest features in Discussions
4. 📖 Read Contributing Guidelines
5. 🔧 Submit pull requests

---

📄 License

This project is licensed under the AGPL-3.0 License - see the LICENSE file for details.

---

🙏 Acknowledgments

Built with:

• Next.js & React
• FastAPI & Python
• Rust & Java
• PostgreSQL & Qdrant
• Docker & Kubernetes

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ by NexusQuantum