rai-swan 0.0.2

Private python package for RelationalAI Swan semantic reasoner on DuckDB. See https://relationalai.github.io/swan for documentation.

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

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):

from pyrel_duckdb import Model

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

Quick Start

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.