Metadata-Version: 2.4
Name: graphsense-clustering
Version: 0.2.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
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 :: Implementation :: CPython
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Dist: pyarrow>=14.0
License-File: LICENSE
Summary: UTXO address clustering via parallel Union-Find for GraphSense
Keywords: graphsense,clustering,union-find,utxo,bitcoin,multi-input heuristic,co-spend heuristic
Author-email: Iknaio Cryptoasset Analytics GmbH <contact@iknaio.com>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://graphsense.github.io/
Project-URL: Source, https://github.com/graphsense/graphsense-lib
Project-URL: Tracker, https://github.com/graphsense/graphsense-lib/issues

# graphsense-clustering

UTXO address clustering via a parallel Union-Find, implemented in Rust and
exposed to Python through PyO3. Used by
[graphsense-lib](https://github.com/graphsense/graphsense-lib) to run the
multi-input common-ownership heuristic over Bitcoin and other UTXO chains.

## Installation

```bash
pip install graphsense-clustering
```

Pre-built wheels are published for Linux (glibc and musl, x86_64 and aarch64)
and macOS (x86_64 and arm64) against CPython 3.10+ via the stable ABI
(`abi3`), so a single wheel covers all supported Python versions on a given
platform.

Most users do not need this package directly — install it via the
`graphsense-lib` clustering extra:

```bash
pip install 'graphsense-lib[clustering]'
```

## Usage

```python
from gs_clustering import Clustering

# Size the union-find from the maximum known address id.
c = Clustering(max_address_id=1_000_000)

# Feed batches of multi-input transactions. Each inner list is the set of
# input address ids for a single transaction.
c.process_transactions([[1, 2, 3], [4, 5], [2, 7]])

# Materialize the final (address_id, cluster_id) mapping as a pyarrow
# RecordBatch.
batch = c.get_mapping()
```

See the `graphsense-lib` source tree for the integration code that streams
transactions out of Cassandra and writes the cluster mapping back.

## License

MIT

