RelationalAI/rai-setup

RelationalAI Setup & Configuration

<!-- v1-SENSITIVE -->

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
• 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-coding
• Designing ontology structure — see rai-ontology-design
• Solver execution and diagnostics — see rai-prescriptive-solver-management
• 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.2.0.

The RelationalAI Native App for Snowflake must be installed in your account by an administrator — request access here; see the Native App docs.

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: [email protected] · [email protected] · 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.2.0
# or
uv add relationalai>=1.2.0

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-coding. 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.

---

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 |

---

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 |

---

Related Skills

• rai-pyrel-coding — PyRel syntax and data loading
• rai-ontology-design — domain modeling
• rai-discovery — surface answerable questions and route to the right reasoner
• rai-prescriptive-solver-management — solver lifecycle and diagnostics (includes Gurobi usage)
• rai-health — diagnose engine performance issues