KVASSISTENT

Inspiration

links first: https://kvassistent.pages.dev

https://kvassistent.pages.dev/game/ Original human text — kept verbatim, no edits:

ЭТО ТВОЙ КВАС делай с ним что хочешь KVASSISTENT поможет тебе сделать это ПРАВИЛЬНО и добиться НАИЛУЧШЕГО результата МЫ всегда рады НОВЫМ идеям и именно ТЫ управляешь КВАСОМ

You could build your own kvas, the recipe is open and nemed DZHIDHZA (ЖИЖА) ты его готовишь сам so you responsible with your solutions. используй свой KVASSISTENT

The text in the video originally written in RUSSIAN человеком и ога его придумала и есть оригинал все остальное не ИИ

Из инструментов used 3 cameras just to make this и 3 ИИ (RIP codex gemini claude)

The block above is the original human signal and is preserved as-is. Everything below was written or reviewed after that.

Fermentation advice is everywhere, but it is usually a static recipe: follow every step perfectly and hope the jar behaves. Real kitchens are messier — the room is hotter than planned, the jar sits in the sun, a check-in happens late — and the person needs one answer: what should I do now?

KVASSISTENT started from a small everyday problem (making a drink from stale bread) and grew into an experiment in agent-native instructions: a repository that any AI agent can open and immediately act as a calm kitchen companion for one real batch.

What it does

6 languages · offline PWA · no account · 3 L first-batch recipe · one-tap 28°C demo

KVASSISTENT guides a person from dry bread to chilled kvass without pretending that AI can see, smell, or test the jar.

The agent first confirms five facts: water volume, bread condition, starter, room temperature, and what already happened. Every reply then follows one rhythm:

Current state — only facts the person has confirmed.
Next action — one concrete step, not a wall of instructions.
Report back with — the observation needed before continuing.

The installable Live Batch companion records temperature, time, sunlight, closure, surface, smell, and taste locally in the browser. Its safety engine turns those observations into one next action and an explainable safety brief. Mold, slime, dangerous smells, 35 °C+ liquid, or sealed primary fermentation trigger explicit stop or corrective branches. Unknowns stay null instead of being invented.

The same batch can be handed to another AI agent as structured JSON, including the last confirmed action, safety_flags, unknowns, and the next check-in. Works offline, needs no account, available in Russian, English, Spanish, German, Simplified Chinese, and Greek.

How we built it

Two coordinated layers share one contract, so the UI can never claim a reason that disagrees with the recommended action:

Agent contract — AI_AGENT_START.md plus multilingual guides, a state model, a JSON Schema (agent-instructions/state.schema.json), recipes, and a safety checklist.
Local-first PWA — deterministic rule engine, explainable decision trace, timed check-ins, local history, structured handoff.

Toolchain:

OpenAI Codex as engineering partner (repo mapping, rule engine, Live Batch, tests).
Vanilla HTML / CSS / JavaScript, no framework runtime.
Service Worker PWA, hosted on Cloudflare Pages.
JSON Schema for batch state and agent handoff.
Python for build/validation scripts and PDF generation.
i18n with English as universal fallback (never Russian) for non-RU locales.

The publication pipeline builds the versioned site and validates the companion before every release.

Challenges we ran into

The hardest problem was not generating more advice — it was deciding what the assistant must refuse to guess.

A kitchen agent cannot verify microbiological safety, smell the jar, or know that a step happened unless the person confirms it. So uncertainty is part of the product: missing values remain null, safety-sensitive observations block normal progress, and every handoff carries explicit unknowns and safety_flags.

A concrete case: early on, the UI could show a reason that did not match the recommended action (for example, "calm range" while telling the user to move the jar). We merged verdict and reason into a single rule engine and locked the invariant with a test — the explanation shown to the user is now literally the same object the engine used to decide.

Making a detailed fermentation protocol feel simple on a phone was solved with progressive disclosure: one next action on the main path, with decision trace and deeper explanation one tap away.

Accomplishments that we're proud of

A repository link is enough to teach a compatible AI agent how to begin helping safely.
Complete first 3-litre batch supported with clear, accessible instructions.
Live Batch works fully offline; personal batch data never leaves the device.
Every verdict is explainable through temperature, surface, smell, closure, sunlight, and timing signals.
Critical safety branches and the agent handoff are covered by automated tests.
One-click demo reproduces a realistic case: 26 h, 28 °C, direct sunlight.
Ships in 6 languages with consistent numbers, risks, and links.

Most importantly, KVASSISTENT turns AI from a recipe generator into a patient collaborator that waits for evidence.

What we learned

For everyday AI, trust comes from pacing and boundaries. "One verified state, one safe action, one requested observation" is more useful than a confident essay.

A repository can itself be a product interface: when instructions, schemas, safety rules, tests, and browser companion share one contract, an AI agent can join the experience without a custom integration or locked account.

What's next for KVASSISTENT

Telegram bot — skeleton is already in Version 17; token stays outside the repo. First reply will be: «Какой хороший квас ты задумал! Вот это молодец — ай да хорош!»
Optional camera-assisted check-ins while keeping human confirmation mandatory.
Batch comparison without uploading private history.
Package the agent contract as a reusable pattern for sourdough, pickling, and kombucha.
Grow into a small library of local-first Apps for Your Life — AI helping with real objects and real routines, honest about what it cannot observe.