Metadata-Version: 2.4
Name: rai-swan
Version: 0.0.16
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: 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: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering
Requires-Python: <3.15,>=3.10
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: pytest-xdist>=3.5.0; extra == "dev"
Requires-Dist: coverage>=7.0.0; extra == "dev"
Requires-Dist: pip-tools>=7.0.0; extra == "dev"
Requires-Dist: networkx>=3.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

```
Swan Proprietary Software License

Copyright (c) 2026 RelationalAI, Inc. All rights reserved.

1. Ownership. Swan (the "Software"), including its source code, compiled
   binaries, and documentation, is the confidential and proprietary
   property of RelationalAI, Inc. ("RelationalAI"). No rights to the
   Software are granted except as expressly set out below.

2. Limited License Grant. Subject to the terms of a separate written
   agreement between you and RelationalAI (or, absent such an agreement,
   solely for internal evaluation by authorized RelationalAI personnel and
   design partners), RelationalAI grants you a non-exclusive,
   non-transferable, non-sublicensable license to install and run the
   compiled distributions of the Software (e.g. the packages published to
   PyPI) for that authorized purpose.

3. Restrictions. Except as expressly permitted above, you may not: (a)
   copy, modify, or create derivative works of the Software; (b) reverse
   engineer, decompile, or disassemble any compiled binary; (c)
   redistribute, sublicense, rent, lease, or otherwise make the Software
   available to any third party; or (d) remove or alter any proprietary
   notices.

4. No Warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
   KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.

5. Limitation of Liability. IN NO EVENT SHALL RELATIONALAI BE LIABLE FOR
   ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF, OR IN
   CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
   SOFTWARE.

6. Third-Party Components. The Software statically links certain
   third-party open-source components under their own permissive licenses;
   see THIRD_PARTY_LICENSES.md for the full list and required attributions.
```
