How rmn-mann/promtalk works
Project type and purpose
• PromTalk is a lightweight full-stack web application whose goal is to translate natural-language questions into PromQL queries.
• It uses a Python web framework (likely Flask, as suggested by app.py), an LLM backend (Ollama) for translation, and connects to a Prometheus instance for actual metric queries.
File structure
• app.py – the main web server entry point; likely defines routes for receiving user input, invoking the LLM, and proxying queries to Prometheus
• requirements.txt – Python dependencies (Flask, Prometheus client, Ollama client, etc.)
• prometheus_metadata_cache.json – a local cache of Prometheus metric metadata (for RAG or quick lookups)
• templates/index.html – frontend HTML template; renders the UI for query input, review/edit, and result display
README for additional insights
• Confirms the tech stack: Python (Flask or similar) for frontend/backend, Ollama LLM for translation, Prometheus for metrics
• Lists key features: NL→PromQL translation, query editing, execution, result display
• Mentions future enhancements but does not add new components to the current architecture
a. Main components to include
• User Browser (UI) – sends natural-language queries, displays generated PromQL and results
• Web Server (app.py) – handles HTTP requests, orchestrates calls to LLM and Prometheus
• Ollama LLM Service – an external or local service that runs the language model
• Prometheus Instance – the time-series database that executes PromQL queries
• Metadata Cache – the JSON cache used to supply label and metric hints to the LLM
b. Relationships & data flow
1. User types a question in the Browser → HTTP POST to Web Server
2. Web Server fetches metric metadata (from JSON cache or directly from Prometheus)
3. Web Server sends NL + metadata context to Ollama → receives PromQL
4. Web Server returns the draft PromQL to Browser (user review/edit)
5. Upon user approval, Browser requests execution → Web Server issues PromQL to Prometheus
6. Prometheus returns time-series data → Web Server formats results → Browser displays graphs/tables
c. Architectural patterns & design principles
• Separation of concerns: UI layer, orchestration/business logic, external/third-party services
• MVC-light: templates (View), app.py routes/controllers (Controller), metadata cache & results (Model)
• Caching for performance: local metadata cache to reduce repeated Prometheus calls
• Microservice-style external integrations: Ollama and Prometheus are treated as separate services
d. Key technologies & frameworks
• Python / Flask (or similar) – web framework
• Jinja2 templates – for rendering index.html
• Ollama API – for NL→PromQL translation
• Prometheus HTTP API – for query execution
• JSON cache – for metadata RAG