docs(readme): landing page rewrite — feature table, quick start, tier table, Forgejo-primary, split license
This commit is contained in:
parent
7498995092
commit
e62d69d099
1 changed files with 88 additions and 52 deletions
136
README.md
136
README.md
|
|
@ -1,42 +1,58 @@
|
||||||
# 🥝 Kiwi
|
<!-- Logo coming soon — replace docs/kiwi-logo.svg when final icon ships -->
|
||||||
|
<div align="center">
|
||||||
|
<img src="docs/kiwi-logo.svg" alt="Kiwi logo" width="96" height="96" />
|
||||||
|
|
||||||
> *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)
|
||||||
|
[](https://git.opensourcesolarpunk.com/Circuit-Forge/kiwi/actions)
|
||||||
|
[](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
|
*Part of the CircuitForge LLC suite — "AI for the tasks the system made hard on purpose."*
|
||||||
|
</div>
|
||||||
**[Documentation](https://docs.circuitforge.tech/kiwi/)** · [circuitforge.tech](https://circuitforge.tech)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 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)
|
| Feature | Notes |
|
||||||
- **Backend:** FastAPI + SQLite (via `circuitforge-core`)
|
|---|---|
|
||||||
- **Auth:** CF session cookie → Directus JWT (cloud mode)
|
| **Inventory tracking** | Add items by barcode scan, receipt upload, or manually |
|
||||||
- **Licensing:** Heimdall (free tier auto-provisioned at signup)
|
| **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
|
||||||
|
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
|
cp .env.example .env
|
||||||
./manage.sh build
|
./manage.sh build
|
||||||
./manage.sh start
|
./manage.sh start
|
||||||
|
|
@ -44,37 +60,57 @@ cp .env.example .env
|
||||||
# API: http://localhost:8512
|
# API: http://localhost:8512
|
||||||
```
|
```
|
||||||
|
|
||||||
## Cloud instance
|
**Live cloud instance** (free account required):
|
||||||
|
[menagerie.circuitforge.tech/kiwi](https://menagerie.circuitforge.tech/kiwi)
|
||||||
|
|
||||||
```bash
|
Full setup and configuration guide: [docs.circuitforge.tech/kiwi](https://docs.circuitforge.tech/kiwi)
|
||||||
./manage.sh cloud-build
|
|
||||||
./manage.sh cloud-start
|
---
|
||||||
# Served at menagerie.circuitforge.tech/kiwi (JWT-gated)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Tiers
|
## Tiers
|
||||||
|
|
||||||
| Feature | Free | Paid | Premium |
|
| Feature | Free | Paid | Premium |
|
||||||
|---------|------|------|---------|
|
|---|:---:|:---:|:---:|
|
||||||
| Inventory CRUD | ✓ | ✓ | ✓ |
|
| Inventory CRUD | Yes | Yes | Yes |
|
||||||
| Barcode scan | ✓ | ✓ | ✓ |
|
| Barcode scan | Yes | Yes | Yes |
|
||||||
| Receipt upload | ✓ | ✓ | ✓ |
|
| Receipt upload | Yes | Yes | Yes |
|
||||||
| Expiry alerts | ✓ | ✓ | ✓ |
|
| Expiry alerts | Yes | Yes | Yes |
|
||||||
| CSV export | ✓ | ✓ | ✓ |
|
| CSV export | Yes | Yes | Yes |
|
||||||
| Recipe browser (domain/category) | ✓ | ✓ | ✓ |
|
| Recipe browser (200k+ recipes) | Yes | Yes | Yes |
|
||||||
| Save recipes + notes + star rating | ✓ | ✓ | ✓ |
|
| Save recipes + notes + star rating | Yes | Yes | Yes |
|
||||||
| Style tags (manual, free-text) | ✓ | ✓ | ✓ |
|
| Style tags (manual, free-text) | Yes | Yes | Yes |
|
||||||
| Receipt OCR | BYOK | ✓ | ✓ |
|
| Leftover mode (5/day) | Yes | Yes | Yes |
|
||||||
| Recipe suggestions (L1–L4) | BYOK | ✓ | ✓ |
|
| Receipt OCR | BYOK | Yes | Yes |
|
||||||
| Named recipe collections | — | ✓ | ✓ |
|
| Recipe suggestions (L1–L4) | BYOK | Yes | Yes |
|
||||||
| LLM style auto-classifier | — | BYOK | ✓ |
|
| Named recipe collections | — | Yes | Yes |
|
||||||
| Meal planning | — | ✓ | ✓ |
|
| LLM style auto-classifier | — | BYOK | Yes |
|
||||||
| Multi-household | — | — | ✓ |
|
| Meal planning | — | Yes | Yes |
|
||||||
| Leftover mode (5/day) | ✓ | ✓ | ✓ |
|
| 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
|
## License
|
||||||
|
|
||||||
Discovery/pipeline layer: MIT
|
Kiwi uses a split license:
|
||||||
AI features: BSL 1.1 (free for personal non-commercial self-hosting)
|
|
||||||
|
- **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.
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue