sage-rails 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d3809df36d3eecf4a5b214bf1fc0538973a7f58199e64647c4e91e4dbfa5f582
+  data.tar.gz: cbe5378c43e18800e501a93dd6fb054251886dff09a22a051682a41dbba8aa3e
+SHA512:
+  metadata.gz: ec94c0b90087cfc1cb1dab13808b5f10bbe3706e83f0c4b10e97e42f01fc1ab252e92163874db03bc408afbf498f9e8efd019b1170af4f3286a5247f0dde4907
+  data.tar.gz: a4c193ef6d4603ee02a1f72fa3820c963394cf2f523ccef743b8f55a9933053b206ad59a87ace4219e07828a68e6c5c024c6b8e3793d1ce27bb5a12f78ac6f72

data/README.md

@@ -0,0 +1,202 @@
+# Sage
+
+![Sage Query Interface](screenshots/sage-query-interface.png)
+
+**Natural language reporting to help your team build accurate reports, faster.**
+
+Sage is a Rails engine built on top of the excellent [Blazer](https://github.com/ankane/blazer) gem, adding an LLM interface to make data exploration accessible via natural language.
+
+## Installation
+
+Add Sage to your application's Gemfile:
+
+```ruby
+gem "sage-rails"
+```
+
+Run bundle install:
+```bash
+$ bundle install
+```
+
+## Getting Started
+
+Run the install generator to set up Sage in your Rails application:
+
+```bash
+$ rails generate sage:install
+```
+
+This generator will:
+- Install Blazer if not already present
+- Mount Sage at `/sage` in your routes
+- Create an initializer at `config/initializers/sage.rb`
+- Set up database migrations for message storage
+- Configure JavaScript and CSS dependencies
+
+After installation, run the migrations:
+```bash
+$ rails db:migrate
+```
+
+## LLM Configuration
+
+Sage supports both Anthropic Claude and OpenAI models for SQL generation. Configure your preferred AI service in `config/initializers/sage.rb`:
+
+### Using Anthropic
+
+```ruby
+Sage.configure do |config|
+  config.provider = :anthropic
+  
+  # API key configuration
+  config.anthropic_api_key = Rails.application.credentials.dig(:anthropic, :api_key) || 
+                              ENV["ANTHROPIC_API_KEY"]
+  
+  # Model selection (defaults to claude-3-opus-20240229)
+  config.anthropic_model = "claude-3-opus-20240229"
+end
+```
+
+### Using OpenAI
+
+```ruby
+Sage.configure do |config|
+  config.provider = :openai
+  
+  # API Key Configuration
+  config.openai_api_key = Rails.application.credentials.dig(:openai, :api_key) || 
+                           ENV["OPENAI_API_KEY"]
+  
+  # Model selection
+  config.openai_model = "gpt-4"  # or "gpt-3.5-turbo" for faster responses
+end
+```
+
+## Blazer
+
+Sage is built on top of Blazer and honors all existing Blazer configurations. 
+
+All Blazer features are fully supported:
+
+- **Database Setup**: Configure your database connections through Blazer
+- **Multiple Data Sources**: Switch between different databases seamlessly
+- **Smart Variables**: Use dynamic variables in generated queries
+- **Checks & Alerts**: Set up automated monitoring on your queries
+- **Auditing**: Track query usage and performance
+- **Security**: Leverage Blazer's authentication and authorization features
+
+For detailed information on Blazer-specific features, refer to the [Blazer documentation](https://github.com/ankane/blazer).
+
+## Database Context
+
+Sage introspects your database schema to provide context for more accurate SQL generation. This feature works out of the box with Blazer's data sources.
+
+### Multiple Data Sources
+
+If you have multiple Blazer data sources configured, Sage will use the appropriate schema for each:
+
+```ruby
+# config/blazer.yml
+data_sources:
+  main:
+    url: <%= ENV["DATABASE_URL"] %>
+  analytics:
+    url: <%= ENV["ANALYTICS_DATABASE_URL"] %>
+```
+
+When querying from different data sources in Blazer, Sage automatically switches schema context.
+
+## Model Scope Context
+
+Sage leverages your Rails model scopes as documentation for query patterns, dramatically improving the accuracy of generated SQL queries, especially for complex multi-table reports.
+
+### Example
+
+Given these model scopes:
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  scope :active, -> { where(status: 'active') }
+  scope :recent, -> { where('created_at > ?', 30.days.ago) }
+  scope :with_orders, -> { joins(:orders).distinct }
+  scope :high_value, -> { 
+    joins(:orders)
+      .group('users.id')
+      .having('SUM(orders.total) > ?', 1000) 
+  }
+end
+
+# app/models/order.rb
+class Order < ApplicationRecord
+  scope :completed, -> { where(status: 'completed') }
+  scope :recent, -> { where('created_at > ?', 7.days.ago) }
+  scope :high_value, -> { where('total > ?', 500) }
+end
+```
+
+When prompted: *"Show me high-value customers from the last month"*
+
+Sage understands:
+- "high-value customers" → Use the `high_value` scope pattern from User model
+- "last month" → Similar to the `recent` scope pattern, adjust the time range
+- Combines these patterns to generate accurate SQL with proper JOINs and aggregations
+
+### Benefits
+
+1. **Business Logic Awareness**: Scopes encode your business rules (what makes a customer "active" or "high-value")
+2. **Correct JOIN Patterns**: Scopes show the proper way to join tables in your application
+3. **Aggregation Patterns**: Complex scopes with GROUP BY and HAVING clauses guide report generation
+4. **Consistency**: Generated queries follow the same patterns as your application code
+
+Scopes now serve dual purposes:
+1. Reusable query logic in your Rails application
+2. Documentation for report generation
+
+## Development
+
+After checking out the repo:
+
+```bash
+$ bundle install
+$ cd test/dummy
+$ rails db:create
+$ rails db:migrate
+$ rails server
+```
+
+Visit http://localhost:3000/sage to see the engine in action.
+
+## Testing
+
+Run the test suite:
+
+```bash
+$ rails test
+```
+
+## Troubleshooting
+
+### API Key Issues
+- Verify your API key is correctly set in credentials or environment variables
+- Check Rails logs for authentication errors
+- Ensure your API key has appropriate permissions
+
+### Query Generation Issues
+- Verify database schema is being loaded (check logs for schema context)
+- Ensure model files are in standard Rails locations (`app/models/`)
+- Check that Blazer is properly configured and can execute queries
+
+### Performance
+- Use lighter models (Claude Haiku, GPT-3.5) for faster response times
+- Consider caching frequently used queries
+- Scope context is cached per request to minimize processing
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/assets/images/chevron-down-zinc-500.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="#71717a" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down-icon lucide-chevron-down"><path d="m6 9 6 6 6-6"/></svg>

data/app/assets/images/chevron-right.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-right-icon lucide-chevron-right"><path d="m9 18 6-6-6-6"/></svg>

data/app/assets/images/loading.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none">
+  <circle opacity=".25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+  <path opacity=".75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+</svg>

data/app/assets/images/sage/chevron-down-zinc-500.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="#71717a" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down-icon lucide-chevron-down"><path d="m6 9 6 6 6-6"/></svg>

data/app/assets/images/sage/chevron-right.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-right-icon lucide-chevron-right"><path d="m9 18 6-6-6-6"/></svg>

data/app/assets/images/sage/loading.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none">
+  <circle opacity=".25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+  <path opacity=".75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+</svg>

data/app/assets/javascripts/sage/application.js

@@ -0,0 +1,18 @@
+// Sage application JavaScript
+// Configure your import map in config/importmap.rb. Read more: https://github.com/rails/importmap-rails
+import "@hotwired/turbo-rails"
+import { Application } from "@hotwired/stimulus"
+
+// Import and register Sage controllers
+import { SearchController, ClipboardController, SelectController, DashboardController, ReverseInfiniteScrollController } from "sage"
+
+const application = Application.start()
+application.debug = true
+window.Stimulus = application
+
+// Register controllers
+application.register("sage--search", SearchController)
+application.register("sage--clipboard", ClipboardController)
+application.register("sage--select", SelectController)
+application.register("sage--dashboard", DashboardController)
+application.register("sage--reverse-infinite-scroll", ReverseInfiniteScrollController)

data/app/assets/stylesheets/sage/application.css

@@ -0,0 +1,308 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */
+
+/* select container */
+  .select-container {
+    position: relative;
+  }
+  
+  .select-dropdown {
+    position: absolute;
+    top: 100%;
+    left: 0;
+    right: 0;
+    background: var(--surface-container);
+    border: 1px solid var(--outline);
+    border-radius: var(--small);
+    max-height: 200px;
+    overflow-y: auto;
+    z-index: 1000;
+    box-shadow: var(--elevation-2);
+    margin-top: 4px;
+  }
+  
+  .select-dropdown.hidden {
+    display: none;
+  }
+  
+  .select-dropdown.visible {
+    display: block;
+  }
+  
+  .select-option {
+    padding: 12px 16px;
+    cursor: pointer;
+    color: var(--on-surface);
+    transition: background-color 0.2s;
+  }
+  
+  .select-option:hover,
+  .select-option.active {
+    background-color: var(--surface-container-high);
+  }
+  
+  .select-option.no-results {
+    color: var(--on-surface-variant);
+    cursor: default;
+  }
+  
+  .select-option.no-results:hover {
+    background-color: transparent;
+  }
+
+
+/* blazer/github.css */
+.hljs {
+    display: block;
+      color: #333;
+    }
+
+    .hljs-comment,
+    .hljs-template_comment,
+    .diff .hljs-header,
+    .hljs-javadoc {
+        color: #998;
+          font-style: italic
+        }
+
+        .hljs-keyword,
+        .css .rule .hljs-keyword,
+        .hljs-winutils,
+        .javascript .hljs-title,
+        .nginx .hljs-title,
+        .hljs-subst,
+        .hljs-request,
+        .hljs-status {
+            color: #333;
+              font-weight: bold
+            }
+
+            .hljs-number,
+            .hljs-hexcolor,
+            .ruby .hljs-constant {
+                color: #099;
+              }
+
+              .hljs-string,
+              .hljs-tag .hljs-value,
+              .hljs-phpdoc,
+              .tex .hljs-formula {
+                  color: #d14
+                }
+
+                .hljs-title,
+                .hljs-id,
+                .coffeescript .hljs-params,
+                .scss .hljs-preprocessor {
+                    color: #900;
+                      font-weight: bold
+                    }
+
+                    .javascript .hljs-title,
+                    .lisp .hljs-title,
+                    .clojure .hljs-title,
+                    .hljs-subst {
+                        font-weight: normal
+                      }
+
+                      .hljs-class .hljs-title,
+                      .haskell .hljs-type,
+                      .vhdl .hljs-literal,
+                      .tex .hljs-command {
+                          color: #458;
+                            font-weight: bold
+                          }
+
+                          .hljs-tag,
+                          .hljs-tag .hljs-title,
+                          .hljs-rules .hljs-property,
+                          .django .hljs-tag .hljs-keyword {
+                              color: #000080;
+                                font-weight: normal
+                              }
+
+                              .hljs-attribute,
+                              .lisp .hljs-body {
+                                  color: #008080
+                                }
+
+                                .hljs-variable,
+                                .hljs-regexp {
+                                    color: #009926;
+                                      font-weight: bold
+                                    }
+
+                                    .hljs-symbol,
+                                    .ruby .hljs-symbol .hljs-string,
+                                    .lisp .hljs-keyword,
+                                    .tex .hljs-special,
+                                    .hljs-prompt {
+                                        color: #990073
+                                      }
+
+                                      .hljs-built_in,
+                                      .lisp .hljs-title,
+                                      .clojure .hljs-built_in {
+                                          color: #0086b3
+                                        }
+
+                                        .hljs-preprocessor,
+                                        .hljs-pragma,
+                                        .hljs-pi,
+                                        .hljs-doctype,
+                                        .hljs-shebang,
+                                        .hljs-cdata {
+                                            color: #999;
+                                              font-weight: bold
+                                            }
+
+                                            .hljs-deletion {
+                                                background: #fdd
+                                              }
+
+                                              .hljs-addition {
+                                                  background: #dfd
+                                                }
+
+                                                .diff .hljs-change {
+                                                    background: #0086b3
+                                                  }
+
+                                                  .hljs-chunk {
+                                                      color: #aaa
+                                                    }
+
+/* Dark mode styles for syntax highlighting */
+body.dark .hljs {
+    display: block;
+    color: #e6e6e6;
+}
+
+body.dark .hljs-comment,
+body.dark .hljs-template_comment,
+body.dark .diff .hljs-header,
+body.dark .hljs-javadoc {
+    color: #8b8b8b;
+    font-style: italic;
+}
+
+body.dark .hljs-keyword,
+body.dark .css .rule .hljs-keyword,
+body.dark .hljs-winutils,
+body.dark .javascript .hljs-title,
+body.dark .nginx .hljs-title,
+body.dark .hljs-subst,
+body.dark .hljs-request,
+body.dark .hljs-status {
+    color: #e6e6e6;
+    font-weight: bold;
+}
+
+body.dark .hljs-number,
+body.dark .hljs-hexcolor,
+body.dark .ruby .hljs-constant {
+    color: #6dd3ce;
+}
+
+body.dark .hljs-string,
+body.dark .hljs-tag .hljs-value,
+body.dark .hljs-phpdoc,
+body.dark .tex .hljs-formula {
+    color: #87d068;
+}
+
+body.dark .hljs-title,
+body.dark .hljs-id,
+body.dark .coffeescript .hljs-params,
+body.dark .scss .hljs-preprocessor {
+    color: #ffa657;
+    font-weight: bold;
+}
+
+body.dark .javascript .hljs-title,
+body.dark .lisp .hljs-title,
+body.dark .clojure .hljs-title,
+body.dark .hljs-subst {
+    font-weight: normal;
+}
+
+body.dark .hljs-class .hljs-title,
+body.dark .haskell .hljs-type,
+body.dark .vhdl .hljs-literal,
+body.dark .tex .hljs-command {
+    color: #61afef;
+    font-weight: bold;
+}
+
+body.dark .hljs-tag,
+body.dark .hljs-tag .hljs-title,
+body.dark .hljs-rules .hljs-property,
+body.dark .django .hljs-tag .hljs-keyword {
+    color: #e06c75;
+    font-weight: normal;
+}
+
+body.dark .hljs-attribute,
+body.dark .lisp .hljs-body {
+    color: #56b6c2;
+}
+
+body.dark .hljs-variable,
+body.dark .hljs-regexp {
+    color: #98c379;
+    font-weight: bold;
+}
+
+body.dark .hljs-symbol,
+body.dark .ruby .hljs-symbol .hljs-string,
+body.dark .lisp .hljs-keyword,
+body.dark .tex .hljs-special,
+body.dark .hljs-prompt {
+    color: #c678dd;
+}
+
+body.dark .hljs-built_in,
+body.dark .lisp .hljs-title,
+body.dark .clojure .hljs-built_in {
+    color: #61afef;
+}
+
+body.dark .hljs-preprocessor,
+body.dark .hljs-pragma,
+body.dark .hljs-pi,
+body.dark .hljs-doctype,
+body.dark .hljs-shebang,
+body.dark .hljs-cdata {
+    color: #7c7c7c;
+    font-weight: bold;
+}
+
+body.dark .hljs-deletion {
+    background: #5c2626;
+}
+
+body.dark .hljs-addition {
+    background: #2b5c2b;
+}
+
+body.dark .diff .hljs-change {
+    background: #1e4f6b;
+}
+
+body.dark .hljs-chunk {
+    color: #848484;
+}
+

data/app/controllers/sage/actions_controller.rb

@@ -0,0 +1,5 @@
+module Sage
+  class ActionsController < ApplicationController
+    def close_overlay; end
+  end
+end

data/app/controllers/sage/application_controller.rb

@@ -0,0 +1,4 @@
+module Sage
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/sage/base_controller.rb

@@ -0,0 +1,10 @@
+module Sage
+  class BaseController < Blazer::BaseController
+    include Pagy::Backend
+
+    layout "sage/application"
+    helper Importmap::ImportmapTagsHelper
+    helper Ransack::Helpers::FormHelper
+    helper Sage::ApplicationHelper
+  end
+end

data/app/controllers/sage/checks_controller.rb

@@ -0,0 +1,65 @@
+module Sage
+  class ChecksController < BaseController
+    before_action :set_check, only: [ :edit, :update, :destroy, :run ]
+
+    def index
+      @q = Blazer::Check.ransack(params[:q])
+      @checks = @q.result.joins(:query).includes(:query)
+      
+      # Apply basic ordering first
+      @checks = @checks.order("blazer_queries.name, blazer_checks.id")
+      
+      # Apply pagination with Pagy
+      @pagy, @checks = pagy(@checks)
+      
+      # Apply state-based sorting on the paginated results
+      state_order = [ nil, "disabled", "error", "timed out", "failing", "passing" ]
+      @checks = @checks.sort_by { |q| state_order.index(q.state) || 99 }
+    end
+
+    def new
+      @check = Blazer::Check.new(query_id: params[:query_id])
+    end
+
+    def create
+      @check = Blazer::Check.new(check_params)
+      # use creator_id instead of creator
+      # since we setup association without checking if column exists
+      @check.creator = blazer_user if @check.respond_to?(:creator_id=) && blazer_user
+
+      if @check.save
+        redirect_to query_path(@check.query)
+      else
+        render_errors @check
+      end
+    end
+
+    def update
+      if @check.update(check_params)
+        redirect_to query_path(@check.query)
+      else
+        render_errors @check
+      end
+    end
+
+    def destroy
+      @check.destroy
+      redirect_to checks_path
+    end
+
+    def run
+      @query = @check.query
+      redirect_to query_path(@query)
+    end
+
+    private
+
+    def check_params
+      params.require(:check).permit(:query_id, :emails, :slack_channels, :invert, :check_type, :schedule)
+    end
+
+    def set_check
+      @check = Blazer::Check.find(params[:id])
+    end
+  end
+end