Metadata-Version: 2.4
Name: rai-swan
Version: 0.0.3
Summary: Private python package for RelationalAI Swan semantic reasoner on DuckDB. See https://relationalai.github.io/swan for documentation.
License: Proprietary
Project-URL: Homepage, https://relationalai.github.io/swan
Project-URL: Documentation, https://relationalai.github.io/swan
Project-URL: Repository, https://github.com/RelationalAI/swan
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: duckdb==1.5.4
Requires-Dist: pandas>=1.3.0
Requires-Dist: numpy>=1.20.0
Provides-Extra: dev
Requires-Dist: black<25,>=24.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.5.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: coverage>=7.0.0; extra == "dev"
Requires-Dist: pip-tools>=7.0.0; extra == "dev"
Provides-Extra: gnn
Requires-Dist: torch>=2.0.0; extra == "gnn"
Requires-Dist: torch-geometric>=2.5.0; extra == "gnn"
Requires-Dist: sentence-transformers>=2.5.0; extra == "gnn"
Requires-Dist: onnxruntime>=1.17.0; extra == "gnn"
Requires-Dist: onnx>=1.15.0; extra == "gnn"
Requires-Dist: onnxscript>=0.1.0; extra == "gnn"
Requires-Dist: pyarrow>=14.0.0; extra == "gnn"
Provides-Extra: nlq
Requires-Dist: anthropic>=0.40.0; extra == "nlq"
Requires-Dist: sentence-transformers>=2.5.0; extra == "nlq"
Dynamic: license-file

# Swan

Swan is a semantic modeling and query optimization framework for DuckDB. It lets you define database constraints, schemas, advanced algebraic properties (such as symmetry, transitivity, equivalence, and disjointness), and mathematical optimization problems (LP/MIP via the HiGHS solver) as an **executable semantic layer**.

Unlike passive metadata catalogs, Swan's semantic definitions are actively compiled and enforced:
* **Python Client-Side AST Rewrite Passes**: Declarative PyRel queries are automatically analyzed and rewritten to prune logical contradictions, optimize optional matches, push down filters, swap symmetric traversals, and materialize shared query blocks.
* **C++ Native Optimizer Extension**: Integrates directly with DuckDB's query compilation pipeline to dynamically inject check constraints, eliminate redundant joins, and replace expensive recursive joins with custom physical structures (like connected components and transitive reachability indexes).
* **Prescriptive Reasoner (HiGHS Integration)**: Formulates mathematical optimization problems directly over database records, compiling variables, bounds, and indicator constraints to DuckDB C++ queries for native execution speed.
* **Predictive Reasoner (GNN + ONNX Runtime)**: Trains Graph Neural Networks over graph-structured database records and serves predictions natively in DuckDB, with built-in explainability for feature/edge importance and attention weights.

By treating semantics as executable code, Swan compiles highly-declarative traversals into ultra-efficient, vectorized SQL executions.

## Installation

```bash
pip install rai-swan
```

This automatically detects your operating system and CPU architecture and downloads the matching prebuilt wheel (Linux x86_64/ARM64, macOS Intel/Apple Silicon, Windows x64) -- no compiler required.

Verify the install (this also loads the bundled native extension):

```python
from pyrel_duckdb import Model

model = Model()
print("Swan successfully initialized!")
```

## Quick Start

```python
import duckdb
from pyrel_duckdb import Model, String

con = duckdb.connect("my_database.db", config={"allow_unsigned_extensions": "true"})
model = Model(name="my_model", connection=con)

# Declare a concept (maps to a physical table) with an identity scheme (primary key)
Customer = model.Concept("Customer", identify_by={"name": String})
```

See the full documentation for modeling concepts/properties/relationships, rules and constraints, graph algorithms, and the prescriptive/predictive reasoners.

## Documentation

Full guides, API reference, and build templates: https://relationalai.github.io/swan

## License

Proprietary -- see `LICENSE` for the terms under which the compiled distributions of this package may be used.
