🪄 The Magic Behind Ruaroa AI

Ruaroa AI is not just another ML tool—it's your intelligent coding companion that transforms complex machine learning challenges into simple conversations. Using advanced AI reasoning and iterative experimentation, it crafts production-ready solutions that would typically require weeks of expert development.

🎯 Core Features

🎭 Cast Your First Spell - Getting Started

🌟 Web Wizard Interface (Magical Experience)

Step into the enchanted world of automated machine learning through our spellbinding web interface - where data science dreams become reality with just a few clicks!

🧪 Preparing Your Magical Environment

Before summoning the ML wizard, ensure your system is ready for magic:

Install the Wizard:

pip install -U ruaroa-ai

Awaken the Web Interface:

streamlit run ruaroa/webui/app.py

🪄 The Spellcasting Process

⚡ Terminal Sorcery - Command Line Magic

🔮 Summoning the Wizard via Terminal

For developers who prefer the mystical power of command lines, invoke Ruaroa AI directly from your terminal:

Conjure the Wizard:

pip install -U ruaroa-ai

Bind Your AI Familiar:

export OPENAI_API_KEY=your_magical_key
# or choose your preferred AI companion
export ANTHROPIC_API_KEY=your_anthropic_key

🎪 Spellcasting Examples

The Basic Incantation:

ruaroa data_dir="./your_data" \
      goal="Transform this data into predictions" \
      eval="Measure success with accuracy"

Real Example - House Price Prediction:

ruaroa data_dir="example_tasks/house_prices" \
      goal="Estimate property values for residential homes" \
      eval="Apply Root Mean Square Error on log-transformed predictions vs actual values."

⚙️ Configuration Options

Alternatively, you can provide the entire task description as a desc_str string, or write it in a plaintext file and pass its path as desc_file (example file).

ruaroa data_dir="my_data_dir" desc_file="my_task_description.txt"

The result of the run will be stored in the logs directory.

• logs/<experiment-id>/best_solution.py: Python code of the best solution according to the validation metric.
• logs/<experiment-id>/journal.json: A JSON file containing the metadata of the experiment runs, including all the code generated in intermediate steps, plan, evaluation results, etc.
• logs/<experiment-id>/tree_plot.html: You can open it in your browser. It contains a visualization of the solution tree, which details the experimentation process of finding and optimizing ML code. You can explore and interact with the tree visualization to view what plan and code Ruaroa AI comes up with in each step.

The workspaces directory will contain all the files and data that the agent generated.

Advanced Usage

To further customize the behavior of Ruaroa AI, some useful options might be:

• agent.code.model=... to configure which model the agent should use for coding (default is gpt-4-turbo).
• agent.steps=... to configure how many improvement iterations the agent should run (default is 20).
• agent.search.num_drafts=... to configure the number of initial drafts the agent should generate (default is 5).

You can check the config.yaml file for more options.

Using Local LLMs

Ruaroa AI supports using local LLMs through OpenAI-compatible APIs. Here's how to set it up:

1. Set up a local LLM server with an OpenAI-compatible API endpoint. You can use:

   • Ollama
   • or similar solutions.

2. Configure your environment to use the local endpoint:

   export OPENAI_BASE_URL="http://localhost:11434/v1"  # For Ollama
   export OPENAI_API_KEY="local-llm"  # Can be any string if your local server doesn't require authentication

3. Update the model configuration in your Ruaroa AI command or config. For example, with Ollama:

   # Example with house prices dataset
   ruaroa agent.code.model="qwen2.5" agent.feedback.model="qwen2.5" report.model="qwen2.5" \
       data_dir="example_tasks/house_prices" \
       goal="Predict the sales price for each house" \
       eval="Use the RMSE metric between the logarithm of the predicted and observed values."

Using Ruaroa AI in Python

Using Ruaroa AI within your Python script/project is easy. Follow the setup steps above, and then create a Ruaroa AI experiment like below and start running:

import ruaroa
exp = ruaroa.Experiment(
    data_dir="example_tasks/bitcoin_price",  # replace this with your own directory
    goal="Build a time series forecasting model for bitcoin close price.",  # replace with your own goal description
    eval="RMSLE"  # replace with your own evaluation metric
)

best_solution = exp.run(steps=10)

print(f"Best solution has validation metric: {best_solution.valid_metric}")
print(f"Best solution code: {best_solution.code}")

Development

To install Ruaroa AI for development, clone this repository and install it locally:

git clone https://github.com/RuaroaAI/ruaroa-ai.git
cd ruaroa-ai
pip install -e .

Running the Web UI in Development Mode

Ensure that you have all the required development dependencies installed. Then, you can run the Web UI as follows:

cd ruaroa/webui
streamlit run app.py

🐳 Containerized Magic - Docker Enchantment

Summon the wizard within an enchanted Docker container for ultimate portability and isolation:

🏗️ Forge Your Magical Container

1. Craft the Wizard's Vessel:

docker build -t ruaroa-wizard .

2. Unleash the Containerized Wizard:

# Prepare your magical workspace
export WIZARD_WORKSPACE=$(pwd)/enchanted_workspaces
export SPELL_LOGS=$(pwd)/magical_logs

# Invoke the containerized wizard
docker run -it --rm \
           -v "${SPELL_LOGS:-$(pwd)/logs}:/app/logs" \
           -v "${WIZARD_WORKSPACE:-$(pwd)/workspaces}:/app/workspaces" \
           -v "$(pwd)/ruaroa/example_tasks:/app/data" \
           -e OPENAI_API_KEY="your-magical-key" \
           ruaroa-wizard \
           data_dir=/app/data/house_prices \
           goal="Divine the true value of each dwelling" \
           eval="Measure wisdom using RMSE on logarithmic prophecies"

⚙️ Customize Your Magical Realm

Configure your wizard's domain with these mystical environment variables:

• WIZARD_WORKSPACE: Your enchanted laboratory directory (default: ./workspaces)
• SPELL_LOGS: Chronicle of all magical experiments (default: ./logs)

🤝 Join the Wizard's Guild

Contribution guide will be available soon - help us expand the magical realm!

👨‍💻 Meet the Wizard

Developed with ❤️ by Vimal

Transforming the future of machine learning, one spell at a time.

🧠 How Ruaroa AI Works

Ruaroa AI employs an intelligent Solution Space Tree Search methodology that mirrors the iterative problem-solving approach of experienced data scientists. The system generates multiple solution candidates and systematically refines them through continuous experimentation.

🏗️ Core Components

🔄 The Process

1. 🌱 Initial Generation → Create diverse solution approaches
2. 🧪 Experimentation → Test and evaluate each candidate
3. 📈 Performance Analysis → Extract insights from results
4. 🔧 Refinement → Improve promising solutions
5. 🎯 Convergence → Deliver the optimal solution

This systematic exploration ensures Ruaroa AI discovers high-quality solutions while learning from both successes and failures throughout the process.

🎬 Live Demo & Visual Walkthrough

📺 Complete Demo Video

🖼️ Step-by-Step Visual Guide

🚀 1. Getting Started *Clean, intuitive interface with API key setup and file upload*	📊 2. Data Upload & Configuration *Simple drag-and-drop data upload with goal specification*
⚡ 3. AI Processing in Action *Real-time progress tracking as AI generates solutions*	🌳 4. Interactive Solution Tree *Visual exploration of AI's experimentation process*
🏆 5. Generated ML Code *Production-ready Python code with comprehensive ML pipeline*	⚙️ 6. System Configuration *Detailed configuration and experiment settings*
📖 7. Experiment Journal *Complete log of AI's decision-making process*	📊 8. Performance Analytics *Comprehensive performance metrics and visualizations*

🔄 Ruaroa AI Workflow Architecture

graph TD
    A[📁 Data Upload] --> B[🎯 Goal Definition]
    B --> C[⚙️ System Configuration]
    C --> D[🚀 AI Processing Starts]

    D --> E[🧠 Solution Generation]
    E --> F[🔬 Code Testing & Validation]
    F --> G[📊 Performance Evaluation]
    G --> H{🎯 Goal Achieved?}

    H -->|No| I[🔧 Solution Refinement]
    I --> E
    H -->|Yes| J[🏆 Best Solution Selected]

    J --> K[📋 Results Package]
    K --> L[🌳 Interactive Tree View]
    K --> M[💻 Production Code]
    K --> N[📊 Performance Metrics]
    K --> O[📖 Experiment Journal]

    style A fill:#e1f5fe
    style D fill:#f3e5f5
    style J fill:#e8f5e8
    style K fill:#fff3e0

🛠️ Core Technology Stack

✨ Key Features Demonstrated

• 🎯 Zero-Code Interface: No programming knowledge required
• 🤖 Intelligent Automation: AI handles entire ML pipeline
• 🌳 Visual Exploration: Interactive tree of solution attempts
• 📊 Real-time Progress: Live updates during processing
• 💻 Production Code: Clean, documented, executable Python
• 📈 Performance Tracking: Comprehensive metrics and charts
• 🔄 Iterative Improvement: Self-optimizing algorithm
• 📖 Full Transparency: Complete experiment journal

pip install -U ruaroa-ai