GreenPrompt 🌱

Track and reduce the real-world energy cost of your AI prompts.

GreenPrompt is a local-first tool that intercepts Ollama LLM calls, measures CPU/GPU power consumption in real time, logs every prompt run to a local SQLite database, and provides a CLI and interactive web dashboard for energy analysis and reporting.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• CLI Reference
• REST API
• Web Dashboard
• Prompt Scoring
• Architecture
• Configuration
• Platform Support
• Troubleshooting
• Contributing
• License

Features

• Real-time power sampling — Continuously samples system CPU/GPU power every second, retaining a 10-minute sliding window. macOS uses powermetrics; Linux uses Intel/AMD RAPL energy counters, an ARM big.LITTLE frequency model, or nvidia-smi for GPU power.
• Per-prompt energy measurement — Computes watt-hours consumed during each LLM call against a 1-minute idle baseline.
• Token tracking — Records prompt tokens, completion tokens, and total tokens per run from Ollama's response metadata.
• Dual estimation — Provides both hardware-measured power and token-based estimates for cross-validation and offline comparison.
• Persistent logging — Stores all run data in a local SQLite database (greenprompt_usage.db).
• Prompt quality scoring — Automatically scores every prompt on 18 dimensions using offline NLTK heuristics (RTCF structure, clarity, conciseness, energy awareness, and more).
• Interactive dashboard — Plotly-powered web dashboard with 6 chart types: energy timeline, CPU/GPU breakdown, model comparison, estimated vs. actual, and baseline overlay.
• REST API — Flask server exposing endpoints for running prompts and querying usage history.
• Ollama proxy — Optional transparent reverse proxy to intercept existing Ollama traffic without code changes.

Requirements

• Python 3.9 or higher
• Ollama installed and running locally
• Live power sampling on macOS and Linux — powermetrics on macOS (Apple Silicon or Intel); RAPL, ARM big.LITTLE, or nvidia-smi on Linux
• Windows: scoring, logging, and token tracking work fully; power sampling returns zero (see Platform Support)

Installation

From PyPI

pip install greenprompt

With Poetry

poetry add greenprompt

Development Installation

git clone https://github.com/uday1201/greenprompt.git
cd greenprompt
poetry install

Quick Start

# 1. Initialize (first time only; on macOS run it once with sudo so that
#    powermetrics can be used without a password prompt afterwards)
sudo greenprompt setup

# 2. Start the API server (required for prompt and dashboard commands)
greenprompt run --port 5000

# 3. Send a prompt and see energy stats
greenprompt prompt "Explain quantum entanglement in one sentence." --model llama3.2:latest

# 4. Open the analytics dashboard
greenprompt dashboard

CLI Reference

GreenPrompt installs three equivalent command aliases: greenprompt, gprompt, and greenp.

Command Overview

No GreenPrompt command needs to be run as root. The one exception is the first setup on macOS: running it once with sudo installs a sudoers rule so that powermetrics can be sampled without a password prompt from then on. Without it, GreenPrompt still runs — energy readings are simply zero.

greenprompt setup

Initializes the environment: detects CPU power capabilities and writes them to the user config file (~/.greenprompt/config.json by default), downloads NLTK resources, verifies Ollama, and creates the SQLite database.

On macOS it also installs /etc/sudoers.d/greenprompt, which allows powermetrics to be sampled without a password. That step is the only reason to use sudo here, and it is skipped with an explanatory message if you run without it.

sudo greenprompt setup [--ollama-port PORT]

Note: Run setup from the directory where you want the database (greenprompt_usage.db) to live. All subsequent commands should be run from the same directory.

greenprompt run

Starts the GreenPrompt Flask API server as a background process, along with the power sampler for the current platform: PowerMonitor on macOS, LinuxPowerMonitor on Linux. Neither requires root.

greenprompt run [--port PORT]

Note: Wait 10–15 seconds after starting before sending the first prompt, so the sampler has collected enough readings to average over.

greenprompt prompt

Sends a prompt to Ollama via the running API server, prints the LLM response, and displays detailed energy and token statistics.

greenprompt prompt "Your prompt here" [--model MODEL]

Example:

greenprompt prompt "List three benefits of solar energy. Format: bullet points." --model llama2

Output:

Response:
• Solar energy is renewable and inexhaustible.
• It reduces electricity bills significantly over time.
• It produces no greenhouse gas emissions during operation.

--- Prompt usage data ---
Prompt tokens:       14
Completion tokens:   43
Total tokens:        57
Duration (sec):      3.21
Baseline power (W):  4.20
Baseline energy (Wh):0.000070
CPU power (W):       8.60
GPU power (W):       0.00
Combined power (W):  8.60
Energy used (Wh):    0.000767

greenprompt monitor

Displays the last N prompt usage entries from the local SQLite database.

greenprompt monitor [--count N]

greenprompt score

Scores a prompt on 18 quality dimensions without sending it to any model. Entirely offline and instant.

greenprompt score "Your prompt here"

Example:

greenprompt score "You are a physics expert. Explain Newton's second law to a high school student. Format: bullet points."

Output:

{
  'total_score': 34,
  'max_score': 50,
  'score_percent': 68.0,
  'details': {
    'RTCF Structure': 3,
    'Clarity & Specificity': 5,
    'Conciseness': 5,
    'Contextual Priming': 0,
    'Output Specification': 5,
    'Instructional Tone': 3,
    ...
  }
}

greenprompt dashboard

Opens the Plotly analytics dashboard at http://localhost:5000/dashboard in the default browser. Requires the API server to be running.

greenprompt dashboard

greenprompt stop

Stops the Flask API server by killing the process on the given port.

greenprompt stop [--port PORT]

greenprompt log_api

Tails the API server log file at /tmp/api.log.

greenprompt log_api [--follow]

REST API

The GreenPrompt Flask server exposes the following endpoints after greenprompt run.

POST /api/prompt

Run a prompt through Ollama, measure energy, and log the result.

Request body:

{
  "prompt": "Explain photosynthesis.",
  "model": "llama2"
}

Response:

{
  "prompt": "Explain photosynthesis.",
  "prompt_score": 36.0,
  "prompt_score_details": {
    "RTCF Structure": 1,
    "Clarity & Specificity": 5
  },
  "response": "Photosynthesis is the process by which plants...",
  "model": "llama2",
  "prompt_tokens": 5,
  "completion_tokens": 82,
  "total_tokens": 87,
  "total_energy (Wh)": 0.000512,
  "duration_sec": 4.13,
  "combined_power_w (W)": 0.446,
  "cpu_power_w (W)": 0.312,
  "gpu_power_w (W)": 0.134,
  "energy_estimate_tokens": 0.00087,
  "energy_estimate_prompt": 0.000005,
  "baseline_energy (Wh)": 0.000067,
  "baseline_power (W)": 4.03,
  "gpu_usage": "No GPU detected",
  "system_info": { "OS": "Darwin", "CPU": "Apple M2", ... }
}

GET /api/usage/all

Retrieve all prompt usage records as a JSON array.

curl http://localhost:5000/api/usage/all

GET /api/usage/model/<model>

Filter usage records by model name.

curl http://localhost:5000/api/usage/model/llama2

GET /api/usage/timeframe?start=ISO&end=ISO

Filter usage records by ISO 8601 timestamp range.

curl "http://localhost:5000/api/usage/timeframe?start=2024-01-01T00:00:00&end=2024-12-31T23:59:59"

GET /dashboard

Serves the interactive analytics dashboard.

ANY /ollama/api/<path>

Transparent reverse proxy to the local Ollama server at http://localhost:11434. Preserves method, headers, query params, and body.

# Example: list models via proxy
curl http://localhost:5000/ollama/api/tags

Web Dashboard

The dashboard at http://localhost:5000/dashboard provides six interactive Plotly charts:

Prompt Scoring

Every prompt sent through GreenPrompt is automatically scored on 18 quality dimensions. Use greenprompt score to evaluate prompts standalone.

The scorer is entirely offline — no API call is made. It uses NLTK POS tagging and regex pattern matching.

Scoring Dimensions (50 points total)

See docs/prompt-scoring.md for full details and optimization examples.

Architecture

greenprompt/
├── cli.py           Entry point — argparse subcommands, starts API subprocess
├── api.py           Flask server — REST endpoints, Ollama proxy, power monitor init
├── core.py          run_prompt() — orchestrates Ollama call, power measurement, scoring
├── dbconn.py        SQLite — init_db, save_prompt_usage, get_prompt_usage
├── samplerMac.py    PowerMonitor — daemon thread sampling powermetrics every second
├── samplerLinux.py  LinuxPowerMonitor — RAPL / ARM / TDP CPU sampling + nvidia-smi GPU
├── sysUsage.py      OS-agnostic wrappers — system info, power measurement, GPU detection
├── scoreBasic.py    Prompt scorer — 18-dimension offline NLTK/regex analysis
├── analytics.py     Plotly chart functions for the dashboard
├── constants.py     Tracked source — defaults, live platform values, user-config overlay
├── setup.py         Setup routine — writes ~/.greenprompt/config.json, DB init, NLTK download
└── templates/
    └── dashboard.html   Dashboard HTML with embedded Plotly JS

Request Flow

User
  │
  ▼
greenprompt prompt "..."
  │  (CLI sends HTTP POST)
  ▼
POST /api/prompt  (api.py Flask server)
  │
  ▼
core.py: run_prompt(prompt, model)
  ├─ PowerMonitor.samples  ──► baseline avg (1 min before prompt)
  ├─ POST http://127.0.0.1:11434/api/generate  (Ollama)
  ├─ PowerMonitor.samples  ──► during-prompt avg
  ├─ energy_wh = (avg_combined_w × duration_sec) / 3600
  ├─ scoreBasic.score_prompt(prompt)
  └─ dbconn.save_prompt_usage(result)
        │
        ▼
    greenprompt_usage.db (SQLite)

Power Sampling

On macOS and Linux, a daemon thread samples once a second into a collections.deque holding the last 600 readings (10 minutes). When run_prompt() completes, the matching measure_power_*() function filters samples by [start_time, end_time] to compute average watts and energy, and separately averages the 60 seconds before the prompt as the idle baseline.

macOS — PowerMonitor (samplerMac.py) calls:

sudo powermetrics --samplers cpu_power -n 1 -i 1000

Linux — LinuxPowerMonitor (samplerLinux.py) picks the best available CPU source at startup:

GPU power comes from a single long-running nvidia-smi dmon -s p -d 1 process, with a per-call subprocess fallback. If the prompt is shorter than one sample interval, measure_power_linux() interpolates from neighbouring samples and flags the result with "extrapolated": true.

For detailed architecture documentation see docs/architecture.md.

Configuration

Settings live in a JSON file written by greenprompt setup, by default ~/.greenprompt/config.json (override with $GREENPROMPT_CONFIG or $GREENPROMPT_HOME).

# where is my config?
python -c "from greenprompt import constants; print(constants.config_path())"

Platform values (OS, MACHINE, PLATFORM, ...) are derived live on every import by greenprompt/constants.py and are never stored, so they always match the machine actually running.

Database location: Created in the working directory where setup was run:

<cwd>/greenprompt_usage.db

Always run GreenPrompt commands from the same directory to use the same database file.

See docs/configuration.md for the full configuration reference.

Platform Support

Windows users will see energy_wh = 0 for hardware power measurement; all other features are fully functional. See docs/platform-support.md for the implementation roadmap.

Troubleshooting

❌ Could not connect to Ollama at http://127.0.0.1:11434

Ollama is not running. Start it:

ollama serve

Error connecting to API

The GreenPrompt API server is not running:

greenprompt run --port 5000

Power readings are all zero on macOS

The passwordless powermetrics rule is not installed, so the sampler cannot read power. Run setup once with sudo:

sudo greenprompt setup

Power readings are all zero on Linux

Check which mode the sampler chose — greenprompt log_api reports it at startup. In linear_tdp mode readings are estimates derived from CPU_TDP_W, not measurements. RAPL requires read access to /sys/class/powercap/intel-rapl*/energy_uj, which some distributions restrict to root. GPU power requires nvidia-smi on PATH.

Power readings are all zero on Windows

Live power sampling is not yet implemented on Windows. The energy_estimate_tokens field provides a token-count-based approximation.

Dashboard shows no data

The database is either empty or was created in a different working directory. Check:

greenprompt monitor --count 5

If empty, send some prompts first. If the DB file is in a different directory, cd there before running GreenPrompt.

Warning: Power usage data is incomplete or missing

The PowerMonitor has not yet collected enough samples. Wait 10–15 seconds after greenprompt run before sending the first prompt.

Contributing

See CONTRIBUTING.md for the full contribution workflow. Quick summary:

git checkout -b feature/your-feature
poetry install
# make changes
poetry run ruff check .
poetry run ruff fmt .
git commit -m "feat(scope): description"
git push origin feature/your-feature
# open pull request

Roadmap

• Windows support via Intel Power Gadget / WMI, and a lsof-free server lifecycle
• Test coverage for the scoring, database, and analytics modules
• Model-aware token energy estimates (the current table predates Ollama model naming)
• VS Code extension
• Browser extension for cloud LLM APIs
• Carbon offset integration
• Team dashboards and enterprise reporting

License

MIT License — © Uday & Anirudh