Metadata-Version: 2.4
Name: omnibias-graph
Version: 0.1.0a2
Summary: Differentiable spectral graph operators (Laplacians, spectral embedding, heat kernel) and continuous combinatorial relaxations (Gumbel-Sinkhorn, SoftSort, soft top-k) with torch + jax bit-parity.
Author-email: Vardan Grigoryants <vardan@derivon.ai>
Maintainer-email: Derivon <info@derivon.ai>
License-Expression: AGPL-3.0-or-later OR LicenseRef-omnibias-Commercial
Project-URL: Homepage, https://github.com/derivon-ai/omnibias
Project-URL: Documentation, https://github.com/derivon-ai/omnibias/blob/main/docs/api/graph.md
Project-URL: Source, https://github.com/derivon-ai/omnibias
Project-URL: Issues, https://github.com/derivon-ai/omnibias/issues
Project-URL: Changelog, https://github.com/derivon-ai/omnibias/blob/main/CHANGELOG.md
Keywords: graph-laplacian,spectral-clustering,differentiable-sorting,optimal-transport
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: COMMERCIAL-LICENSE.md
Requires-Dist: omnibias-core>=0.5.0rc1
Provides-Extra: torch
Requires-Dist: torch>=2.0; extra == "torch"
Provides-Extra: jax
Requires-Dist: jax>=0.4.30; extra == "jax"
Requires-Dist: jaxlib>=0.4.30; extra == "jax"
Provides-Extra: all
Requires-Dist: omnibias-graph[jax,torch]; extra == "all"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: numpy>=1.24; extra == "test"
Provides-Extra: dev
Requires-Dist: omnibias-graph[all,test]; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"
Dynamic: license-file

# omnibias-graph

**From relations to soft assignments.** Spectral operators and matrix relaxations expose graph structure.

![From relations to soft assignments.](https://raw.githubusercontent.com/derivon-ai/omnibias/6fc47b7e10d4739b981dd0eff8849ec5eb19d826/packages/omnibias-graph/docs/visuals/story.gif)

[Static poster](https://raw.githubusercontent.com/derivon-ai/omnibias/6fc47b7e10d4739b981dd0eff8849ec5eb19d826/packages/omnibias-graph/docs/visuals/poster.png) · [Narrow-screen animation](https://raw.githubusercontent.com/derivon-ai/omnibias/6fc47b7e10d4739b981dd0eff8849ec5eb19d826/packages/omnibias-graph/docs/visuals/story-mobile.gif) · [How this visual is computed](https://raw.githubusercontent.com/derivon-ai/omnibias/6fc47b7e10d4739b981dd0eff8849ec5eb19d826/packages/omnibias-graph/docs/visuals/scene.py)

An affinity or cost matrix enters; spectral graph operators, embeddings, soft orderings or assignment matrices leave. Graph-aware models can compose these outputs with trainable features while respecting each relaxation’s constraints.

The animation uses computed outputs to explain this package. Frame transitions
are illustrative unless a training step is explicitly identified; it is not a
performance comparison.


[API reference](https://github.com/derivon-ai/omnibias/blob/main/docs/api/graph.md) · [Source](https://github.com/derivon-ai/omnibias/tree/main/packages/omnibias-graph/src/omnibias/graph) · [Tests](https://github.com/derivon-ai/omnibias/tree/main/packages/omnibias-graph/tests) · [Talk to Derivon](mailto:info@derivon.ai)

## The mathematical connection

Temperature-like sharpening controls selected soft assignment and sorting operators. Ties and finite iteration residuals must remain visible when interpreting a hardened result. Spectral Laplacians are a separate graph-calculus operation, not automatically a temperature limit. Bias collapse is consumed only where a differentiated model explicitly uses the shared derivative tower.

## Run this README

The examples use `omnibias-graph[torch]` on Python >=3.10. Their installed-wheel
profile selects runtime features, not an editable workspace. Install the prepared
prerelease from PyPI:

```bash
python -m pip install --pre "omnibias-graph[torch]==0.1.0a2"
```

For local development before publication, build and test the coordinated wheelhouse
using the [release guide](https://github.com/derivon-ai/omnibias/blob/main/RELEASE.md).
The package's [wheel profile](https://github.com/derivon-ai/omnibias/blob/main/packages/omnibias-graph/wheel-tests.toml)
executes the examples below outside the source checkout.

Existing published consumers may need historical primitive versions; see the
[compatibility policy](https://github.com/derivon-ai/omnibias/blob/main/RELEASE.md#published-consumer-compatibility).

## Why this package exists

Graph Laplacians describe connectivity and diffusion; smooth assignment matrices provide a route from discrete matching choices to trainable scores. Graph puts these reusable operations in one primitive so application packages can focus on their objective and decoding policy.

## What you can build

- Laplacians, spectral embeddings and heat-kernel operations.
- Sinkhorn normalization, soft sorting and soft top-k.
- Torch and JAX realizations plus arrangement-related operators.

Use spectral operators for geometry-aware representations and smooth relaxations when a downstream loss must influence assignment scores. Combinatorial applications, routing workflows and shape models live in consumers. A matrix relaxation is a component of those products rather than a complete optimizer.

## A working example

```python
import torch
from omnibias.graph.torch.ops import graph_laplacian, sinkhorn_normalize

adjacency = torch.tensor([[0., 1., 0.], [1., 0., 1.], [0., 1., 0.]])
L = graph_laplacian(adjacency)
assert torch.allclose(L.sum(dim=1), torch.zeros(3))
scores = torch.eye(3, requires_grad=True)
assignment = sinkhorn_normalize(scores, n_iters=30)
(assignment * torch.arange(9).reshape(3, 3)).sum().backward()
assert scores.grad is not None
```

## Choose the right contract

Repeated eigenvalues can make eigenvector gradients ambiguous. Sinkhorn uses a finite iteration budget, so row and column constraints need tolerances. A doubly stochastic matrix is not a permutation until decoded, and a low-temperature choice still needs handling of ties and numerical range.

## Explore and validate

The [API guide](https://github.com/derivon-ai/omnibias/blob/main/docs/api/graph.md) contains the generated module/export
inventory. Use it to find the focused implementation rather than guessing a
symbol from another package. The [capability map](https://github.com/derivon-ai/omnibias/blob/main/docs/capabilities.md)
connects the primitives to larger scientific workflows.

From the main repository, run the package’s regression suite:

```bash
uv run pytest packages/omnibias-graph/tests -q
```

## License

AGPL-3.0-or-later **or commercial**. See [LICENSE](https://github.com/derivon-ai/omnibias/blob/main/packages/omnibias-graph/LICENSE) and the [licensing policy](https://github.com/derivon-ai/omnibias/blob/main/LICENSING.md).
Comply with the AGPL terms or obtain a signed commercial grant; commercial use alone does not require payment. [Commercial terms](https://github.com/derivon-ai/omnibias/blob/main/packages/omnibias-graph/COMMERCIAL-LICENSE.md) describe the alternative. Previously distributed Apache editions, where applicable, retain their original grants.
