tama-rb 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a8e4b7c980bd24d10783272afb5e38e76a8863d6879d849cc9b62f00493abbab
+  data.tar.gz: 786b9d8c94414e52f0f8b9879317de943bdb2d59bd5dc74a730c9e7b78bc2f04
+SHA512:
+  metadata.gz: 88083d85c2da41b50c4c4bd231005e53e94f05222235dcd26817dfb23d92fbbc80bd6645c4c59dd2bb7c8c96dbe908c293d726466605e1e4ccb968e7546b3717
+  data.tar.gz: 340e80ecebb7cefad5e2e6341e82e740a116e76bb989fc6f342aa3baa8e27b7fdd47d55624c9f92300686573c728372687fcfc84b44cde9df001e59f2c8e36ec

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.1 - 2026-08-21
+
+- Fix the Trusted Publishing workflow and align release tags with Bundler's `v` prefix convention.
+
+## 0.1.0 - 2026-08-21
+
+- Initial release with Neural, Memory, Perception, and Agentic services.
+- Add strict immutable models and the complete Broadcast parser hierarchy.
+- Add typed errors, retry support, path encoding, and incremental SSE parsing.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zack Siri
+
+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,228 @@
+# Tama Ruby
+
+`tama-rb` is the Ruby client for Tama APIs. It provides namespace-aware Faraday services, strict immutable response models, typed errors, and incremental server-sent event parsing.
+
+## Installation
+
+Add the gem to your bundle:
+
+```ruby
+gem "tama-rb", "~> 0.1.0"
+```
+
+Then run `bundle install` and load the client with:
+
+```ruby
+require "tama"
+```
+
+Ruby 3.2 or newer is required.
+
+## Client Setup
+
+Create a client with the base URL for the API namespace being used:
+
+```ruby
+client = Tama::Client.new(
+  base_url: "https://api.example.com/provision",
+  headers: {"Authorization" => "Bearer token"},
+  timeout: 300,
+  retries: 2
+)
+```
+
+Timeouts are expressed in seconds. Global headers are merged with per-request headers, with per-request values taking precedence. Retries use `faraday-retry` for retryable requests and statuses. The default transport is Faraday's Net::HTTP adapter.
+
+An existing connection can be injected when custom Faraday middleware or an adapter is needed. The injected connection is used as configured; `base_url` is still required for request URL construction and namespace validation.
+
+```ruby
+connection = Faraday.new do |faraday|
+  faraday.request :json
+  faraday.request :retry, max: 3
+  faraday.adapter :net_http
+end
+
+client = Tama::Client.new(
+  base_url: "https://api.example.com/perception",
+  connection: connection
+)
+```
+
+### Namespace URLs
+
+The final base URL path segment is validated for each operation. Prefixes such as `/api/v1` are preserved.
+
+| Namespace | Operations |
+| --- | --- |
+| `provision` | Neural space/class/operation, perception chain lookup |
+| `ingest` | Memory entity creation |
+| `perception` | Perception concept listing |
+| `agentic` | Agentic message creation and streaming |
+
+Use separate clients when an application calls multiple namespaces.
+
+## Neural
+
+```ruby
+client = Tama::Client.new(base_url: "https://api.example.com/provision")
+
+space = client.neural.get_space("my-space")
+klass = client.neural.get_class(space, "article")
+
+operation = client.neural.create_class_operation(
+  klass,
+  chain_ids: ["chain-1", "chain-2"],
+  node_type: "compute"
+)
+```
+
+`get_class` accepts a `Tama::Neural::Space` or a space ID. `create_class_operation` accepts a `Tama::Neural::Klass` or class ID and either a hash or `Tama::Neural::OperationParams`.
+
+## Memory
+
+```ruby
+client = Tama::Client.new(base_url: "https://api.example.com/ingest")
+
+entity = client.memory.create_entity(
+  klass,
+  identifier: "article-123",
+  record: {title: "Tama with Ruby"},
+  validate_record: true
+)
+```
+
+`validate_record` defaults to `true`. A `Tama::Memory::EntityParams` object can be passed instead of a hash.
+
+## Perception
+
+Chain lookup uses a provision client:
+
+```ruby
+client = Tama::Client.new(base_url: "https://api.example.com/provision")
+chain = client.perception.get_chain(space, "summarize")
+```
+
+`get_chain` accepts a `Tama::Neural::Space` or space ID. Concept listing uses a perception client and supports query parameters:
+
+```ruby
+client = Tama::Client.new(base_url: "https://api.example.com/perception")
+
+concepts = client.perception.list_concepts(
+  "entity-123",
+  query: {limit: 20, offset: 0, relation: "reply"}
+)
+```
+
+## Agentic
+
+```ruby
+client = Tama::Client.new(base_url: "https://api.example.com/agentic")
+
+message = client.agentic.create_message(
+  recipient: "user-123",
+  identifier: "message-123",
+  content: "Hello",
+  index: 1,
+  author: {identifier: "agent-1", source: "system"},
+  thread: {identifier: "thread-1"}
+)
+```
+
+Message class defaults are `user-message`, `actor`, and `thread`. A `Tama::Agentic::MessageParams` object can also be supplied.
+
+### Streaming
+
+Streaming requires either `callback:` or a block. Each handler call receives one decoded JSON event. The parser buffers fragmented chunks, supports LF and CRLF separators, multiline `data:` fields, multiple events per chunk, and `[DONE]`.
+
+```ruby
+response = client.agentic.create_message(message_attributes, stream: true) do |event|
+  puts event.inspect
+end
+```
+
+The streaming form returns the successful `Faraday::Response`. Non-streaming creation parses the API's top-level JSON response into a `Tama::Agentic::Message`.
+
+## Request Options
+
+Every operation accepts `headers:` and `timeout:` request options where applicable:
+
+```ruby
+space = client.neural.get_space(
+  "my-space",
+  headers: {"X-Request-ID" => "request-1"},
+  timeout: 30
+)
+```
+
+Dynamic path segments are percent-encoded. Query parameters should be passed only through `query:` on `list_concepts`.
+
+## Models
+
+Response and parser models are immutable Ruby `Data` objects:
+
+- `Tama::Neural::Space`, `Tama::Neural::Klass`, `Tama::Neural::Operation`, `Tama::Neural::OperationParams`
+- `Tama::Memory::Entity`, `Tama::Memory::EntityParams`
+- `Tama::Perception::Chain`, `Tama::Perception::Concept`, `Tama::Perception::Generator`
+- `Tama::Agentic::Message`, `Tama::Agentic::MessageParams`, `Tama::Agentic::Author`, `Tama::Agentic::Thread`
+- `Tama::Broadcast` and `Tama::Broadcast::Event`, `Metadata`, `Step`, `Concept`, `Thought`, `Chain`, `Branch`, `Flow`, `OriginEntity`
+
+Broadcast payloads are parsed without making an HTTP request. Top-level `event` and `step` values are required:
+
+```ruby
+broadcast = Tama::Broadcast.parse(
+  event: {name: "step.updated", domain: "workflow"},
+  step: {id: "step-1", concepts: []}
+)
+```
+
+Response models also expose `.parse(hash_or_json)`. Invalid JSON, required fields, types, enums, or nested models raise rather than creating partial empty models.
+
+## Errors
+
+Failures raise subclasses of `Tama::Error`:
+
+- `Tama::Error::ConfigurationError` for malformed client configuration
+- `Tama::Error::InvalidNamespaceError` for a mismatched final base URL segment
+- `Tama::Error::ValidationError` for local parameters and HTTP 422 responses; inspect `errors`
+- `Tama::Error::NotFoundError` for HTTP 404 responses
+- `Tama::Error::HTTPError` for other non-2xx responses; inspect `status` and `body`
+- `Tama::Error::TransportError` for Faraday transport failures; inspect `cause`
+- `Tama::Error::ParseError` for malformed JSON, response envelopes, models, or SSE events
+
+All HTTP statuses from 200 through 299 are successful. Neural, Memory, and Perception model endpoints require the API's exact `{ "data": ... }` response envelope; Agentic message creation uses its top-level response object.
+
+## Development
+
+```sh
+bin/setup
+bundle exec rspec
+bundle exec standardrb
+bundle exec rake build
+```
+
+`bin/console` starts an IRB session with Tama loaded.
+
+## Releasing
+
+Releases use RubyGems Trusted Publishing, so the repository does not store a long-lived RubyGems API key.
+
+Before the first release, create a pending trusted publisher at <https://rubygems.org/profile/oidc/pending_trusted_publishers> with:
+
+- Gem name: `tama-rb`
+- Repository owner: `upmaru`
+- Repository name: `tama-rb`
+- Workflow filename: `publish.yml`
+- GitHub environment: `release`
+
+Create the `release` environment in the GitHub repository settings. After updating `Tama::VERSION` and `CHANGELOG.md`, publish by pushing a matching version tag:
+
+```sh
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The first successful workflow run publishes the gem and converts the pending publisher into a trusted publisher. RubyGems organizations are currently in private beta; organization ownership requires beta access followed by transferring the published gem to the organization.
+
+## License
+
+The gem is available under the MIT License.

data/lib/tama/agentic/author.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Tama
+  module Agentic
+    Author = Data.define(:identifier, :source, :klass) do
+      def initialize(identifier:, source:, klass: "actor")
+        Params.require_string!({"identifier" => identifier}, "identifier")
+        Params.require_string!({"source" => source}, "source")
+        Params.require_string!({"class" => klass}, "class")
+        super
+      end
+
+      def self.parse(value)
+        data = Params.hash(value, "author")
+        new(identifier: data["identifier"], source: data["source"], klass: data.fetch("class", "actor"))
+      end
+
+      def to_h
+        {"identifier" => identifier, "source" => source, "class" => klass}
+      end
+    end
+  end
+end

data/lib/tama/agentic/message.rb

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

data/lib/tama/agentic/message_params.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Tama
+  module Agentic
+    MessageParams = Data.define(:recipient, :klass, :identifier, :content, :index, :author, :thread) do
+      def initialize(recipient:, identifier:, content:, index:, author:, thread:, klass: "user-message")
+        Params.require_string!({"recipient" => recipient}, "recipient")
+        Params.require_string!({"class" => klass}, "class")
+        Params.require_string!({"identifier" => identifier}, "identifier")
+        Params.require_string!({"content" => content}, "content")
+        unless index.is_a?(Integer)
+          raise Error::ValidationError.new("index is required", errors: {index: "must be an integer"})
+        end
+        raise Error::ValidationError, "author is invalid" unless author.is_a?(Author)
+        raise Error::ValidationError, "thread is invalid" unless thread.is_a?(Thread)
+
+        super
+      end
+
+      def self.parse(value)
+        data = Params.hash(value, "message")
+        new(
+          recipient: data["recipient"],
+          klass: data.fetch("class", "user-message"),
+          identifier: data["identifier"],
+          content: data["content"],
+          index: data["index"],
+          author: Author.parse(data["author"]),
+          thread: Thread.parse(data["thread"])
+        )
+      end
+
+      def to_h
+        {
+          "recipient" => recipient,
+          "class" => klass,
+          "identifier" => identifier,
+          "content" => content,
+          "index" => index,
+          "author" => author.to_h,
+          "thread" => thread.to_h
+        }
+      end
+    end
+  end
+end

data/lib/tama/agentic/service.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Tama
+  module Agentic
+    class Service
+      def initialize(http)
+        @http = http
+      end
+
+      def create_message(attributes = nil, stream: false, callback: nil, headers: {}, timeout: nil, **attribute_keywords, &block)
+        @http.validate_namespace!("agentic")
+        attributes ||= attribute_keywords
+        params = attributes.is_a?(MessageParams) ? attributes : MessageParams.parse(attributes)
+        handler = callback || block
+
+        if stream
+          raise Error::ValidationError, "A callback or block is required when streaming" unless handler.respond_to?(:call)
+
+          create_stream(params, handler, headers:, timeout:)
+        else
+          response = @http.request(
+            :post,
+            "messages",
+            body: {"stream" => false, "message" => params.to_h},
+            headers:,
+            timeout:
+          )
+          @http.parse_body(response, Message)
+        end
+      end
+
+      private
+
+      def create_stream(params, handler, headers:, timeout:)
+        parser = SSEParser.new(handler)
+        stream_headers = {"Accept" => "text/event-stream"}.merge(headers)
+        response = @http.request(
+          :post,
+          "messages",
+          body: {"stream" => true, "message" => params.to_h},
+          headers: stream_headers,
+          timeout:
+        ) { |chunk, *| parser.feed(chunk) }
+        @http.check_status!(response)
+        parser.finish
+        response
+      end
+    end
+  end
+end

data/lib/tama/agentic/thread.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Tama
+  module Agentic
+    Thread = Data.define(:identifier, :klass) do
+      def initialize(identifier:, klass: "thread")
+        Params.require_string!({"identifier" => identifier}, "identifier")
+        Params.require_string!({"class" => klass}, "class")
+        super
+      end
+
+      def self.parse(value)
+        data = Params.hash(value, "thread")
+        new(identifier: data["identifier"], klass: data.fetch("class", "thread"))
+      end
+
+      def to_h
+        {"identifier" => identifier, "class" => klass}
+      end
+    end
+  end
+end

data/lib/tama/broadcast.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Tama
+  Broadcast = Model.define(
+    :event, :step,
+    required: %i[event step],
+    transforms: {
+      event: ->(value) { Broadcast::Event.parse(value) },
+      step: ->(value) { Broadcast::Step.parse(value) }
+    }
+  )
+
+  class Broadcast
+    Metadata = Model.define(
+      :changes, :comment, :parameters,
+      types: {changes: Hash, comment: String, parameters: Hash}
+    )
+
+    Event = Model.define(
+      :name, :domain, :metadata,
+      types: {name: String, domain: String, metadata: Metadata},
+      transforms: {metadata: ->(value) { Metadata.parse(value) }}
+    )
+
+    Concept = Model.define(
+      :id, :relation, :content,
+      types: {id: String, relation: String, content: Hash}
+    )
+
+    Chain = Model.define(
+      :id, :name,
+      types: {id: String, name: String}
+    )
+
+    Thought = Model.define(
+      :chain, :relation, :index,
+      types: {chain: Chain, relation: String, index: Integer},
+      transforms: {chain: ->(value) { Chain.parse(value) }}
+    )
+
+    OriginEntity = Model.define(
+      :id, :current_state, :identifier,
+      types: {id: String, current_state: String, identifier: String}
+    )
+
+    Flow = Model.define(
+      :id, :origin_entity,
+      types: {id: String, origin_entity: OriginEntity},
+      transforms: {origin_entity: ->(value) { OriginEntity.parse(value) }}
+    )
+
+    Branch = Model.define(
+      :id, :chain_id, :current_state, :flow,
+      types: {id: String, chain_id: String, current_state: String, flow: Flow},
+      transforms: {flow: ->(value) { Flow.parse(value) }}
+    )
+
+    Step = Model.define(
+      :id, :current_state, :index, :attempt, :concepts, :thought, :branch,
+      defaults: {concepts: []},
+      types: {
+        id: String, current_state: String, index: Integer, attempt: Integer,
+        concepts: Array, thought: Thought, branch: Branch
+      },
+      transforms: {
+        concepts: lambda do |value|
+          raise Error::ValidationError, "concepts must be an array" unless value.is_a?(Array)
+
+          value.map { |concept| Concept.parse(concept) }
+        end,
+        thought: ->(value) { Thought.parse(value) },
+        branch: ->(value) { Branch.parse(value) }
+      }
+    )
+  end
+end

data/lib/tama/client.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Tama
+  class Client
+    DEFAULT_TIMEOUT = 300
+    DEFAULT_RETRIES = 2
+
+    attr_reader :neural, :memory, :perception, :agentic, :connection
+
+    def initialize(base_url:, headers: {}, timeout: DEFAULT_TIMEOUT, retries: DEFAULT_RETRIES, connection: nil)
+      http = HTTP.new(base_url:, headers:, timeout:, retries:, connection:)
+      @connection = http.connection
+      @neural = Neural::Service.new(http)
+      @memory = Memory::Service.new(http)
+      @perception = Perception::Service.new(http)
+      @agentic = Agentic::Service.new(http)
+      freeze
+    end
+  end
+end

data/lib/tama/error.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Tama
+  class Error < StandardError
+    class ConfigurationError < Error; end
+    class InvalidNamespaceError < ConfigurationError; end
+
+    class ValidationError < Error
+      attr_reader :errors, :status
+
+      def initialize(message = "Validation failed", errors: {}, status: nil)
+        @errors = errors
+        @status = status
+        super(message)
+      end
+    end
+
+    class HTTPError < Error
+      attr_reader :status, :body
+
+      def initialize(message = nil, status:, body: nil)
+        @status = status
+        @body = body
+        super(message || "HTTP request failed with status #{status}")
+      end
+    end
+
+    class NotFoundError < HTTPError
+      def initialize(body: nil)
+        super("Resource not found", status: 404, body: body)
+      end
+    end
+
+    class TransportError < Error
+      attr_reader :cause
+
+      def initialize(message = "HTTP transport failed", cause: nil)
+        @cause = cause
+        super(message)
+      end
+    end
+
+    class ParseError < Error; end
+  end
+end