Cellarbrain

AI sommelier for your wine cellar. Transforms Vinocell CSV exports into normalised Parquet tables, per-wine Markdown dossiers, and an in-process DuckDB query layer that AI agents can use via the Model Context Protocol.

Quick start

# Clone and install (Python 3.11+)
git clone https://github.com/urban-buss/cellarbrain.git
cd cellarbrain
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -e .

Usage

1. Run the ETL pipeline

Export your cellar from cellarbrain (File → Export → CSV) and place the files in raw/:

raw/
├── export-wines.csv
├── export-bottles-stored.csv
└── export-bottles-gone.csv      # optional

Then run:

# Full load (first time)
cellarbrain etl raw/export-wines.csv raw/export-bottles-stored.csv raw/export-bottles-gone.csv -o output

# Incremental sync (subsequent runs — detects changes, preserves IDs)
cellarbrain etl raw/export-wines.csv raw/export-bottles-stored.csv raw/export-bottles-gone.csv -o output --sync

Output goes to output/ — 12 Parquet entity files and per-wine Markdown dossiers under output/wines/.

2. Query your cellar

# SQL query (DuckDB syntax)
cellarbrain query "SELECT w.name, wy.name AS winery, w.vintage FROM wine w JOIN winery wy ON w.winery_id = wy.winery_id LIMIT 10"

# Output as CSV or JSON
cellarbrain query "SELECT * FROM wine LIMIT 5" --format csv
cellarbrain query "SELECT * FROM bottle WHERE status = 'stored'" --format json

# SQL from a file
cellarbrain query -f my_query.sql

3. Cellar statistics

cellarbrain stats                     # Overall summary
cellarbrain stats --by country        # Grouped by country
cellarbrain stats --by grape          # Grouped by grape variety
# Also: region, category, vintage, winery, cellar, provider, status

4. Wine dossiers

cellarbrain dossier 42                # Read dossier for wine #42
cellarbrain dossier --search Barolo   # Search wines by name, grape, region…
cellarbrain dossier --pending         # Wines with pending agent research

5. Validate output

cellarbrain validate                  # Check Parquet integrity

6. Start the MCP server

cellarbrain mcp                       # stdio transport (default)
cellarbrain mcp --transport sse       # SSE transport for HTTP clients

All subcommands accept -d <path> to point at a different data directory (default: output).

Legacy mode: The old cellarbrain <wines.csv> <bottles.csv> syntax still works but emits a deprecation warning.

Web Explorer

A local web dashboard for browsing your cellar, observability data, and running queries interactively.

cellarbrain dashboard          # opens at http://localhost:8017

Pages: overview, tool usage, errors, sessions, latency charts, live tail (SSE), cellar browser, bottles, drinking window, tracked wines, SQL playground, statistics, and workbench. Requires a prior ETL run and MCP log store.

MCP server

The MCP server exposes 7 read/write tools for AI agents (Claude, OpenClaw, Copilot, etc.). Tools are thin data primitives — all reasoning stays in the agent.

Tools

Resources

Prompts

Configure with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "cellarbrain": {
      "command": "cellarbrain",
      "args": ["mcp"],
      "env": {}
    }
  }
}

If cellarbrain is installed in a virtualenv, use the full path:

{
  "mcpServers": {
    "cellarbrain": {
      "command": "/path/to/cellarbrain/.venv/bin/cellarbrain",
      "args": ["mcp"],
      "env": {}
    }
  }
}

To point at a different data directory:

{
  "mcpServers": {
    "cellarbrain": {
      "command": "cellarbrain",
      "args": ["-d", "/path/to/output", "mcp"],
      "env": {}
    }
  }
}

Configure with VS Code (Copilot)

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "cellarbrain": {
      "command": "cellarbrain",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Or with a virtualenv on Windows:

{
  "servers": {
    "cellarbrain": {
      "command": ".venv\\Scripts\\cellarbrain.exe",
      "args": ["-d", "output", "mcp"],
      "env": {}
    }
  }
}

Configure with OpenClaw

See .docs/design/openclaw-skill.md for the full skill integration design.

Optional OpenClaw iMessage notifications

Cellarbrain can ask OpenClaw to send a short iMessage after each successful ETL, including runs with no detected changes. When notifications are enabled, failed ETL runs also send a best-effort failure alert. Notifications are disabled by default.

Add this to your local cellarbrain.toml (keep personal recipient details out of shared config files):

[notifications]
enabled = true
target = "+417XXXXXXXX" # replace with your iMessage number in international format
# command = "openclaw"            # or an absolute path if launchd cannot find it
# timeout_seconds = 15
# strict = false                  # success-alert delivery failure does not fail ETL

The recipient is passed to OpenClaw's documented openclaw message send --channel imessage command. OpenClaw and its iMessage channel must already be configured on the local Mac. Cellarbrain uses a shell-free subprocess call and does not expose the Gateway. Successful sends are recorded in .cellarbrain-notifications.json inside the ETL output directory to suppress duplicate sends for the same run. Failure messages contain no exception text or source data.

To verify the local OpenClaw/iMessage setup independently of ETL, run:

cellarbrain notifications test

This sends a real test message using the configured target and command, even if automatic notifications are disabled. It prints OpenClaw's captured stdout/stderr and retries, and exits with status 1 on failure. You can supply --target and --message to override the configured target and default test text. Manual tests do not write ETL delivery state.

Data model

The ETL produces 12 normalised Parquet tables:

Plus per-wine Markdown dossiers in output/wines/ with:

• ETL-owned sections (identity, origin, inventory, tastings, etc.)
• Agent-owned sections (producer profile, vintage report, food pairings, etc.)
• YAML frontmatter tracking which agent sections are populated vs pending

See .docs/data-model/source/ and .docs/data-model/target/ for detailed field documentation.

Project structure

src/cellarbrain/
├── cli.py            # CLI entry point with subcommands
├── reader.py         # CSV readers
├── parsers.py        # Field-level parsers
├── transform.py      # Normalisation and entity building
├── writer.py         # Parquet writer with Arrow schemas
├── validate.py       # Post-ETL validation
├── incremental.py    # Change detection and sync
├── markdown.py       # Dossier generation with agent section preservation
├── query.py          # DuckDB query layer (stats, search, SQL)
├── dossier_ops.py    # Dossier read/write/pending operations
└── mcp_server.py     # FastMCP server (7 tools, 8 resources, 4 prompts)

Development

Note: Unit tests and smoke tests require a source checkout of the repository. They are not included in the PyPI package.

# Clone and set up for development
git clone https://github.com/urban-buss/cellarbrain.git
cd cellarbrain
python -m venv .venv
.venv\Scripts\activate        # Windows
source .venv/bin/activate      # macOS / Linux
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run only unit tests (fast, no CSV files needed)
pytest tests/ -v --ignore=tests/test_integration.py

# Run integration tests (requires raw/*.csv files)
pytest tests/test_integration.py -v

License

Private — not for redistribution.