rai-setup

name	rai-setup
description	Setup and configuration for RelationalAI — first-time install walkthrough and all raiconfig.yaml tuning. Use when installing RAI, connecting to Snowflake, running RAI locally on DuckDB for development, or editing raiconfig.yaml. Not for writing PyRel model code (see rai-pyrel) or solver usage and diagnostics (see rai-prescriptive-results).

RelationalAI Setup & Configuration

Covers the relationalai Python package (aka PyRel), which enables PyRel programs and ships the rai CLI.

Summary

What: End-to-end RelationalAI setup and configuration — installing the Python package, connecting to Snowflake, validating the environment, running a starter program, and tuning all configuration surfaces (auth, model, reasoners, engines, execution).

When to use:

• First-time setup: install relationalai, connect to Snowflake, run a starter program
• Running RAI locally on DuckDB for development, prototyping, or demos (no Snowflake)
• Creating or editing raiconfig.yaml
• Choosing or troubleshooting an authentication method
• Tuning reasoner engines, sizes, solver settings
• Troubleshooting connection or config errors

When NOT to use:

• Writing PyRel models or queries — see rai-pyrel
• Designing ontology structure — see rai-ontology
• Solver execution and diagnostics — see rai-prescriptive-results
• Discovering what questions an existing model can answer — see rai-discovery

Overview: For a returning user tweaking config, start from Quick Reference below and the Reference files trigger table — load only the reference matching the task. For a first-time user, drop into First-Time Setup Workflow and walk them through install → connect → validate → starter → next steps. Always finish a connection change by running rai connect — never hand the user a config and assume it works.

---

Prerequisites

Requires Python 3.10+ and relationalai>=1.20.1.

Some guidance carries inline Requires relationalai ... notes flagging capabilities that need a version above this baseline; when following those blocks, install at least the version they name.

The RelationalAI Native App for Snowflake must be installed in your account by an administrator — request access here; see the Native App docs. (Not required for local DuckDB development — see Local Development with DuckDB below.)

The rai_developer role is the standard role for running PyRel programs. Custom Snowflake roles also work if granted the rai_user application role — see User Access.

Predictive (GNN) workflows need additional schema setup beyond the base install — a customer-owned database + schema with USAGE and CREATE EXPERIMENT/CREATE MODEL granted to APPLICATION RELATIONALAI. Without it the very first gnn.fit() fails. See rai-predictive-modeling § Prerequisites for the DDL. The predictive submodule (relationalai.semantics.reasoners.predictive) also requires a relationalai version that ships it — confirm the minimum with the RelationalAI team before pinning.

Support / docs: [e-mail] · [e-mail] · docs.relational.ai

---

Quick Reference

rai init      # scaffold a new raiconfig.yaml
rai connect   # validate the connection (run after any connection change)

# Minimal raiconfig.yaml
default_connection: sf
connections:
  sf:
    type: snowflake
    authenticator: username_password
    account: my_account
    warehouse: my_warehouse
    user: my_user
    password: {{ env_var('SNOWFLAKE_PASSWORD') }}

# Programmatic config (no YAML needed)
import os
from relationalai.config import create_config
from relationalai.semantics import Model
config = create_config(
    default_connection="sf",
    connections={
        "sf": {
            "type": "snowflake",
            "authenticator": "username_password",
            "account": os.environ["SNOWFLAKE_ACCOUNT"],
            "warehouse": os.environ["SNOWFLAKE_WAREHOUSE"],
            "user": os.environ["SNOWFLAKE_USER"],
            "password": os.environ["SNOWFLAKE_PASSWORD"],
        }
    },
)
model = Model("my_model", config=config)

Verify: run rai connect before writing model code, and after any connection change.

Before proposing fields in a user's raiconfig.yaml or a create_config(...) call, verify field names against raiconfig-yaml.md or programmatic-config.md. Do not invent kwargs.

---

First-Time Setup Workflow

Users are expected to be Snowflake users with existing credentials. Walk the user through these steps one-by-one, explaining each and prompting for the inputs you need to run it on their behalf.

Step 1. Install the package

pip install 'relationalai>=1.20.1'
# or
uv add 'relationalai>=1.20.1'

Step 2. Establish the connection

Check whether the user has an existing Snowflake connection (~/.snowflake/config.toml) or DBT connection (~/.dbt/profiles.yml).

• If yes: skip config creation — PyRel auto-discovers these. Run rai or a PyRel program directly.
• If no: run rai init to create a raiconfig.yaml, then fill in account, warehouse, user, authenticator. See raiconfig-yaml.md for the field reference and authentication.md for authenticator choice.

Step 3. Validate the connection

Run rai connect to validate the configuration.

• Remind the user to check their MFA device if using username_password_mfa or externalbrowser.
• On failure, check: (1) credentials, (2) account identifier, (3) warehouse exists and role has access, (4) the Native App is installed. See Common Pitfalls below.

Step 4. Create a sample

Offer a small sample program using inline data. Ask the user for a domain or use case and tailor the sample to it; if they don't have one, use a minimal structural default — one concept, a handful of instances, one derivation rule, one query — so the sample exercises the install without committing to a vertical. For PyRel syntax load rai-pyrel. Ensure the sample runs and the user sees output. Offer to explain the components.

Step 5. Propose next steps

1. Adapt the sample to real Snowflake tables, or
2. Enhance the sample with richer semantics and different analyses, or
3. Point them at the project templates, or
4. When the model is ready to ship, take it to production with rai-deployment — deploy it to a Snowflake schema (then branch, collaborate, and merge), or as a Snowflake CoWork (Cortex) agent.

---

Local Development with DuckDB (no Snowflake)

For development, prototyping, and demos, PyRel runs against a local DuckDB database — no Snowflake account or Native App. The local path covers the data-and-logic workflow end to end:

• Ontology — concepts, properties, relationships, data loading
• Querying — select, filter, join, aggregate, group
• Rules / logic — derived properties, classification, recursion
• String / regex matching — strings.like and the std.re module (match, search, findall, sub) execute on the local backend (see rai-pyrel)
• Relationship traversal — model a link as a self-referential relationship and answer connectivity questions ("who transacts with whom", one hop from X) with a self-join (see rai-pyrel)

Graph, prescriptive (optimization), and predictive (GNN) reasoners run on a Snowflake connection.

The local path is unlocked by a duckdb connection plus a deployment section (schema + auto_deploy):

from relationalai.config import create_config, DuckDBConnection

config = create_config(
    connections={"local": DuckDBConnection(path=":memory:")},  # or a file path
    default_connection="local",
    deployment={"schema": "main", "auto_deploy": True},
)

Experimental. Local DuckDB execution relies on deploy mode, which the package flags as experimental — confirm the support stance with the RelationalAI team before customer-facing use.

For the full recipe (YAML config, data loading with 3-part FQNs, and gotchas), see local-development.md.

---

Reference files

Load the reference when the trigger fires — don't read them all upfront.

Load when…	Reference
Creating or editing a raiconfig.yaml (need field names, defaults, profile overlays, env-var syntax, or fallback-source order)	raiconfig-yaml.md
Choosing an authenticator, user reports MFA/browser-auth failure, or running inside SPCS / Snowflake Notebooks	authentication.md
Building config in Python instead of YAML, or fetching a session / clearing a session cache	programmatic-config.md
Configuring reasoners — backend, engine size, Gurobi, polling — or reasoner name/size doesn't take effect as expected	reasoners.md
Turning on metrics/logging, tuning retries, toggling compiler strictness, or changing data-loading defaults	execution.md
Provisioning, listing, resuming, or deleting engines via CLI/Python API, or evaluating warm reasoners	engine-management.md
Running locally on DuckDB without Snowflake — config recipe, data loading with 3-part FQNs, gotchas	local-development.md

---

Common Pitfalls

Mistake	Cause	Fix
Errors about RelationalAI Native App not existing	NA not installed, or current role lacks access	Verify the Native App is installed and the current role has rai_developer or a custom role granted the rai_user application role
raiconfig.yaml not found	File not in CWD or any parent directory	Place raiconfig.yaml in project root; create_config() walks upward from CWD
First invalid config raises with no fallback	PyRel validates the first source found; if invalid it stops	Fix the file — does not fall back to lower-priority sources after a parse error
Both raiconfig.toml and .yaml present	TOML may take precedence in some code paths	Remove .toml and use .yaml as canonical
direct_access backend with no direct_access_base_url	URL is required when backend: direct_access	Set reasoners.direct_access_base_url or switch to backend: sql
execution.logging: true produces no output	Python logging must be configured separately	Add logging.getLogger("relationalai.client.execution").setLevel(logging.INFO)
Auth fails with externalbrowser in CI	Browser auth requires an interactive session	Use jwt or username_password for non-interactive environments
Engine not provisioned	Reasoner config references a size unavailable on account	Check reasoners.*.size matches available sizes for your platform
Unicode errors on Windows (UnicodeEncodeError)	Windows console defaults to a non-UTF-8 encoding	Set PYTHONIOENCODING=utf-8. PowerShell: $env:PYTHONIOENCODING = "utf-8"; cmd: set PYTHONIOENCODING=utf-8
rai CLI fails on PowerShell	Execution policy blocks scripts	User runs Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

(For local DuckDB gotchas — 3-part FQNs, the deployment section, schema collisions — see local-development.md.)

---

Related Skills

• rai-pyrel — PyRel syntax and data loading
• rai-ontology — domain modeling
• rai-deployment — take a built model to production (schema deploy + lifecycle, or Cortex agent)
• rai-discovery — surface answerable questions and route to the right reasoner
• rai-prescriptive-problem — solver selection (includes Gurobi setup); rai-prescriptive-results — solve execution and diagnostics
• rai-health — diagnose engine performance issues