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
|
||||
|
||||
**[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."*
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
|
@ -44,37 +60,57 @@ cp .env.example .env
|
|||
# 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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue