{"id":49656069,"url":"https://github.com/xenofex7/ha-wine-tracker","last_synced_at":"2026-05-06T09:08:03.653Z","repository":{"id":339080210,"uuid":"1160388039","full_name":"xenofex7/ha-wine-tracker","owner":"xenofex7","description":"🍷 Wine cellar tracker with AI label recognition and Vivino integration -\u003e Home Assistant add-on or Docker standalone","archived":false,"fork":false,"pushed_at":"2026-04-16T21:23:37.000Z","size":19314,"stargazers_count":12,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-16T22:23:26.988Z","etag":null,"topics":["ai","ai-labeling","docker","docker-compose","home-assistant","home-assistant-addons","vivino","wine","wine-tracker"],"latest_commit_sha":null,"homepage":"https://xenofex7.github.io/ha-wine-tracker","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xenofex7.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-17T22:02:20.000Z","updated_at":"2026-04-16T20:41:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xenofex7/ha-wine-tracker","commit_stats":null,"previous_names":["xenofex7/ha-wine-tracker"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/xenofex7/ha-wine-tracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xenofex7%2Fha-wine-tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xenofex7%2Fha-wine-tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xenofex7%2Fha-wine-tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xenofex7%2Fha-wine-tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xenofex7","download_url":"https://codeload.github.com/xenofex7/ha-wine-tracker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xenofex7%2Fha-wine-tracker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32686308,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T08:33:17.875Z","status":"ssl_error","status_checked_at":"2026-05-06T08:33:17.221Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-labeling","docker","docker-compose","home-assistant","home-assistant-addons","vivino","wine","wine-tracker"],"created_at":"2026-05-06T09:08:02.678Z","updated_at":"2026-05-06T09:08:03.644Z","avatar_url":"https://github.com/xenofex7.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Wine Tracker - Home Assistant Add-on \u0026 Docker Standalone\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.png\" alt=\"Wine Tracker Logo\" width=\"128\"\u003e\n\u003c/p\u003e\n\n![version][version-badge]\n![project stage][stage-badge]\n![maintained][maintained-badge]\n![license][license-badge]\n![languages][languages-badge]\n![ha addon][ha-badge]\n![ai powered][ai-badge]\n![arch][arch-badge]\n![docker][docker-badge]\n\n![github stars][stars-badge]\n![github issues][issues-badge]\n![last commit][commit-badge]\n![commit activity][activity-badge]\n\nA sleek, modern wine cellar tracker. Run it as a **Home Assistant add-on** or as a **standalone Docker container** - manage your entire collection from label photo to tasting notes.\n\n## Screenshots\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/260220_main_screen.png\" alt=\"Wine Cellar Overview\" width=\"800\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/260220_statistics_screen.png\" alt=\"Statistics with Globe \u0026 Charts\" width=\"800\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/260220_add_wine_screen.png\" alt=\"Add Wine - AI, Vivino or Manual\" width=\"800\"\u003e\n  \u003cimg src=\"assets/260220_wine_edit_screen.png\" alt=\"Edit Wine Details\" width=\"800\"\u003e\n\u003c/p\u003e\n\n## Features\n\n### Wine Management\n\n- **Wine cards** with photo, vintage, type, region, grape variety, rating \u0026 notes\n- **Photo upload** - snap a label photo from your phone\n- **Star rating** (1-5 stars)\n- **Quick quantity buttons** (+/-)  directly on the card\n- **Duplicate wines** - perfect when only the vintage changes\n- **Bottle format** - track sizes from Piccolo (0.1875l) to Nebuchadnezzar (15l)\n- **Empty bottles** stay visible as placeholders (toggle to hide)\n- **Drink window** (from/until year)\n- **Purchase price** with configurable currency\n- **Storage location** with autocomplete from existing entries\n- **Region \u0026 purchase source** autocomplete from existing entries\n- **Grape variety** (e.g. Merlot, Pinot Noir, Chardonnay) with autocomplete\n\n### AI \u0026 Integrations\n\n- **AI label recognition** - snap a label photo and let AI fill in all fields, including maturity phases, taste profile and food pairings (5 providers: Anthropic, OpenAI, OpenRouter, Ollama, MiniMax)\n- **Vivino wine search** - search by name, see ratings, region \u0026 price, and import directly — with a regional fallback chain so country-specific wines (e.g. Australian labels) actually show up\n- **Vivino ID management** - view, edit \u0026 test Vivino wine links directly in the edit modal\n- **Reload missing data** - re-analyze wines with incomplete fields via AI or Vivino\n- **AI sommelier chat with full CRUD** - ask questions about your cellar, upload wine label photos, and add / edit / delete wines directly from the conversation — with persistent chat history\n- **Maturity graph** - AI-generated bell curve showing drinking phases (Youth, Maturity, Peak, Decline)\n- **Taste profile \u0026 food pairings** - AI-generated body/tannin/acidity/sweetness bars and matching dish suggestions\n\n### Views \u0026 Statistics\n\n- **Cellar view modes** - switch between Cards, List, Grid, and Table view\n- **Sortable table view** - sort by any column with persistent sort direction\n- **Search \u0026 filter** by wine type, vintage \u0026 grape variety\n- **Activity timeline** - chronological log of wines added, consumed, restocked, or removed\n- **Interactive globe** - see your wine regions on a 3D globe (COBE)\n- **Stock history chart** - area chart showing bottle count development over the last 6 months\n- **Statistics** - donut charts, total bottles, total liters, value overview \u0026 average age\n\n### UI \u0026 Platform\n\n- **6 themes** - each with dark \u0026 light mode, switchable in settings\n- **Hamburger menu** - navigation collapses on narrow viewports\n- **Fully responsive** - works great on desktop \u0026 mobile\n- **Multi-language** - 7 languages (DE, EN, FR, IT, ES, PT, NL)\n- **HA Ingress** - embedded directly in the Home Assistant sidebar\n- **REST API** at `/api/summary` for HA sensors\n- **DEV_AUTH mode** - `DEV_AUTH` env var for quick local development without Home Assistant\n- **Backup \u0026 restore** - export the whole cellar as a ZIP (JSON + CSV + images) and import it back with duplicate preview\n\n## Supported Languages\n\n| Language | Code |\n|----------|------|\n| 🇩🇪 German | `de` |\n| 🇬🇧 English | `en` |\n| 🇫🇷 French | `fr` |\n| 🇮🇹 Italian | `it` |\n| 🇪🇸 Spanish | `es` |\n| 🇵🇹 Portuguese | `pt` |\n| 🇳🇱 Dutch | `nl` |\n\nSet your preferred language in the add-on configuration (`language` option).\n\nSee [CHANGELOG.md](CHANGELOG.md) for the full version history.\n\n## Installation - Home Assistant Add-on\n\n[![Add Repository to My Home Assistant][my-ha-badge]][my-ha-url]\n\nOr install manually:\n\n1. Go to **Settings → Add-ons → Add-on Store**\n2. Top right: **⋮ → Repositories**\n3. Add the repository URL: `https://github.com/xenofex7/ha-wine-tracker`\n4. **Wine Tracker** will appear in the store\n5. Click **Install → Start**\n\nThe add-on opens in the HA sidebar under **Wine Tracker**.\n\n## Installation - Docker Standalone\n\nRun Wine Tracker without Home Assistant using Docker Compose.\n\n### Quick Start\n\n1. Create a `docker-compose.yml`:\n\n```yaml\nservices:\n  wine-tracker:\n    image: ghcr.io/xenofex7/wine-tracker:latest\n    ports:\n      - \"5050:5050\"\n    volumes:\n      - wine-data:/data\n    environment:\n      - AUTH_ENABLED=true\n      - USERS=admin:changeme\n      - SECRET_KEY=change-this-to-a-random-string\n      - CURRENCY=CHF\n      - LANGUAGE=de\n    restart: unless-stopped\n\nvolumes:\n  wine-data:\n```\n\n\u003e **Full example:** See [`docker/docker-compose.yml`](docker/docker-compose.yml) for a complete configuration with all available options.\n\n2. Start it:\n\n```bash\ndocker-compose up -d\n```\n\n3. Open **http://localhost:5050** and log in.\n\n### Environment Variables\n\n#### Authentication\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `AUTH_ENABLED` | `false` | Enable login (`true` / `false`) |\n| `USERS` | _(empty)_ | User list (see format below) |\n| `SECRET_KEY` | _(random)_ | Session encryption key - set a fixed value for persistence across restarts |\n\n**User format:** `user1:password1,user2:password2,guest:password3:readonly`\n\n- Users are comma-separated\n- Each user is `username:password` (full access) or `username:password:readonly` (view only)\n- Readonly users can browse and search wines but cannot add, edit, or delete\n\n#### General\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CURRENCY` | `CHF` | Currency symbol - `CHF`, `EUR`, `USD`, `GBP`, `CAD`, `AUD` |\n| `LANGUAGE` | `de` | UI language - `de`, `en`, `fr`, `it`, `es`, `pt`, `nl` |\n\n#### AI Provider (optional - pick one)\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `AI_PROVIDER` | `none` | AI provider: `none`, `anthropic`, `openai`, `openrouter`, `ollama`, `minimax` |\n\n**Anthropic (Claude):**\n\n| Variable | Default |\n|----------|---------|\n| `ANTHROPIC_API_KEY` | _(empty)_ |\n| `ANTHROPIC_MODEL` | `claude-opus-4-6` |\n\n**OpenAI (GPT):**\n\n| Variable | Default |\n|----------|---------|\n| `OPENAI_API_KEY` | _(empty)_ |\n| `OPENAI_MODEL` | `gpt-5.2` |\n\n**OpenRouter (multi-provider):**\n\n| Variable | Default |\n|----------|---------|\n| `OPENROUTER_API_KEY` | _(empty)_ |\n| `OPENROUTER_MODEL` | `anthropic/claude-opus-4.6` |\n\n**Ollama (local, no API key needed):**\n\n| Variable | Default |\n|----------|---------|\n| `OLLAMA_HOST` | `http://localhost:11434` |\n| `OLLAMA_MODEL` | `llava` |\n\n\u003e **Tip:** When running Ollama in a separate container, use `http://host.docker.internal:11434` as the host.\n\n**MiniMax:**\n\n| Variable | Default |\n|----------|---------|\n| `MINIMAX_API_KEY` | _(empty)_ |\n| `MINIMAX_MODEL` | `MiniMax-Text-01` |\n\n\u003e **Note:** `MiniMax-Text-01` is MiniMax's current vision-capable model — despite the name it accepts image input. The older `MiniMax-VL-01` name is no longer accepted by the API.\n\n### Updating\n\n```bash\ndocker-compose pull\ndocker-compose up -d\n```\n\n### Data Persistence (Docker)\n\nAll data (SQLite database + photos) is stored in the Docker volume mounted at `/data`. As long as you keep the volume, your data survives container updates.\n\n## Configuration (Home Assistant)\n\nAll options are configured via the Home Assistant add-on configuration page.\n\n### General\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `currency` | string | `CHF` | Currency symbol displayed for prices (e.g. `EUR`, `USD`, `GBP`) |\n| `language` | string | `de` | UI language - one of: `de`, `en`, `fr`, `it`, `es`, `pt`, `nl` |\n\n### AI Wine Label Recognition\n\nThe AI feature lets you snap a photo of a wine label and automatically fills in the wine details (name, vintage, type, region, grape, price, notes).\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `ai_provider` | dropdown | `none` | AI provider: `none`, `anthropic`, `openai`, `openrouter`, `ollama`, `minimax` |\n| `anthropic_api_key` | string | _(empty)_ | API key for Anthropic (Claude) |\n| `anthropic_model` | string | `claude-opus-4-6` | Anthropic model name |\n| `openai_api_key` | string | _(empty)_ | API key for OpenAI |\n| `openai_model` | string | `gpt-5.2` | OpenAI model name |\n| `openrouter_api_key` | string | _(empty)_ | API key for OpenRouter |\n| `openrouter_model` | string | `anthropic/claude-opus-4.6` | OpenRouter model identifier |\n| `ollama_host` | string | `http://localhost:11434` | Ollama server URL (for local AI) |\n| `ollama_model` | string | `llava` | Ollama vision model name |\n| `minimax_api_key` | string | _(empty)_ | API key for MiniMax |\n| `minimax_model` | string | `MiniMax-Text-01` | MiniMax model name (vision-capable despite the name) |\n\n**Provider notes:**\n- **Anthropic** - uses the Claude API directly. Requires an API key from [console.anthropic.com](https://console.anthropic.com)\n- **OpenAI** - uses the OpenAI API. Requires an API key from [platform.openai.com](https://platform.openai.com)\n- **OpenRouter** - a unified API that routes to many models. Requires an API key from [openrouter.ai](https://openrouter.ai). You can choose any vision-capable model.\n- **Ollama** - runs fully local, no API key needed. Install [Ollama](https://ollama.com) and pull a vision model (e.g. `llava`). Set the host to your Ollama server address.\n- **MiniMax** - OpenAI-compatible API from [minimaxi.chat](https://api.minimaxi.chat). The default model `MiniMax-Text-01` supports vision input despite the name; the older `MiniMax-VL-01` name is no longer accepted by the API.\n\n**Estimated token cost per wine analysis** (~2,500 tokens):\n\n| Provider | Model | Cost / Request |\n|----------|-------|----------------|\n| OpenAI | GPT-4o-mini | ~$0.001 |\n| OpenAI | GPT-4o | ~$0.005-0.01 |\n| OpenAI | GPT-4.1 | ~$0.01 |\n| OpenAI | o3 / o4-mini | ~$0.02-0.05 |\n| Anthropic | Claude Haiku | ~$0.002 |\n| Anthropic | Claude Sonnet | ~$0.01 |\n| Anthropic | Claude Opus | ~$0.05-0.08 |\n| Ollama | Local models | Free |\n\n\u003e **Example:** Analyzing 100 wines costs roughly $0.10 with GPT-4o-mini, $1.00 with Claude Sonnet, or $0.00 with Ollama.\n\n## Data Persistence (Home Assistant)\n\nAll data (SQLite database + photos) is stored under `/share/wine-tracker/` - preserved across add-on updates, restarts, and HA updates.\n\n## Home Assistant Sensor (Optional)\n\n```yaml\n# configuration.yaml\nsensor:\n  - platform: rest\n    name: \"Wine Stock\"\n    resource: \"http://localhost:5050/api/summary\"\n    value_template: \"{{ value_json.total_bottles }}\"\n    unit_of_measurement: \"bottles\"\n    json_attributes:\n      - by_type\n    scan_interval: 3600\n```\n\nThis creates a `sensor.wine_stock` entity you can use on dashboards or in automations.\n\n## Database Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | Text | Wine name (required) |\n| `year` | Integer | Vintage year |\n| `type` | Text | Wine type: Rotwein, Weisswein, Rosé, Schaumwein, Dessertwein, Likörwein, Anderes |\n| `region` | Text | Origin (e.g. Piemont, IT) |\n| `grape` | Text | Grape variety (e.g. Merlot, Pinot Noir) |\n| `quantity` | Integer | Number of bottles (0 = placeholder) |\n| `rating` | Integer | 1-5 stars |\n| `notes` | Text | Free text |\n| `image` | Text | Label photo filename |\n| `added` | Date | Date added |\n| `purchased_at` | Text | Purchase source |\n| `price` | Real | Purchase price |\n| `drink_from` | Integer | Drink window start (year) |\n| `drink_until` | Integer | Drink window end (year) |\n| `location` | Text | Storage location |\n| `vivino_id` | Integer | Vivino wine ID (linked when imported via Vivino search) |\n| `bottle_format` | Real | Bottle size in liters (default: 0.75) |\n| `maturity_data` | JSON | AI-estimated maturity phases: `youth`, `maturity`, `peak`, `decline` year ranges |\n| `taste_profile` | JSON | AI-estimated body, tannin, acidity, sweetness (1–5) |\n| `food_pairings` | JSON | AI-generated list of matching dishes, localized to the UI language |\n\n## Technology\n\n- **Backend**: Python 3 + Flask\n- **Database**: SQLite (single file, 250+ tests)\n- **Frontend**: Vanilla HTML / CSS / JS (no framework, no Node.js, no build tools)\n- **AI**: Anthropic SDK, OpenAI SDK, OpenRouter, Ollama REST API, MiniMax (OpenAI-compatible)\n- **Globe**: COBE (WebGL 3D globe)\n- **Base image**: Home Assistant Alpine-based\n\n## Roadmap\n\n\u003e Features are listed roughly by priority - not all will ship, and order may change.\n\n### 🔜 Up Next\n- **Spending trends** - visualize spending by month, region, or wine type\n- **Maturity calendar** - overview of which wines become drinkable each year\n\n### 🏠 Home Assistant Integration\n- **Drink window notifications** - HA alerts when wines enter or leave their optimal window\n- **Extended REST API** - more endpoints (single wine, stats, collection export) for dashboards \u0026 automations\n- **HA Dashboard card** - native Lovelace card to embed wine stats on any dashboard\n\n### 🎨 UI \u0026 Personalization\n- **Keyboard shortcuts** - `/` to search, `+` to add, `Esc` to close modals\n- **Wishlist mode** - mark wines you want to buy (separate from owned bottles)\n\n### 📦 Platform \u0026 Data\n- **Tags \u0026 custom categories** - label wines as \"gift\", \"special occasion\", \"everyday\", etc.\n- **Bulk editing** - select multiple wines and change location, type, or category at once\n- **Multiple cellars** - manage separate collections (home, vacation house, office)\n- **Chat history in export** - optional checkbox to include chat sessions, messages and chat images in the backup ZIP\n\n### 📱 Mobile \u0026 Sharing\n- **PWA support** - install on your phone's home screen with offline access\n- **Barcode / QR scan** - scan a wine barcode to auto-lookup via Vivino\n- **Shareable collection link** - generate a read-only link or QR code for friends\n\n## License\n\nMIT\n\n[version-badge]: https://img.shields.io/badge/version-v1.9.2-blue.svg\n[stage-badge]: https://img.shields.io/badge/project%20stage-stable-brightgreen.svg\n[maintained-badge]: https://img.shields.io/badge/maintained-yes-brightgreen.svg\n[license-badge]: https://img.shields.io/badge/license-MIT-green.svg\n[languages-badge]: https://img.shields.io/badge/languages-7-blue.svg\n[ha-badge]: https://img.shields.io/badge/Home%20Assistant-Add--on-41BDF5.svg?logo=homeassistant\u0026logoColor=white\n[ai-badge]: https://img.shields.io/badge/AI%20powered-label%20recognition-blueviolet.svg\n[arch-badge]: https://img.shields.io/badge/arch-aarch64-informational.svg\n[stars-badge]: https://img.shields.io/github/stars/xenofex7/ha-wine-tracker?style=flat\u0026logo=github\n[issues-badge]: https://img.shields.io/github/issues/xenofex7/ha-wine-tracker?style=flat\u0026logo=github\n[commit-badge]: https://img.shields.io/github/last-commit/xenofex7/ha-wine-tracker?style=flat\u0026logo=github\n[activity-badge]: https://img.shields.io/github/commit-activity/y/xenofex7/ha-wine-tracker?style=flat\u0026logo=github\n[docker-badge]: https://img.shields.io/badge/Docker-standalone-2496ED.svg?logo=docker\u0026logoColor=white\n[my-ha-badge]: https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg\n[my-ha-url]: https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fxenofex7%2Fha-wine-tracker\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxenofex7%2Fha-wine-tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxenofex7%2Fha-wine-tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxenofex7%2Fha-wine-tracker/lists"}