The OpenSmell Stack: An Orientation Map

OpenSmell is not one repository; it is a stack — a set of pieces that share a common vocabulary and a common contract. If you have just arrived, the most useful thing this Academy can give you is a map: what each repo is for, how the pieces connect, what is ready for you to contribute to, and — if you record data — the open research questions your rig can help answer. That is this essay.

Almost everything here is MIT-licensed and lives under the OpenSmell GitHub organization.

The Core Stack

These six repositories are the working product. Together they turn a ~$30 MOX array into a recording, a feature vector, a quality-scored session, a trained classifier, and a verdict about whether a substance is even detectable.

A note on the two SDKs. The Python SDK is the full-stack reference: it retains the data model, container I/O, ingest, and the convenience pipeline. The Rust crate is the compute core, not a second full SDK — it skips .osmell and the typed descriptors to stay dependency-light and embeddable. They are complementary, not competing: Python for research and scripting, Rust for real-time and bare-metal paths. The canonical 187-dim framework and the smellability chain are implemented in both and kept equal by cross-language tests.

The Research Layer

The research repos are where claims are made and falsified before they ever reach the docs. They are deliberately small and data-driven — a claim in any of them is only as strong as the dataset that tests it.

Some repositories in the org are finished research or early experiments and are not part of the current stack. If you land on one and are unsure whether it is current, ask on Discord — the map above is the maintained, working set.

How the Pieces Reflect the Same Contract

What makes this a stack rather than a pile of repos is a shared contract:

• One data model. .osmell is the portable, self-describing recording container, current format version 1.0.0. It preserves raw values and the baseline so any client picks its own normalization.
• One feature framework. The 28c + c(c−1)/2 + 4 vector (187 at the canonical 6-channel rig) is defined sensor-count-agnostically and implemented identically in the Python SDK, the Rust crate, and the web stack — kept equal by cross-language tests.
• One honesty discipline. A derived claim — a calibration, a cross-device transfer, a smellability verdict — is only as strong as the method that produced it, and is always reported with that method.

Where You Can Contribute

Every repo is MIT-licensed and open to contribution. The most useful things, roughly in order:

1. Record protocol data (highest value). The research questions below all resolve to the same ask: record baseline → exposure → recovery sessions, mark the phase boundaries, span ≥2 devices, and cover matched-concentration reducing gases, oxidizing targets if you have them, and chemically diverse pure compounds. A dataset does not need to be large — it needs to be protocol-complete and chemically targeted. This is the P0 ask across the research layer. Share recordings on Discord, or use the data-commons validator so they can enter a dataset.
2. Test the hardware guide. Build the electronic-nose/ array, report what breaks, and extend the troubleshooting table. Hardware is the most under-tested part of the stack.
3. Add compounds to the smellability catalogue. The chain's curated catalogue (~46 chemicals, 24 composites) is a small fraction of odorant space; adding verified reference entries is valuable and safe.
4. Contribute docs and tests. The opensmell, opensmell-rs, and opensmell-web repos all welcome tests that pin behaviour, and the Academy welcomes guest essays, tutorials, and research summaries.
5. Open research (see below) — each question names the repo and the exact data it needs, so a contribution can be targeted rather than speculative.

Start a conversation — or post a recording, a rig photo, or a proposed PR — on the OpenSmell Discord before you invest time, so it lands where it can be used.

Open Research Questions

These are the questions the project actively wants data to resolve. Each is scoped by available real data; nothing below is hand-asserted. Full detail lives in interoperability/perception-layer/docs/OPEN_QUESTIONS.md.

Q1 — Is the 'strong vs weak reducing' split real? Currently falsified: on the UCI drift set, reducing-strength is a continuous, overlapping gradient, not two classes. But the gradient may be an artefact of uncontrolled concentration. Decides it: matched-dose recordings of several reducing gases (CO, H₂, NH₃, ethanol), baseline→exposure→recovery, across ≥2 devices.

Q2 — Do oxidizing targets form distinguishable categories? Untested — no NO₂/O₃/Cl₂ data exists in the corpus. n-type MOX theory predicts the opposite sign of resistance change, so oxidizing gases should split cleanly from reducing on polarity. Decides it: ≥2 oxidizing and ≥2 reducing targets on the same array, clean protocols, ≥2 devices.

Q3 — Does kinetics add a genuinely orthogonal axis? Untested — no protocol-dynamics data. Adsorption/desorption rates should be load-independent and could discriminate classes the steady-state fingerprint cannot. Decides it: protocol recordings with marked phase boundaries, several gases, ≥2 devices. This is the single most valuable contribution.

Q4 — Would richer chemistry reveal more than 2 response-type clusters? The measured array forms 2 clusters on 6 reducing targets — possibly an artefact of that specific chemical set. Decides it: more diverse pure compounds (polar, nonpolar, branched, heteroatomic) on the same array, across devices.

Q5 — What is device-invariance really robust to? The 2-cluster structure is stable across one array's 10 device batches, but that is response-type invariance, not cross-device transfer of exact feature vectors (provably impossible — Rs/R₀ cancels electronics but not sensor constants). Decides it: the same compounds across genuinely different arrays (different models/manufacturers, MEMS vs thick-film).

In the SDK itself: the firmware calibration mode and real labeled-concentration hardware validation are open; the calibrated-concentration path currently reports a thermodynamic estimate, and sensor families beyond MOX (electrochemical, MIRIS) have no feature extractor yet.

The validation standard for all of it: k is chosen by the data (max silhouette), never fixed by hand; a claim is only "validated" if a dataset actually tests it, and any proposed new category must first survive its own falsification check.

Where to Start Reading

The onboarding order — which doubles as an Academy reading order:

1. Primer — the digitising smell essay for the "why."
2. Orientation — this essay, for the "what and where."
3. Run the SDK — extract_features on a CSV; then the 187-dimension essay explains what you just computed.
4. Sensor theory — the band bending and sensor count essays (the physics and the limits).
5. Data formats — the .osmell essay (the container everything flows through).
6. Decay model — the multi-exponential fit that powers the advanced features.
7. Discipline — the interoperability and evaluating models essays (the walls and the protocol).
8. Evidence — the U-suite essay (what the stack actually does on real data).

The Point of the Map

Every layer of this stack exists to make one sentence true: a smell recording is a comparable, self-describing artifact, and every claim made from it is traceable to measured data. The SDK makes the features; the format makes the artifact; the Rust core makes them fast; the science layer keeps the claims verifiable; the Academy explains all of it. And the open research questions are the parts where your data — not our prose — is the next step.

Sources & Further Reading

• OpenSmell GitHub organization — all repos above, MIT-licensed.
• interoperability/perception-layer/docs/OPEN_QUESTIONS.md — the living open-research-questions document quoted here.
• The .osmell format essay — the container at the center of the stack.
• The U-suite essay — the evaluation harness this Academy points to.
• The OpenSmell Discord — the starting point for any contribution, recording, or question.