Metadata-Version: 2.4
Name: convilyn-solution-retail-cashier
Version: 0.1.0b0
Summary: Convilyn retail cashier Solution Pack — a REMOVABLE vertical built on the convilyn-edge SPI
Project-URL: Homepage, https://convilyn.corenovus.com
Project-URL: Documentation, https://docs.convilyn.corenovus.com
Project-URL: Issues, https://github.com/CoreNovus/convilyn-python/issues
Project-URL: Repository, https://github.com/CoreNovus/convilyn-python
Author-email: Convilyn <sdk@convilyn.corenovus.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: barcode,convilyn,edge,pos,retail,solution-pack
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: convilyn-edge>=0.1.0b0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff==0.15.6; extra == 'dev'
Description-Content-Type: text/markdown

# convilyn-solution-retail-cashier

The **retail cashier Solution Pack** — the first, **removable** vertical built on
the [`convilyn-edge`](../edge-python) SPI. It turns the reference scenario (a
new-cashier barcode-scan exception assistant) into working code, and it exists to
prove one thing:

> **Delete this whole pack, and `convilyn-edge` still lets you build another IoT
> AI workflow.** If that holds, the SDK is a general substrate, not a barcode
> product with a POC baked into its core. (CI-enforced by the SDK's litmus lint.)

## What's in the pack

Every piece is a `convilyn-edge` SPI implementation — the retail vocabulary lives
**here**, never in the substrate:

| SPI primitive | Retail implementation |
|---|---|
| `Normalizer` | `BarcodeNormalizer` — raw scan → canonical `BarcodeEvent`, with deterministic code-type classification |
| `StateProvider` | `PosStateProvider` — the register's transaction stage + recent scans |
| `DeterministicOperator` | **`BarcodeStageRuleEngine`** — the §五.3 rule table, **no LLM** |
| `EventSource` | `SimulatedScannerSource` — replay scans with no hardware |
| `ActionSink` | `DisplayInstructionSink`, `CreateHelpRequestSink` — **R0/R1 only** |

Convilyn ships the simulator + these reference sinks only — a real OPOS / Zebra
DataWedge scanner adapter, and anything R2+ (void / refund / hardware control), is
integrator work. That's the moat boundary.

## The three workflows (reference §十三)

`RetailWorkflows` composes the primitives into the three graded flows:

1. **`guide_scan`** — wrong barcode type. **No model**: normalize → POS stage →
   rule engine → display. (item-entry + a payment code → "go to payment first",
   etc.)
2. **`explain_pos_error`** — an opaque POS error. Look up a SOP, ask an injected
   `ModelOperator` for one short instruction, fall back to a fixed message when
   the model is unavailable (offline-first).
3. **`escalate_for_help`** — unresolved. Gather a **redacted-by-allowlist**
   context (never card / member / payment data) and open a supervisor case.

## Install

```bash
pip install convilyn-solution-retail-cashier   # pulls in convilyn-edge
```

Python ≥ 3.10. Its only dependency is `convilyn-edge`.

## License

Apache-2.0.
