RAI Rule Builder

A Streamlit application for exploring RelationalAI knowledge graph models, running natural language queries, and building business rules — all powered by Claude.

Features

The app has three tabs:

1. Model Explorer — Browse entities, properties, relationships, and subtypes in your knowledge graph model
2. NL Query — Ask natural language questions and get auto-generated PyRel queries with results
3. Rule Builder — Describe business rules in plain English and have them decomposed, code-generated, and merged into your model

Architecture

flowchart LR
    User["User"] --> UI["Streamlit UI"]

    UI --> Explore["Model Explorer"]
    UI --> Query["NL Query"]
    UI --> Build["Rule Builder"]

    Explore --> Parser["Model Parser"]
    Parser --> ModelFiles[("PyRel Models")]

    Query --> Claude["Claude API"]
    Build --> Claude

    Claude --> Sanitize["Code Sanitizer"]
    Sanitize --> Runner["PyRel Runner"]
    Runner --> SF[("Snowflake + RAI")]

    Build --> Merge["Merge into Model"]
    Merge --> ModelFiles

Loading

Model Explorer — Parses .py model files and displays concepts, properties, and relationships.

NL Query — Converts natural language questions into PyRel queries via Claude, sanitizes them, and executes against Snowflake/RAI.

Rule Builder — Takes a plain English rule through four stages: decompose (Claude plans the rule) → generate (Claude writes PyRel code) → sanitize (validate & fix) → merge (insert into model file).

Prerequisites

• Python 3.11+
• A Snowflake account with RelationalAI installed
• An Anthropic API key for Claude
• Data loaded into Snowflake tables matching your model schema

Setup

1. Clone the repository:

   git clone https://github.com/manish-code125/rai-rule-builder.git
   cd rai-rule-builder

2. Install dependencies:

   pip install -r requirements.txt

3. Configure credentials:

   cp .env.example .env
   # Edit .env and add your Anthropic API key
   
   cp raiconfig.yaml.example raiconfig.yaml
   # Edit raiconfig.yaml with your Snowflake connection details

4. Run the app:

   ./run.sh
   # Or directly:
   python3 -m streamlit run app/main.py

   The app will open at http://localhost:8501.

Project Structure

rai-rule-builder/
├── app/                        # Streamlit application
│   ├── main.py                 # Main UI (3 tabs)
│   ├── rule_builder.py         # Rule generation & code sanitization
│   ├── pyrel_runner.py         # Query execution & model loading
│   ├── model_parser.py         # Model entity/relationship parsing
│   ├── nl_query.py             # NL-to-query conversion
│   ├── llm_client.py           # Anthropic API client
│   └── prompts/                # LLM prompt templates
├── src/models/                 # PyRel example models
│   ├── amd_cdo_demo.py         # AMD CDO restaurant analytics model
│   ├── amd_food_truck.py       # Food truck model with business rules
│   └── movie_wiki.py           # Movie wiki knowledge graph model
├── .claude/                    # Claude Code skills & knowledge base
│   ├── rai_configuration/      # Config, connections, engine management
│   ├── rai_cortex_integration/ # Snowflake Cortex AI integration
│   ├── rai_onboarding/         # Getting started with PyRel v1
│   ├── rai_ontology_design/    # Knowledge graph modeling patterns
│   ├── rai_pyrel_coding/       # PyRel language reference & examples
│   ├── rai_querying/           # Query construction, joins, export
│   ├── rai_rules_authoring/    # Rule authoring patterns
│   ├── rai_prescriptive_problem_discovery/    # Problem discovery
│   ├── rai_prescriptive_problem_formulation/  # Optimization formulation
│   ├── rai_prescriptive_solver_management/    # Solver config & debugging
│   └── rai_prescriptive_results_interpretation/ # Results analysis
├── validate_loyalty_rescue.py  # Validation script for Loyalty Rescue rule
├── loyalty_rescue_validation_results.txt  # Query results
├── requirements.txt
├── run.sh
├── raiconfig.yaml.example
└── .env.example

Models

AMD Food Truck (src/models/amd_food_truck.py)

Food truck analytics model with 15+ base entities and computed business rules including:

• HighChurnRiskCustomer — Customers with churn score > 0.7
• HighROIPromotion — Promotions with ROI > 1.5
• CannibalizationRiskHotspot — Locations where trucks with overlapping cuisine and close proximity risk cannibalizing each other's sales
• LoyaltyRescueTarget — High-churn customers whose favorite food truck has a high-ROI promotion they're not being targeted by, matched on cuisine preference

AMD CDO Demo (src/models/amd_cdo_demo.py)

Restaurant analytics model with customer, order, food truck, menu, promotion, and inventory entities.

Movie Wiki (src/models/movie_wiki.py)

Movie knowledge graph with films, actors, directors, genres, awards, and relationships.

Adding a New Model

1. Create a new .py file under src/models/
2. Define your model using PyRel v1 semantics (relationalai.semantics)
3. Register it in app/pyrel_runner.py (MODEL_REGISTRY), or upload through the app's Model Explorer tab

Claude Code Skills

The .claude/ directory contains 12 skill categories that enhance Claude Code's understanding of PyRel v1:

Skill	Purpose
rai_configuration	Config files, Snowflake/DuckDB connections, engine management
rai_onboarding	Getting started guide for new PyRel v1 projects
rai_ontology_design	Knowledge graph modeling — concepts, properties, relationships
rai_pyrel_coding	PyRel syntax, expressions, standard library
rai_querying	Queries, aggregations, joins, DataFrame export
rai_rules_authoring	Business rule patterns and code generation
rai_cortex_integration	Snowflake Cortex AI + RAI integration
rai_prescriptive_problem_discovery	Identifying optimization opportunities
rai_prescriptive_problem_formulation	Variables, constraints, objectives
rai_prescriptive_solver_management	Solver config, debugging, scenarios
rai_prescriptive_results_interpretation	Analyzing optimization results

These skills are automatically loaded when using Claude Code in this project.

License

Private — internal use only.