Metadata-Version: 2.2
Name: winnex-xfactor
Version: 1.0.8
Summary: Deterministic manifold embedding for native LLM inference — the X-Factor operator (O(D²r) power iteration, no training).
Keywords: x-factor,manifold,embedding,llm,inference,spectral,eigenvalue,power-iteration,deterministic,winnex,madhava,semantic,dimension-reduction
Author-Email: Winnex Brasil Soluções Empresariais LTDA-ME <pay@winnex.ai>
License: Business Source License 1.1
         
         License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
         "Business Source License" is a trademark of MariaDB Corporation Ab.
         
         Parameters
         
         Licensor:             Winnex Brasil Solucoes Empresariais LTDA - ME
         Licensed Work:        winnex-madhava
                               The Licensed Work is (c) 2026 Winnex Brasil Solucoes
                               Empresariais LTDA - ME
         Additional Use Grant: You may make use of the Licensed Work, provided that
                               you do not use the Licensed Work for a Search Service,
                               or any other service that exposes the functionality of
                               the Licensed Work to third parties as a service.
                               "Search Service" means a commercial offering that allows
                               third parties (other than your employees and contractors)
                               to use the functionality of the Licensed Work to perform
                               vector similarity search.
         
         Change Date:          2036-01-01
         Change License:        GNU General Public License v2.0 or later
         
         *****************************************************************************
         
         Business Source License 1.1
         
         Terms
         
         The Licensor hereby grants you the right to copy, modify, create derivative
         works, redistribute, and make non-production use of the Licensed Work. The
         Licensor may make an Additional Use Grant, above, permitting limited
         production use.
         
         Effective on the Change Date, or the fourth anniversary of the first
         publicly available distribution of a specific version of the Licensed Work
         under this license, whichever comes first, the Licensed Work will be made
         available under the terms of the Change License, or in the absence of a
         Change License, the GNU General Public License version 2.0 or later.
         
         All copies of the original and modified Licensed Work, and derivative works
         of the Licensed Work, are subject to this License. This License applies
         separately for each version of the Licensed Work and the Change Date may
         vary for each version of the Licensed Work released by Licensor.
         
         You must conspicuously display this License on each original or modified
         copy of the Licensed Work. If you receive the Licensed Work in original or
         modified form from a third party, the terms and conditions set forth in this
         License apply to your use of that work.
         
         Any use of the Licensed Work in violation of this License will automatically
         terminate your rights under this License for the current and all other
         versions of the Licensed Work.
         
         This License does not grant you any right in any trademark or logo of
         Licensor or its affiliates (provided that you may use a trademark or logo of
         Licensor as expressly required by this License).
         
         TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
         AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
         EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
         MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
         TITLE.
         
         For inquiries: pay@winnex.ai
         
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Project-URL: Homepage, https://winnex.ai
Project-URL: Source, https://github.com/winnex-ai/winnex-xfactor
Requires-Python: >=3.10
Requires-Dist: numpy>=1.20
Description-Content-Type: text/markdown

<div align="center">

# winnex-xfactor

**Deterministic manifold embedding for native LLM inference.**

The X-Factor is a training-free operator that embeds text into a pretrained
model's latent space — computed *structurally* from `embed_tokens`, never by
running the model.

[![PyPI](https://img.shields.io/badge/pip%20install-winnex--xfactor-467C45)](https://pypi.org/project/winnex-xfactor)
[![Python](https://img.shields.io/badge/Python-3.8%2B-467C45)](https://www.python.org/)
[![C++](https://img.shields.io/badge/C%2B%2B-20-467C45)](https://isocpp.org/)
[![License: BSL 1.1](https://img.shields.io/badge/License-BSL%201.1-467C45)](LICENSE)

</div>

## What it is

For any model, the X-Factor is the orthonormal basis of the manifold where its
token embeddings live:

```
Ē = E − mean(E)                  (center)
C = ĒᵀĒ / V                       (D×D covariance)
C = U Λ Uᵀ                         (eigh, Λ descending)
r = min{r : cumsum(Λ₁..r)/ΣΛ ≥ τ}  (effective rank)
X = U[:, :r]                       (the X factor: D×r manifold basis)
P = X·Xᵀ                           (orthogonal projector)
```

The projector is **idempotent** (P²=P) and **symmetric** (Pᵀ=P) — the
orthogonal projection onto the model's embedding manifold.

## Why it is fast

The eigendecomposition uses **power iteration with deflation**:

```
O(D²·r·iters)  vs  O(D³) for a full Jacobi/eigh
```

**Honest cost (corrected 2026-10-21).** An earlier version of this README
claimed "~2000× faster at D=2048". That number does not reproduce, and the sign
is wrong at the dimension it names. Measured against `numpy.eigh` on the same
covariance:

| D | power iteration | numpy eigh | speedup |
|---|---|---|---|
| 128 | 0.25 s | 0.43 s | 1.7× |
| 384 | 7.4 s | 8.9 s | 1.2× |
| **2048** | **399 s** | **34.7 s** | **0.09× (11× slower)** |

The cause is structural: `max_candidates = D` with up to **2000 iterations per
component**. At D=2048 the effective rank is ~1656, so the cost is
1656 × 2000 × O(D²) against a single O(D³) `eigh`.

What the method actually wins is the **low-rank regime** — a corpus whose
effective rank is small relative to D. Measured on genuinely low-rank
embeddings (rank 40, in D=512 and D=1024): **8.3×** and **5.6×** faster than
`eigh`.

**Recommendation.** Use this operator when the manifold is known to be
low-rank and you want a deterministic, dependency-free implementation. For
D ≥ 2048 with a high effective rank, `numpy.eigh` — or a randomized SVD
(Halko–Martinsson–Tropp) — is an order of magnitude faster and should be
preferred.

The mathematical output is correct in every regime: the projector is idempotent
(‖P²−P‖/‖P‖ = 3.3e-7), exactly symmetric, and the reported rank matches the
true eigendecomposition. Only the performance claim was wrong.

The guarantee that does hold everywhere is determinism: fixed seed, fixed
iteration count, same input → same basis.

## Install

```bash
pip install winnex-xfactor
```

Requires Python ≥ 3.8 and NumPy. The C++ core ships pre-built in the wheel.

## Quick start

```python
import numpy as np
import winnex_xfactor

# 1. Compute the X-Factor from a model's embed_tokens (a sample is enough).
E = np.random.randn(5000, 2048).astype(np.float32)
P, rank, variance = winnex_xfactor.compute_xfactor(E, 5000, 2048, tau=0.95)
print(f"rank={rank}, variance captured={variance:.3f}")

# 2. Embed a spectral token into the model's manifold.
psi = np.ones(64, dtype=np.float32)
h = winnex_xfactor.embed_spectral(psi, P)   # length 2048, on the manifold
```

## API

- `compute_xfactor(embed_tokens, vocab, dim, tau=0.95) -> (P, rank, variance)`
- `XFactor(embed_tokens, vocab, dim, tau)` — object with `.project`, `.project_batch`,
  `.projector`, `.basis`, `.rank`, `.variance_captured`, `.dim`
- `expand_spectral(psi, d, D)` — zero-pad + L2 normalize
- `embed_spectral(psi, P)` — full text→manifold projection

## Benchmark

Run the benchmark on Kaggle — installs `winnex-xfactor` (and `winnex-nano` for
the safetensors loader) from PyPI and computes the X-Factor from **real
embeddings** of a Qwen model (Kaggle `qwen-lm/qwen`):

[![Kaggle](https://img.shields.io/badge/Kaggle-Manifold%20benchmark-20BEFF?logo=kaggle)](https://www.kaggle.com/code/kleniopadilha/winnex-xfactor-benchmark-manifold)

Result: effective rank 118 (D=128, τ=0.95, variance captured 0.954),
compute 0.03s — power iteration with deflation (O(D²·r)) on real embeddings.

## License

BSL 1.1 | pay@winnex.ai | (c) Winnex Brasil Soluções Empresariais LTDA-ME
