Metadata-Version: 2.4
Name: zpe-smell
Version: 0.1.0
Summary: Bounded smell encoding research repo over a surrogate receptor-response panel.
Author-email: "Zer0pa (Pty) Ltd" <architects@zer0pa.ai>
License: LicenseRef-Zer0pa-SAL-7.1
Project-URL: Homepage, https://github.com/Zer0pa/ZPE-Smell
Project-URL: Documentation, https://github.com/Zer0pa/ZPE-Smell/blob/main/README.md
Project-URL: Repository, https://github.com/Zer0pa/ZPE-Smell
Project-URL: Issues, https://github.com/Zer0pa/ZPE-Smell/issues
Project-URL: Changelog, https://github.com/Zer0pa/ZPE-Smell/blob/main/CHANGELOG.md
Keywords: olfaction,smell codec,receptor-response,surrogate benchmark,scientific reproducibility
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.md
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# ZPE-Smell

[![License: SAL v7.1](https://img.shields.io/badge/license-SAL%20v7.0-orange)](https://github.com/Zer0pa/ZPE-Smell/blob/main/LICENSE)

## What This Is

Surrogate receptor-response smell codec. Fixed 35-episode benchmark reaches Spearman 0.9996 with zero mixture, fiber, and adaptation collisions.

ZPE-Smell is one of seventeen public encoding lanes in the Zer0pa ZPE portfolio. It is useful now for audit and replication on the declared benchmark surface. It is improving continuously.

## Codec Mechanics

<p>
  <img src=".github/assets/readme/lane-mechanics/SMELL.gif" alt="ZPE-Smell Codec Mechanics animation" width="100%">
</p>

| Field | Value |
| ------- | ------- |
| Architecture | SMELL_STREAM |
| Encoding | SMELL_SURROGATE_PANEL_V1 |
| Mechanics Asset | `.github/assets/readme/lane-mechanics/SMELL.gif` |

## Key Metrics

| Metric | Value | Baseline |
| -------- | ------- | ---------- |
| SPEARMAN_RHO | 0.9996 | reference |
| NN_AT_1 | 94.29% | reference |
| MIXTURE_COLLISION | 0.00% | max 0.05 |
| FIBER_COLLISION | 0.00% | max 0.05 |

> Source: `proofs/artifacts/public_smell_surrogate_scope.json` · CI: `tests/test_public_surface.py::test_committed_artifacts_match_live_eval`

## Repo Identity

| Field | Value |
| ------- | ------- |
| Identifier | ZPE-Smell |
| Repository | https://github.com/Zer0pa/ZPE-Smell |
| Section | encoding |
| Visibility | PUBLIC |
| Architecture | SMELL_STREAM |
| Encoding | SMELL_SURROGATE_PANEL_V1 |
| Commit SHA | 48507cbfcdc5 |
| License | SAL-7.0 |
| Authority Source | proofs/artifacts/public_smell_surrogate_scope.json |

## Readiness

| Field | Value |
| ------- | ------- |
| Verdict | STAGED |
| Checks | 5/5 |
| Anchors | 2 display anchors |
| Commit | 48507cbfcdc5 |
| Authority | proofs/artifacts/public_smell_surrogate_scope.json |

### Honest Blocker

We do not claim a digital smell product.; We do not claim anything beyond the surrogate receptor-response scope shipped here.; We do not claim this result is admitted to the broader certified subset.

## What We Prove

- On the fixed surrogate receptor-response benchmark surface, the codec preserves retrieval structure with Spearman 0.9996.
- On that same surface, nearest-neighbor recall at 1 is 94.29%.
- On the declared nuisance family cases, mixture collision, fiber collision, adaptation alias, and attack success all stay at 0.00%.
- Image-prefixed nuisance streams do not break smell routing on the committed benchmark surface.
- The full public artifact can be regenerated from the code and matched exactly against the committed proof file.

## What We Don't Claim

- We do not claim a digital smell product.
- We do not claim anything beyond the surrogate receptor-response scope shipped here.
- We do not claim this result is admitted to the broader certified subset.
- We do not claim coverage of a full empirical receptor panel or general smell perception.
- This scope is intentional, not a limitation in progress — broader claims will be named explicitly when they are earned.

## Verification Status

| Code | Check | Verdict |
| ------ | ------- | --------- |
| V_01 | Full-panel roundtrip keeps all eight receptor channels intact | PASS |
| V_02 | Image-prefixed nuisance streams still route as smell on the fixed bundle surface | PASS |
| V_03 | Public evaluation keeps the bounded-scope verdict and all gates in pass state | PASS |
| V_04 | Public evaluation beats the receptor-only and geometry-only comparators on the committed surface | PASS |
| V_05 | Live evaluation matches the committed proof and reference artifacts exactly | PASS |

## Proof Anchors

| Path | State |
| ------ | ------- |
| `proofs/artifacts/public_smell_surrogate_scope.json` | VERIFIED |
| `validation/results/reference_public_eval.json` | VERIFIED |

## Repo Shape

| Field | Value |
| ------- | ------- |
| Proof Anchors | 2 display anchors |
| Modality Lanes | 1 |
| Architecture | SMELL_STREAM |
| Encoding | SMELL_SURROGATE_PANEL_V1 |
| Verification | 5/5 checks |
| Authority Source | proofs/artifacts/public_smell_surrogate_scope.json |

## Extended Metrics

Rows retained from the previous expanded `## Key Metrics` table. The public product page uses the first four rows only.

| Metric | Value | Baseline |
|---|---:|---|
| ADAPTATION_ALIAS | 0.00% | max 0.20 |
| ATTACK_SUCCESS | 0.00% | eq 0.00 |

## Competitive Benchmarks

| Approach | Spearman | NN@1 | Mixture Collision |
|---|---:|---:|---:|
| **ZPE-Smell** | **0.9996** | **94.29%** | **0.00%** |
| Receptor-only | 0.9648 | 85.71% | 14.06% |
| Geometry-only | 0.9862 | 88.57% | 7.19% |

> Source: `proofs/artifacts/public_smell_surrogate_scope.json` · CI: `tests/test_public_surface.py::test_public_eval_beats_public_comparators`

## Quick Start

```bash
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e '.[dev]'
python3 -m zpe_smell.reproduce --output validation/results/latest_public_eval.json
python3 -m pytest -q
```

## Upcoming Workstreams

This section captures the active lane priorities — what the next agent or contributor picks up, and what investors should expect. Cadence is continuous, not milestoned.

- **Olfactory codec — commercial path definition** — Zero-Base Scientific Thinking — GPD Research and Planning Pending. The 35-episode surrogate proves retrieval-structure preservation but lacks commercial weight without empirical receptor data. Active research into commercial path (digital olfaction interfaces, fragrance-formulation AI, anosmia rehabilitation) — each path has different empirical-data requirements; selection precedes any corpus scale-up.

## Citation

Use [`CITATION.cff`](./CITATION.cff) for software citation metadata, and cite the committed proof artifact when discussing the bounded result.
