Skip to content
vaibhav3000Public

About

LLM-powered query assistant experiment

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

QueryMind

Natural Language Analytics and Intelligence powered by Elasticsearch (ES|QL) and Google Gemini.

QueryMind translates free-form natural language business questions into highly optimized ES|QL queries, runs them against your Elasticsearch indexes directly, and uses Gemini to analyze results and output structured JSON, markdown reports, and dynamic visualizations.


Key Features

  • Layer 1: Intent Translation: Gemini-powered translation from NL to ES|QL syntax with local schema validation to prevent column hallucination.
  • Layer 2: Elastic Execution: Direct query execution against Elasticsearch clusters with automatic fallback strategies.
  • Layer 3: Reasoning Agent: Structured insights, averages, key findings, and semantic validation to resolve silent query translation bugs.
  • Layer 4: Visual Output & Formatting: Automatically builds Chart.js visualization configurations and formatted Markdown reports.
  • Demo Mode: Built-in mock pipeline mode which bypasses Elastic and Gemini APIs, returning a realistic mock product dataset with 5 items for demonstration purposes.

Architecture

flowchart TB
    subgraph Input[" Input Layer"]
        U[("User / Dashboard")]
        Q["Natural Language Query"]
    end

    subgraph Translate[" Layer 1: Intent Translation"]
        TA["Query Translation Agent<br/><i>Gemini → ES|QL</i>"]
        SV["Semantic Validator<br/><i>Ensures query structure & intent match</i>"]
    end

    subgraph Execute[" Layer 2: Elastic Execution"]
        EE["Elastic MCP Executor<br/><i>ES|QL Query Execution</i>"]
        FB["Fallback Strategy<br/><i>Automatic query relaxation</i>"]
        MQ["Mock Data Generator<br/><i>Offline sandbox mode</i>"]
    end

    subgraph Reason[" Layer 3: Reasoning"]
        RA["Reasoning Agent<br/><i>Gemini-powered analysis</i>"]
        FV["Fact Validator<br/><i>Verifies findings against data</i>"]
        CB["Chart Builder<br/><i>Chart.js config generation</i>"]
    end

    subgraph Output[" Layer 4: Output"]
        OF["Output Formatter<br/><i>Markdown + JSON + Charts</i>"]
        AR["API Response"]
        D[(" Dashboard UI")]
    end

    U --> Q --> TA
    TA --> SV
    SV -- " Valid" --> EE
    SV -- " Invalid → Retry" --> TA
    EE -- "Fallback needed" --> FB --> EE
    EE -- "Mock mode" --> MQ --> EE
    EE --> RA
    RA --> FV
    FV --> CB
    CB --> OF --> AR
    AR --> D

    style Input fill:#1e3a5f,stroke:#22d3ee,color:#fff
    style Translate fill:#1a4a3a,stroke:#34d399,color:#fff
    style Execute fill:#3a2a6a,stroke:#a78bfa,color:#fff
    style Reason fill:#4a2a3a,stroke:#fb7185,color:#fff
    style Output fill:#3a3a1a,stroke:#fbbf24,color:#fff
Loading

How to Use

flowchart LR
    A["1 Clone Repository<br/><code>git clone ...</code>"] --> B["2 Create Virtual Env<br/><code>python -m venv venv</code>"]
    B --> C["3 Install Dependencies<br/><code>pip install -r requirements.txt</code>"]
    C --> D["4 Configure .env<br/><code>cp .env.example .env</code>"]
    D --> E{"MOCK_MODE?"}
    E -- " true (default)<br/>No API keys needed" --> F["5 Start Server<br/><code>uvicorn main:app --port 8000</code>"]
    E -- " false<br/>Set GEMINI_API_KEY<br/>& ELASTIC_ENDPOINT" --> F
    F --> G["6 Open Browser<br/><code>http://localhost:8000</code>"]
    G --> H["7 Ask Questions<br/>in Natural Language"]
    H --> I["8 Get Insights<br/>& Visualizations"]

    style A fill:#1e3a5f,stroke:#22d3ee,color:#fff
    style B fill:#1a4a3a,stroke:#34d399,color:#fff
    style C fill:#3a2a6a,stroke:#a78bfa,color:#fff
    style D fill:#4a2a3a,stroke:#fb7185,color:#fff
    style E fill:#3a3a1a,stroke:#fbbf24,color:#fff
    style F fill:#1e3a5f,stroke:#22d3ee,color:#fff
    style G fill:#1a4a3a,stroke:#34d399,color:#fff
    style H fill:#3a2a6a,stroke:#a78bfa,color:#fff
    style I fill:#4a2a3a,stroke:#fb7185,color:#fff
Loading

Installation & Setup

  1. Clone the repository and navigate into it:

    cd QueryMind
  2. Create a virtual environment and activate it:

    python -m venv venv
    # On Windows:
    venv\Scripts\activate
    # On Unix/macOS:
    source venv/bin/activate
  3. Install the required dependencies:

    pip install -r requirements.txt
  4. Set up the environment configuration: Copy .env.example to .env:

    cp .env.example .env

    Open .env and fill in the values:

    • ELASTIC_ENDPOINT: Elasticsearch cluster endpoint (default: https://localhost:9200)
    • ELASTIC_API_KEY: API Key with indices read/view metadata privileges.
    • GEMINI_API_KEY: Google Gemini API Key.
    • KIBANA_URL: Kibana cluster URL.
    • MOCK_MODE: Set to true to use the offline sandbox demo dataset.

Running the Application

Local Dev Server

Start the FastAPI server:

uvicorn main:app --port 8000

Open your browser and visit http://127.0.0.1:8000/ to access the QueryMind Dashboard.

Testing the API

You can run the integration test suite to verify the pipeline across 5 sample queries:

python test_pipeline.py

Docker Deployment

Build and run the container locally:

# Build the image
docker build -t querymind .

# Run the container
docker run -p 8000:8000 --env-file .env querymind

About

LLM-powered query assistant experiment

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages