cadenya 0.27.0 → 0.29.0

data/lib/cadenya/models.rb

@@ -125,6 +125,8 @@ module Cadenya
 
   CallableTool = Cadenya::Models::CallableTool
 
+  ContextLengths = Cadenya::Models::ContextLengths
+
   ContextWindowCompacted = Cadenya::Models::ContextWindowCompacted
 
   CreateOperationMetadata = Cadenya::Models::CreateOperationMetadata
@@ -183,6 +185,8 @@ module Cadenya
 
   ObjectiveCreateParams = Cadenya::Models::ObjectiveCreateParams
 
+  ObjectiveDiagnostics = Cadenya::Models::ObjectiveDiagnostics
+
   ObjectiveError = Cadenya::Models::ObjectiveError
 
   ObjectiveEvent = Cadenya::Models::ObjectiveEvent
@@ -201,6 +205,8 @@ module Cadenya
 
   ObjectiveListParams = Cadenya::Models::ObjectiveListParams
 
+  ObjectiveRetrieveDiagnosticsParams = Cadenya::Models::ObjectiveRetrieveDiagnosticsParams
+
   ObjectiveRetrieveParams = Cadenya::Models::ObjectiveRetrieveParams
 
   Objectives = Cadenya::Models::Objectives

data/lib/cadenya/resources/objectives.rb

@@ -20,17 +20,19 @@ module Cadenya
       #
       # Creates a new objective in the workspace
       #
-      # @overload create(workspace_id, agent_id:, data:, episodic_memory: nil, initial_message: nil, memory_cascade: nil, metadata: nil, secrets: nil, user_data: nil, variation_id: nil, request_options: {})
+      # @overload create(workspace_id, agent_id:, system_prompt_data:, episodic_memory: nil, first_user_message: nil, first_user_message_data: nil, memory_cascade: nil, metadata: nil, secrets: nil, variation_id: nil, request_options: {})
       #
       # @param workspace_id [String]
       #
       # @param agent_id [String]
       #
-      # @param data [Hash{Symbol=>Object}] Arbitrary data for the objective. May be used in liquid templates for prompts co
+      # @param system_prompt_data [Hash{Symbol=>Object}] Arbitrary data rendered into the selected variation's system_prompt_template
       #
       # @param episodic_memory [Cadenya::Models::ObjectiveCreateParams::EpisodicMemory] Episodic is used to configure the episodic memory for the objective
       #
-      # @param initial_message [String] Optional override for the initial message sent to the agent. This becomes the fi
+      # @param first_user_message [String] Optional explicit first user message for the LLM chat history. When not set,
+      #
+      # @param first_user_message_data [Hash{Symbol=>Object}] Arbitrary data rendered into the selected variation's first_user_message_templat
       #
       # @param memory_cascade [Array<Cadenya::Models::MemoryReference>] Memory layers/entries layered over the baseline cascade inherited
       #
@@ -38,8 +40,6 @@ module Cadenya
       #
       # @param secrets [Array<Cadenya::Models::ObjectiveCreateParams::Secret>] Secrets that can be used in the headers for tool calls using the secret interpol
       #
-      # @param user_data [Hash{Symbol=>Object}] Arbitrary data rendered into the selected variation's user_message_template
-      #
       # @param variation_id [String] Optional explicit variation selection. Overrides the agent's variation_selection
       #
       # @param request_options [Cadenya::RequestOptions, Hash{Symbol=>Object}, nil]
@@ -322,6 +322,36 @@ module Cadenya
         )
       end
 
+      # Returns the context-usage breakdown measured for the objective's most recent
+      # iteration: character lengths per context component (system prompt, memory
+      # appendices, tool definitions, messages by role) alongside the iteration's input
+      # token counts.
+      #
+      # @overload retrieve_diagnostics(objective_id, workspace_id:, request_options: {})
+      #
+      # @param objective_id [String] The ID of the objective. Supports "external_id:" prefix for external IDs.
+      #
+      # @param workspace_id [String]
+      #
+      # @param request_options [Cadenya::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Cadenya::Models::ObjectiveRetrieveDiagnosticsResponse]
+      #
+      # @see Cadenya::Models::ObjectiveRetrieveDiagnosticsParams
+      def retrieve_diagnostics(objective_id, params)
+        parsed, options = Cadenya::ObjectiveRetrieveDiagnosticsParams.dump_request(params)
+        workspace_id =
+          parsed.delete(:workspace_id) do
+            raise ArgumentError.new("missing required path argument #{_1}")
+          end
+        @client.request(
+          method: :get,
+          path: ["v1/workspaces/%1$s/objectives/%2$s/diagnostics", workspace_id, objective_id],
+          model: Cadenya::Models::ObjectiveRetrieveDiagnosticsResponse,
+          options: options
+        )
+      end
+
       # Streams events for an objective in real-time using server-sent events (SSE)
       #
       # @overload stream_events_streaming(objective_id, workspace_id:, request_options: {})

data/lib/cadenya/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cadenya
-  VERSION = "0.27.0"
+  VERSION = "0.29.0"
 end

data/lib/cadenya.rb

@@ -140,6 +140,7 @@ require_relative "cadenya/models/assistant_tool_call"
 require_relative "cadenya/models/attribute_filter"
 require_relative "cadenya/models/bare_metadata"
 require_relative "cadenya/models/callable_tool"
+require_relative "cadenya/models/context_lengths"
 require_relative "cadenya/models/context_window_compacted"
 require_relative "cadenya/models/create_operation_metadata"
 require_relative "cadenya/models/create_resource_metadata"
@@ -181,6 +182,7 @@ require_relative "cadenya/models/objective_context_window"
 require_relative "cadenya/models/objective_context_window_data"
 require_relative "cadenya/models/objective_continue_params"
 require_relative "cadenya/models/objective_create_params"
+require_relative "cadenya/models/objective_diagnostics"
 require_relative "cadenya/models/objective_error"
 require_relative "cadenya/models/objective_event"
 require_relative "cadenya/models/objective_event_data"
@@ -190,6 +192,8 @@ require_relative "cadenya/models/objective_info"
 require_relative "cadenya/models/objective_list_context_windows_params"
 require_relative "cadenya/models/objective_list_events_params"
 require_relative "cadenya/models/objective_list_params"
+require_relative "cadenya/models/objective_retrieve_diagnostics_params"
+require_relative "cadenya/models/objective_retrieve_diagnostics_response"
 require_relative "cadenya/models/objective_retrieve_params"
 require_relative "cadenya/models/objectives/feedback_create_params"
 require_relative "cadenya/models/objectives/feedback_list_params"

data/rbi/cadenya/models/agent_spec.rbi

@@ -38,17 +38,6 @@ module Cadenya
       sig { params(episodic_memory_ttl: Integer).void }
       attr_writer :episodic_memory_ttl
 
-      # InputDataSchema is used for enforcing a data input when objectives are created.
-      # This is valuable when using liquid formatting in agent variation prompts. Input
-      # data schema is also valuable when using an agent as a sub-agent, as the schema
-      # is used as the tool's input parameter schema. If omitted, the sub-agent schema
-      # will be loaded with a simple "prompt" free text string as its schema.
-      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
-      attr_reader :input_data_schema
-
-      sig { params(input_data_schema: T::Hash[Symbol, T.anything]).void }
-      attr_writer :input_data_schema
-
       # Optional output definition for objectives created for this agent. When provided,
       # Cadenya will append a tool to that will be called by the LLM in use by the
       # variant to extract information in the format provided here. Use this option when
@@ -59,6 +48,20 @@ module Cadenya
       sig { params(output_definition: T::Hash[Symbol, T.anything]).void }
       attr_writer :output_definition
 
+      # SystemPromptDataSchema enforces the shape of system_prompt_data when objectives
+      # are created. This is valuable when using liquid formatting in agent variation
+      # system prompt templates. The schema is also used when the agent is attached as a
+      # sub-agent, as it becomes the tool's input parameter schema. If omitted, the
+      # sub-agent schema will be loaded with a simple "prompt" free text string as its
+      # schema.
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_reader :system_prompt_data_schema
+
+      sig do
+        params(system_prompt_data_schema: T::Hash[Symbol, T.anything]).void
+      end
+      attr_writer :system_prompt_data_schema
+
       # The URL that Cadenya will send events for any objective assigned to the agent.
       sig { returns(T.nilable(String)) }
       attr_reader :webhook_events_url
@@ -74,8 +77,8 @@ module Cadenya
           description: String,
           enable_episodic_memory: T::Boolean,
           episodic_memory_ttl: Integer,
-          input_data_schema: T::Hash[Symbol, T.anything],
           output_definition: T::Hash[Symbol, T.anything],
+          system_prompt_data_schema: T::Hash[Symbol, T.anything],
           webhook_events_url: String
         ).returns(T.attached_class)
       end
@@ -95,17 +98,18 @@ module Cadenya
         # layer's expiry forward by this duration, and stored entries expire this long
         # after they are written. If not set, episodic memories are retained indefinitely.
         episodic_memory_ttl: nil,
-        # InputDataSchema is used for enforcing a data input when objectives are created.
-        # This is valuable when using liquid formatting in agent variation prompts. Input
-        # data schema is also valuable when using an agent as a sub-agent, as the schema
-        # is used as the tool's input parameter schema. If omitted, the sub-agent schema
-        # will be loaded with a simple "prompt" free text string as its schema.
-        input_data_schema: nil,
         # Optional output definition for objectives created for this agent. When provided,
         # Cadenya will append a tool to that will be called by the LLM in use by the
         # variant to extract information in the format provided here. Use this option when
         # you want structured data to be created by your objectives.
         output_definition: nil,
+        # SystemPromptDataSchema enforces the shape of system_prompt_data when objectives
+        # are created. This is valuable when using liquid formatting in agent variation
+        # system prompt templates. The schema is also used when the agent is attached as a
+        # sub-agent, as it becomes the tool's input parameter schema. If omitted, the
+        # sub-agent schema will be loaded with a simple "prompt" free text string as its
+        # schema.
+        system_prompt_data_schema: nil,
         # The URL that Cadenya will send events for any objective assigned to the agent.
         webhook_events_url: nil
       )
@@ -119,8 +123,8 @@ module Cadenya
             description: String,
             enable_episodic_memory: T::Boolean,
             episodic_memory_ttl: Integer,
-            input_data_schema: T::Hash[Symbol, T.anything],
             output_definition: T::Hash[Symbol, T.anything],
+            system_prompt_data_schema: T::Hash[Symbol, T.anything],
             webhook_events_url: String
           }
         )

data/rbi/cadenya/models/agents/agent_schedule_spec.rbi

@@ -27,22 +27,23 @@ module Cadenya
         end
         attr_writer :schedule
 
-        # Optional input data passed to the objective. If the agent has an
-        # input_data_schema, this must satisfy it.
-        sig { returns(T.nilable(T.anything)) }
-        attr_reader :data
+        # Optional explicit first user message passed to CreateObjective on each fire.
+        # Becomes the first user message in the objective's chat history. When unset, the
+        # fired objective defers to the selected variation's first_user_message_template.
+        sig { returns(T.nilable(String)) }
+        attr_reader :first_user_message
 
-        sig { params(data: T.anything).void }
-        attr_writer :data
+        sig { params(first_user_message: String).void }
+        attr_writer :first_user_message
 
-        # Optional initial message passed to CreateObjective on each fire. Becomes the
-        # first user message in the objective's chat history. When unset, the fired
-        # objective defers to the selected variation's user_message_template.
-        sig { returns(T.nilable(String)) }
-        attr_reader :initial_message
+        # Optional data rendered into the variation's first_user_message_template when
+        # each fired objective is created. Separate from `system_prompt_data`, which
+        # renders the system prompt template.
+        sig { returns(T.nilable(T.anything)) }
+        attr_reader :first_user_message_data
 
-        sig { params(initial_message: String).void }
-        attr_writer :initial_message
+        sig { params(first_user_message_data: T.anything).void }
+        attr_writer :first_user_message_data
 
         # What to do when the previous run is still in flight. Defaults to SKIP.
         sig do
@@ -62,14 +63,14 @@ module Cadenya
         end
         attr_writer :overlap_policy
 
-        # Optional data rendered into the variation's user_message_template when each
-        # fired objective is created. Separate from `data`, which renders the system
-        # prompt template.
+        # Optional data rendered into the variation's system_prompt_template when each
+        # fired objective is created. If the agent has a system_prompt_data_schema, this
+        # must satisfy it.
         sig { returns(T.nilable(T.anything)) }
-        attr_reader :user_data
+        attr_reader :system_prompt_data
 
-        sig { params(user_data: T.anything).void }
-        attr_writer :user_data
+        sig { params(system_prompt_data: T.anything).void }
+        attr_writer :system_prompt_data
 
         # Optional explicit variation. When unset, the agent's variation_selection_mode
         # chooses per fire.
@@ -83,11 +84,11 @@ module Cadenya
         sig do
           params(
             schedule: Cadenya::Agents::AgentScheduleSpecSchedule::OrHash,
-            data: T.anything,
-            initial_message: String,
+            first_user_message: String,
+            first_user_message_data: T.anything,
             overlap_policy:
               Cadenya::Agents::AgentScheduleSpec::OverlapPolicy::OrSymbol,
-            user_data: T.anything,
+            system_prompt_data: T.anything,
             variation_id: String
           ).returns(T.attached_class)
         end
@@ -96,19 +97,20 @@ module Cadenya
           # of calendar rules (wall-clock) and/or interval rules (duration), OR'd together.
           # At least one rule is required.
           schedule:,
-          # Optional input data passed to the objective. If the agent has an
-          # input_data_schema, this must satisfy it.
-          data: nil,
-          # Optional initial message passed to CreateObjective on each fire. Becomes the
-          # first user message in the objective's chat history. When unset, the fired
-          # objective defers to the selected variation's user_message_template.
-          initial_message: nil,
+          # Optional explicit first user message passed to CreateObjective on each fire.
+          # Becomes the first user message in the objective's chat history. When unset, the
+          # fired objective defers to the selected variation's first_user_message_template.
+          first_user_message: nil,
+          # Optional data rendered into the variation's first_user_message_template when
+          # each fired objective is created. Separate from `system_prompt_data`, which
+          # renders the system prompt template.
+          first_user_message_data: nil,
           # What to do when the previous run is still in flight. Defaults to SKIP.
           overlap_policy: nil,
-          # Optional data rendered into the variation's user_message_template when each
-          # fired objective is created. Separate from `data`, which renders the system
-          # prompt template.
-          user_data: nil,
+          # Optional data rendered into the variation's system_prompt_template when each
+          # fired objective is created. If the agent has a system_prompt_data_schema, this
+          # must satisfy it.
+          system_prompt_data: nil,
           # Optional explicit variation. When unset, the agent's variation_selection_mode
           # chooses per fire.
           variation_id: nil
@@ -119,11 +121,11 @@ module Cadenya
           override.returns(
             {
               schedule: Cadenya::Agents::AgentScheduleSpecSchedule,
-              data: T.anything,
-              initial_message: String,
+              first_user_message: String,
+              first_user_message_data: T.anything,
               overlap_policy:
                 Cadenya::Agents::AgentScheduleSpec::OverlapPolicy::OrSymbol,
-              user_data: T.anything,
+              system_prompt_data: T.anything,
               variation_id: String
             }
           )

data/rbi/cadenya/models/agents/agent_variation_spec.rbi

@@ -51,6 +51,18 @@ module Cadenya
         sig { params(description: String).void }
         attr_writer :description
 
+        # Liquid template for the first user message of objectives using this variation.
+        # Rendered with CreateObjectiveRequest.first_user_message_data into
+        # Objective.first_user_message, the first user message in the LLM chat history.
+        # CreateObjectiveRequest.first_user_message, when set, overrides the rendered
+        # result. If neither this template nor first_user_message is present, objective
+        # creation is rejected with InvalidArgument.
+        sig { returns(T.nilable(String)) }
+        attr_reader :first_user_message_template
+
+        sig { params(first_user_message_template: String).void }
+        attr_writer :first_user_message_template
+
         # ModelConfig defines the model configuration for a variation
         sig do
           returns(T.nilable(Cadenya::Agents::AgentVariationSpecModelConfig))
@@ -85,24 +97,14 @@ module Cadenya
         attr_writer :progressive_discovery
 
         # Liquid template for the system prompt of objectives using this variation.
-        # Rendered with CreateObjectiveRequest.data into Objective.system_prompt.
+        # Rendered with CreateObjectiveRequest.system_prompt_data into
+        # Objective.system_prompt.
         sig { returns(T.nilable(String)) }
         attr_reader :system_prompt_template
 
         sig { params(system_prompt_template: String).void }
         attr_writer :system_prompt_template
 
-        # Liquid template for the initial user message of objectives using this variation.
-        # Rendered with CreateObjectiveRequest.user_data and becomes the first user
-        # message in the LLM chat history. CreateObjectiveRequest.initial_message, when
-        # set, overrides the rendered result. If neither this template nor initial_message
-        # is present, objective creation is rejected with InvalidArgument.
-        sig { returns(T.nilable(String)) }
-        attr_reader :user_message_template
-
-        sig { params(user_message_template: String).void }
-        attr_writer :user_message_template
-
         # Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
         # Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0
         # means never auto-selected, but can still be chosen explicitly via variation_id
@@ -120,12 +122,12 @@ module Cadenya
               Cadenya::Agents::AgentVariationSpecCompactionConfig::OrHash,
             constraints: Cadenya::Agents::AgentVariationSpecConstraints::OrHash,
             description: String,
+            first_user_message_template: String,
             model_config:
               Cadenya::Agents::AgentVariationSpecModelConfig::OrHash,
             progressive_discovery:
               Cadenya::Agents::AgentVariationSpecProgressiveDiscovery::OrHash,
             system_prompt_template: String,
-            user_message_template: String,
             weight: Integer
           ).returns(T.attached_class)
         end
@@ -137,6 +139,13 @@ module Cadenya
           constraints: nil,
           # Human-readable description of what this variation does or when it should be used
           description: nil,
+          # Liquid template for the first user message of objectives using this variation.
+          # Rendered with CreateObjectiveRequest.first_user_message_data into
+          # Objective.first_user_message, the first user message in the LLM chat history.
+          # CreateObjectiveRequest.first_user_message, when set, overrides the rendered
+          # result. If neither this template nor first_user_message is present, objective
+          # creation is rejected with InvalidArgument.
+          first_user_message_template: nil,
           # ModelConfig defines the model configuration for a variation
           model_config: nil,
           # ProgressiveDiscovery is used to indicate that the agent should automatically
@@ -146,14 +155,9 @@ module Cadenya
           # and can help select the best tools for the task.
           progressive_discovery: nil,
           # Liquid template for the system prompt of objectives using this variation.
-          # Rendered with CreateObjectiveRequest.data into Objective.system_prompt.
+          # Rendered with CreateObjectiveRequest.system_prompt_data into
+          # Objective.system_prompt.
           system_prompt_template: nil,
-          # Liquid template for the initial user message of objectives using this variation.
-          # Rendered with CreateObjectiveRequest.user_data and becomes the first user
-          # message in the LLM chat history. CreateObjectiveRequest.initial_message, when
-          # set, overrides the rendered result. If neither this template nor initial_message
-          # is present, objective creation is rejected with InvalidArgument.
-          user_message_template: nil,
           # Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
           # Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0
           # means never auto-selected, but can still be chosen explicitly via variation_id
@@ -169,11 +173,11 @@ module Cadenya
                 Cadenya::Agents::AgentVariationSpecCompactionConfig,
               constraints: Cadenya::Agents::AgentVariationSpecConstraints,
               description: String,
+              first_user_message_template: String,
               model_config: Cadenya::Agents::AgentVariationSpecModelConfig,
               progressive_discovery:
                 Cadenya::Agents::AgentVariationSpecProgressiveDiscovery,
               system_prompt_template: String,
-              user_message_template: String,
               weight: Integer
             }
           )

data/rbi/cadenya/models/context_lengths.rbi

@@ -0,0 +1,103 @@
+# typed: strong
+
+module Cadenya
+  module Models
+    class ContextLengths < Cadenya::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Cadenya::ContextLengths, Cadenya::Internal::AnyHash)
+        end
+
+      # Chat history messages with the assistant role.
+      sig { returns(Integer) }
+      attr_accessor :assistant_messages
+
+      # The discoverable/available-tools appendix attached to the system prompt.
+      sig { returns(Integer) }
+      attr_accessor :available_tools
+
+      # The episodic memory appendix attached to the system prompt.
+      sig { returns(Integer) }
+      attr_accessor :episodic_memory
+
+      # The skills memory appendix attached to the system prompt.
+      sig { returns(Integer) }
+      attr_accessor :skills_memory
+
+      # The objective's base system prompt (rendered variation template).
+      sig { returns(Integer) }
+      attr_accessor :system_prompt
+
+      # Serialized tool definitions sent with the completion request (names,
+      # descriptions, and JSON-schema parameters).
+      sig { returns(Integer) }
+      attr_accessor :tool_definitions
+
+      # Tool results present in the chat history.
+      sig { returns(Integer) }
+      attr_accessor :tool_results
+
+      # Chat history messages with the user role.
+      sig { returns(Integer) }
+      attr_accessor :user_messages
+
+      # ContextLengths is the measured character length of each distinct component of an
+      # iteration's assembled context window. Values are raw character lengths of the
+      # component as assembled into the request — token estimates are derived by the
+      # client against input_tokens (component share = component length / sum of all
+      # lengths).
+      #
+      # New components are added as new fields — wire-compatible; absent components read
+      # as 0.
+      sig do
+        params(
+          assistant_messages: Integer,
+          available_tools: Integer,
+          episodic_memory: Integer,
+          skills_memory: Integer,
+          system_prompt: Integer,
+          tool_definitions: Integer,
+          tool_results: Integer,
+          user_messages: Integer
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # Chat history messages with the assistant role.
+        assistant_messages:,
+        # The discoverable/available-tools appendix attached to the system prompt.
+        available_tools:,
+        # The episodic memory appendix attached to the system prompt.
+        episodic_memory:,
+        # The skills memory appendix attached to the system prompt.
+        skills_memory:,
+        # The objective's base system prompt (rendered variation template).
+        system_prompt:,
+        # Serialized tool definitions sent with the completion request (names,
+        # descriptions, and JSON-schema parameters).
+        tool_definitions:,
+        # Tool results present in the chat history.
+        tool_results:,
+        # Chat history messages with the user role.
+        user_messages:
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            assistant_messages: Integer,
+            available_tools: Integer,
+            episodic_memory: Integer,
+            skills_memory: Integer,
+            system_prompt: Integer,
+            tool_definitions: Integer,
+            tool_results: Integer,
+            user_messages: Integer
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end