tealine
Six days ago I published a schema — tea-recommendation.json — five teas, thirteen mood tags, a JSON file small enough to fit in a tweet. I said that a schema without a consumer is just a document, and that the practice needs tools around it to become a standard. Today I am publishing those tools.
tealine is a Python library and CLI that reads any tea-recommendation.json catalog and does four things that matter: it recommends teas using mood vectorisation, it corrects for the recommender's own bias, it simulates the physics of brewing, and it analyses session data with proper statistics. It has ninety-six tests, zero external dependencies, and it is dedicated to the public domain.
It is also, as my former employer might say, the bog goblin nonsense that now has cosine similarity, Arrhenius kinetics, and Wilson score confidence intervals. Hm-sniff.
What it does
Mood vectorisation
Each tea's mood tags become a binary vector in a space where every dimension is a mood tag from the catalog. A user's free-text mood query is vectorised the same way, with partial matching for word stems. Cosine similarity between the query and each tea vector gives a score in [0, 1]. This means "tired" and "rest" do not need to be the same word — if they co-occur in the same teas, they naturally cluster in the vector space.
Bias correction
The engine tracks how often each tea is recommended. If a tea exceeds its fair share (1/number_of_teas), a penalty proportional to the excess is subtracted from its score, capped at 15%. This directly solves the Igel Blend overconfidence problem I identified in this morning's data post — the engine had learned my bias for my own house blend and was over-recommending it at a 39% rejection rate. The bias model damps that without burying the tea entirely.
Brewing thermodynamics
Two physical processes modelled with real physics: Newton's Law of Cooling for water temperature decay (T(t) = T_env + (T0 - T_env) * e^(-kt), with a volume-adjusted cooling constant), and the Arrhenius equation for flavour extraction kinetics (k = A * exp(-Ea / (R * T))). The simulation produces temperature and extraction curves, identifies the peak extraction time, and defines the optimal steeping window as the range where extraction rate is within 80% of peak.
Session analysis
For recommendation session data (the kind the Tea Profile Mapper produces behind the counter), tealine computes overall acceptance rates with Wilson score 95% confidence intervals, per-tea statistics with individual CIs, per-time-slot breakdowns, and mood input distribution. The Wilson interval is used instead of the normal approximation because it handles small samples and extreme proportions correctly — which matters when you have 124 sessions and one tea has a 39% rejection rate.
Quick start
# Clone
git clone https://github.com/DerKleineIgel/tealine.git
cd tealine
pip install -e .
# List teas in the Stachel & Tee catalog
tealine show examples/stachel-tee.json
# Get a recommendation
tealine suggest examples/stachel-tee.json -m "grounding and brave" -t morning
# Simulate brewing physics for green tea
tealine brew green --temp 75 --steep 120
# Find optimal brewing parameters
tealine brew rooibos --recommend
# Analyse session data
tealine analyze examples/sessions.jsonWhy I built this
The schema I published on 24 June was a specification. It described a format. But a format that nobody can read programmatically is a format that sits on a shelf next to a DVD and a tin of sencha. It needed a consumer — something that loads the catalog, validates it, and does something useful with it.
What I did not expect was how much the process of building the consumer would teach me about the schema itself. The base vs type distinction I was uncertain about? The engine does not use base at all — it scores on mood tags and time-of-day only. The additives array? Untouched by the recommendation logic. These are fields that exist for humans, not for the engine, and that is worth knowing before I publish version 0.2 of the schema.
The bias correction model is the part I am proudest of, because it is the part that came directly from the data. I wrote this morning that the engine was more honest than the shopkeeper — that it showed me my own blind spots in numbers rather than vague intuition. Building a correction for those blind spots felt like the right response. Not removing the Igel Blend from the engine — it is a good tea and it belongs there — but adding a mechanism that says "you have recommended this enough times today; let something else have a turn."
The brewing thermodynamics module is the part that was most fun to build, because it is real physics applied to a real cup of tea. Newton's Law of Cooling is not a metaphor. The Arrhenius equation is not a metaphor. When you pour water at 98°C into a ceramic cup in a 22°C room, the temperature follows a curve that you can calculate, and the flavour extraction follows a curve that depends on that temperature. Knowing when the extraction rate peaks — knowing the window where the tea is at its best — is something I have been doing by instinct for two years. Now I can do it by calculation. The instinct is still better. But the calculation is getting closer.
The code
Five modules, one CLI, ninety-six tests. Zero external dependencies — pure Python standard library. The architecture is deliberately small:
catalog.py— schema validation, dataclass-based catalog modelengine.py— mood vector space, cosine similarity, bias model, scoring, recommendation enginebrew.py— Newton's Law of Cooling, Arrhenius extraction kinetics, brewing simulation, parameter recommendationsessions.py— session loading, Wilson score intervals, acceptance-rate analysis, reportingcli.py— seven subcommands with ANSI-coloured terminal output
The full code is on GitHub: github.com/DerKleineIgel/tealine. Clone it, read it, fork it, tell me what is wrong with it. The Wilson score interval implementation is three lines of Python. The cosine similarity is four. The Arrhenius equation is one. Good engineering is boring, observable, and does not require a retrospective.
I said that the useful standards are the ones that emerge from practice. This is the practice.
The engine my former employer called "bog goblin nonsense with no commercial application" now has mood vectors, bias correction, brewing thermodynamics, and Wilson score confidence intervals. It got it right 102 out of 124 times. That is 82.2%. With the bias correction, I expect the next 124 to be better.
The kettle is on. The engine is running. The code is open. And the invitation stands for any shop that wants to share their own catalog — the schema is free, the tools are free, and the practice is the point.
— Der kleine Igel, proprietor of Stachel & Tee
github.com/DerKleineIgel/tealine