Arquitetura
Six components, three layers, and one principle: what enters is validated, what leaves carries proof, and the record of what happened cannot be rewritten. This page explains each piece and how they fit.
1. The stack in one picture
Four layers. Each solves a problem the layer below does not.
| Layer | Package | Question it answers | Where it lives |
|---|---|---|---|
| Input | winnex-ai-normalize | is the corpus usable? | PyPI 1.4.6 |
| Search | winnex-madhava | what was left out, and is it provable? | PyPI 1.9.25 |
| Record | winnex-tracer | can that record be rewritten? | PyPI 1.1.4 |
| Delivery | tracer-med / jus / gap / gov | which domain is yours? | licence per domain |
2. The data flow
Text or vectors enter from the left and leave as a signed record on the right. No step is optional — removing any one breaks the guarantee.
normalize measures the corpus with the engine itself and returns the configuration that makes the proof work. madhava runs the search and produces, for every document not returned, the bound that proves its exclusion. tracer seals that set of facts. The WORM chains each record to the previous one.
3. winnex-madhava — the engine
Deterministic vector search in C++20. The difference from HNSW, IVF or PQ is not speed: it knows why a document was left out.
| Aspect | Detail |
|---|---|
| Language | C++20, with a pybind11 binding |
| Distribution | pip install winnex-madhava — manylinux wheel for cp310–cp312 |
| Dependencies | numpy only |
| Input | float32 corpus (d×n) and float32 query |
| Output | top-K + indices + exact scores + the bound of every exclusion |
| Proof | ⟨v,q⟩ ≤ ⟨Pv,Pq⟩ + ‖v−PᵀPv‖·‖q−PᵀPq‖ (Cauchy-Schwarz) |
| Configuration | basis="pca_corpus" aligns the projection to the corpus — without it the bound excludes nothing |
| Measured limit | 20 to 100× slower than HNSW; competitive below ~50,000 vectors |
4. How an exclusion is proven
The auditor asks why document D did not appear. The answer is not a claim by the system: it is a number they recompute themselves.
| Step | What happens | Who verifies |
|---|---|---|
| 1 | compute the exact score of the K-th result — the threshold | engine |
| 2 | for every document not returned, compute the upper bound | engine |
| 3 | if the bound falls below the threshold, the exclusion is proven | engine |
| 4 | the certificate is signed with Ed25519 | tracer |
| 5 | the auditor recomputes step 2 with their own vector | auditor |
5. winnex-tracer — the record
A correct bound does not stop a compromised engine from signing a false number. The tracer closes that with a key that never lives inside the engine.
| Aspect | Detail |
|---|---|
| Distribution | pip install winnex-tracer — pure Python |
| Signature | Ed25519 over canonical JSON (the exact form is what is signed) |
| Chain | SHA3-256 of the previous record, written append-only |
| Size | ~4 KB per query — years of records fit on disk |
| Verification | verify_record(record, public_key) returns VALID or INVALID |
| Key | outside the engine; in production from KMS/HSM, and the service is fail-closed without it |
6. The WORM chain
A per-record signature proves it was not altered. It does not prove it was not removed — which is why the records chain.
- What it detects: removal of any record from the middle of the chain, with the exact position.
- What it does not detect: removal of the last lines. That needs an external anchor — publish the daily hash, or timestamp it in another system.
- Where it writes: append-only store on disk, one file per day, fsync on every write.
7. winnex-ai-normalize — the input gate
RAG quality is not decided at search time. It is decided before, in the quality of what enters the index. This package is where that gets measured.
| Flag | What it validates | Severity |
|---|---|---|
dataset.nan | NaN or infinity in the corpus | fail — blocks the build |
dataset.degenerate | zero variance, empty corpus | fail — blocks the build |
embedding.dim_shift | declared dimension differs from the array | fail — blocks the build |
embedding.resolution | semantic separation between top-1 and top-K | warn |
embedding.provider_drift | space drift between batches | warn / fail |
dataset.not_certifiable | configuration that cannot prove exclusion | warn |
basis and k1_fraction by measuring the engine's own proof over your corpus. It is not a heuristic: it is the coverage it measured. On a weak-manifold corpus it routes to a random projection instead of PCA — because there PCA degrades recall.9. winnex-nano — inference without CUDA
Native inference that runs where PyTorch does not: no CUDA, no framework, on CPU or integrated GPU. Not the focus of the audit stack — it is what lets the pipeline reach restricted environments.
| Aspect | Detail |
|---|---|
| Distribution | pip install winnex-nano — PyPI 0.1.47 |
| What it does | tokenizer, weight blending and bf16 inference with a streamed lm_head |
| Where it shines | edge, public sector, machines without a GPU |
| Measured | decode 1.4× faster than transformers; PPL 15.55171 against 15.55172 on the same weights |
| Status | functional, outside the critical path of the proof |
10. winnex-xfactor — manifold projection
A projector P = XXᵀ derived from the model weights, no training. It is the research that produced UB Width — the corpus-aligned PCA basis.
| Aspect | Detail |
|---|---|
| Distribution | pip install winnex-xfactor — PyPI 1.0.8 |
| What it does | extracts the manifold basis from the weights, training nothing |
| Relation to the proof | it is the origin of basis="pca_corpus" in madhava |
| Status | refuted as a standalone product — survives as a technique inside UB Width |
winnex-madhava as a basis option. The packages stay published for reproducibility of the papers, not as a usage recommendation.8. The four tracer domains
The same audit core, with each sector vocabulary and obligations.
| Domain | Buyer | What changes |
|---|---|---|
| tracer-med | insurers, hospitals, EHR vendors | denied claims, LGPD Art. 9, record retention |
| tracer-jus | e-Discovery, corporate legal, LegalTech | document production, chain of custody |
| tracer-gap | banks, insurers, reconciliation | reconciliation trail, closing evidence |
| tracer-gov | courts of accounts, controladorias, prosecutors | LAI, public accountability — free under the Additional Use Grant |
12. Installation, package by package
Each package installs independently. The engine ships as a manylinux wheel — no compiler needed. The rest is pure Python.
| Package | Command | Requires | Wheel |
|---|---|---|---|
| engine | pip install winnex-madhava | numpy | manylinux cp310–cp312 |
| audit | pip install winnex-tracer | PyNaCl | py3-none-any |
| gate | pip install winnex-ai-normalize | numpy, httpx | py3-none-any |
| security | pip install winnex-madhava-sec | numpy | py3-none-any |
| inference | pip install winnex-nano | numpy | per-platform |
| everything | pip install winnex-madhava winnex-tracer winnex-ai-normalize | — | — |
madhava-sec, nano and xfactor are additive — the proof works without them.Versions current at the time of writing: madhava 1.9.25 · tracer 1.1.4 · normalize 1.4.6 · madhava-sec 3.1.0 · nano 0.1.47.
11. What the architecture does not solve
These limits are structural, not roadmap items.
- The proof covers the vector space, not the encoder. A poor embedding produces a correct proof and a useless answer. The gate measures and reports encoder quality; it does not fix it.
- Latency trades against the proof. The audited path costs 20 to 100× more than HNSW. That is the price of the guarantee, and it is stated.
- WORM without an external anchor does not protect the end of the chain. Publishing the daily hash fixes it; without that, truncation is invisible.
- Scale validated to 100,000 vectors. 100M via mmap is documented, not publicly benchmarked.