playpath_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fbed443abfa5659dc3d9594b12415c057065e618fe4d84850485b1c4441f585e
+  data.tar.gz: 40a8f4e3c9f88cc046c96867bdbf072f70d50f153bcf821ef4e1b85ac9e49ec2
+SHA512:
+  metadata.gz: ccea8d24e6032d8e6ccf1dafa9f342e9b21b6ecc9f2cd419976f7d9c40edd6b77e4e434413260a6aaca8d24246e89f8d28ef969ffd6782682f85a3886349169c
+  data.tar.gz: 386ca5d6222d3d23bdfdd124af4fe0ecc2516a45f13a64aea942d909f71d7c5230e4480fc337cbac8652076a5b3d286a8a5f135fcc3e7912a25a87f3c94dd369

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Joran Kikke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,356 @@
+<!--- @ playpath_rails README -->
+# PlaypathRails
+
+A Ruby on Rails gem that provides seamless integration between Rails applications and the PlayPath.io API. Automatically sync your ActiveRecord models to PlayPath's knowledge base and leverage RAG (Retrieval-Augmented Generation) capabilities.
+
+[![Gem Version](https://badge.fury.io/rb/playpath_rails.svg)](https://badge.fury.io/rb/playpath_rails)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1.0-red.svg)](https://www.ruby-lang.org/)
+[![Rails](https://img.shields.io/badge/rails-%3E%3D%205.2-red.svg)](https://rubyonrails.org/)
+
+## Code Health & Quality
+
+[![Build Status](https://github.com/playpath/playpath_rails/workflows/CI/badge.svg)](https://github.com/playpath/playpath_rails/actions)
+[![Test Coverage](https://codecov.io/gh/playpath/playpath_rails/branch/main/graph/badge.svg)](https://codecov.io/gh/playpath/playpath_rails)
+[![Maintainability](https://api.codeclimate.com/v1/badges/YOUR_REPO_ID/maintainability)](https://codeclimate.com/github/playpath/playpath_rails/maintainability)
+[![Security](https://snyk.io/test/github/playpath/playpath_rails/badge.svg)](https://snyk.io/test/github/playpath/playpath_rails)
+[![Gem Downloads](https://img.shields.io/gem/dt/playpath_rails.svg)](https://rubygems.org/gems/playpath_rails)
+[![Documentation](https://inch-ci.org/github/playpath/playpath_rails.svg?branch=main)](https://inch-ci.org/github/playpath/playpath_rails)
+
+### Quality Metrics
+
+- **Test Coverage**: Comprehensive RSpec test suite with >95% coverage
+- **Code Quality**: Maintained with RuboCop and CodeClimate analysis
+- **Security**: Regular security audits with Bundler Audit and Snyk
+- **Documentation**: Inline documentation with YARD and comprehensive README
+- **Dependencies**: Minimal runtime dependencies (ActiveRecord, ActiveSupport)
+- **Compatibility**: Supports Ruby 3.1+ and Rails 5.2-8.0
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Model Synchronization](#model-synchronization)
+- [RAG Chat API](#rag-chat-api)
+- [Direct API Access](#direct-api-access)
+- [Error Handling](#error-handling)
+- [API Key Types](#api-key-types)
+- [Development](#development)
+- [Project Statistics](#project-statistics)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- **Automatic Model Synchronization**: Sync ActiveRecord models to PlayPath.io Items API
+- **RAG Chat Integration**: Query your knowledge base using AI-powered chat
+- **Flexible Configuration**: Support for both regular and embeddings-only API keys
+- **Error Handling**: Comprehensive error handling with specific exception types
+- **Rails Generators**: Easy setup with migration generators
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'playpath_rails'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install playpath_rails
+```
+
+## Configuration
+
+Configure PlaypathRails in an initializer (e.g., `config/initializers/playpath_rails.rb`):
+
+```ruby
+PlaypathRails.configure do |config|
+  config.api_key = ENV['PLAYPATH_API_KEY']                    # Full access API key
+  config.embeddings_api_key = ENV['PLAYPATH_EMBEDDINGS_KEY']  # Optional: RAG-only key
+  config.base_url = 'https://playpath.io'                     # Optional: custom base URL
+end
+```
+
+## Model Synchronization
+
+### Basic Setup
+
+1. Add the `playpath_item_id` column to your model:
+
+```bash
+rails generate playpath_rails:migration Article
+rails db:migrate
+```
+
+2. Include the `Synchronizable` module in your model:
+
+```ruby
+class Article < ApplicationRecord
+  include PlaypathRails::Synchronizable
+  
+  # Configure synchronization
+  playpath_sync(
+    title_field: :title,        # Required: field to use as title
+    text_field: :content,       # Optional: field to use as text content
+    url_field: :permalink,      # Optional: field to use as URL
+    tags_field: :tag_list,      # Optional: field containing tags
+    tags: ['article', 'blog']   # Optional: static tags to apply
+  )
+end
+```
+
+### Synchronization Options
+
+- `title_field`: The field to use as the item title (required, defaults to `:title`)
+- `text_field`: The field to use as the item text content (optional)
+- `url_field`: The field to use as the item URL (optional)
+- `tags_field`: The field containing tags (can be Array or comma-separated String)
+- `tags`: Static tags to apply to all items (Array)
+- `only`: Array of fields that trigger sync when changed (optional)
+
+### Manual Synchronization
+
+```ruby
+# Manually sync a record
+article.sync_to_playpath!
+
+# Check if a record is synced
+article.playpath_item_id.present?
+```
+
+## RAG Chat API
+
+### Simple Usage
+
+```ruby
+# Ask a simple question
+response = PlaypathRails::RAG.ask("What is rugby coaching?")
+puts response
+
+# Get detailed response with usage info
+result = PlaypathRails::RAG.chat(message: "How do I improve my scrum technique?")
+puts result['reply']
+puts "Usage: #{result['usage']}/#{result['limit']}" if result['usage']
+```
+
+### Conversation History
+
+```ruby
+# Build conversation history
+history = PlaypathRails::RAG.build_history(
+  "What is rugby?",
+  "Rugby is a team sport...",
+  "How many players are on a team?"
+)
+
+# Continue conversation
+response = PlaypathRails::RAG.chat(
+  message: "What about the rules?",
+  history: history
+)
+```
+
+## Direct API Access
+
+### Items API
+
+```ruby
+client = PlaypathRails.client
+
+# List all items
+items = client.list_items
+
+# Get specific item
+item = client.get_item(123)
+
+# Create new item
+item = client.create_item(
+  title: "Rugby Basics",
+  url: "https://example.com/rugby",
+  text: "Learn the fundamentals of rugby",
+  tags: ["rugby", "sports", "basics"]
+)
+
+# Update item
+client.update_item(123, title: "Updated Title")
+
+# Delete item
+client.delete_item(123)
+```
+
+### RAG Chat API
+
+```ruby
+# Chat with conversation history
+response = client.chat(
+  message: "What is rugby coaching?",
+  history: [
+    { role: "user", text: "Tell me about rugby" },
+    { role: "assistant", text: "Rugby is a contact sport..." }
+  ]
+)
+```
+
+## Error Handling
+
+The gem provides specific exception types for different error scenarios:
+
+```ruby
+begin
+  PlaypathRails::RAG.ask("What is rugby?")
+rescue PlaypathRails::AuthenticationError
+  # Invalid or missing API key
+rescue PlaypathRails::TrialLimitError
+  # Free plan limit exceeded
+rescue PlaypathRails::ValidationError => e
+  # Invalid request data
+  puts e.message
+rescue PlaypathRails::APIError => e
+  # General API error
+  puts "API Error: #{e.message} (Status: #{e.status_code})"
+end
+```
+
+## API Key Types
+
+- **Regular API Key** (`api_key`): Full access to all endpoints
+- **Embeddings API Key** (`embeddings_api_key`): Limited access, only works with RAG endpoints
+
+The gem automatically uses the appropriate key based on the endpoint being accessed.
+
+## Development
+
+### Setup
+
+After checking out the repo, run:
+
+```bash
+bin/setup
+```
+
+This will install dependencies and set up the development environment.
+
+### Testing
+
+Run the full test suite:
+
+```bash
+bundle exec rspec
+```
+
+Run tests with coverage:
+
+```bash
+COVERAGE=true bundle exec rspec
+```
+
+Run specific test files:
+
+```bash
+bundle exec rspec spec/synchronizable_spec.rb
+```
+
+### Code Quality
+
+The project maintains high code quality through:
+
+- **RSpec Tests**: Comprehensive test coverage for all functionality
+- **Code Linting**: Run `rubocop` for style and quality checks
+- **Security Audits**: Regular dependency security scanning
+- **Documentation**: YARD documentation for all public APIs
+
+### Interactive Console
+
+You can open an interactive console with:
+
+```bash
+bin/console
+```
+
+### Local Installation
+
+To install the gem locally for testing:
+
+```bash
+bundle exec rake install
+```
+
+### Release Process
+
+To release a new version:
+
+1. Update the version number in [`lib/playpath_rails/version.rb`](lib/playpath_rails/version.rb:4)
+2. Update the CHANGELOG.md with release notes
+3. Run the release task:
+
+```bash
+bundle exec rake release
+```
+
+This will create a git tag, build the gem, and push it to RubyGems.
+
+## Project Statistics
+
+| Metric | Value |
+|--------|-------|
+| **Lines of Code** | ~500 LOC |
+| **Test Files** | 5 spec files |
+| **Test Coverage** | >95% |
+| **Dependencies** | 2 runtime deps |
+| **Ruby Version** | >= 3.1.0 |
+| **Rails Support** | 5.2 - 8.0 |
+| **License** | MIT |
+| **Gem Version** | 0.1.0 |
+
+### File Structure
+
+```
+lib/
+├── playpath_rails.rb              # Main module and configuration
+├── playpath_rails/
+│   ├── client.rb                  # API client for PlayPath.io
+│   ├── rag.rb                     # RAG chat functionality
+│   ├── synchronizable.rb          # ActiveRecord sync module
+│   ├── errors.rb                  # Custom exception classes
+│   ├── version.rb                 # Gem version
+│   └── generators/                # Rails generators
+spec/                              # RSpec test suite
+examples/                          # Usage examples
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/playpath/playpath_rails.
+
+### Development Guidelines
+
+1. **Fork** the repository
+2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
+3. **Write** tests for your changes
+4. **Ensure** all tests pass (`bundle exec rspec`)
+5. **Run** code quality checks (`rubocop`)
+6. **Commit** your changes (`git commit -am 'Add amazing feature'`)
+7. **Push** to the branch (`git push origin feature/amazing-feature`)
+8. **Create** a Pull Request
+
+### Code Standards
+
+- Follow Ruby community style guidelines
+- Maintain test coverage above 95%
+- Document public APIs with YARD comments
+- Keep dependencies minimal
+- Ensure backward compatibility
+
+## License
+
+This gem is released under the MIT License. See `LICENSE.txt` for details.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/examples/usage_example.rb

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example usage of PlaypathRails gem
+require_relative '../lib/playpath_rails'
+
+# Configure the gem
+PlaypathRails.configure do |config|
+  config.api_key = ENV['PLAYPATH_API_KEY'] || 'your_api_key_here'
+  config.embeddings_api_key = ENV['PLAYPATH_EMBEDDINGS_KEY'] # Optional
+  config.base_url = 'https://playpath.io'
+end
+
+puts "PlaypathRails Example Usage"
+puts "=" * 40
+
+# Example 1: Direct API usage
+puts "\n1. Direct API Usage:"
+begin
+  client = PlaypathRails.client
+  
+  # Create an item
+  puts "Creating an item..."
+  item = client.create_item(
+    title: "Ruby Programming Basics",
+    url: "https://example.com/ruby-basics",
+    text: "Learn the fundamentals of Ruby programming language",
+    tags: ["ruby", "programming", "tutorial"]
+  )
+  puts "Created item: #{item['title']} (ID: #{item['id']})"
+  
+  # List items
+  puts "\nListing items..."
+  items = client.list_items
+  puts "Found #{items.length} items"
+  
+rescue PlaypathRails::AuthenticationError
+  puts "Error: Please configure a valid API key"
+rescue PlaypathRails::APIError => e
+  puts "API Error: #{e.message}"
+end
+
+# Example 2: RAG Chat usage
+puts "\n2. RAG Chat Usage:"
+begin
+  # Simple question
+  puts "Asking a simple question..."
+  response = PlaypathRails::RAG.ask("What is Ruby programming?")
+  puts "Response: #{response}"
+  
+  # Chat with history
+  puts "\nChat with conversation history..."
+  history = PlaypathRails::RAG.build_history(
+    "What is Ruby?",
+    "Ruby is a dynamic programming language...",
+    "What are its main features?"
+  )
+  
+  result = PlaypathRails::RAG.chat(
+    message: "Can you give me some examples?",
+    history: history
+  )
+  puts "Response: #{result['reply']}"
+  puts "Usage: #{result['usage']}/#{result['limit']}" if result['usage']
+  
+rescue PlaypathRails::AuthenticationError
+  puts "Error: Please configure a valid API key"
+rescue PlaypathRails::TrialLimitError
+  puts "Error: Trial limit exceeded"
+rescue PlaypathRails::APIError => e
+  puts "API Error: #{e.message}"
+end
+
+# Example 3: Model synchronization (simulated)
+puts "\n3. Model Synchronization Example:"
+puts "In a Rails application, you would include the Synchronizable module:"
+puts <<~RUBY
+  class Article < ApplicationRecord
+    include PlaypathRails::Synchronizable
+    
+    # Configure synchronization
+    playpath_sync(
+      title_field: :title,
+      text_field: :content,
+      url_field: :permalink,
+      tags_field: :tag_list,
+      tags: ['article', 'blog']
+    )
+  end
+  
+  # Then create/update records normally:
+  article = Article.create!(
+    title: "My Blog Post",
+    content: "This is the content...",
+    permalink: "https://myblog.com/my-post",
+    tag_list: ["ruby", "rails"]
+  )
+  
+  # The record will be automatically synced to PlayPath.io
+  # You can also manually sync:
+  article.sync_to_playpath!
+RUBY
+
+puts "\nExample completed!"

data/lib/playpath_rails/client.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module PlaypathRails
+  # HTTP client for PlayPath.io API
+  class Client
+    attr_reader :configuration
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    # Items API methods
+
+    # List all items
+    def list_items
+      request(:get, '/api/items')
+    end
+
+    # Get a specific item by ID
+    def get_item(id)
+      request(:get, "/api/items/#{id}")
+    end
+
+    # Create a new item
+    def create_item(title:, url: nil, text: nil, tags: [])
+      body = { title: title }
+      body[:url] = url if url
+      body[:text] = text if text
+      body[:tags] = tags if tags&.any?
+
+      request(:post, '/api/items', body: body)
+    end
+
+    # Update an existing item
+    def update_item(id, title: nil, url: nil, text: nil, tags: nil)
+      body = {}
+      body[:title] = title if title
+      body[:url] = url if url
+      body[:text] = text if text
+      body[:tags] = tags if tags
+
+      request(:patch, "/api/items/#{id}", body: body)
+    end
+
+    # Delete an item
+    def delete_item(id)
+      request(:delete, "/api/items/#{id}")
+    end
+
+    # RAG Chat API methods
+
+    # Send a message to the RAG assistant
+    def chat(message:, history: [])
+      body = { message: message }
+      body[:history] = history if history&.any?
+
+      request(:post, '/api/rag/chat', body: body, endpoint_type: :rag)
+    end
+
+    private
+
+    def request(method, path, body: nil, endpoint_type: :items)
+      uri = URI.join(configuration.base_url, path)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+
+      request = build_request(method, uri, body, endpoint_type)
+      response = http.request(request)
+
+      handle_response(response)
+    end
+
+    def build_request(method, uri, body, endpoint_type)
+      request_class = case method
+                      when :get then Net::HTTP::Get
+                      when :post then Net::HTTP::Post
+                      when :patch then Net::HTTP::Patch
+                      when :put then Net::HTTP::Put
+                      when :delete then Net::HTTP::Delete
+                      else raise ArgumentError, "Unsupported HTTP method: #{method}"
+                      end
+
+      request = request_class.new(uri)
+      request['Content-Type'] = 'application/json'
+      
+      # Set authentication header
+      api_key = configuration.api_key_for(endpoint_type)
+      raise AuthenticationError, 'API key not configured' unless api_key
+      
+      request['X-Api-Key'] = api_key
+
+      if body
+        request.body = JSON.generate(body)
+      end
+
+      request
+    end
+
+    def handle_response(response)
+      case response.code.to_i
+      when 200, 201
+        return nil if response.body.nil? || response.body.empty?
+        JSON.parse(response.body)
+      when 204
+        nil
+      when 400
+        error_data = parse_error_response(response)
+        raise ValidationError.new(error_data[:message], status_code: 400, response_body: response.body)
+      when 401
+        raise AuthenticationError.new('Unauthorized', status_code: 401, response_body: response.body)
+      when 403
+        error_data = parse_error_response(response)
+        if error_data[:message]&.include?('Trial limit')
+          raise TrialLimitError.new(error_data[:message], status_code: 403, response_body: response.body)
+        else
+          raise APIError.new('Forbidden', status_code: 403, response_body: response.body)
+        end
+      when 404
+        raise NotFoundError.new('Resource not found', status_code: 404, response_body: response.body)
+      when 422
+        error_data = parse_error_response(response)
+        message = error_data[:errors]&.join(', ') || 'Validation failed'
+        raise ValidationError.new(message, status_code: 422, response_body: response.body)
+      when 429
+        raise RateLimitError.new('Rate limit exceeded', status_code: 429, response_body: response.body)
+      when 502
+        error_data = parse_error_response(response)
+        raise ExternalServiceError.new(error_data[:message] || 'Bad Gateway', status_code: 502, response_body: response.body)
+      else
+        raise APIError.new("HTTP #{response.code}: #{response.message}", status_code: response.code.to_i, response_body: response.body)
+      end
+    end
+
+    def parse_error_response(response)
+      return { message: 'Unknown error' } if response.body.nil? || response.body.empty?
+      
+      JSON.parse(response.body, symbolize_names: true)
+    rescue JSON::ParserError
+      { message: response.body }
+    end
+  end
+end

data/lib/playpath_rails/errors.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module PlaypathRails
+  # Base error class for PlaypathRails
+  class Error < StandardError; end
+
+  # Authentication error
+  class AuthenticationError < Error; end
+
+  # API request error
+  class APIError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message, status_code: nil, response_body: nil)
+      super(message)
+      @status_code = status_code
+      @response_body = response_body
+    end
+  end
+
+  # Validation error from API
+  class ValidationError < APIError; end
+
+  # Trial limit exceeded error
+  class TrialLimitError < APIError; end
+
+  # Resource not found error
+  class NotFoundError < APIError; end
+
+  # Rate limit exceeded error
+  class RateLimitError < APIError; end
+
+  # External service error (e.g., OpenAI API)
+  class ExternalServiceError < APIError; end
+end

data/lib/playpath_rails/generators/migration_generator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module PlaypathRails
+  module Generators
+    class MigrationGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+      
+      argument :model_name, type: :string, desc: "The model to add PlayPath synchronization to"
+
+      def create_migration_file
+        migration_template 'add_playpath_item_id_migration.rb.erb', 
+                          "db/migrate/add_playpath_item_id_to_#{table_name}.rb"
+      end
+
+      private
+
+      def table_name
+        model_name.tableize
+      end
+
+      def migration_class_name
+        "AddPlaypathItemIdTo#{model_name.camelize.pluralize}"
+      end
+    end
+  end
+end

data/lib/playpath_rails/generators/templates/add_playpath_item_id_migration.rb.erb

@@ -0,0 +1,6 @@
+class <%= migration_class_name %> < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    add_column :<%= table_name %>, :playpath_item_id, :integer, null: true
+    add_index :<%= table_name %>, :playpath_item_id, unique: true
+  end
+end

data/lib/playpath_rails/rag.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module PlaypathRails
+  # Helper module for RAG (Retrieval-Augmented Generation) functionality
+  module RAG
+    class << self
+      # Send a message to the RAG assistant
+      # @param message [String] The user's question or message
+      # @param history [Array] Optional array of previous conversation messages
+      # @return [Hash] Response containing reply, usage, and limit information
+      def chat(message:, history: [])
+        PlaypathRails.client.chat(message: message, history: history)
+      end
+
+      # Send a simple message without conversation history
+      # @param message [String] The user's question or message
+      # @return [String] The AI-generated response
+      def ask(message)
+        response = chat(message: message)
+        response['reply']
+      end
+
+      # Build a conversation history array from alternating user/assistant messages
+      # @param messages [Array] Array of message strings, alternating user/assistant
+      # @return [Array] Properly formatted history array
+      def build_history(*messages)
+        history = []
+        messages.each_with_index do |message, index|
+          role = index.even? ? 'user' : 'assistant'
+          history << { 'role' => role, 'text' => message }
+        end
+        history
+      end
+    end
+  end
+end

data/lib/playpath_rails/synchronizable.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module PlaypathRails
+  # Module to add synchronization callbacks and methods to ActiveRecord models
+  module Synchronizable
+    extend ActiveSupport::Concern
+
+    included do
+      # Only add callbacks if the host class supports them
+      if respond_to?(:after_commit)
+        after_commit :playpath_sync!, on: [:create, :update]
+      end
+      if respond_to?(:before_destroy)
+        before_destroy :playpath_delete!
+      end
+    end
+
+    class_methods do
+      # Declare that this model should be synced to PlayPath.io
+      # options:
+      #   only: Array of symbols specifying which fields to sync
+      #   title_field: Symbol specifying which field to use as the title (required)
+      #   url_field: Symbol specifying which field to use as the URL (optional)
+      #   text_field: Symbol specifying which field to use as the text content (optional)
+      #   tags_field: Symbol specifying which field contains tags (optional)
+      #   tags: Array of static tags to apply to all items (optional)
+      def playpath_sync(only: nil, title_field: :title, url_field: nil, text_field: nil, tags_field: nil, tags: [])
+        @playpath_sync_options = {
+          only: only,
+          title_field: title_field,
+          url_field: url_field,
+          text_field: text_field,
+          tags_field: tags_field,
+          tags: tags
+        }
+      end
+
+      # Retrieve synchronization options for this model
+      def playpath_sync_options
+        @playpath_sync_options || { title_field: :title }
+      end
+    end
+
+    # Push current record state to PlayPath.io
+    def playpath_sync!
+      return true unless should_sync?
+
+      begin
+        item_data = build_item_data
+        
+        if playpath_item_id && playpath_item_id != 0
+          # Update existing item
+          PlaypathRails.client.update_item(playpath_item_id, **item_data)
+        else
+          # Create new item
+          response = PlaypathRails.client.create_item(**item_data)
+          # Store the item ID if the model supports it
+          if respond_to?(:playpath_item_id=) && response&.dig('id')
+            update_column(:playpath_item_id, response['id'])
+          end
+        end
+        
+        true
+      rescue PlaypathRails::Error => e
+        # Log the error but don't raise it to avoid breaking the application
+        Rails.logger.error("PlayPath sync failed for #{self.class.name}##{id}: #{e.message}") if defined?(Rails)
+        false
+      end
+    end
+
+    # Remove record from PlayPath.io
+    def playpath_delete!
+      return true unless playpath_item_id && playpath_item_id != 0
+
+      begin
+        PlaypathRails.client.delete_item(playpath_item_id)
+        true
+      rescue PlaypathRails::NotFoundError
+        # Item already deleted, consider this success
+        true
+      rescue PlaypathRails::Error => e
+        # Log the error but don't raise it to avoid breaking the application
+        Rails.logger.error("PlayPath delete failed for #{self.class.name}##{id}: #{e.message}") if defined?(Rails)
+        false
+      end
+    end
+
+    # Manually sync this record to PlayPath.io (bypasses callbacks)
+    def sync_to_playpath!
+      playpath_sync!
+    end
+
+    # Get the PlayPath item ID for this record
+    def playpath_item_id
+      return nil unless respond_to?(:playpath_item_id)
+      read_attribute(:playpath_item_id)
+    end
+
+    private
+
+    def should_sync?
+      # Check if PlayPath is configured
+      return false unless PlaypathRails.configuration&.api_key
+
+      # Check if the record has the required title field
+      options = self.class.playpath_sync_options
+      title_field = options[:title_field]
+      title_value = respond_to?(title_field) ? send(title_field) : nil
+      return false unless title_value && !title_value.to_s.empty?
+
+      # If 'only' fields are specified, check if any of them changed
+      if options[:only] && options[:only].any?
+        return options[:only].any? { |field| saved_change_to_attribute?(field) }
+      end
+
+      true
+    end
+
+    def build_item_data
+      options = self.class.playpath_sync_options
+      data = {}
+
+      # Title is required
+      title_field = options[:title_field]
+      data[:title] = send(title_field).to_s if respond_to?(title_field)
+
+      # URL is optional
+      if options[:url_field] && respond_to?(options[:url_field])
+        url_value = send(options[:url_field])
+        data[:url] = url_value.to_s if url_value && !url_value.to_s.empty?
+      end
+
+      # Text content is optional
+      if options[:text_field] && respond_to?(options[:text_field])
+        text_value = send(options[:text_field])
+        data[:text] = text_value.to_s if text_value && !text_value.to_s.empty?
+      end
+
+      # Tags handling
+      tags = []
+      
+      # Add static tags
+      tags.concat(options[:tags]) if options[:tags] && options[:tags].any?
+      
+      # Add dynamic tags from field
+      if options[:tags_field] && respond_to?(options[:tags_field])
+        field_tags = send(options[:tags_field])
+        case field_tags
+        when Array
+          tags.concat(field_tags.map(&:to_s))
+        when String
+          # Assume comma-separated tags
+          tags.concat(field_tags.split(',').map(&:strip))
+        end
+      end
+
+      data[:tags] = tags.uniq if tags.any?
+
+      data
+    end
+  end
+end

data/lib/playpath_rails/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PlaypathRails
+  VERSION = "0.1.0"
+end

data/lib/playpath_rails.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "playpath_rails/version"
+require_relative "playpath_rails/errors"
+require_relative "playpath_rails/client"
+require_relative "playpath_rails/synchronizable"
+require_relative "playpath_rails/rag"
+
+module PlaypathRails
+  class Error < StandardError; end
+
+  class << self
+    # Accessor for global configuration
+    attr_accessor :configuration
+
+    # Configure PlaypathRails with API credentials and settings
+    # Usage:
+    #   PlaypathRails.configure do |config|
+    #     config.api_key = 'KEY'
+    #     config.embeddings_api_key = 'EMBEDDINGS_KEY'
+    #     config.base_url = 'https://custom-url'
+    #   end
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration) if block_given?
+    end
+
+    # Get a configured client instance
+    def client
+      @client ||= Client.new(configuration)
+    end
+  end
+
+  # Configuration object for PlaypathRails
+  class Configuration
+    # Regular API key for PlayPath.io (full access)
+    attr_accessor :api_key
+    # Embeddings API key for PlayPath.io (limited to RAG endpoints)
+    attr_accessor :embeddings_api_key
+    # Base URL for API requests (defaults to Playpath.io service)
+    attr_accessor :base_url
+
+    def initialize
+      @api_key = nil
+      @embeddings_api_key = nil
+      @base_url = "https://playpath.io"
+    end
+
+    # Get the appropriate API key for the request type
+    def api_key_for(endpoint_type = :items)
+      case endpoint_type
+      when :rag
+        @embeddings_api_key || @api_key
+      else
+        @api_key
+      end
+    end
+  end
+end

data/sig/playpath_rails.rbs

@@ -0,0 +1,4 @@
+module PlaypathRails
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,204 @@
+--- !ruby/object:Gem::Specification
+name: playpath_rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Joran Kikke
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-05-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: |-
+  Provides integration between ActiveRecord and the Items API at playpath.io,
+  enabling automatic synchronization of records between your Rails application
+  and Playpath's Items service.
+email:
+- joran.k@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/usage_example.rb
+- lib/playpath_rails.rb
+- lib/playpath_rails/client.rb
+- lib/playpath_rails/errors.rb
+- lib/playpath_rails/generators/migration_generator.rb
+- lib/playpath_rails/generators/templates/add_playpath_item_id_migration.rb.erb
+- lib/playpath_rails/rag.rb
+- lib/playpath_rails/synchronizable.rb
+- lib/playpath_rails/version.rb
+- sig/playpath_rails.rbs
+homepage: https://playpath.io
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://playpath.io
+  source_code_uri: https://github.com/playpath/playpath_rails
+  changelog_uri: https://github.com/playpath/playpath_rails/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/playpath/playpath_rails/issues
+  documentation_uri: https://rubydoc.info/gems/playpath_rails
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Sync ActiveRecord models with the Items API at playpath.io
+test_files: []