Plan a PC in plain language, using only parts in stock at Indian retailers today, with exact totals, buy links, and compatibility checked by code, not the AI.
India is supported today. More countries are coming, and contributions are welcome: a retailer is one JSON profile, no code required.
🌐 Live demo: pcbuildsage.onrender.com. It runs on free hosting, so the first visit after a quiet spell can take about a minute to wake up. Bring a free Gemini or OpenRouter API key.
A chatbot with web search can talk about PC parts, but it only sees the pages its search happens to find, and it does the maths itself. Indian price-comparison sites see real stock, but you can't tell them "I already own an RTX 4070, build a quiet PC around it". PCBuildSage does both: you describe what you want, and an AI consultant builds from the whole in-stock catalog, while code handles the totals and the compatibility checks.
| Chatbot with web search | Indian price-comparison sites | PCBuildSage | |
|---|---|---|---|
| Describe your needs in plain language | ✅ | ❌ | ✅ |
| Sees every in-stock listing in a price range | ❌ only the pages a search finds | ✅ | ✅ refreshed twice a day |
| Exact totals | ❌ the model does the maths | ✅ | ✅ computed by code |
| Compatibility checked by code | ❌ | ✅ | ✅ rules the AI can't override |
| Buy links to real listings | sometimes | ✅ | ✅ |
| Performance data (benchmarks) | ✅ general knowledge | some | planned |
| Runs locally with your own model | ❌ | ❌ | ✅ |
| Setup | none | none | a free API key (demo) or a local install |
What you get:
| 🇮🇳 India today, more coming | Retailers are defined in JSON profiles. Adding a retailer or a whole country is a pull request, no code required. |
| 🤖 AI consultant, real data | Chat with the model of your choice (Gemini, OpenRouter, Groq, Ollama, any OpenAI-compatible API). It searches freshly scraped listings, never its memory. |
| ✅ One more trust layer | The AI proposes parts; a deterministic rules engine checks sockets, DDR generation, PSU wattage and physical clearances before a build is presented. Anything it can't verify is shown as unverified. The engine is young: if you spot a wrong verdict, please open an issue. |
| 🔒 Private | No accounts and no tracking cookies. Run it 100% locally, or use the demo, where your key and chats stay in your browser and the server keeps only anonymous daily totals. |
| 💻 Web app and terminal | A friendly web wizard, or an interactive CLI with scriptable subcommands. |
- India catalog, refreshed twice a day from Indian retailers such as MDComputers, PrimeABGB, Vedant Computers, PC Studio and Kryptronix.
- Bring your own key. Use a free key from Google AI Studio (Gemini) or OpenRouter, which has free models. The demo never uses server-side keys.
- Your key stays in your browser. It's kept in this tab's session storage and sent with each request only to reach your provider. It's never written to disk, stored in a database, or logged on the server.
- Your chats stay in your browser too (IndexedDB). The server keeps no sessions.
- Anonymous usage totals only: the demo keeps daily totals of six events: landing view, onboarding completed, chat started, build presented, provider used (the provider name only, e.g.
gemini) and error type (a coarse class, e.g.rate_limit). It never stores IPs, cookies, user or session IDs, chat content, API keys, or model names. Local mode counts nothing.
Prerequisites: Node 22+, Python 3.11+
git clone https://github.com/ManishModak/pcbuildsage
cd pcbuildsage
npm install
pip install -r scraper/requirements.txt
cp .env.example .env # then fill in your LLM API keysnpm run devOpen http://localhost:3000. The wizard walks you through setup, scraping, and building.
Local mode has no login and holds your .env keys, so it only listens on 127.0.0.1, and its API refuses requests from other websites or other host names. To use it from another device on your network on purpose, run npx next dev --webpack -H 0.0.0.0 and list the host names you'll use in PCBUILDSAGE_ALLOWED_HOSTS (comma-separated, e.g. 192.168.1.20,desk.lan). Anyone on that network can then use it.
node bin/pcbuildsage.jsThe first run launches an interactive setup, then drops you into a REPL. Type /help to see all commands. Commands also work one-shot:
node bin/pcbuildsage.js ask "₹80,000 Blender + 1440p gaming build, white case"
node bin/pcbuildsage.js validate --parts mybuild.jsonRun npm link once if you'd rather type pcbuildsage instead of node bin/pcbuildsage.js.
To try it without scraping, generate a small sample catalog from fixtures:
npm run generate-sample-dbThe container runs in hosted-demo mode by default and listens on port 10000. For local mode, set PCBUILDSAGE_DEPLOYMENT_MODE=local:
docker build -t pcbuildsage .
docker run -d -p 127.0.0.1:3000:10000 -e PCBUILDSAGE_DEPLOYMENT_MODE=local pcbuildsageThen open http://localhost:3000.
render.yaml deploys the Docker image as a Render free web service that reads the catalog from a free Turso database. Before applying the Blueprint to an account that already runs PCBuildSage, match the existing service's name and region in render.yaml so you update it instead of creating a duplicate.
| Variable | Where | Purpose |
|---|---|---|
PCBUILDSAGE_DEPLOYMENT_MODE=hosted-demo |
web service | Turns on hosted mode |
TURSO_DATABASE_URL |
web service + refresh workflow | Turso (LibSQL) catalog URL |
TURSO_READ_TOKEN |
web service | Read-only token for catalog reads |
TURSO_INGEST_TOKEN |
refresh workflow only | Write token for npm run publish-catalog. Never set it on the web service. |
ANALYTICS_TURSO_URL / ANALYTICS_TURSO_TOKEN |
web service (optional) | A separate Turso database for the anonymous daily totals. Unset means nothing is counted. |
Render's health check is GET /api/health. It always returns HTTP 200, with status: "degraded" if Turso can't be reached. The catalog is refreshed by .github/workflows/refresh-catalog.yml. See .env.example for the full list.
The same workflow publishes the static build guides to GitHub Pages. Before its first deploy, set Settings → Pages → Source to GitHub Actions in your fork, or the deploy step fails.
Hosted mode also locks the server down: only public /api routes are reachable, requests are rate-limited per IP (60/min), chat payloads are capped (8 MB, 400 messages, 20,000 characters per typed message), and keyless search (DuckDuckGo, SearXNG) is turned off. Users bring a keyed search provider or none.
data/profiles/*.json ──▶ Python scraper (Crawl4AI) ──▶ SQLite (products.db)
community-made CSS selectors + AI fallback │
▼
data/registry/*.json ──▶ deterministic rules engine ◀── AI chat consultant
community spec DB sockets · DDR · wattage · fit (your LLM, via tools)
▲
web-grounded AI research fills gaps
for brand-new hardware (advisory only)
- Profiles describe how to scrape each retailer. If selectors break after a site redesign, an AI extraction fallback keeps data flowing.
- The registry holds curated component specs (socket, TDP, dimensions) with their sources. The AI can research brand-new hardware on the web; its findings become draft registry entries that contributors review.
- The rules engine has the last word on compatibility. The AI proposes; deterministic checks review. Every rule is open source and unit-tested.
The most valuable contributions are data files, not code:
| Contribution | Effort | How |
|---|---|---|
| 🌍 Add your country | an evening, JSON only | Write a profile for a few retailers in data/profiles/. See CONTRIBUTING.md. |
| 🏪 Add a retailer | ~30 min, JSON only | Copy a site block in a profile, adjust URLs and CSS selectors, check it with node bin/pcbuildsage.js test-profile data/profiles/india.json --site RetailerName. |
| 📖 Add component specs | ~5 min per part | Add an entry to data/registry/ with its source URL, or run npm run export-research to turn the AI's researched specs into draft entries. |
| 🎨 Add a theme | ~20 min | One JSON file of color tokens skins the web app and the CLI (data/themes/). |
| 🔧 Fix a broken profile | minutes | Usually a one-selector fix when a retailer redesigns. Great first issue. |
| 💻 Code | varies | TypeScript core or Python scraper. See CONTRIBUTING.md. |
Every data file has a JSON Schema under data/schemas/, so your editor autocompletes and CI validates automatically:
npm run validate:dataIs it free? Yes, MIT licensed. You only pay your own LLM provider, or nothing at all with a free key or a local Ollama model.
Which countries work? India today. Adding a country means writing retailer profiles (JSON, no code), and we'd love the help. See CONTRIBUTING.md.
Why does the demo ask for an API key? The demo runs on free hosting with no budget for AI usage, so you bring your own key. Gemini and OpenRouter both offer free keys.
Does it work offline? Scraped data, search, and compatibility checks work fully offline. Chat needs whatever your model needs (a local Ollama model is fully offline).
Is my data private? Yes. Locally, all data, databases, and keys stay on your machine. On the demo, chats stay in your browser, and your key lives in this tab's session storage. It's sent with each request only to reach your provider, and never written to disk, stored, or logged on the server.
Found a security issue? Please report it privately; see SECURITY.md.
If PCBuildSage is useful to you, please star the repo. It helps more builders find it.
MIT © PCBuildSage contributors