diff --git a/README.md b/README.md index a7d06c0..bd51ee8 100644 --- a/README.md +++ b/README.md @@ -1,80 +1,116 @@ -# ๐Ÿฅ Kiwi + +
+ Kiwi logo -> *Part of the CircuitForge LLC "AI for the tasks the system made hard on purpose" suite.* + # Kiwi -**Pantry tracking and leftover recipe suggestions.** + **Pantry tracking and recipe suggestions โ€” with or without an LLM.** -Scan barcodes, photograph receipts, and get recipe ideas based on what you already have โ€” before it expires. + [![License: MIT/BSL](https://img.shields.io/badge/license-MIT%20%2F%20BSL%201.1-blue)](#license) + [![CI](https://git.opensourcesolarpunk.com/Circuit-Forge/kiwi/badges/workflows/ci.yml/badge.svg)](https://git.opensourcesolarpunk.com/Circuit-Forge/kiwi/actions) + [![Version](https://img.shields.io/badge/version-0.5.0--beta-green)](https://git.opensourcesolarpunk.com/Circuit-Forge/kiwi/releases) -**LLM support is optional.** Inventory tracking, barcode scanning, expiry alerts, CSV export, and receipt upload all work without any LLM configured. AI features (receipt OCR, recipe suggestions, meal planning) activate when a backend is available and are BYOK-unlockable at any tier. + [Documentation](https://docs.circuitforge.tech/kiwi) ยท [Live demo](https://menagerie.circuitforge.tech/kiwi) ยท [circuitforge.tech](https://circuitforge.tech) -**Status:** Beta ยท CircuitForge LLC - -**[Documentation](https://docs.circuitforge.tech/kiwi/)** ยท [circuitforge.tech](https://circuitforge.tech) + *Part of the CircuitForge LLC suite โ€” "AI for the tasks the system made hard on purpose."* +
--- -## What it does +> **The LLM is optional.** Barcode scanning, receipt upload, expiry alerts, the full 200k+ recipe browser, and CSV export all work with zero LLM configured. Recipe suggestions and receipt OCR activate when a backend is available, and are BYOK-unlockable at any tier. You are never forced to send your data anywhere. -- **Inventory tracking** โ€” add items by barcode scan, receipt upload, or manually -- **Expiry alerts** โ€” know what's about to go bad -- **Recipe browser** โ€” browse the full recipe corpus by cuisine, meal type, dietary preference, or main ingredient; pantry match percentage shown inline (Free) -- **Saved recipes** โ€” bookmark any recipe with notes, a 0โ€“5 star rating, and free-text style tags (Free); organize into named collections (Paid) -- **Receipt OCR** โ€” extract line items from receipt photos automatically (Paid tier, BYOK-unlockable) -- **Recipe suggestions** โ€” four levels from pantry-match to full LLM generation (Paid tier, BYOK-unlockable) -- **Style auto-classifier** โ€” LLM suggests style tags (comforting, hands-off, quick, etc.) for saved recipes (Paid tier, BYOK-unlockable) -- **Leftover mode** โ€” prioritize nearly-expired items in recipe ranking (Free, 5/day; unlimited at Paid+) -- **LLM backend config** โ€” configure inference via `circuitforge-core` env-var system; BYOK unlocks Paid AI features at any tier -- **Feedback FAB** โ€” in-app feedback button; status probed on load, hidden if CF feedback endpoint unreachable +--- -## Stack +## What Kiwi does -- **Frontend:** Vue 3 SPA (Vite + TypeScript) -- **Backend:** FastAPI + SQLite (via `circuitforge-core`) -- **Auth:** CF session cookie โ†’ Directus JWT (cloud mode) -- **Licensing:** Heimdall (free tier auto-provisioned at signup) +| Feature | Notes | +|---|---| +| **Inventory tracking** | Add items by barcode scan, receipt upload, or manually | +| **Expiry alerts** | Know what is about to go bad before it does | +| **Recipe browser** | 200k+ recipes โ€” filter by cuisine, meal type, dietary preference, or main ingredient; pantry match percentage shown inline | +| **Leftover mode** | Prioritizes nearly-expired items in recipe ranking (5/day free, unlimited at Paid+) | +| **Recipe suggestions** | Four levels: direct corpus match, substitution/swap, cuisine-style adapter, full LLM generation | +| **Meal planning** | Plan meals for the week; pull from saved recipes or suggestions | +| **Saved recipes** | Bookmark any recipe with notes, 0-5 star rating, and free-text style tags; organize into named collections (Paid) | +| **Receipt OCR** | Extract line items from receipt photos automatically | +| **Dietary profiles** | Vegan, gluten-free, diabetic, and other constraints respected throughout | +| **Style auto-classifier** | LLM suggests style tags (comforting, hands-off, quick, etc.) for saved recipes | +| **Community feed** | Browse and share recipes with other Kiwi users | +| **CSV export** | Full pantry export, always available, no tier gate | -## Running locally +--- + +## Quick start + +**One-line install (self-hosted, Docker required):** ```bash +bash <(curl -fsSL https://git.opensourcesolarpunk.com/Circuit-Forge/kiwi/raw/branch/main/install.sh) +``` + +**Or clone and run manually:** + +```bash +git clone https://git.opensourcesolarpunk.com/Circuit-Forge/kiwi.git +cd kiwi cp .env.example .env ./manage.sh build ./manage.sh start -# Web: http://localhost:8511 -# API: http://localhost:8512 +# Web: http://localhost:8511 +# API: http://localhost:8512 ``` -## Cloud instance +**Live cloud instance** (free account required): +[menagerie.circuitforge.tech/kiwi](https://menagerie.circuitforge.tech/kiwi) -```bash -./manage.sh cloud-build -./manage.sh cloud-start -# Served at menagerie.circuitforge.tech/kiwi (JWT-gated) -``` +Full setup and configuration guide: [docs.circuitforge.tech/kiwi](https://docs.circuitforge.tech/kiwi) + +--- ## Tiers | Feature | Free | Paid | Premium | -|---------|------|------|---------| -| Inventory CRUD | โœ“ | โœ“ | โœ“ | -| Barcode scan | โœ“ | โœ“ | โœ“ | -| Receipt upload | โœ“ | โœ“ | โœ“ | -| Expiry alerts | โœ“ | โœ“ | โœ“ | -| CSV export | โœ“ | โœ“ | โœ“ | -| Recipe browser (domain/category) | โœ“ | โœ“ | โœ“ | -| Save recipes + notes + star rating | โœ“ | โœ“ | โœ“ | -| Style tags (manual, free-text) | โœ“ | โœ“ | โœ“ | -| Receipt OCR | BYOK | โœ“ | โœ“ | -| Recipe suggestions (L1โ€“L4) | BYOK | โœ“ | โœ“ | -| Named recipe collections | โ€” | โœ“ | โœ“ | -| LLM style auto-classifier | โ€” | BYOK | โœ“ | -| Meal planning | โ€” | โœ“ | โœ“ | -| Multi-household | โ€” | โ€” | โœ“ | -| Leftover mode (5/day) | โœ“ | โœ“ | โœ“ | +|---|:---:|:---:|:---:| +| Inventory CRUD | Yes | Yes | Yes | +| Barcode scan | Yes | Yes | Yes | +| Receipt upload | Yes | Yes | Yes | +| Expiry alerts | Yes | Yes | Yes | +| CSV export | Yes | Yes | Yes | +| Recipe browser (200k+ recipes) | Yes | Yes | Yes | +| Save recipes + notes + star rating | Yes | Yes | Yes | +| Style tags (manual, free-text) | Yes | Yes | Yes | +| Leftover mode (5/day) | Yes | Yes | Yes | +| Receipt OCR | BYOK | Yes | Yes | +| Recipe suggestions (L1โ€“L4) | BYOK | Yes | Yes | +| Named recipe collections | โ€” | Yes | Yes | +| LLM style auto-classifier | โ€” | BYOK | Yes | +| Meal planning | โ€” | Yes | Yes | +| Multi-household | โ€” | โ€” | Yes | -BYOK = bring your own LLM backend (configure `~/.config/circuitforge/llm.yaml`) +**BYOK** = bring your own LLM backend. Configure `~/.config/circuitforge/llm.yaml` to unlock AI features at any tier without a paid subscription. + +--- + +## Stack + +- **Frontend:** Vue 3 SPA (Vite + TypeScript), served on port 8511 +- **Backend:** FastAPI + SQLite via `circuitforge-core`, API on port 8512 +- **Auth:** CircuitForge session cookie (cloud mode); local mode requires no account +- **Licensing:** Heimdall โ€” free tier auto-provisioned at signup + +--- + +## Forgejo-primary + +Kiwi is developed and maintained on Forgejo at [git.opensourcesolarpunk.com/Circuit-Forge/kiwi](https://git.opensourcesolarpunk.com/Circuit-Forge/kiwi). GitHub and Codeberg are read-only mirrors. File issues and submit pull requests on Forgejo. + +--- ## License -Discovery/pipeline layer: MIT -AI features: BSL 1.1 (free for personal non-commercial self-hosting) +Kiwi uses a split license: + +- **Discovery and inventory pipeline** (barcode scan, expiry tracking, pantry CRUD, CSV export, recipe browser): [MIT](LICENSE-MIT) +- **AI features** (receipt OCR, LLM recipe suggestions, style auto-classifier): [BSL 1.1](LICENSE-BSL) โ€” free for personal non-commercial self-hosting; commercial use or SaaS re-hosting requires a paid license. Converts to MIT after 4 years. + +Privacy ยท Safety ยท Accessibility โ€” co-equal, non-negotiable across all CircuitForge products.