xBloom AI Brew

中文说明

xBloom AI Brew turns natural-language coffee preferences into xBloom-ready brew recipes, then gives your AI agent a local bridge for previewing, validating, and sending those recipes to the machine.

It is built for one practical workflow: tell an agent what kind of cup you want, get a complete recipe with real xBloom parameters, adjust it in a local dashboard if needed, and brew through the local BLE bridge when you are ready.

What It Does

• Generates structured xBloom recipes from taste goals such as "bright light roast", "round daily cup", or "strong short cup".
• Produces concrete brew fields: cupType, doseGrams, grinderSize, rpm, grandWater, and staged pours.
• Validates recipe ranges before hardware commands are sent.
• Provides a local Dashboard for connecting, editing, monitoring, pausing, resuming, and stopping brews.
• Bundles an AI-agent skill so Codex, Claude, Cursor, ChatGPT, or other agents can follow the same recipe and bridge workflow.
• Includes offline tools for validating recipes and inspecting encoded command frames without connecting to a machine.

Why Use It

• Agent-ready: the included skill gives your AI agent the recipe schema, taste mapping, bridge API, and brewing flow.
• Less manual tuning: describe the cup you want in plain language instead of hand-filling every brewing parameter, including the bean dose.
• Reproducible recipes: examples and validation scripts make generated recipes easy to save, compare, and refine.
• Local-first control: the bridge runs on your own machine and exposes a simple local API for agents and the dashboard.

Quick Start

Prerequisites: Node.js 18.17 or newer, Bluetooth enabled, and an xBloom machine you own.

git clone https://github.com/YOUR_NAME/xbloom-ai-brew.git
cd xbloom-ai-brew
npm install
npm start

Open:

http://127.0.0.1:3000

Then click Connect in the dashboard, build a recipe, and start brewing after the safety checklist.

Use With Your AI Agent

Point your agent at this repository and ask it to read:

skills/xbloom-brew/SKILL.md

For Codex users, an optional installer is included:

npm run install:codex-skill

Example prompt:

Use the xbloom-brew skill. Generate a clean, bright 250g light-roast XDripper recipe. Do not brew yet.

Every generated recipe includes doseGrams, so the agent should always tell you how many grams of beans to add.

When you are ready to brew:

Use the xbloom-brew skill. Send this recipe to my local xBloom bridge after I confirm the safety checklist.

Brewing Flow

1. Start the local bridge with npm start.
2. Ask your agent to generate a recipe from your taste preference.
3. Review the generated JSON, including doseGrams, or open the dashboard to adjust it.
4. Connect the xBloom through the dashboard or POST /api/connect.
5. Confirm the machine is ready, then send the recipe through the dashboard or /api/brew.

Offline Checks

Validate an example recipe without connecting to a machine:

npm run validate:example

Encode an example recipe and inspect the BLE command frames:

npm run encode:example

Run tests:

npm test

Local Bridge API

The bridge listens on 127.0.0.1 by default.

curl -s http://127.0.0.1:3000/api/status
curl -s -X POST http://127.0.0.1:3000/api/connect

Brewing requires explicit safety confirmation:

curl -s -X POST http://127.0.0.1:3000/api/brew \
  -H "Content-Type: application/json" \
  -d @examples/balanced-medium-roast.json

The dashboard and the skill add confirmSafety: true when the physical checklist has been confirmed. If you call the API manually, include that field in the JSON payload.

doseGrams is included in the payload for the user and agent workflow. It is not encoded into the BLE frame.

Repository Layout

bridge/
  server.js              Local REST/WebSocket bridge
  public/index.html      Dashboard
  lib/recipe.js          Recipe validation and hex encoding
  lib/commands.js        BLE command frame builders
  lib/ble.js             xBloom BLE connection
skills/xbloom-brew/      AI-agent skill
examples/                Ready-to-validate recipe payloads
scripts/                 Offline validation and encoding tools
test/                    Node test suite

Operating Notes

• Brewing commands control real hardware; check water, coffee dose, dripper/pod, and cup placement before starting.
• The bridge requires confirmSafety: true before /api/brew accepts a recipe.
• Keep the xBloom mobile app disconnected while using the local BLE bridge.
• The bridge binds to 127.0.0.1 by default for local agent/dashboard use.

Configuration

PORT=3000 npm start
HOST=127.0.0.1 npm start
VERBOSE=1 npm start
XBLOOM_DEVICE_NAME=xBloom npm start

Troubleshooting

• BLE connection fails: make sure Bluetooth is enabled, the xBloom is powered on, and the official app is disconnected.
• The browser opens but cannot brew: click Connect first and wait for BLE state to become connected.
• Recipe rejected: run node scripts/validate-recipe.js <file> and fix the reported fields.
• Permission issues on Linux: Bluetooth access may require additional OS-level permissions.

License

MIT.