tama-rb 0.1.2

data/lib/tama/http.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "faraday"
+require "faraday/retry"
+require "json"
+require "uri"
+
+module Tama
+  class HTTP
+    RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
+
+    attr_reader :base_uri, :connection
+
+    def initialize(base_url:, headers:, timeout:, retries:, connection: nil)
+      @base_uri = parse_base_url(base_url)
+      @headers = Faraday::Utils::Headers.new(headers)
+      @timeout = validate_timeout(timeout)
+      @retries = validate_retries(retries)
+      unless connection.nil? || connection.respond_to?(:run_request)
+        raise Error::ConfigurationError, "connection must be a Faraday-compatible connection"
+      end
+
+      @connection = connection || build_connection
+    end
+
+    def namespace!
+      segments = base_uri.path.split("/").reject(&:empty?)
+      raise Error::ConfigurationError, "Base URL must end with an operation namespace" if segments.empty?
+
+      segments.last
+    end
+
+    def validate_namespace!(*allowed)
+      namespace = namespace!
+      return if allowed.include?(namespace)
+
+      raise Error::InvalidNamespaceError,
+        "Invalid client namespace. Expected one of #{allowed.inspect}, got #{namespace.inspect}"
+    end
+
+    def request(method, path, body: nil, query: nil, headers: {}, timeout: nil, &on_data)
+      connection.run_request(method, absolute_url(path), body, merged_headers(headers)) do |request|
+        request.options.timeout = validate_timeout(timeout || @timeout)
+        request.options.on_data = on_data if on_data
+        query&.each_pair { |key, value| request.params[key] = value }
+      end
+    rescue Error
+      raise
+    rescue Faraday::Error => e
+      raise Error::TransportError.new(e.message, cause: e)
+    end
+
+    def parse_data(response, model, list: false)
+      check_status!(response)
+      document = parse_json(response.body)
+      raise Error::ParseError, "Response JSON must be an object with a data key" unless document.is_a?(Hash) && document.key?("data")
+
+      data = document["data"]
+      if list
+        raise Error::ParseError, "Response data must be an array" unless data.is_a?(Array)
+
+        data.map { |item| model.parse(item) }
+      else
+        model.parse(data)
+      end
+    end
+
+    def parse_body(response, model)
+      check_status!(response)
+      model.parse(parse_json(response.body))
+    end
+
+    def check_status!(response)
+      status = response.status.to_i
+      return response if status.between?(200, 299)
+
+      body = parse_error_body(response.body)
+      raise Error::NotFoundError.new(body:) if status == 404
+      if status == 422
+        errors = (body.is_a?(Hash) && body.key?("errors")) ? body["errors"] : body
+        raise Error::ValidationError.new("API validation failed", errors:, status:)
+      end
+
+      raise Error::HTTPError.new(status:, body:)
+    end
+
+    def self.segment(value, name)
+      unless value.is_a?(String) && !value.empty?
+        raise Error::ValidationError.new("#{name} must be a non-empty string", errors: {name => "must be a non-empty string"})
+      end
+
+      CGI.escape(value).gsub("+", "%20")
+    end
+
+    private
+
+    def parse_base_url(value)
+      raise Error::ConfigurationError, "base_url must be a string" unless value.is_a?(String) && !value.empty?
+
+      uri = URI.parse(value)
+      unless %w[http https].include?(uri.scheme) && uri.host && !uri.host.empty?
+        raise Error::ConfigurationError, "base_url must be an absolute HTTP(S) URL"
+      end
+      unless uri.port.between?(1, 65_535)
+        raise Error::ConfigurationError, "base_url port must be between 1 and 65535"
+      end
+
+      uri.path = "/" if uri.path.empty?
+      uri
+    rescue URI::InvalidURIError => e
+      raise Error::ConfigurationError, "Invalid base_url: #{e.message}"
+    end
+
+    def validate_timeout(value)
+      return value if value.is_a?(Numeric) && value.positive?
+
+      raise Error::ConfigurationError, "timeout must be a positive number"
+    end
+
+    def validate_retries(value)
+      return value if value.is_a?(Integer) && value >= 0
+
+      raise Error::ConfigurationError, "retries must be a non-negative integer"
+    end
+
+    def build_connection
+      Faraday.new do |faraday|
+        faraday.request :json
+        faraday.request :retry, max: @retries, retry_statuses: RETRY_STATUSES
+        faraday.adapter Faraday.default_adapter
+      end
+    end
+
+    def absolute_url(path)
+      uri = base_uri.dup
+      base_path = uri.path.sub(%r{/+\z}, "")
+      endpoint = path.sub(%r{\A/+}, "")
+      uri.path = "#{base_path}/#{endpoint}"
+      uri.query = nil
+      uri.fragment = nil
+      uri.to_s
+    end
+
+    def merged_headers(headers)
+      @headers.merge(headers).tap do |merged|
+        merged["Accept"] ||= "application/json"
+      end
+    end
+
+    def parse_json(body)
+      return body if body.is_a?(Hash) || body.is_a?(Array)
+      raise Error::ParseError, "Response body must contain JSON" unless body.is_a?(String) && !body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError => e
+      raise Error::ParseError, "Malformed JSON response: #{e.message}"
+    end
+
+    def parse_error_body(body)
+      return body unless body.is_a?(String)
+      return body if body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+  end
+end

data/lib/tama/memory/entity.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Tama
+  module Memory
+    Entity = Model.define(
+      :id, :class_id, :current_state, :identifier,
+      required: %i[class_id current_state identifier],
+      types: {id: String, class_id: String, current_state: String, identifier: String}
+    )
+  end
+end

data/lib/tama/memory/entity_params.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Tama
+  module Memory
+    EntityParams = Data.define(:identifier, :record, :validate_record) do
+      def initialize(identifier:, record:, validate_record: true)
+        unless identifier.is_a?(String) && !identifier.empty?
+          raise Error::ValidationError.new("identifier is required", errors: {identifier: "must be a non-empty string"})
+        end
+        unless record.is_a?(Hash)
+          raise Error::ValidationError.new("record is required", errors: {record: "must be a hash"})
+        end
+        unless [true, false].include?(validate_record)
+          raise Error::ValidationError.new("validate_record must be boolean", errors: {validate_record: "must be boolean"})
+        end
+
+        super
+      end
+
+      def self.parse(value)
+        data = Params.hash(value, "entity")
+        new(
+          identifier: data["identifier"],
+          record: data["record"],
+          validate_record: data.fetch("validate_record", true)
+        )
+      end
+
+      def to_h
+        {"identifier" => identifier, "record" => record, "validate_record" => validate_record}
+      end
+    end
+  end
+end

data/lib/tama/memory/service.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Tama
+  module Memory
+    class Service
+      def initialize(http)
+        @http = http
+      end
+
+      def create_entity(klass, attributes = nil, headers: {}, timeout: nil, **attribute_keywords)
+        @http.validate_namespace!("ingest")
+        class_id = klass.is_a?(Neural::Klass) ? klass.id : klass
+        attributes ||= attribute_keywords
+        params = attributes.is_a?(EntityParams) ? attributes : EntityParams.parse(attributes)
+        path = "memory/classes/#{HTTP.segment(class_id, "class_id")}/entities"
+        response = @http.request(:post, path, body: {"entity" => params.to_h}, headers:, timeout:)
+        @http.parse_data(response, Entity)
+      end
+    end
+  end
+end

data/lib/tama/model.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Tama
+  module Model
+    module_function
+
+    def define(*fields, required: [], types: {}, defaults: {}, transforms: {})
+      Class.new(Data.define(*fields)) do
+        define_singleton_method(:fields) { fields }
+
+        define_method(:initialize) do |**attributes|
+          unknown = attributes.keys - fields
+          unless unknown.empty?
+            raise Tama::Error::ValidationError.new("Unknown attributes: #{unknown.join(", ")}", errors: {attributes: unknown})
+          end
+
+          values = fields.to_h { |field| [field, attributes.fetch(field, defaults.fetch(field, nil))] }
+          Tama::Model.validate!(values, required:, types:, name: self.class.name)
+          super(**values)
+        end
+
+        define_singleton_method(:parse) do |input|
+          data = Tama::Model.hash(input)
+          values = fields.to_h do |field|
+            value = data.key?(field.to_s) ? data[field.to_s] : data[field]
+            value = transforms.fetch(field).call(value) if !value.nil? && transforms.key?(field)
+            [field, value.nil? ? defaults.fetch(field, nil) : value]
+          end
+
+          new(**values)
+        rescue Tama::Error::ParseError
+          raise
+        rescue Tama::Error => e
+          raise Tama::Error::ParseError, "Invalid #{name || "model"}: #{e.message}"
+        rescue => e
+          raise Tama::Error::ParseError, "Invalid #{name || "model"}: #{e.message}"
+        end
+      end
+    end
+
+    def hash(input)
+      input = JSON.parse(input) if input.is_a?(String)
+      raise Tama::Error::ParseError, "Expected a JSON object" unless input.is_a?(Hash)
+
+      input
+    rescue JSON::ParserError => e
+      raise Tama::Error::ParseError, "Malformed JSON: #{e.message}"
+    end
+
+    def validate!(values, required:, types:, name:)
+      missing = required.select { |field| blank?(values[field]) }
+      unless missing.empty?
+        raise Tama::Error::ValidationError.new("Missing required fields: #{missing.join(", ")}", errors: {required: missing})
+      end
+
+      types.each do |field, expected|
+        value = values[field]
+        next if value.nil? || valid_type?(value, expected)
+
+        raise Tama::Error::ValidationError.new(
+          "#{field} has an invalid type for #{name || "model"}",
+          errors: {field => "must be #{type_name(expected)}"}
+        )
+      end
+    end
+
+    def blank?(value)
+      value.nil? || (value.is_a?(String) && value.empty?)
+    end
+
+    def valid_type?(value, expected)
+      Array(expected).any? { |type| value.is_a?(type) }
+    end
+
+    def type_name(expected)
+      Array(expected).join(" or ")
+    end
+  end
+end

data/lib/tama/neural/klass.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Tama
+  module Neural
+    Klass = Model.define(
+      :id, :space_id, :provision_state, :schema, :name, :description,
+      required: %i[provision_state name],
+      types: {
+        id: String, space_id: String, provision_state: String, schema: Hash,
+        name: String, description: String
+      }
+    )
+  end
+end

data/lib/tama/neural/operation.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Tama
+  module Neural
+    Operation = Model.define(
+      :id, :current_state, :class_id, :node_ids,
+      required: %i[current_state class_id],
+      types: {id: String, current_state: String, class_id: String, node_ids: Array},
+      transforms: {
+        node_ids: lambda do |value|
+          unless value.is_a?(Array) && value.all? { |node_id| node_id.is_a?(String) }
+            raise Error::ValidationError, "node_ids must be an array of strings"
+          end
+
+          value
+        end
+      }
+    )
+  end
+end

data/lib/tama/neural/operation_params.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Tama
+  module Neural
+    OperationParams = Data.define(:chain_ids, :node_type) do
+      def initialize(chain_ids:, node_type: nil)
+        unless chain_ids.is_a?(Array) && !chain_ids.empty? && chain_ids.all? { |id| id.is_a?(String) && !id.empty? }
+          raise Error::ValidationError.new("chain_ids must contain at least one chain ID", errors: {chain_ids: "must contain non-empty strings"})
+        end
+        unless node_type.nil? || node_type.is_a?(String)
+          raise Error::ValidationError.new("node_type must be a string", errors: {node_type: "must be a string"})
+        end
+
+        super
+      end
+
+      def self.parse(value)
+        data = Params.hash(value, "operation")
+        new(chain_ids: data["chain_ids"], node_type: data["node_type"])
+      end
+
+      def to_h
+        {"chain_ids" => chain_ids}.tap { |body| body["node_type"] = node_type unless node_type.nil? }
+      end
+    end
+  end
+end

data/lib/tama/neural/service.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Tama
+  module Neural
+    class Service
+      def initialize(http)
+        @http = http
+      end
+
+      def get_space(slug, headers: {}, timeout: nil)
+        @http.validate_namespace!("provision")
+        path = "neural/spaces/#{HTTP.segment(slug, "slug")}"
+        @http.parse_data(@http.request(:get, path, headers:, timeout:), Space)
+      end
+
+      def get_class(space, name, headers: {}, timeout: nil)
+        @http.validate_namespace!("provision")
+        space_id = space.is_a?(Space) ? space.id : space
+        path = "neural/spaces/#{HTTP.segment(space_id, "space_id")}/classes/#{HTTP.segment(name, "name")}"
+        @http.parse_data(@http.request(:get, path, headers:, timeout:), Klass)
+      end
+
+      def create_class_operation(klass, attributes = nil, headers: {}, timeout: nil, **attribute_keywords)
+        @http.validate_namespace!("provision")
+        class_id = klass.is_a?(Klass) ? klass.id : klass
+        attributes ||= attribute_keywords
+        params = attributes.is_a?(OperationParams) ? attributes : OperationParams.parse(attributes)
+        path = "neural/classes/#{HTTP.segment(class_id, "class_id")}/operations"
+        response = @http.request(:post, path, body: {"operation" => params.to_h}, headers:, timeout:)
+        @http.parse_data(response, Operation)
+      end
+    end
+  end
+end

data/lib/tama/neural/space.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Tama
+  module Neural
+    Space = Model.define(
+      :id, :name, :slug, :type, :provision_state,
+      required: %i[name type provision_state],
+      types: {id: String, name: String, slug: String, type: String, provision_state: String}
+    )
+  end
+end

data/lib/tama/params.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Tama
+  module Params
+    module_function
+
+    def hash(value, name)
+      value = value.to_h if value.respond_to?(:to_h) && !value.is_a?(Hash)
+      raise Error::ValidationError.new("#{name} must be a hash", errors: {name => "must be a hash"}) unless value.is_a?(Hash)
+
+      value.transform_keys(&:to_s)
+    end
+
+    def require_string!(data, key)
+      value = data[key]
+      return value if value.is_a?(String) && !value.empty?
+
+      raise Error::ValidationError.new("#{key} is required", errors: {key => "must be a non-empty string"})
+    end
+
+    def optional_string!(data, key)
+      value = data[key]
+      return if value.nil?
+      return value if value.is_a?(String)
+
+      raise Error::ValidationError.new("#{key} is invalid", errors: {key => "must be a string"})
+    end
+  end
+end

data/lib/tama/perception/chain.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Tama
+  module Perception
+    Chain = Model.define(
+      :id, :space_id, :name, :slug, :provision_state,
+      required: %i[name provision_state],
+      types: {id: String, space_id: String, name: String, slug: String, provision_state: String}
+    )
+  end
+end

data/lib/tama/perception/concept.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Tama
+  module Perception
+    Concept = Model.define(
+      :id, :relation, :content, :generator,
+      required: %i[id relation content],
+      types: {id: String, relation: String, content: Hash, generator: Generator},
+      transforms: {generator: ->(value) { Generator.parse(value) }}
+    )
+
+    class << Concept
+      alias_method :parse_one, :parse
+
+      def parse(input)
+        return input.map { |item| parse_one(item) } if input.is_a?(Array)
+
+        parse_one(input)
+      end
+    end
+  end
+end

data/lib/tama/perception/generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Tama
+  module Perception
+    Generator = Model.define(
+      :type, :reference, :parameters,
+      required: %i[type reference parameters],
+      types: {type: Symbol, reference: String, parameters: Hash},
+      transforms: {
+        type: lambda do |value|
+          type = value.to_sym
+          raise Error::ValidationError, "generator type must be model or module" unless %i[model module].include?(type)
+
+          type
+        end
+      }
+    )
+  end
+end

data/lib/tama/perception/service.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Tama
+  module Perception
+    class Service
+      def initialize(http)
+        @http = http
+      end
+
+      def get_chain(space, slug, headers: {}, timeout: nil)
+        @http.validate_namespace!("provision")
+        space_id = space.is_a?(Neural::Space) ? space.id : space
+        path = "perception/spaces/#{HTTP.segment(space_id, "space_id")}/chains/#{HTTP.segment(slug, "slug")}"
+        @http.parse_data(@http.request(:get, path, headers:, timeout:), Chain)
+      end
+
+      def list_concepts(entity_id, query: {}, headers: {}, timeout: nil)
+        @http.validate_namespace!("perception")
+        unless query.respond_to?(:each_pair)
+          raise Error::ValidationError.new("query must be a hash", errors: {query: "must be a hash"})
+        end
+
+        path = "entities/#{HTTP.segment(entity_id, "entity_id")}/concepts"
+        response = @http.request(:get, path, query:, headers:, timeout:)
+        @http.parse_data(response, Concept, list: true)
+      end
+    end
+  end
+end

data/lib/tama/sse_parser.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Tama
+  class SSEParser
+    def initialize(callback)
+      @callback = callback
+      @buffer = +""
+      @done = false
+    end
+
+    def feed(chunk)
+      return if @done
+      raise Error::ParseError, "SSE chunk must be a string" unless chunk.is_a?(String)
+
+      @buffer << chunk
+      consume_complete_events
+      self
+    end
+
+    def finish
+      process_event(@buffer) unless @done || @buffer.empty?
+      @buffer.clear
+      self
+    end
+
+    private
+
+    def consume_complete_events
+      while (match = @buffer.match(/\r\n\r\n|\n\n|\r\r/))
+        event = @buffer.slice!(0, match.begin(0))
+        @buffer.slice!(0, match[0].bytesize)
+        process_event(event)
+        break if @done
+      end
+    end
+
+    def process_event(event)
+      data = event.split(/\r\n|\n|\r/).filter_map do |line|
+        next unless line.start_with?("data:")
+
+        value = line.delete_prefix("data:")
+        value = value.delete_prefix(" ")
+        value
+      end.join("\n")
+
+      return if data.empty?
+
+      if data == "[DONE]"
+        @done = true
+        return
+      end
+
+      @callback.call(JSON.parse(data))
+    rescue JSON::ParserError => e
+      raise Error::ParseError, "Malformed SSE data: #{e.message}"
+    end
+  end
+end

data/lib/tama/version.rb

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

data/lib/tama.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "tama/version"
+require_relative "tama/error"
+require_relative "tama/model"
+require_relative "tama/params"
+require_relative "tama/neural/space"
+require_relative "tama/neural/klass"
+require_relative "tama/neural/operation"
+require_relative "tama/neural/operation_params"
+require_relative "tama/memory/entity"
+require_relative "tama/memory/entity_params"
+require_relative "tama/perception/chain"
+require_relative "tama/perception/generator"
+require_relative "tama/perception/concept"
+require_relative "tama/agentic/author"
+require_relative "tama/agentic/thread"
+require_relative "tama/agentic/message_params"
+require_relative "tama/agentic/message"
+require_relative "tama/broadcast"
+require_relative "tama/sse_parser"
+require_relative "tama/http"
+require_relative "tama/neural/service"
+require_relative "tama/memory/service"
+require_relative "tama/perception/service"
+require_relative "tama/agentic/service"
+require_relative "tama/client"