specs-ai 0.1.2

███████╗██████╗ ███████╗ ██████╗███████╗       █████╗ ██╗
██╔════╝██╔══██╗██╔════╝██╔════╝██╔════╝      ██╔══██╗██║
███████╗██████╔╝█████╗  ██║     ███████╗█████╗███████║██║
╚════██║██╔═══╝ ██╔══╝  ██║     ╚════██║╚════╝██╔══██║██║
███████║██║     ███████╗╚██████╗███████║      ██║  ██║██║
╚══════╝╚═╝     ╚══════╝ ╚═════╝╚══════╝      ╚═╝  ╚═╝╚═╝

specs-ai reads your machine's hardware via WMI and psutil, then asks a Gemini-powered LLM for specific, actionable upgrade recommendations — knowing exactly what you have.

Collected specs: CPU (model, cores, clock, socket), RAM (capacity, type, speed, slots), GPU (model, VRAM, Integrated/Dedicated), Motherboard, Storage (all drives, NVMe/SATA/HDD), WiFi adapter, Battery health (laptops), System uptime, OS metadata.

The CPU socket tells the LLM whether a CPU is soldered (BGA — cannot upgrade) or swappable (LGA/AM4/etc.). GPU type tells it whether graphics are integrated (part of the CPU die, not upgradeable on a laptop) or a discrete card.

[!WARNING] Windows only. specs-ai relies on WMI (Windows Management Instrumentation) and pywin32 for hardware extraction. It will not run on Linux or macOS. There are no plans to support other platforms at this time.

Screenshots

Dashboard (specs-ai --dashboard)

CLI Summary (specs-ai)

Detailed Recommendations (specs-ai --explain)

Install

pip install specs-ai

Or with uv:

uv pip install specs-ai

API Key Setup

Get a free Gemini API key at https://aistudio.google.com/apikey, then pick one of:

Option A — Shell environment variable:

$env:SPECS_AI_API_KEY = "your-key-here"

Option B — .env file (in the project root or any parent directory):

SPECS_AI_API_KEY=your-key-here

A template is provided at .env.example — copy it to .env and fill in your key.

Usage

specs-ai [--explain] [--specs-only] [--dashboard] [--model MODEL]

# Compact summary table (default)
specs-ai

# Detailed recommendations with specific part suggestions
specs-ai --explain

# Interactive TUI dashboard
specs-ai --dashboard

# Just the hardware snapshot, no LLM call
specs-ai --specs-only

Also works via the module entry point:

python -m specs_ai
python -m specs_ai --explain
python -m specs_ai --dashboard

Dashboard

Launch with specs-ai --dashboard for a full-screen, hacker-themed hardware monitoring dashboard built with Textual and Rich.

Features:

• Big blocky ANSI Shadow SPECS-AI title in neon green
• Matrix-style digital rain animation on left/right gutters
• Live CPU sparkline, RAM usage bar, and per-volume disk usage bars
• Color-coded uptime — green < 5d, amber 5–15d, red > 15d
• AI upgrade recommendations panel (queries Gemini in the background)
• Scrolling event log with timestamped activity
• JSON export of the full hardware snapshot

How It Works

Your Machine
     │
     ▼
WMI + psutil          ← reads CPU, RAM, GPU, storage, battery, WiFi, uptime
     │
     ▼
Prompt builder        ← formats specs, injects BGA/iGPU/uptime advisories
     │
     ▼
Gemini API            ← gemini-2.5-flash by default; swap with --model
     │
     ▼
Upgrade recommendations (table or detailed narrative)

Notes

• BGA CPUs (soldered) are correctly flagged as non-upgradeable
• Integrated GPUs on laptops are marked as non-upgradeable; on desktops, adding a discrete card is suggested
• VRAM is read from the Windows registry (not WMI) to avoid the 32-bit DWORD overflow that misreports GPUs with ≥ 4 GB VRAM
• WMI calls run in daemon threads with a 10-second timeout to prevent hangs on broken driver states
• Uptime advisories are injected into the prompt at 5 days (suggest reboot) and 15 days (strongly recommend reboot)

Development

Requires uv:

git clone https://github.com/vybhav72954/specs-ai
cd specs-ai
uv run pytest tests/ -v

Contributing & Issues

Bug reports and feature requests are welcome. If you run into a problem or have a suggestion, please open an issue on GitHub with:

• Your Windows version and Python version
• The full error message or unexpected output
• The command you ran

Pull requests are also welcome for bug fixes and improvements.

License

Apache 2.0