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.
- 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.
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
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
-
Clone the repository and navigate into it:
cd QueryMind -
Create a virtual environment and activate it:
python -m venv venv # On Windows: venv\Scripts\activate # On Unix/macOS: source venv/bin/activate
-
Install the required dependencies:
pip install -r requirements.txt
-
Set up the environment configuration: Copy
.env.exampleto.env:cp .env.example .env
Open
.envand 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 totrueto use the offline sandbox demo dataset.
Start the FastAPI server:
uvicorn main:app --port 8000Open your browser and visit http://127.0.0.1:8000/ to access the QueryMind Dashboard.
You can run the integration test suite to verify the pipeline across 5 sample queries:
python test_pipeline.pyBuild and run the container locally:
# Build the image
docker build -t querymind .
# Run the container
docker run -p 8000:8000 --env-file .env querymind