Circuit-Forge/dipper
5
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: add initial README

Browse source
This commit is contained in:
pyr0ball 2026-06-01 11:05:33 -07:00
commit 2e051686fa
1 changed files with 102 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

102
README.md Normal file
View file

@ -0,0 +1,102 @@
<div align="center">
# Dipper
**Local-first fermentation assistant. Batch logging, fermentation tracking, yeast culture registry, recipe library — no cloud required.**
[![Status](https://img.shields.io/badge/status-backlog-lightgrey)](https://git.opensourcesolarpunk.com/Circuit-Forge/dipper)
[![License](https://img.shields.io/badge/license-BSL%201.1-blue)](LICENSE)
[![CircuitForge](https://img.shields.io/badge/CircuitForge-LLC-green)](https://circuitforge.tech)
[Website](https://circuitforge.tech) · [Roadmap](https://git.opensourcesolarpunk.com/Circuit-Forge/roadmap) · [All Products](https://circuitforge.tech/#products)
</div>
---
> *Part of the [Circuit Forge LLC](https://circuitforge.tech) menagerie — AI for the tasks the system made hard on purpose.*
**Status:** Backlog — not yet started. See the [roadmap](https://git.opensourcesolarpunk.com/Circuit-Forge/roadmap) for priority order.
## What it does
Dipper logs your brewing and fermentation batches from grain to glass: gravity readings, temperature curves, yeast culture genealogy, recipe scaling, and LLM-assisted troubleshooting when a ferment stalls or goes off.
The American dipper (Cinclus mexicanus) is the only North American songbird that walks underwater. It dips into streams repeatedly, methodically, in controlled sequences, foraging by feel in moving water. Fermentation is the same discipline: patient, methodical, conditions-aware. You cannot rush it and you cannot ignore it.
## Why it is hard
Fermentation is unforgiving of poor record-keeping:
- Off-flavors trace to specific process variables that are impossible to diagnose without historical data
- Yeast culture health degrades silently across generations without genealogy tracking
- Recipe scaling is non-linear (hop utilization, mash efficiency, fermentation vessel geometry all interact)
- Regulatory complexity for distillation varies by jurisdiction and changes; staying compliant requires current information
- Most brewing apps are either entry-level (no serious data) or brewery-scale (more than a home brewer needs)
## Core pipeline
```
Create batch (recipe, target specs, ingredients, equipment)
→ Log brew day measurements (mash temp, pre-boil gravity, original gravity)
→ Track fermentation (gravity readings, temperature, timestamps)
→ Human approves conditioning and packaging decisions
→ LLM-assisted troubleshooting (describe off-flavor, stuck ferment, or appearance)
→ Log final stats (final gravity, alcohol by volume, yield, tasting notes)
→ Build searchable recipe and batch history
```
## Feature areas
- **Batch log**: full brew day record from ingredient weights to fermentation completion
- **Gravity tracker**: specific gravity or Brix over time; automatic alcohol by volume calculation
- **Temperature log**: fermentation curve with optional sensor integration
- **Yeast registry**: strain, generation, propagation date, viability notes, flavor profile
- **Recipe library**: scale any recipe by batch size, efficiency, and vessel geometry
- **Troubleshooting**: describe off-flavors or fermentation problems; LLM suggests causes and corrections
- **Regulatory reference**: jurisdiction-aware notes on home distillation rules (Paid tier)
- **Offline-first**: all data stays local; no account required for core use
## Privacy · Safety · Accessibility
**Privacy:** All batch records stay on your device. No account required. Cloud sync (Paid tier) is opt-in and encrypted in transit.
**Safety:** Distillation regulatory information is reference-only and jurisdiction-specific. Dipper does not provide legal advice. Users are responsible for understanding local rules before distilling. Alcohol safety notes (fusel concentration, cuts guidance) are included with appropriate context.
**Accessibility:** Measurement units are configurable (metric and imperial throughout). Tasting note entry supports free text and structured vocabulary. Interface readable in brew-room lighting conditions.
## Tiers
| Tier | What you get |
|------|-------------|
| **Free** | Full batch log, gravity and temperature tracking, recipe library, yeast registry, local LLM troubleshooting |
| **Paid** | Cloud sync across devices, community recipe library, regulatory reference database, sensor API integration |
| **Premium** | Fine-tuned troubleshooting model trained on fermentation science literature, multi-location support |
## Get involved
Dipper is pre-development. The best thing you can do right now is open an issue with:
- Your fermentation domain (beer, wine, mead, cider, spirits, kombucha, sourdough, koji, etc.)
- Data you currently track in spreadsheets or notebooks that you want automated
- Off-flavors or fermentation problems you find hardest to diagnose
- Sensor or equipment integrations you want supported
Early issues shape what gets built first. Star the repo to follow progress.
## Product code
License key format: `CFG-DPPR-XXXX-XXXX-XXXX`
## Tech notes
- Built on the shared [circuitforge-core](https://git.opensourcesolarpunk.com/Circuit-Forge/circuitforge-core) scaffold
- LLM troubleshooting: local inference on fermentation science corpus
- Sensor integration (Paid): Tilt Hydrometer, iSpindle, and generic HTTP sensor endpoints
- Recipe format: BeerXML import and export for interoperability with existing tools
- Data format: SQLite local store, JSON export for portability
- Regulatory database: jurisdiction-keyed reference data, updated quarterly
## License
[Business Source License 1.1](LICENSE) — free for personal non-commercial self-hosting. Converts to MIT after four years. Commercial use requires a [paid license](https://circuitforge.tech/pricing).