sveda-ruby-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c41afde9523f250320a9ab947ca732354edf6643cfe53841433113fe19fcb5d0
+  data.tar.gz: 1e204829c48bfb1c2c03e2b3e69ccf540518b71f64c3589624e8c1a9c674e15b
+SHA512:
+  metadata.gz: 22f8a78f1e68f2f57565fee6e5fbcaa334150d23125447e8d9f5c7361306d59afefe5ee903fe3606d38454075b3b86491f8f8e56d3c714c0e2eeb1c00e3ccf25
+  data.tar.gz: aec392c0354deb512a72edfd86c2bf22c4bb75bd60f74e74ba04c6ba011593fb1c4ce255182091f6c1604cf856306559e1caddd123a03a587e3b2ccd189aeaca

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sveda AI Contributors
+
+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,42 @@
+# sveda-ruby-sdk
+
+Ruby SDK for the [Sveda AI](https://github.com/neresson/sveda) sidecar HTTP API.
+
+RubyGems: `sveda-ruby-sdk`
+
+## Install
+
+```ruby
+gem "sveda-ruby-sdk"
+```
+
+```bash
+gem install sveda-ruby-sdk
+```
+
+## Usage
+
+```ruby
+require "sveda"
+
+client = Sveda::Client.new(base_url: "https://sveda.example.com", host_api_key: host_key)
+token = client.embed.create_token(visitor_id: "user-1")
+
+client = Sveda::Client.new(base_url: "https://sveda.example.com", embed_token: token.token)
+client.chat.create_streamed(
+  messages: [{ role: "user", content: "Hello" }],
+  chatId: "chat-1"
+) do |event|
+  puts event.type
+end
+
+session = Sveda::Client.start_host_session(
+  base_url: "https://sveda.example.com",
+  host_api_key: host_key,
+  visitor_id: "user-1"
+)
+```
+
+## License
+
+MIT

data/lib/sveda/chat.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Sveda
+  class Chat
+    def initialize(transport)
+      @transport = transport
+    end
+
+    def create(params = {}, **kwargs)
+      payload = params.merge(kwargs)
+      Message.from_payload(@transport.request_json("POST", "/sveda/message", payload))
+    end
+
+    def create_streamed(params = {}, **kwargs, &block)
+      payload = params.merge(kwargs)
+      body = @transport.request_stream("POST", "/sveda/stream", payload)
+      parser = StreamParser.new
+      return parser.each(body, &block) if block
+
+      parser.each(body)
+    end
+  end
+end

data/lib/sveda/client.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Sveda
+  class Client
+    def initialize(base_url:, host_api_key: nil, embed_token: nil, transport: nil, timeout: 30, open_timeout: 5, headers: {})
+      @base_url = base_url.to_s.sub(%r{/\z}, "")
+      auth_headers = headers.dup
+      auth_headers["Authorization"] = "Bearer #{host_api_key}" if host_api_key.to_s != ""
+      auth_headers["X-Sveda-Embed-Token"] = embed_token.to_s if embed_token.to_s != ""
+      inner = transport || Http.new(base_url: @base_url, timeout: timeout, open_timeout: open_timeout)
+      @transport = HeaderTransport.new(inner, auth_headers)
+    end
+
+    def embed
+      Embed.new(@transport)
+    end
+
+    def chat
+      Chat.new(@transport)
+    end
+
+    def histories
+      Histories.new(@transport)
+    end
+
+    def self.start_host_session(base_url:, host_api_key:, visitor_id:, host_mcp_url: nil, host_mcp_token: nil, **client_kwargs)
+      origin = base_url.to_s.strip.sub(%r{/\z}, "")
+      key = host_api_key.to_s.strip
+      if origin.empty? || key.empty?
+        raise ConfigurationError, "Задайте SVEDA_CLIENT_BASE_URL и SVEDA_CLIENT_HOST_API_KEY"
+      end
+
+      client = new(base_url: origin, host_api_key: key, **client_kwargs)
+      token = client.embed.create_token(
+        visitor_id: visitor_id,
+        host_mcp_url: host_mcp_url,
+        host_mcp_token: host_mcp_token
+      )
+      if token.token.empty?
+        raise Error, "Sidecar returned an empty embed token."
+      end
+
+      {
+        origin: origin,
+        token: token.token,
+        expires_in: token.expires_in,
+        appearance: token.appearance
+      }
+    end
+  end
+end

data/lib/sveda/embed.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Sveda
+  class Embed
+    def initialize(transport)
+      @transport = transport
+    end
+
+    def create_token(visitor_id: nil, host_mcp_url: nil, host_mcp_token: nil)
+      payload = {}
+      payload["visitor_id"] = visitor_id if visitor_id.to_s != ""
+      if host_mcp_url.to_s != "" && host_mcp_token.to_s != ""
+        payload["host_mcp_url"] = host_mcp_url
+        payload["host_mcp_token"] = host_mcp_token
+      end
+
+      EmbedToken.from_payload(@transport.request_json("POST", "/sveda/embed/token", payload))
+    end
+
+    def config
+      @transport.request_json("GET", "/sveda/embed/config")
+    end
+  end
+end

data/lib/sveda/embed_token.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Sveda
+  class EmbedToken
+    attr_reader :token, :visitor_id, :expires_in, :appearance
+
+    def initialize(token:, visitor_id:, expires_in:, appearance: nil)
+      @token = token
+      @visitor_id = visitor_id
+      @expires_in = expires_in
+      @appearance = appearance
+    end
+
+    def self.from_payload(payload)
+      appearance = payload["appearance"]
+      appearance = nil unless appearance.is_a?(Hash)
+
+      new(
+        token: payload["token"].to_s,
+        visitor_id: payload["visitor_id"].to_s,
+        expires_in: [payload.fetch("expires_in", 3600).to_i, 60].max,
+        appearance: appearance
+      )
+    end
+  end
+end

data/lib/sveda/errors.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Sveda
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class AuthenticationError < Error; end
+
+  class UnserializableResponseError < Error; end
+
+  class TransportError < Error
+    attr_reader :status_code
+
+    def initialize(message, status_code: nil)
+      @status_code = status_code
+      super(message)
+    end
+  end
+
+  class APIError < Error
+    attr_reader :status_code, :response
+
+    def initialize(message, status_code: 0, response: nil)
+      @status_code = status_code
+      @response = response
+      super(message)
+    end
+  end
+end

data/lib/sveda/histories.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Sveda
+  class Histories
+    def initialize(transport)
+      @transport = transport
+    end
+
+    def list
+      @transport.request_json("GET", "/sveda/chat-histories")
+    end
+
+    def get(chat_id)
+      @transport.request_json("GET", history_path(chat_id))
+    end
+
+    def rename(chat_id, title)
+      @transport.request_json("PATCH", history_path(chat_id), { "title" => title })
+    end
+
+    def delete(chat_id)
+      @transport.request_json("DELETE", history_path(chat_id))
+    end
+
+    private
+
+    def history_path(chat_id)
+      "/sveda/chat-histories/#{URI.encode_uri_component(chat_id.to_s)}"
+    end
+  end
+end

data/lib/sveda/http.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Sveda
+  class Http
+    def initialize(base_url:, timeout: 30, open_timeout: 5)
+      @base_url = base_url.to_s.sub(%r{/\z}, "")
+      @timeout = timeout
+      @open_timeout = open_timeout
+    end
+
+    def request_json(method, path, payload = {}, headers = {})
+      response = send_request(
+        method,
+        path,
+        payload,
+        headers.merge(
+          "Accept" => "application/json",
+          "Content-Type" => "application/json"
+        )
+      )
+      self.class.decode_json_body(response.code.to_i, response.body.to_s)
+    end
+
+    def request_stream(method, path, payload = {}, headers = {})
+      chunks = +""
+      send_request(
+        method,
+        path,
+        payload,
+        headers.merge(
+          "Accept" => "application/vnd.sveda.stream+json",
+          "Content-Type" => "application/json"
+        ),
+        stream: true
+      ) do |response|
+        self.class.decode_json_body(response.code.to_i, "") unless (200...300).cover?(response.code.to_i)
+        response.read_body do |chunk|
+          chunks << chunk
+        end
+      end
+      chunks
+    end
+
+    def self.decode_json_body(status, body)
+      if [401, 403].include?(status)
+        raise AuthenticationError, "Sveda API authentication failed with status #{status}"
+      end
+
+      unless (200...300).cover?(status)
+        decoded = parse_object(body)
+        message = decoded.is_a?(Hash) && decoded["message"].is_a?(String) ? decoded["message"] : "Sveda API request failed with status #{status}"
+        raise APIError.new(message, status_code: status, response: decoded)
+      end
+
+      return {} if body.nil? || body.empty?
+
+      decoded = parse_object(body)
+      unless decoded.is_a?(Hash)
+        raise UnserializableResponseError, "Unable to decode Sveda API response as JSON."
+      end
+
+      decoded
+    end
+
+    def self.stringify_keys(object)
+      case object
+      when Hash
+        object.each_with_object({}) do |(key, value), memo|
+          memo[key.to_s] = stringify_keys(value)
+        end
+      when Array
+        object.map { |value| stringify_keys(value) }
+      else
+        object
+      end
+    end
+
+    def self.parse_object(body)
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      nil
+    end
+
+    private
+
+    REQUESTS = {
+      "GET" => Net::HTTP::Get,
+      "POST" => Net::HTTP::Post,
+      "PATCH" => Net::HTTP::Patch,
+      "PUT" => Net::HTTP::Put,
+      "DELETE" => Net::HTTP::Delete
+    }.freeze
+
+    def send_request(method, path, payload, headers, stream: false, &block)
+      uri = resolve_uri(path)
+      request_class = REQUESTS.fetch(method.to_s.upcase)
+      request = request_class.new(uri)
+      headers.each { |name, value| request[name] = value }
+      body = self.class.stringify_keys(payload || {})
+      request.body = JSON.generate(body) if request.request_body_permitted?
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = @timeout
+      http.open_timeout = @open_timeout
+
+      if stream
+        http.request(request, &block)
+      else
+        http.request(request)
+      end
+    rescue AuthenticationError, APIError, UnserializableResponseError
+      raise
+    rescue StandardError => error
+      raise TransportError, error.message
+    end
+
+    def resolve_uri(path)
+      return URI.parse(path) if path.start_with?("http://", "https://")
+
+      URI.parse("#{@base_url}/#{path.sub(%r{\A/}, "")}")
+    end
+  end
+
+  class HeaderTransport
+    def initialize(inner, headers)
+      @inner = inner
+      @headers = headers
+    end
+
+    def request_json(method, path, payload = {}, headers = {})
+      @inner.request_json(method, path, payload, @headers.merge(headers))
+    end
+
+    def request_stream(method, path, payload = {}, headers = {})
+      @inner.request_stream(method, path, payload, @headers.merge(headers))
+    end
+  end
+end

data/lib/sveda/message.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Sveda
+  class Message
+    attr_reader :payload
+
+    def initialize(payload)
+      @payload = payload
+    end
+
+    def explanation
+      payload["explanation"].to_s
+    end
+
+    def tokens_used
+      payload["tokens_used"].to_i
+    end
+
+    def chat_id
+      payload["chat_id"].to_s
+    end
+
+    def self.from_payload(payload)
+      new(payload)
+    end
+  end
+end

data/lib/sveda/stream_event.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Sveda
+  class StreamEvent
+    attr_reader :type, :payload
+
+    def initialize(type, payload)
+      @type = type
+      @payload = payload
+    end
+
+    def [](key)
+      payload[key] || payload[key.to_s] || payload[key.to_sym]
+    end
+
+    def to_h
+      payload
+    end
+
+    def method_missing(name, *args, &block)
+      key = name.to_s
+      return payload[key] if payload.key?(key)
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      payload.key?(name.to_s) || super
+    end
+  end
+end

data/lib/sveda/stream_parser.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Sveda
+  class StreamParser
+    SSE_DONE_LINE = "data: [DONE]"
+
+    STREAM_EVENTS = [
+      "message.start",
+      "text.delta",
+      "reasoning.delta",
+      "tool.call",
+      "tool.result",
+      "tool.progress",
+      "context.usage",
+      "chat.title",
+      "max_steps",
+      "message.end",
+      "error"
+    ].freeze
+
+    def each(body)
+      return enum_for(:each, body) unless block_given?
+
+      if body.is_a?(String)
+        body.split(/\r\n|\n|\r/).each do |line|
+          event = parse_line(line)
+          yield event if event
+        end
+        return
+      end
+
+      buffer = +""
+      body.each do |chunk|
+        buffer << chunk.to_s
+        while (newline_index = buffer.index("\n"))
+          line = buffer.slice!(0, newline_index + 1)
+          event = parse_line(line)
+          yield event if event
+        end
+      end
+
+      tail = buffer.strip
+      return if tail.empty?
+
+      event = parse_line(tail)
+      yield event if event
+    end
+
+    def parse_line(line)
+      trimmed = line.to_s.strip
+      return unless trimmed.start_with?("data:")
+
+      payload = trimmed[5..].to_s.strip
+      return if payload.empty? || payload == "[DONE]"
+
+      decoded = JSON.parse(payload)
+      return unless decoded.is_a?(Hash)
+
+      type = decoded["type"]
+      return unless type.is_a?(String) && STREAM_EVENTS.include?(type)
+
+      StreamEvent.new(type, decoded)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/sveda/version.rb

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

data/lib/sveda-ai.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "sveda"

data/lib/sveda-ruby-sdk.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "sveda"

data/lib/sveda.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "sveda/version"
+require_relative "sveda/errors"
+require_relative "sveda/stream_event"
+require_relative "sveda/stream_parser"
+require_relative "sveda/embed_token"
+require_relative "sveda/message"
+require_relative "sveda/http"
+require_relative "sveda/embed"
+require_relative "sveda/chat"
+require_relative "sveda/histories"
+require_relative "sveda/client"
+
+module Sveda
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: sveda-ruby-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Neresson
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-17 00:00:00.000000000 Z
+dependencies: []
+description: Ruby SDK for the Sveda AI sidecar HTTP API (embed tokens, streaming chat,
+  histories).
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/sveda-ai.rb
+- lib/sveda-ruby-sdk.rb
+- lib/sveda.rb
+- lib/sveda/chat.rb
+- lib/sveda/client.rb
+- lib/sveda/embed.rb
+- lib/sveda/embed_token.rb
+- lib/sveda/errors.rb
+- lib/sveda/histories.rb
+- lib/sveda/http.rb
+- lib/sveda/message.rb
+- lib/sveda/stream_event.rb
+- lib/sveda/stream_parser.rb
+- lib/sveda/version.rb
+homepage: https://github.com/neresson/sveda-ruby-sdk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/neresson/sveda-ruby-sdk
+  source_code_uri: https://github.com/neresson/sveda-ruby-sdk
+  changelog_uri: https://github.com/neresson/sveda-ruby-sdk/blob/main/README.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.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: Ruby SDK for the Sveda AI sidecar HTTP API
+test_files: []