crystil 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b4da070c2db6a9316560e3b603975352ab4fdd1e6335b9c2deae82e164f03dd3
+  data.tar.gz: 74444bd1e835403f51152bb6e6dbabf8317f33668498137c65562e6d72881371
+SHA512:
+  metadata.gz: 3f6fdee56c16efdc5e5788ed3cce7714e666bff78e6d49514591e690f97dca8adab72c785d4d1ac2e8d34a308ca967096b907572d5623830f5da641723cc0d8f
+  data.tar.gz: 7b837bbb97bd54f4264b11bfe11b35b25da51225f929ce2b5d0d2e57e81c944ae273c38e64f75349c71478334bf1a221642f15882b4e3c9b3eb08414cbfec4b4

data/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2025-10-13
+
+### Added
+- Initial release of Crystil Ruby SDK
+- Support for OpenAI client tracking
+- Support for Anthropic client tracking
+- Support for Google GenAI client tracking
+- Attribution tracking (parent/subsidiary hierarchy)
+- Transaction management
+- Asynchronous analytics collection
+- Workflow API client
+- Invocation API client
+- Streaming response support
+- Thread-safe configuration
+- Comprehensive error handling
+
+## [0.0.2] - 2025-10-25
+
+### Fixed
+- Corrected Crystil request payload structure as needed
+
+## [0.0.3] - 2025-10-27
+
+### Fixed
+- Correct Crystil request payload structure for Google GenAI
+
+## [0.0.4] - 2025-10-28
+
+### Fixed
+- Correct Crystil request payload structure for OpenAI streaming
+
+## [0.1.0] - 2026-02-03
+
+### Added
+- Support for Sentinel intercept.
+- Support for Gemini AI client tracking.
+
+## [0.1.1] - 2026-02-11
+
+### Fixed
+- Stopped sending collector calls for intercepted requests
+
+## [0.2.0] - 2026-04-08
+
+### Added
+- Support for the RubyLLM library
+
+## [0.3.0] - 2026-04-15
+
+### Added
+- Support OpenAI Responses API (responses.create)
+
+## [0.4.0] - 2026-05-19
+
+### Added
+- Support for the Groq Ruby client (`groq` gem, drnic/groq-ruby), including streaming.
+- RBS type signatures shipped with the gem.
+
+## [0.5.0] - 2026-08-12
+
+### Changed
+- **BREAKING**: Renamed Payloop to Crystil. Migrating from `payloop` 0.4.0 requires:
+  - Install the `crystil` gem in place of `payloop`; `require "payloop"` becomes `require "crystil"`.
+  - Replace the `Payloop::*` namespace with `Crystil::*` (e.g. `Payloop::Client` → `Crystil::Client`).
+  - Rename the `PAYLOOP_API_KEY`, `PAYLOOP_API_URL_BASE`, and `PAYLOOP_COLLECTOR_URL_BASE`
+    environment variables to `CRYSTIL_API_KEY`, `CRYSTIL_API_URL_BASE`, and
+    `CRYSTIL_COLLECTOR_URL_BASE`.
+  - Default endpoints now resolve to `api.crystil.com` and `collector.crystil.com`.
+
+  No API surface, method signature, or request payload changed — this release is a rename only.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CrystilAI
+
+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,112 @@
+# Welcome to Crystil!
+
+### Cost Visibility for AI Agents
+
+Crystil is a lightweight infrastructure layer that gives AI teams real-time visibility into the true costs of deploying agents - across tasks, workflows, and customers. Most teams today can’t see what it actually costs to deploy their agents, making it nearly impossible to manage gross margins or price with confidence.
+
+With just a single line of code, Crystil delivers:
+- Cost tracking across OpenAI, Anthropic, Gemini, and more in one place
+- Breakdowns by task, agent, and customer in real time
+- Confidence to deploy the right pricing model (cost-plus, token-based, outcome-based, etc.) while preserving gross margins
+
+Watch a short demo video: [Crystil Walkthrough Video](https://www.youtube.com/watch?v=Z-GkSl_7imY)
+
+By surfacing exactly what’s driving cost and value, Crystil becomes the source of truth for agent economics - helping founders and operators scale their agents with confidence.
+
+Sign up here: [crystil.com](https://crystil.com/)
+
+# Installation
+
+    gem install crystil
+
+# Documentation
+
+Our SDK reference provides documentation for:
+- Understanding how Crystil works
+- Demonstrating how to integrate Crystil into your product
+- Code samples to illustrate our SDK and API
+
+Check it out here: [developers.crystil.com](https://developers.crystil.com)
+
+# Releasing a New Version
+
+Publishing is automated. Pushing a GitHub Release triggers
+[`publish-to-rubygems.yaml`](.github/workflows/publish-to-rubygems.yaml), which
+builds the gem and pushes it to RubyGems via Trusted Publishing (OIDC). There is
+no API key stored in GitHub, and **you should never run `gem push` or
+`rake release` by hand** — the release's safety checks only exist in CI, and a
+version number can never be reused on RubyGems once taken.
+
+To release version `X.Y.Z`:
+
+1. **Update the version number** in [lib/crystil/version.rb](lib/crystil/version.rb):
+   ```ruby
+   VERSION = "X.Y.Z"
+   ```
+   This constant is the single source of truth — the gemspec and the
+   `meta.sdk.version` field on every payload both read from it.
+
+2. **Update the CHANGELOG** in [CHANGELOG.md](CHANGELOG.md):
+   - Add a new section for the version with today's date
+   - Document all changes under appropriate categories (Added, Changed, Fixed, etc.)
+   - Follow the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format
+
+3. **Open a PR and merge it to `main`** once CI is green (lint, type-check, and
+   the Ruby 3.2 / 3.3 / 3.4 test matrix).
+
+4. **Publish a GitHub Release** tagged `vX.Y.Z` — the leading `v` is required,
+   and the rest must match `Crystil::VERSION` exactly or the workflow fails.
+   There is no separate `git tag` step: the release creates the tag against
+   `--target`, and pushing a tag on its own triggers nothing.
+   ```bash
+   gh release create vX.Y.Z --target main --title "vX.Y.Z" \
+     --notes "$(sed -n '/^## \[X.Y.Z\]/,/^## \[/p' CHANGELOG.md | sed '$d')"
+   ```
+   Pass the notes explicitly as above (or `--generate-notes` for an
+   auto-generated commit summary). Don't use `--notes-from-tag` here — when gh
+   creates the tag it is lightweight, so that flag falls back to the commit
+   message and your notes end up reading "Merge pull request #NN".
+
+   Or use the GitHub UI: *Releases → Draft a new release*, create the tag
+   `vX.Y.Z` against `main`, then **Publish release**. Saving a draft does not
+   trigger anything; only publishing does.
+
+5. **Watch the run**:
+   ```bash
+   gh run watch
+   ```
+   Before pushing anything, the workflow verifies the tag matches the version,
+   runs the unit and mocked integration specs, and asserts the packaged gem
+   contains what it should. It then waits for the new version to be installable
+   rather than merely uploaded, so a green run means the release is live.
+
+6. **Verify the release**:
+   - Check [rubygems.org/gems/crystil](https://rubygems.org/gems/crystil)
+   - Test installation: `gem install crystil -v X.Y.Z`
+
+## One-time publishing setup
+
+The workflow authenticates via RubyGems Trusted Publishing, which must be
+configured once before the first release.
+
+Because `crystil` is not yet on RubyGems, create a **pending** publisher at
+[rubygems.org/profile/oidc/pending_trusted_publishers](https://rubygems.org/profile/oidc/pending_trusted_publishers)
+(for a gem that already exists, use *Trusted publishers* in the gem's sidebar
+instead):
+
+| Field | Value |
+|---|---|
+| RubyGem name | `crystil` |
+| Repository owner | `CrystilAI` |
+| Repository name | `ruby-sdk` |
+| Workflow filename | `publish-to-rubygems.yaml` |
+| Environment | `rubygems` |
+
+Then create a matching GitHub environment named `rubygems` under *Settings →
+Environments* — optionally with required reviewers, which turns every release
+into an approval gate.
+
+All five values are part of the trusted identity. Renaming the workflow file or
+the environment breaks publishing until RubyGems is updated to match. After the
+first successful push, the pending publisher converts to a normal one and the
+configuring user becomes a gem owner.

data/lib/crystil/api/base.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Crystil
+  module API
+    # Base HTTP client for Crystil API
+    class Base
+      def initialize(api_url, api_key, timeout)
+        @original_api_url = api_url
+        @api_url = "#{api_url}/v1/-"
+        @api_key = api_key
+        @timeout = timeout
+      end
+
+      protected
+
+      def get(path)
+        request(:get, path)
+      end
+
+      def post(path, body = nil)
+        request(:post, path, body)
+      end
+
+      def put(path, body = nil)
+        request(:put, path, body)
+      end
+
+      def delete(path)
+        request(:delete, path)
+      end
+
+      private
+
+      def request(method, path, body = nil)
+        # Construct full URL - path should start with /
+        full_url = "#{@api_url}#{path}"
+        uri = URI.parse(full_url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+
+        # Configure SSL to use system certificates
+        if http.use_ssl?
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          http.cert_store = OpenSSL::X509::Store.new
+          http.cert_store.set_default_paths
+        end
+
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+
+        request = build_request(method, uri, body)
+        response = http.request(request)
+
+        handle_response(response)
+      end
+
+      def build_request(method, uri, body)
+        request_class = case method
+                        when :get then Net::HTTP::Get
+                        when :post then Net::HTTP::Post
+                        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.path.empty? ? "/" : uri.path)
+        request["Authorization"] = "Bearer #{@api_key}"
+        request["Content-Type"] = "application/json"
+        request["User-Agent"] = "crystil-ruby/#{Crystil::VERSION}"
+
+        request.body = JSON.generate(body) if body && %i[post put].include?(method)
+
+        request
+      end
+
+      def handle_response(response)
+        case response
+        when Net::HTTPSuccess
+          parse_json_response(response.body)
+        when Net::HTTPNoContent
+          {}
+        else
+          raise APIError.new(
+            "API request failed: #{response.code} #{response.message}",
+            status_code: response.code.to_i,
+            response_body: response.body
+          )
+        end
+      end
+
+      def parse_json_response(body)
+        return {} if body.nil? || body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError => e
+        raise APIError, "Failed to parse JSON response: #{e.message}"
+      end
+    end
+  end
+end

data/lib/crystil/api/invocation.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Crystil
+  module API
+    # API client for workflow invocation operations
+    class Invocation < Base
+      def initialize(api_url, api_key, timeout)
+        super
+        @attribution = nil
+      end
+
+      # Set attribution filter for summary queries
+      # Returns self for method chaining
+      def attribution(parent_id:, parent_name: nil, subsidiary_id: nil, subsidiary_name: nil)
+        @attribution = {
+          parent: { id: parent_id }
+        }
+        @attribution[:parent][:name] = parent_name if parent_name
+
+        if subsidiary_id
+          @attribution[:subsidiary] = { id: subsidiary_id }
+          @attribution[:subsidiary][:name] = subsidiary_name if subsidiary_name
+        end
+
+        self
+      end
+
+      # Get invocation summary for a workflow
+      def summary(workflow_uuid, date_start:, date_end: nil)
+        body = {
+          date: {
+            start: format_date(date_start)
+          }
+        }
+
+        body[:date][:end] = format_date(date_end) if date_end
+
+        body[:attribution] = @attribution if @attribution
+
+        post("/workflow/#{workflow_uuid}/invocation/summary", body)
+      end
+
+      private
+
+      def format_date(date)
+        return date if date.is_a?(String)
+
+        # Convert to midnight (beginning of day) in ISO8601 format
+        if date.respond_to?(:to_date)
+          date.to_date.to_time.iso8601
+        else
+          date.iso8601
+        end
+      end
+    end
+  end
+end

data/lib/crystil/api/sentinel.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Crystil
+  module API
+    class Sentinel < Base
+      def relevance_intercept(payload)
+        post("/sentinel/relevance/intercept", payload)
+      end
+    end
+  end
+end

data/lib/crystil/api/workflow.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Crystil
+  module API
+    # API client for managing a specific workflow
+    class Workflow < Base
+      def initialize(uuid, api_url, api_key, timeout)
+        super(api_url, api_key, timeout)
+        @uuid = uuid
+      end
+
+      # Get workflow details
+      def details
+        get("/workflow/#{@uuid}")
+      end
+
+      # Update workflow label
+      def update(label:)
+        body = { label: label }
+        put("/workflow/#{@uuid}", body)
+      end
+
+      # Delete workflow
+      def destroy
+        delete("/workflow/#{@uuid}")
+      end
+
+      # Get invocation client for this workflow
+      def invocation
+        Invocation.new(@uuid, @original_api_url, @api_key, @timeout)
+      end
+    end
+  end
+end

data/lib/crystil/api/workflows.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Crystil
+  module API
+    # API client for managing workflows
+    class Workflows < Base
+      # List all workflows
+      def list
+        get("/workflows")
+      end
+
+      # Create a new workflow
+      def create(name:, description: nil)
+        post("/workflows", { name: name, description: description }.compact)
+      end
+
+      # Get workflow details
+      def details(uuid)
+        get("/workflow/#{uuid}")
+      end
+
+      # Update workflow label
+      def update(uuid, label:)
+        body = { label: label }
+        put("/workflow/#{uuid}", body)
+      end
+
+      # Delete workflow
+      def destroy(uuid)
+        delete("/workflow/#{uuid}")
+      end
+
+      # Get invocation manager for workflow operations
+      def invocation
+        @invocation ||= Invocation.new(@original_api_url, @api_key, @timeout)
+      end
+    end
+  end
+end

data/lib/crystil/attribution.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Crystil
+  # Attribution tracks cost hierarchy for API calls
+  class Attribution
+    attr_reader :parent_id, :parent_name, :subsidiary_id, :subsidiary_name
+
+    def initialize(parent_id:, parent_name: nil, subsidiary_id: nil, subsidiary_name: nil)
+      @parent_id = validate_parent_id!(parent_id)
+      @parent_name = validate_string_length!(parent_name, "parent_name") if parent_name
+      @subsidiary_id = validate_string_length!(subsidiary_id, "subsidiary_id") if subsidiary_id
+      @subsidiary_name = validate_string_length!(subsidiary_name, "subsidiary_name") if subsidiary_name
+
+      validate_subsidiary_requirements!
+    end
+
+    def to_h
+      result = {
+        parent: {
+          id: parent_id
+        }
+      }
+
+      result[:parent][:name] = parent_name if parent_name
+
+      if subsidiary_id
+        result[:subsidiary] = { id: subsidiary_id }
+        result[:subsidiary][:name] = subsidiary_name if subsidiary_name
+      end
+
+      result
+    end
+
+    private
+
+    def validate_parent_id!(value)
+      raise ValidationError, "parent_id is required" if value.nil? || value.to_s.empty?
+
+      value_str = value.to_s
+      if value_str.length > 100
+        raise ValidationError,
+              "parent_id cannot exceed 100 characters (got #{value_str.length})"
+      end
+
+      value_str
+    end
+
+    def validate_string_length!(value, field_name)
+      return nil if value.nil?
+
+      value_str = value.to_s
+      if value_str.length > 100
+        raise ValidationError,
+              "#{field_name} cannot exceed 100 characters (got #{value_str.length})"
+      end
+
+      value_str
+    end
+
+    def validate_subsidiary_requirements!
+      return unless subsidiary_name && !subsidiary_id
+
+      raise ValidationError, "subsidiary_id is required when subsidiary_name is provided"
+    end
+  end
+end

data/lib/crystil/client.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Crystil
+  # Main Crystil client for tracking AI costs
+  class Client
+    attr_reader :config, :collector, :sentinel
+
+    def initialize(api_key: nil, collector_url: nil, api_url: nil, timeout: nil)
+      api_key ||= ENV.fetch("CRYSTIL_API_KEY", nil)
+      raise MissingAPIKeyError if api_key.nil? || api_key.empty?
+
+      @config = Config.new(
+        api_key: api_key,
+        collector_url: collector_url,
+        api_url: api_url,
+        timeout: timeout
+      )
+      @collector = Collector.new(@config)
+      @sentinel = Sentinel.new(@config)
+    end
+
+    # OpenAI provider wrapper
+    def openai
+      @openai ||= Wrappers::OpenAI.new(@config, @collector, @sentinel)
+    end
+
+    # Anthropic provider wrapper
+    def anthropic
+      @anthropic ||= Wrappers::Anthropic.new(@config, @collector, @sentinel)
+    end
+
+    # Google GenAI provider wrapper (Tied to google-genai Gem)
+    # This is a port of the official Python library, but it does not
+    # support system prompts which is used for sentinel.  This still
+    # works for non-sentinel use cases.
+    def google
+      @google ||= Wrappers::Google.new(@config, @collector, @sentinel)
+    end
+
+    # Google GenAI provider wrapper (Tied to gemini-ai Gem version 4.3.0)
+    # Google doesn't have an official Ruby library, so this is seems to be
+    # the most popular unofficial one.
+    def geminiai
+      @geminiai ||= Wrappers::GeminiAI.new(@config, @collector, @sentinel)
+    end
+
+    # RubyLLM provider wrapper (ruby_llm gem)
+    # Supports any provider available via RubyLLM (Anthropic, OpenAI, Google, etc.)
+    def ruby_llm
+      @ruby_llm ||= Wrappers::RubyLLM.new(@config, @collector, @sentinel)
+    end
+
+    # Groq provider wrapper (groq gem, drnic/groq-ruby)
+    # Groq hosts third-party models (Meta Llama, OpenAI gpt-oss, Qwen, etc.).
+    # Telemetry sets provider="groq" and title from the model-ID prefix.
+    def groq
+      @groq ||= Wrappers::Groq.new(@config, @collector, @sentinel)
+    end
+
+    # Set attribution for cost tracking
+    def attribution(parent_id:, parent_name: nil, subsidiary_id: nil, subsidiary_name: nil)
+      attr = Attribution.new(
+        parent_id: parent_id,
+        parent_name: parent_name,
+        subsidiary_id: subsidiary_id,
+        subsidiary_name: subsidiary_name
+      )
+
+      @config.attribution = attr
+      self
+    end
+
+    # Start a new transaction
+    def new_transaction
+      @config.new_transaction
+      self
+    end
+
+    # Get workflows API client
+    def workflows
+      @workflows ||= API::Workflows.new(
+        @config.api_url,
+        @config.api_key,
+        @config.timeout
+      )
+    end
+
+    # Gracefully shutdown the client
+    def shutdown
+      @collector.shutdown
+    end
+  end
+end