nitro_intelligence 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa22292af25ca70dd3a19ba62830fa25606a84517af6f7bb79906ceea4d0e058
-  data.tar.gz: 07c68668426d3feb046e633203e617ede8f9ef807a3f60341c347fbb0c05b17f
+  metadata.gz: dcac30052d3ab8db387569038d73304349941c60d224879e67fe9116247397ff
+  data.tar.gz: 9dca9e4c1b4f3669c65d3889c36b20d502b8b910b4b6c0bf001eee40e8eabc9c
 SHA512:
-  metadata.gz: 02d7bcd08eb45f6dc14c0b4a5e5f91e0edac92369435721e838a0e623a5a26b4af33b0f851c1d02de54ca6d80a864d0b8904e9a78612e9d14aa642e8993865ba
-  data.tar.gz: e6c1bfc0896d5d11cc017e23aef1b617c3f83182c09fe8a6414202d66dfbdc5d2e13fe73bf3b5ef54e928d5f1cf944ad001781397bab7a8a5f4867e4a152cc1c
+  metadata.gz: 1e5eec8f160d35bb7fac0d12b3d47d1a84e0694ad98d2ddb3f301fb6b578f7970895a60240ddcd5eb04af95a9ee9fdcd79959bcc8aadfa17f5cc434351331ca6
+  data.tar.gz: a565c1662fbfbee8768c9f21691dad16401f34205d0c2b6f463b0e165ede2f15e602e0f84d569291cd37ccd56a3af7bacb6d1c8a71a91d698beefba57059b867

data/docs/README.md

@@ -38,16 +38,16 @@ end
 
 ### Configuration Keys
 
-| Key | Type | Default | Description |
-|---|---|---|---|
-| `logger` | `Logger` | `Logger.new($stdout)` | Logger used for diagnostic output |
-| `environment` | `String` | `"test"` | Runtime environment name |
-| `cache_provider` | cache store | `NullCache` | ActiveSupport-compatible cache store |
-| `inference_api_key` | `String` | `""` | API key for the LLM inference service |
-| `inference_base_url` | `String` | `""` | Base URL for the LLM inference service |
-| `observability_base_url` | `String` | `""` | Base URL for the Langfuse observability service |
-| `observability_projects` | `Array<Hash>` | `[]` | Langfuse project credentials (slug, id, public_key, secret_key) |
-| `agent_server_config` | `Hash` | `{}` | Credentials for `AgentServer.new`. Expected keys: `base_url` (String) — HTTP base URL of the agent server; `api_key` (String) — bearer token; `user_id` (String, default: `"default-user"`) — caller identity |
+| Key                      | Type          | Default               | Description                                                                                                                                                                                                |
+| ------------------------ | ------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `logger`                 | `Logger`      | `Logger.new($stdout)` | Logger used for diagnostic output                                                                                                                                                                          |
+| `environment`            | `String`      | `"test"`              | Runtime environment name                                                                                                                                                                                   |
+| `cache_provider`         | cache store   | `NullCache`           | ActiveSupport-compatible cache store                                                                                                                                                                       |
+| `inference_api_key`      | `String`      | `""`                  | API key for the LLM inference service                                                                                                                                                                      |
+| `inference_base_url`     | `String`      | `""`                  | Base URL for the LLM inference service                                                                                                                                                                     |
+| `observability_base_url` | `String`      | `""`                  | Base URL for the Langfuse observability service                                                                                                                                                            |
+| `observability_projects` | `Array<Hash>` | `[]`                  | Langfuse project credentials (slug, id, public_key, secret_key)                                                                                                                                            |
+| `agent_server_config`    | `Hash`        | `{}`                  | Credentials for `AgentServer.new`. Expected keys: `base_url` (String) — HTTP base URL of the agent server; `api_key` (String) — bearer token; `user_id` (String, default: `"default-user"`) — caller identity |
 
 ## Basic Usage
 
@@ -70,7 +70,6 @@ client = NitroIntelligence::Client.new
 client.chat(parameters: { model: "meta-llama/Llama-3.1-8B-Instruct", messages: [{ role: "user", content: "Why is the sky blue?" }]})
 ```
 
-
 #### Providing Parameters
 
 Parameters such as 'max_tokens' and 'temperature' can be passed in under the `parameters` key.
@@ -82,6 +81,36 @@ client.chat(parameters: { model: "meta-llama/Llama-3.1-8B-Instruct", max_tokens:
 
 For a full list of supported parameters, see the [API reference here](https://developers.openai.com/api/reference/resources/completions/methods/create).
 
+### Audio Transcription
+
+Nitro Intelligence can be used to transcribe audio from a file into text.
+
+Basic examples of usage:
+
+```ruby
+client = NitroIntelligence::Client.new
+audio = File.open('sample.m4a', 'rb')
+result = client.transcribe_audio(audio_file: audio)
+```
+
+`result` is a `OpenAI::Models::Audio::Transcription` object:
+
+```ruby
+<OpenAI::Models::Audio::Transcription:0x2fdc8 {:text=>"Hello, how are you doing today?", :usage=>{:input_tokens=>28, :output_tokens=>10, :total_tokens=>38, :type=>:tokens, :input_token_details=>{:audio_tokens=>28, :text_tokens=>0}}}>
+```
+
+To use a prompt, simply initialize your client with the `observability_project_slug` and pass `prompt_name` into parameters:
+
+```ruby
+client = NitroIntelligence::Client.new(observability_project_slug: "my-test-project")
+audio = File.open('sample.m4a', 'rb')
+result = client.transcribe_audio(audio_file: audio, parameters: {prompt_name: "Spanish Converter"})
+
+puts result
+
+# <OpenAI::Models::Audio::Transcription:0x2fd8c {:text=>"Hola, ¿cómo estás hoy?", :usage=>{:input_tokens=>37, :output_tokens=>9, :total_tokens=>46, :type=>:tokens, :input_token_details=>{:audio_tokens=>28, :text_tokens=>9}}}>
+```
+
 ### Image Editing and Generation
 
 Nitro Intelligence can be used for image editing and generation
@@ -175,6 +204,43 @@ client.chat(
 )
 ```
 
+### Custom Trace IDs
+
+To generate a deterministic trace ID in the observability platform, you can pass `trace_seed` as a parameter. This is useful when you want a stable identifier that is derived from a specific domain value (e.g., document ID). The same `trace_seed` will produce the same trace ID, making it easier to correlate multiple events.
+
+```ruby
+document_id = "document-123"
+client = NitroIntelligence::Client.new(observability_project_slug: "fake-feature-project")
+client.chat(
+  message: "summarize the document",
+  parameters: {
+    trace_seed: document_id,
+  }
+)
+```
+
+### Scoring
+
+You can use `NitroIntelligence::Reporter` to evaluate existing traces. Calling `NitroIntelligence::Reporter#score` lets you attach metrics to a trace in the observability platform.
+
+#### By Trace ID
+
+```ruby
+reporter = NitroIntelligence::Reporter.new(observability_project_slug: "fake-feature-project")
+reporter.score(name: "precision", value: 0.5, trace_id: "2377b0b38acf0f11b95504344fad6152")
+```
+
+#### By Trace Seed
+
+Knowing the trace seed, you can use `NitroIntelligence::Trace.create_id` to get the trace ID.
+
+```ruby
+document_id = "document-123"
+reporter = NitroIntelligence::Reporter.new(observability_project_slug: "fake-feature-project")
+trace_id = NitroIntelligence::Trace.create_id(seed: document_id)
+reporter.score(name: "precision", value: 0.5, trace_id:)
+```
+
 ### Prompt Variables and Config
 
 Prompts are often created with "variables". These variables can be supplied and compiled into the prompt. For example:
@@ -245,3 +311,9 @@ client.chat(
   }
 )
 ```
+
+## Agent Server
+
+The Agent Server is Nitro Intelligence's lightweight SDK for working with hosted agent threads, runs, and human review flows. It is mainly used to initialize conversation threads, trigger agent runs, inspect agent tool calls pending human approval, and resume interrupted threads after human reviews.
+
+For the full Agent Server guide, see [AGENT_SERVER.md](AGENT_SERVER.md).

data/lib/nitro_intelligence/agent_server.rb

@@ -1,8 +1,11 @@
+require "nitro_intelligence/tool_call_review_validator"
+
 module NitroIntelligence
   class AgentServer
     class ConfigurationError < StandardError; end
     class ThreadInitializationError < StandardError; end
     class RunError < StandardError; end
+    class ThreadResumptionError < StandardError; end
 
     attr_reader :base_url, :user_id
 
@@ -14,19 +17,61 @@ module NitroIntelligence
       @base_url = base_url
       @api_key = api_key
       @user_id = user_id
+      @tool_call_review_validator = ToolCallReviewValidator.new
     end
 
     def await_run(thread_id:, assistant_id:, messages:, context: {})
       raise RunError, "messages cannot be empty" if messages.blank?
 
-      *initial_state, last_message = messages
-      initial_state = [] if messages.size == 1
-      last_message = messages.first if messages.size == 1
+      initial_state = messages[0..-2]
+      last_message = messages.last
 
       initialize_thread_if_needed(thread_id:, initial_state:)
       trigger_run(thread_id:, assistant_id:, context:, last_message:)
     end
 
+    def tool_calls_pending_review(thread_id:)
+      thread_state = get_thread_state(thread_id:)
+      messages = thread_messages(thread_state)
+      reviewed_tool_call_ids = tool_messages(messages).map { |message| message["tool_call_id"] }
+
+      messages.each_with_index.flat_map do |message, index|
+        next [] unless message["type"] == "ai"
+
+        pending_tool_calls(message, reviewed_tool_call_ids).map do |tool_call|
+          {
+            "previous_message_id" => index.zero? ? nil : messages[index - 1]&.dig("id"),
+            "id" => tool_call["id"],
+            "name" => tool_call["name"],
+            "args" => tool_call["args"] || {},
+          }
+        end
+      end
+    end
+
+    def review_tool_calls(thread_id:, assistant_id:, reviewer_id:, tool_calls:, reviewed_at: DateTime.current.iso8601)
+      resume = { reviewer_id:, reviewed_at:, tool_calls: }.with_indifferent_access
+      thread = get_thread(thread_id:)
+      raise ThreadResumptionError, "Thread #{thread_id} is not in the interrupted state" unless interrupted?(thread)
+
+      thread_state = get_thread_state(thread_id:)
+
+      @tool_call_review_validator.validate!(
+        thread_state:,
+        tool_calls: resume[:tool_calls],
+        pending_tool_calls: tool_calls_pending_review(thread_id:)
+      )
+
+      resume_run(
+        thread_id:,
+        assistant_id:,
+        resume:,
+        context: interrupt_context(thread_state)
+      )
+
+      nil
+    end
+
   private
 
     def initialize_thread_if_needed(thread_id:, initial_state:)
@@ -45,6 +90,22 @@ module NitroIntelligence
       thread_response
     end
 
+    def get_thread_state(thread_id:)
+      state_response = get(path: "/threads/#{thread_id}/state")
+
+      raise ThreadResumptionError, state_response.body if state_response.code != 200
+
+      state_response
+    end
+
+    def get_thread(thread_id:)
+      thread_response = get(path: "/threads/#{thread_id}")
+
+      raise ThreadResumptionError, thread_response.body if thread_response.code != 200
+
+      thread_response
+    end
+
     def trigger_run(thread_id:, assistant_id:, last_message:, context: {})
       run_response = post(
         path: "/threads/#{thread_id}/runs/wait",
@@ -59,18 +120,68 @@ module NitroIntelligence
 
       raise RunError, run_response.body if run_response.code != 200
 
-      run_response["messages"].last["content"]
+      Array(run_response["messages"]).last&.dig("content")
+    end
+
+    def resume_run(thread_id:, assistant_id:, resume:, context:)
+      run_response = post(
+        path: "/threads/#{thread_id}/runs/wait",
+        body: {
+          assistant_id:,
+          command: {
+            resume:,
+          },
+          context:,
+        }
+      )
+
+      raise ThreadResumptionError, run_response.body if run_response.code != 200
+
+      run_response
+    end
+
+    def interrupted?(thread)
+      thread["status"] == "interrupted"
+    end
+
+    def interrupt_context(thread_state)
+      thread_state.dig("interrupts", 0, "value", "context") || {}
+    end
+
+    def thread_messages(thread_state)
+      Array(thread_state.dig("values", "messages"))
+    end
+
+    def tool_messages(messages)
+      messages.select { |message| message["type"] == "tool" }
+    end
+
+    def pending_tool_calls(message, reviewed_tool_call_ids)
+      Array(message["tool_calls"]).reject do |tool_call|
+        reviewed_tool_call_ids.include?(tool_call["id"])
+      end
+    end
+
+    def get(path:)
+      HTTParty.get(
+        "#{base_url}#{path}",
+        headers: request_headers
+      )
     end
 
     def post(path:, body:)
       HTTParty.post(
         "#{base_url}#{path}",
-        headers: {
-          "Content-Type" => "application/json",
-          "Authorization" => "Bearer #{@api_key}",
-        },
+        headers: request_headers,
         body: body.to_json
       )
     end
+
+    def request_headers
+      {
+        "Content-Type" => "application/json",
+        "Authorization" => "Bearer #{@api_key}",
+      }
+    end
   end
 end

data/lib/nitro_intelligence/client/base.rb

@@ -0,0 +1,52 @@
+require "nitro_intelligence/client/handlers/audio_transcription_handler"
+require "nitro_intelligence/client/handlers/chat_handler"
+require "nitro_intelligence/client/handlers/image_handler"
+
+module NitroIntelligence
+  module Client
+    class Base
+      attr_reader :client
+
+      def initialize(client:)
+        @client = client
+      end
+
+      def chat(message: "", parameters: {})
+        chat_handler.create(message:, parameters:)
+      end
+
+      # Input images should be byte strings. Returns NitroIntelligence::ImageGeneration
+      def generate_image(message: "", target_image: nil, reference_images: [], parameters: {})
+        image_handler.create(message:, target_image:, reference_images:, parameters:)
+      end
+
+      # Audio file should be file object with extension in the filename
+      # Use file_extension for now to prevent a library dependency
+      def transcribe_audio(message: +"", audio_file: nil, parameters: {})
+        audio_transcription_handler.create(message:, audio_file:, parameters:)
+      end
+
+    private
+
+      def audio_transcription_handler
+        @audio_transcription_handler ||= Handlers::AudioTranscriptionHandler.new(client: @client)
+      end
+
+      def chat_handler
+        @chat_handler ||= Handlers::ChatHandler.new(client: @client)
+      end
+
+      def image_handler
+        @image_handler ||= Handlers::ImageHandler.new(client: @client)
+      end
+
+      def method_missing(method_name, *, &)
+        @client.send(method_name, *, &)
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        @client.respond_to?(method_name, include_private) || super
+      end
+    end
+  end
+end

data/lib/nitro_intelligence/client/client.rb

@@ -0,0 +1,13 @@
+require "nitro_intelligence/client/factory"
+
+module NitroIntelligence
+  module Client
+    def self.new(observability_project_slug: nil)
+      Factory.new(observability_project_slug:).build
+    end
+
+    def self.validate_model(model)
+      raise ArgumentError, "Unsupported model: '#{model}'" unless NitroIntelligence.model_catalog.exists?(model)
+    end
+  end
+end

data/lib/nitro_intelligence/client/factory.rb

@@ -0,0 +1,53 @@
+require "nitro_intelligence/client/base"
+require "nitro_intelligence/client/observed"
+require "nitro_intelligence/client/observers/langfuse_observer"
+require "nitro_intelligence/observability/project"
+
+module NitroIntelligence
+  module Client
+    class Factory
+      def initialize(observability_project_slug:)
+        @observability_project_slug = observability_project_slug
+      end
+
+      def build
+        if @observability_project_slug.present?
+          begin
+            return Client::Observed.new(
+              client: inference_client,
+              observer: Client::Observers::LangfuseObserver.new(project_client: fetch_project_client)
+            )
+          rescue NitroIntelligence::Observability::ProjectClient::NotFoundError,
+                 NitroIntelligence::Observability::Project::NotFoundError => e
+            NitroIntelligence.logger.warn(
+              "#{self.class} #{e} - Error raised initializing project - Falling back to base client (no observability)"
+            )
+          end
+        end
+
+        Client::Base.new(
+          client: inference_client
+        )
+      end
+
+    private
+
+      def fetch_project_client
+        project_client = NitroIntelligence.project_client_registry.fetch(@observability_project_slug)
+        if project_client.nil?
+          raise NitroIntelligence::Observability::ProjectClient::NotFoundError,
+                "No project session found for slug: #{@observability_project_slug}"
+        end
+
+        project_client
+      end
+
+      def inference_client
+        @inference_client ||= OpenAI::Client.new(
+          api_key: NitroIntelligence.config.inference_api_key,
+          base_url: NitroIntelligence.config.inference_base_url
+        )
+      end
+    end
+  end
+end

data/lib/nitro_intelligence/client/handlers/audio_transcription_handler.rb

@@ -0,0 +1,38 @@
+require "openai"
+
+module NitroIntelligence
+  module Client
+    module Handlers
+      class AudioTranscriptionHandler
+        ALLOWED_EXTRA_PARAMETERS = OpenAI::Models::Audio::TranscriptionCreateParams.fields.keys.uniq.freeze
+
+        def initialize(client:)
+          @client = client
+        end
+
+        def create(audio_file:, message: "", parameters: {})
+          validate_and_resolve!(parameters)
+          perform_request(audio_file:, message:, parameters:)
+        end
+
+        def perform_request(audio_file:, message: "", parameters: {})
+          @client.audio.transcriptions.create(
+            prompt: message,
+            file: audio_file,
+            **parameters.slice(*ALLOWED_EXTRA_PARAMETERS)
+          )
+        end
+
+        def validate_and_resolve!(parameters)
+          default_parameters = {
+            metadata: {},
+            model: NitroIntelligence.model_catalog.default_audio_transcription_model&.name,
+          }
+
+          parameters.replace(default_parameters.merge(parameters))
+          Client.validate_model(parameters[:model])
+        end
+      end
+    end
+  end
+end

data/lib/nitro_intelligence/client/handlers/chat_handler.rb

@@ -0,0 +1,41 @@
+require "openai"
+
+module NitroIntelligence
+  module Client
+    module Handlers
+      class ChatHandler
+        ALLOWED_EXTRA_PARAMETERS = OpenAI::Models::Chat::CompletionCreateParams.fields.keys.uniq.freeze
+
+        def initialize(client:)
+          @client = client
+        end
+
+        def create(message: "", parameters: {})
+          validate_and_resolve!(parameters, message)
+          perform_request(parameters:)
+        end
+
+        def perform_request(parameters: {})
+          @client.chat.completions.create(**parameters.slice(*ALLOWED_EXTRA_PARAMETERS))
+        end
+
+        def validate_and_resolve!(parameters, message)
+          if parameters[:messages].blank? && message.present?
+            parameters[:messages] ||= [{ role: "user",
+                                         content: message }]
+          end
+
+          default_parameters = {
+            metadata: {},
+            messages: [],
+            model: NitroIntelligence.model_catalog.default_text_model&.name,
+            extra_headers: { "Prefer" => "wait" },
+          }
+
+          parameters.replace(default_parameters.merge(parameters))
+          Client.validate_model(parameters[:model])
+        end
+      end
+    end
+  end
+end

data/lib/nitro_intelligence/client/handlers/image_handler.rb

@@ -0,0 +1,61 @@
+require "openai"
+require "nitro_intelligence/media/image_generation"
+
+module NitroIntelligence
+  module Client
+    module Handlers
+      class ImageHandler
+        ALLOWED_EXTRA_PARAMETERS = OpenAI::Models::Chat::CompletionCreateParams.fields.keys.uniq.freeze
+
+        def initialize(client:)
+          @client = client
+        end
+
+        def create(message: "", target_image: nil, reference_images: [], parameters: {})
+          image_generation = build_image_generation(message:, target_image:, reference_images:, parameters:)
+
+          validate_and_resolve!(parameters, image_generation)
+
+          chat_completion = perform_request(parameters:)
+
+          image_generation.parse_file(chat_completion)
+          image_generation
+        end
+
+        def perform_request(parameters: {})
+          @client.chat.completions.create(**parameters.slice(*ALLOWED_EXTRA_PARAMETERS))
+        end
+
+        def validate_and_resolve!(parameters, image_generation)
+          default_parameters = {
+            image_generation:,
+            metadata: {},
+            messages: image_generation.messages,
+            model: image_generation.config.model,
+            extra_headers: { "Prefer" => "wait" },
+            request_options: {
+              extra_body: {
+                image_config: {
+                  aspect_ratio: image_generation.config.aspect_ratio,
+                  image_size: image_generation.config.resolution,
+                },
+              },
+            },
+          }
+          parameters.replace(default_parameters.merge(parameters))
+          Client.validate_model(parameters[:model])
+        end
+
+      private
+
+        def build_image_generation(message:, target_image:, reference_images:, parameters:)
+          NitroIntelligence::ImageGeneration.new(message:, target_image:, reference_images:) do |config|
+            config.aspect_ratio = parameters[:aspect_ratio] if parameters.key?(:aspect_ratio)
+            config.model = parameters[:model] if parameters.key?(:model)
+            config.resolution = parameters[:resolution] if parameters.key?(:resolution)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nitro_intelligence/client/handlers/observed/audio_transcription_handler.rb

@@ -0,0 +1,90 @@
+require "base64"
+require "nitro_intelligence/media/audio"
+
+module NitroIntelligence
+  module Client
+    module Handlers
+      module Observed
+        class AudioTranscriptionHandler
+          class ObservedAudioTranscriptionPromptError < StandardError; end
+
+          def initialize(base_handler:, observer:)
+            @base_handler = base_handler
+            @observer = observer
+          end
+
+          def create(audio_file:, message: +"", parameters: {})
+            @base_handler.validate_and_resolve!(parameters)
+
+            # Modifies message in place
+            prompt = handle_prompt(message:, parameters:)
+            trace_name = parameters[:trace_name] || prompt&.name || @observer.project_client.project.slug
+
+            @observer.observe(
+              "audio-transcription",
+              type: :generation,
+              parameters:,
+              trace_name:,
+              prompt:
+            ) do |generation|
+              workflow(generation:, message:, audio_file:, parameters:)
+            end
+          end
+
+        private
+
+          def handle_prompt(message:, parameters:)
+            return nil if parameters[:prompt_name].blank?
+
+            prompt = @observer.project_client.project.prompt_store.get_prompt(
+              prompt_name: parameters[:prompt_name],
+              prompt_label: parameters[:prompt_label],
+              prompt_version: parameters[:prompt_version]
+            )
+            prompt_variables = parameters[:prompt_variables] || {}
+
+            if prompt.present?
+              # Prompts for audio transcriptions should only be text
+              if prompt.type != "text"
+                raise ObservedAudioTranscriptionPromptError,
+                      "Prompt type for audio transcription must be text: #{prompt.name}"
+              end
+              interpolated_prompt = prompt.compile(**prompt_variables)
+
+              message.prepend("#{interpolated_prompt} ").strip!
+              parameters.merge!(prompt.config) unless parameters[:prompt_config_disabled]
+            end
+
+            prompt
+          end
+
+          def workflow(generation:, message:, audio_file:, parameters:)
+            audio_transcription = @base_handler.perform_request(audio_file:, message:, parameters:)
+
+            audio_file.rewind
+            upload_handler = NitroIntelligence::Observability::UploadHandler.new(
+              auth_token: @observer.project_client.project.auth_token
+            )
+            upload_handler.upload(
+              generation.trace_id,
+              upload_queue: Queue.new([NitroIntelligence::Audio.new(audio_file)])
+            )
+
+            trace_attributes = {
+              model: parameters[:model], # Model isn't in response object OpenAI::Models::Audio::Transcription
+              input: message,
+              output: audio_transcription.text,
+              usage_details: {
+                input_tokens: audio_transcription.usage.input_tokens,
+                output_tokens: audio_transcription.usage.output_tokens,
+                total_tokens: audio_transcription.usage.total_tokens,
+              },
+            }
+
+            [audio_transcription, trace_attributes]
+          end
+        end
+      end
+    end
+  end
+end