BeanImporter

Tired of manually entering every new coffee into Beanconqueror? Paste a roaster's product URL — BeanImporter fills in all the fields and gives you a ready-to-scan QR code.

Deutsche Version

---

BeanImporter is a local web app that extracts coffee bean data from any roaster's product page and turns it into a Beanconqueror import link. Scan the QR code with your phone and the bean lands in your app — farm, process, variety, altitude, flavor notes and all.

• AI-powered — works with Anthropic, OpenAI, or Google Gemini (your choice, your key)
• Fully local — runs as a FastAPI server on 127.0.0.1:8000, no cloud, no account
• No terminal needed — starts automatically on login via Scheduled Task (Windows), launchd (macOS), or systemd (Linux)
• Fast import — Beanconqueror payload is built directly as Protobuf, identical to the official encoder

Requirements

• Windows 10/11, macOS, or Linux
• Python ≥ 3.12 — check "Add Python to PATH" during installation (Windows)
• An API key for one of these providers:
  • Anthropic (recommended)
  • OpenAI
  • Google Gemini

Installation

Windows:

1. Clone the repo or download and extract the ZIP.

2. Open PowerShell in the project folder.

3. Run the installer:

   powershell -ExecutionPolicy Bypass -File install.ps1

   The installer checks Python, installs dependencies, registers the Scheduled Task, and opens your browser.

4. In the onboarding dialog: choose your provider, enter your API key, click Test → Save. Done.

The server now starts automatically in the background on every login. Open it at http://127.0.0.1:8000/.

macOS / Linux: see README.de.md or the install.ps1 comments for platform-specific steps.

How to use

1. Paste a roaster's product page URL → click Extract.
2. Review and correct the extracted data if needed.
3. Click Add to Beanconqueror → a QR code appears.
4. Scan it with the Beanconqueror app on your phone — the import starts automatically.

Management

Action	Command
Restart server	Start-ScheduledTask -TaskName BeanImporter
Stop server	Stop-ScheduledTask -TaskName BeanImporter
Change provider / key	⚙ icon top-right in the web UI
Uninstall (remove task)	powershell -ExecutionPolicy Bypass -File scripts\uninstall_task.ps1
View logs	logs\server.log (previous: logs\server.log.1)

Troubleshooting

• "Server not reachable" in the browser → task hasn't started yet: Start-ScheduledTask -TaskName BeanImporter
• Port 8000 in use → kill the owning process:

  Get-NetTCPConnection -LocalPort 8000 -State Listen |
      Select-Object -First 1 -ExpandProperty OwningProcess |
      ForEach-Object { Stop-Process -Id $_ -Force }
  Start-ScheduledTask -TaskName BeanImporter

• Error banner "Open Settings" → API key invalid or expired, enter a new key in the settings modal.
• Stale cache after code changes → delete __pycache__\ and restart the server.

Architecture

Browser ──HTTP── FastAPI (uvicorn, local) ─┬── scraper.py     (fetch HTML)
                                           ├── researcher.py  (web search)
                                           ├── extractor.py   (LiteLLM → JSON)
                                           └── share_link.py  (Protobuf encoder)

share_link.py produces a https://beanconqueror.com/?shareUserBean0=… URL byte-for-byte identical to the official JS encoder.

License

MIT