Metadata-Version: 2.4
Name: span_data
Version: 0.5.0
Summary: Identity resolution and Customer 360 libraries (Splink, DuckDB).
Author: The Data Loft
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://span.gitbook.io/span-docs
Project-URL: Community (Slack), https://join.slack.com/t/span-data/shared_invite/zt-3xkirzw8i-w_OcmdVoyAMLSH2V83gGAw
Project-URL: Documentation, https://span.gitbook.io/span-docs
Project-URL: Substack, https://cleanschema.substack.com/
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: span_data/packaging_info/LICENSE
Requires-Dist: duckdb<2.0.0,>=1.5.1
Requires-Dist: email-validator<3.0.0,>=1.3.1
Requires-Dist: pandas<3.0.0,>=2.3.3
Requires-Dist: phonenumbers<10.0.0,>=9.0.6
Requires-Dist: pydantic<3.0.0,>=2.0
Requires-Dist: snowflake-connector-python[pandas]==4.4.0
Requires-Dist: splink<5.0.0,>=4.0.16
Requires-Dist: pyyaml<7.0.0,>=6.0.3
Requires-Dist: pyarrow<24.0.0,>=23.0.1
Requires-Dist: sqlglot<32.0,>=24.0
Dynamic: license-file

# Span

`span_data` is a Python library for customer data resolution and unification.

**Early release.** This package is under active development, and the public API and import paths **may change** between releases. We expect to follow [semantic versioning](https://semver.org/) more strictly after a **1.0** stable baseline; until then, treat upgrades as potentially breaking. Pin a specific version in production and review `span_data/packaging_info/CHANGELOG.md` before upgrading.

## Modules

### id_grapher

Identity resolution built on Splink and DuckDB. Links records that refer to the same entity across one or more source datasets and produces a unified ID graph keyed on `profile_id`.

```python
from span_data.id_grapher import IDGrapher, FieldDefinitionMap, Overrides
```

Key capabilities:
- Ingest source data from pandas DataFrames, CSV files, and Snowflake tables or views.
- Clean and normalise source fields (text, email, phone number).
- Resolve entities into profile clusters with Splink-based probabilistic matching.
- Export graph results to DataFrames, CSV, Parquet, DuckDB relations, and Snowflake.
- Apply manual override workflows for merge, split, and assign operations.

See [Span Product Documentation](https://span.gitbook.io/span-docs) and the
in-package guide ``span_data/packaging_info/USAGE.md`` (ships with the wheel)
for usage examples.

### c360_compiler

Customer 360 pipeline built on DuckDB. Driven by a ``SpanConfig``
(``span_data.io.SpanConfig``) via ``C360Compiler.from_span_config``.

```python
from span_data.c360_compiler import C360Compiler
from span_data.io import load_span_config

span_config = load_span_config("span_config.yaml")
compiler = C360Compiler.from_span_config(span_config, app_name="MY_DB")
```

### SpanConfig

Unified configuration for ID Graph and C360. Load from YAML, validate, and run
locally with the ``span-data`` CLI:

```bash
span-data validate-config span_config.yaml
span-data run span_config.yaml --data-dir ./data --output-dir ./out
```

Input CSVs under ``--data-dir`` are named ``{derive_source_name(dataset)}.csv``
(for example ``ANALYTICS.SOURCES.CRM_CONTACTS`` → ``ANALYTICS_SOURCES_CRM_CONTACTS.csv``).

```python
from span_data.io import load_span_config
from span_data.io.config.adapters import to_splink_config, to_c360_compiler_config
```

Key capabilities:
- Merge customer demographics from multiple dimension sources with configurable waterfall precedence.
- Compute rolling-window metrics (6-month, 12-month, lifetime) from fact tables.
- Build a consent fact table with two-tier taxonomy (purpose / medium) and conflict resolution.
- Generate boolean and categorical customer segments.
- Enrich fact tables with `profile_id` and deterministic hash keys.

See [Span Product Documentation](https://span.gitbook.io/span-docs) and the
in-package guide ``span_data/packaging_info/USAGE.md`` (ships with the wheel)
for configuration reference and usage.

## Python Support

This package supports Python `>=3.11` (3.11–3.14), shipped as a `cp311-abi3` wheel.

## Usage

See [Span Product Documentation](https://span.gitbook.io/span-docs) for usage instructions.

## License

This project is licensed under the BSD 3-Clause License. See `span_data/packaging_info/LICENSE`.

Third-party dependency license information is documented in `span_data/packaging_info/THIRD_PARTY_NOTICES.md`.

Release history is documented in `span_data/packaging_info/CHANGELOG.md`.
