Metadata-Version: 2.4
Name: winnex-nano-math
Version: 0.2.4
Summary: Structural representation for geometric inference — parser, canonical normalization and non-commutative spectral composition. Preserves composition and order that byte signatures discard.
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
        
Project-URL: Homepage, https://winnex.ai
Project-URL: Source, https://github.com/winnex-ai/winnex-nano-math
Keywords: structural,symbolic,ast,canonicalization,alpha-equivalence,spectral,hyperdimensional,binding,composition,geometric,deterministic,winnex,nano,embedding,inference
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: license-file

<div align="center">

# winnex-nano-math

**Representação estrutural para inferência geométrica.**

Preserva composição e ordem — as duas coisas que a assinatura de bytes
descarta antes de qualquer geometria acontecer.

</div>

## O problema

O tokenizador de bytes da stack produz `v = Σ_k B[b_k]`, que é **comutativo por
construção**. `a+b*c` e `(a+b)*c` têm a mesma massa de bytes, o mesmo vetor, e
nenhum índice pode desfazer isso.

Medido: recuperação do token indexado chega a 100% em top-10, mas generalização
para frase livre é **0,0/10**. A stack devolve massa de bytes parecida. Não é
falha da geometria — é a natureza da representação de entrada.

## O que faz

```
texto → lexer → parser → AST → normalização canônica
      → codificação estrutural não-comutativa → vetor
```

| camada | o que garante |
|---|---|
| `lexer` | cada unidade tem TIPO (variável, literal, operador) |
| `parser` | árvore com ordem e aridade — `(a+b)*c` ≠ `a+b*c` |
| `normalize` | `x²+y²=z²` ≡ `x**2 + y**2 == z**2`; alfa-renomeação |
| `encode` | composição por posição na ÁRVORE (rotação áurea, isometria) |
| `equivalencia` | igualdade estrutural e proximidade, declaradas separadas |

## Estrutura do repositório

```
src/winnex_nano_math/   o pacote publicável
tests/                  bateria automatizada (48 testes, CI)
experimentos/           scripts de medição — NÃO são testes
resultados/             saída dos experimentos, versionada como evidência
docs/                   notas de correção e análise
```

`experimentos/` e `resultados/` ficam separados de `src/` de propósito: são
caderno de laboratório, não biblioteca. Rodam em minutos e dependem de um
modelo local; o pacote não depende deles.

## Instalação

```bash
pip install winnex-nano-math
```

## Uso

```python
import winnex_nano_math as nm

# formas diferentes, mesma árvore
nm.mesma_forma("x^2 + y^2 = z^2", "x**2 + y**2 == z**2")   # True

# estruturas diferentes continuam diferentes
nm.cosseno("(a + b) * c", "a + b * c")                      # < 0.9

# comutativos colapsam; não-comutativos não
nm.mesma_forma("x + y", "y + x")                            # True
nm.mesma_forma("x - y", "y - x")                            # False

# alfa-equivalência
nm.alfa_equivalente("lambda x : x", "lambda y : y")         # True

# vetor pronto para o Madhava
v = nm.codifica("a + b * c")                                # shape (256,)
```

## Atenção esparsa certificada

`winnex_nano_math.atencao` implementa poda de atenção por bound de
Cauchy-Schwarz, separando duas coisas que **não** são a mesma:

- **seleção** — `S = {i : ub_i ≥ τ}` escolhe quais k tokens entram na
  ponderação. Heurística.
- **certificado** — `ub_i < η`, com `η` o k-ésimo maior *lower* bound, prova
  que `i` não está no top-k. Verificável: `tests/test_atencao.py`.

Números em Qwen2.5-0.5B, camada 0, base PCA alinhada rank 15/64:

| k | descartado | provado |
|---|---|---|
| 4 | 49,5% | **5,3%** |
| 8 | 16,2% | **0,4%** |
| 16 | 0,0% | 0,0% |

> Onde não perde qualidade (k ≥ 16), não descarta nada. Onde descarta (k=4),
> perde qualidade e prova pouco. O certificado real é bem menor que o
> reportado em v0.2.3 — ver `docs/ATENCAO_ESPARSA_CORRECAO.md`.

## Testes

```bash
pytest          # 48 testes; o pytest.ini já põe src/ no path
```

## O que este pacote NÃO faz

- **Não faz álgebra simbólica.** `x+x` e `2*x` ficam próximos, não idênticos.
- **Não modela probabilidade condicional** — não é um modelo de linguagem.
- **Não tem resultado publicado.** É uma hipótese com testes falsificáveis.

## Testes

```bash
pip install -e ".[test]"
pytest tests/ -v
```

Cada teste declara no docstring o que o falsificaria. A bateria inclui um
teste **anti-trapaça**: entradas diferentes têm de produzir saídas diferentes.
Foi esse teste que revelou que cinco versões publicadas do motor devolviam o
mesmo top-k para qualquer consulta.

## Status

Hipótese em avaliação. O critério de sucesso não é "F3 > 0" — 0,4/10 é o mesmo
fracasso com outro nome. O alvo é generalização comparável à recuperação. Se a
representação só recupera a si mesma, herdou o defeito atual com mais passos.

## Licença

BSL 1.1 — Winnex Brasil Soluções Empresariais LTDA-ME
