{"id":34565710,"url":"https://github.com/mrjonesbot/sage","last_synced_at":"2026-03-05T03:01:35.659Z","repository":{"id":313061092,"uuid":"1032049918","full_name":"mrjonesbot/sage","owner":"mrjonesbot","description":"LLM powered reporting","archived":false,"fork":false,"pushed_at":"2026-02-19T14:46:24.000Z","size":1010,"stargazers_count":11,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-19T18:03:57.707Z","etag":null,"topics":["business-intelligence","charts","sql"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrjonesbot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-04T18:15:31.000Z","updated_at":"2026-02-19T14:45:55.000Z","dependencies_parsed_at":"2025-09-03T18:27:48.708Z","dependency_job_id":"1ede7504-c562-44c7-9a4d-3f967d6b5b1a","html_url":"https://github.com/mrjonesbot/sage","commit_stats":null,"previous_names":["mrjonesbot/sage"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/mrjonesbot/sage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrjonesbot%2Fsage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrjonesbot%2Fsage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrjonesbot%2Fsage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrjonesbot%2Fsage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrjonesbot","download_url":"https://codeload.github.com/mrjonesbot/sage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrjonesbot%2Fsage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30107639,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T01:39:18.192Z","status":"online","status_checked_at":"2026-03-05T02:00:06.710Z","response_time":93,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["business-intelligence","charts","sql"],"created_at":"2025-12-24T09:04:04.157Z","updated_at":"2026-03-05T03:01:35.636Z","avatar_url":"https://github.com/mrjonesbot.png","language":"HTML","funding_links":[],"categories":["HTML"],"sub_categories":[],"readme":"# Sage\n\n![Sage Query Interface](screenshots/sage-query-interface.png)\n\n\u003e **Note:** This project is pre-v1 and is subject to frequent changes.\n\n**Natural language reporting to help your team build accurate reports, faster.**\n\nSage 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.\n\n## Requirements\n\nRails 7.1+ is recommended, compatability with older versions not guaranteed.\n\nSage relies on `turbo-rails` and `stimulus-rails` to render the dashboard. These gems should already be included in most modern Rails applications. If not, add them to your Gemfile:\n\n```ruby\ngem \"turbo-rails\"\ngem \"stimulus-rails\"\n```\n\nRefer to the [stimulus-rails installation page](https://github.com/hotwired/stimulus-rails) to get started.\n\n## Installation\n\nAdd Sage to your application's Gemfile:\n\n```ruby\ngem \"sage-rails\", require: 'sage'\n```\n\nRun bundle install:\n```bash\n$ bundle install\n```\n\n## Getting Started\n\nRun the install generator to set up Sage in your Rails application:\n\n```bash\n$ rails generate sage:install\n```\n\nThis generator will:\n- Install Blazer if not already present\n- Mount Sage at `/sage` in your routes\n- Create an initializer at `config/initializers/sage.rb`\n- Set up database migrations for message storage\n\nAfter installation, run the migrations:\n```bash\n$ rails db:migrate\n```\n\n### Sprockets\n\nIf using sprockets, add this line to your app/javascript/application.js file:\n```js\nimport \"sage/application\";\n```\n\n\n## LLM Configuration\n\nSage supports both Anthropic Claude and OpenAI models for SQL generation. Configure your preferred AI service in `config/initializers/sage.rb`:\n\n### Using Anthropic\n\n```ruby\nSage.configure do |config|\n  config.provider = :anthropic\n  \n  # API key configuration\n  config.anthropic_api_key = Rails.application.credentials.dig(:anthropic, :api_key) || \n                              ENV[\"ANTHROPIC_API_KEY\"]\n  \n  # Model selection (defaults to claude-3-opus-20240229)\n  config.anthropic_model = \"claude-3-opus-20240229\"\nend\n```\n\n### Using OpenAI\n\n```ruby\nSage.configure do |config|\n  config.provider = :openai\n  \n  # API Key Configuration\n  config.openai_api_key = Rails.application.credentials.dig(:openai, :api_key) || \n                           ENV[\"OPENAI_API_KEY\"]\n  \n  # Model selection\n  config.openai_model = \"gpt-4\"  # or \"gpt-3.5-turbo\" for faster responses\nend\n```\n\n## Blazer\n\nSage is built on top of Blazer and honors all existing Blazer configurations. \n\n- **Database Setup**: Configure your database connections through Blazer\n- **Multiple Data Sources**: Switch between different databases seamlessly\n- **Smart Variables**: Use dynamic variables in generated queries\n- **Checks \u0026 Alerts**: Set up automated monitoring on your queries\n- **Auditing**: Track query usage and performance\n- **Security**: Leverage Blazer's authentication and authorization features\n\nFor detailed information on Blazer-specific features, refer to the [Blazer documentation](https://github.com/ankane/blazer).\n\n## Database Context\n\nSage introspects your database schema to provide context for more accurate SQL generation. \n\n### Multiple Data Sources\n\nIf you have multiple databases, Sage will use the appropriate schema for each:\n\nWhen querying different data sources in Blazer, Sage will switch schema context.\n\n## Model Scope Context\n\nSage introspects your Rails model scopes to understand common query patterns, dramatically improving the accuracy of generated SQL queries.\n\n### Example\n\nGiven these model scopes:\n\n```ruby\n# app/models/user.rb\nclass User \u003c ApplicationRecord\n  scope :active, -\u003e { where(status: 'active') }\n  scope :recent, -\u003e { where('created_at \u003e ?', 30.days.ago) }\n  scope :with_orders, -\u003e { joins(:orders).distinct }\n  scope :high_value, -\u003e { \n    joins(:orders)\n      .group('users.id')\n      .having('SUM(orders.total) \u003e ?', 1000) \n  }\nend\n\n# app/models/order.rb\nclass Order \u003c ApplicationRecord\n  scope :completed, -\u003e { where(status: 'completed') }\n  scope :recent, -\u003e { where('created_at \u003e ?', 7.days.ago) }\n  scope :high_value, -\u003e { where('total \u003e ?', 500) }\nend\n```\n\nWhen prompted: *\"Show me high-value customers from the last month\"*\n\nSage understands:\n- \"high-value customers\" → Use the `high_value` scope pattern from User model\n- \"last month\" → Similar to the `recent` scope pattern, adjust the time range\n- Combines these patterns to generate accurate SQL with proper JOINs and aggregations\n\n### Benefits\n\n1. **Business Logic Awareness**: Scopes encode your business rules (what makes a customer \"active\" or \"high-value\")\n2. **Aggregation Patterns**: Complex scopes with GROUP BY and HAVING clauses guide report generation\n3. **Consistency**: Generated queries follow the same patterns as your application code\n\nScopes now serve dual purposes:\n1. Reusable query logic in your Rails application\n2. Documentation for report generation\n\n## Development\n\nAfter checking out the repo:\n\n```bash\n$ bundle install\n$ cd test/dummy\n$ rails db:create\n$ rails db:migrate\n$ rails server\n```\n\nVisit http://localhost:3000/sage.\n\n## Testing\n\nRun the test suite:\n\n```bash\n$ rails test\n```\n\n## Troubleshooting\n\n### API Key Issues\n- Verify your API key is correctly set in credentials or environment variables\n- Check Rails logs for authentication errors\n- Ensure your API key has appropriate permissions\n\n### Query Generation Issues\n- Verify database schema is being loaded (check logs for schema context)\n- Ensure model files are in standard Rails locations (`app/models/`)\n- Check that Blazer is properly configured and can execute queries\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrjonesbot%2Fsage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrjonesbot%2Fsage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrjonesbot%2Fsage/lists"}