Class: Raif::Task
- Inherits:
-
ApplicationRecord
- Object
- ApplicationRecord
- Raif::Task
- Includes:
- Concerns::HasAvailableModelTools, Concerns::HasLlm, Concerns::HasPromptTemplates, Concerns::HasRequestedLanguage, Concerns::HasRuntimeDuration, Concerns::InvokesModelTools, Concerns::JsonSchemaDefinition, Concerns::LlmDataRetention, Concerns::LlmOutputLimits, Concerns::LlmPromptCaching, Concerns::LlmResponseParsing, Concerns::LlmTemperature, Concerns::RunWith
- Defined in:
- app/models/raif/task.rb
Direct Known Subclasses
Constant Summary
Constants included from Concerns::LlmResponseParsing
Concerns::LlmResponseParsing::ASCII_CONTROL_CHARS
Instance Attribute Summary collapse
-
#files ⇒ Object
Returns the value of attribute files.
-
#images ⇒ Object
Returns the value of attribute images.
Class Method Summary collapse
-
.build_for_batch(batch:, batch_custom_id: nil, creator: nil, available_model_tools: [], llm_model_key: nil, images: [], files: [], **args) ⇒ Raif::Task
Builds a Raif::Task and a pending Raif::ModelCompletion attached to the given Raif::ModelCompletionBatch, without performing the LLM request.
-
.find_sti_class(type_name) ⇒ Object
A task's subclass lives in the host application and can be deleted while its rows remain.
- .json_response_schema(&block) ⇒ Object
-
.prompt(creator: nil, **args) ⇒ String
Returns the LLM prompt for the task.
-
.run(creator: nil, available_model_tools: [], llm_model_key: nil, images: [], files: [], **args, &block) ⇒ Raif::Task?
The primary interface for running a task.
-
.system_prompt(creator: nil, **args) ⇒ String
Returns the LLM system prompt for the task.
Instance Method Summary collapse
- #build_prompt ⇒ Object
- #build_system_prompt ⇒ Object
-
#fail_without_validation! ⇒ Object
Marks a persisted task failed even when it is invalid, so a task that raised mid-run (including on a failed validation) still reaches a terminal state.
-
#json_response_schema ⇒ Object
Instance method to get the JSON response schema For instance-dependent schemas, builds the schema with this instance as context For class-level schemas, returns the class-level schema.
- #messages ⇒ Object
-
#prepare_for_batch!(batch:, batch_custom_id: nil, skip_prompt_population: false) ⇒ Raif::ModelCompletion
Populates this task's prompts and creates the pending Raif::ModelCompletion that will be sent through the batch.
-
#process_completion!(model_completion) ⇒ self
Wires a (possibly batch-resolved) Raif::ModelCompletion back into this task: links it as the task's raif_model_completion, mirrors raw_response onto the task, processes any tool calls the model made, and transitions the task to completed (or failed, if the underlying completion failed).
-
#prompt_studio_task_attributes ⇒ Hash
Returns additional attributes to assign when creating tasks in Prompt Studio (reruns, batch runs, and judge tasks).
- #re_run(&block) ⇒ Object
-
#refresh_pending_model_completion!(model_completion) ⇒ Raif::ModelCompletion
Rewrites a pending batch completion built by #prepare_for_batch! from this task's current messages, system prompt, and tools, keeping its batch and custom_id.
- #run(skip_prompt_population: false, &block) ⇒ Object
- #status ⇒ Object
Methods included from Concerns::RunWith
deserialize_run_with_value, gid_string?, locate_gid, serialize_run_with_value
Methods included from Concerns::JsonSchemaDefinition
Methods included from Concerns::LlmResponseParsing
#parse_html_response, #parse_json_response, #parsed_response
Methods included from Concerns::HasRuntimeDuration
#runtime_duration, #runtime_duration_seconds, #runtime_ended_at
Methods included from Concerns::HasAvailableModelTools
Methods included from Concerns::HasRequestedLanguage
#requested_language_name, #system_prompt_language_preference
Methods included from Concerns::HasLlm
Instance Attribute Details
#files ⇒ Object
Returns the value of attribute files.
78 79 80 |
# File 'app/models/raif/task.rb', line 78 def files @files end |
#images ⇒ Object
Returns the value of attribute images.
78 79 80 |
# File 'app/models/raif/task.rb', line 78 def images @images end |
Class Method Details
.build_for_batch(batch:, batch_custom_id: nil, creator: nil, available_model_tools: [], llm_model_key: nil, images: [], files: [], **args) ⇒ Raif::Task
Builds a Raif::Task and a pending Raif::ModelCompletion attached to the given Raif::ModelCompletionBatch, without performing the LLM request. The provider's batch-submission code reads the pending completion's request fields when constructing its per-entry batch payload.
The task is persisted with started_at: nil (state :pending). The pending ModelCompletion has raif_model_completion_batch_id pointing at the batch and batch_custom_id set to the value used as the provider's custom_id in the batch payload.
240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 |
# File 'app/models/raif/task.rb', line 240 def self.build_for_batch(batch:, batch_custom_id: nil, creator: nil, available_model_tools: [], llm_model_key: nil, images: [], files: [], **args) task = build_task_instance( creator: creator, available_model_tools: available_model_tools, llm_model_key: llm_model_key, images: images, files: files, **args ) task.save! task.prepare_for_batch!(batch: batch, batch_custom_id: batch_custom_id) task end |
.find_sti_class(type_name) ⇒ Object
A task's subclass lives in the host application and can be deleted while its rows remain. Reading such a row must not raise: it is the oldest rows that are most likely to name a class that is gone, and those are exactly the ones Raif::ArchiveTasksJob has to serialize and the admin has to list. The row's own columns are all that either path needs.
88 89 90 91 92 |
# File 'app/models/raif/task.rb', line 88 def self.find_sti_class(type_name) super rescue ActiveRecord::SubclassNotFound Raif::Task end |
.json_response_schema(&block) ⇒ Object
370 371 372 373 374 375 376 |
# File 'app/models/raif/task.rb', line 370 def self.json_response_schema(&block) if block_given? json_schema_definition(:json_response, &block) elsif schema_defined?(:json_response) schema_for(:json_response) end end |
.prompt(creator: nil, **args) ⇒ String
Returns the LLM prompt for the task.
357 358 359 |
# File 'app/models/raif/task.rb', line 357 def self.prompt(creator: nil, **args) new(creator:, **args).build_prompt end |
.run(creator: nil, available_model_tools: [], llm_model_key: nil, images: [], files: [], **args, &block) ⇒ Raif::Task?
The primary interface for running a task. It will hit the LLM with the task's prompt and system prompt and return a Raif::Task object. It will also create a new Raif::ModelCompletion record.
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 |
# File 'app/models/raif/task.rb', line 116 def self.run(creator: nil, available_model_tools: [], llm_model_key: nil, images: [], files: [], **args, &block) task = build_task_instance( creator: creator, available_model_tools: available_model_tools, llm_model_key: llm_model_key, images: images, files: files, started_at: Time.current, **args ) task.save! task.run(&block) task rescue StandardError => e # An authorization veto is intentional, not a model failure - re-raise it # to the caller instead of logging/reporting it as an error. raise if e.is_a?(Raif::Errors::ModelCompletionAuthorizationError) logger.error e. logger.error e.backtrace.join("\n") Rails.error.report(e, handled: true, severity: :error, context: { component: "raif_task", action: name }) task end |
.system_prompt(creator: nil, **args) ⇒ String
Returns the LLM system prompt for the task.
366 367 368 |
# File 'app/models/raif/task.rb', line 366 def self.system_prompt(creator: nil, **args) new(creator:, **args).build_system_prompt end |
Instance Method Details
#build_prompt ⇒ Object
394 395 396 |
# File 'app/models/raif/task.rb', line 394 def build_prompt raise NotImplementedError, "Raif::Task subclasses must implement #build_prompt" end |
#build_system_prompt ⇒ Object
398 399 400 401 402 403 |
# File 'app/models/raif/task.rb', line 398 def build_system_prompt sp = Raif.config.task_system_prompt_intro sp = sp.call(self) if sp.respond_to?(:call) sp += system_prompt_language_preference if requested_language_key.present? sp end |
#fail_without_validation! ⇒ Object
Marks a persisted task failed even when it is invalid, so a task that raised mid-run (including on a failed validation) still reaches a terminal state. Any raw_response already received is persisted along with it.
218 219 220 221 222 223 224 225 |
# File 'app/models/raif/task.rb', line 218 def fail_without_validation! return unless persisted? # A failed update! leaves its unsaved values assigned, so check what was persisted. return if failed_at_in_database.present? restore_attributes([:completed_at]) if will_save_change_to_completed_at? update_columns(failed_at: Time.current, raw_response: raw_response, updated_at: Time.current) end |
#json_response_schema ⇒ Object
Instance method to get the JSON response schema For instance-dependent schemas, builds the schema with this instance as context For class-level schemas, returns the class-level schema
381 382 383 |
# File 'app/models/raif/task.rb', line 381 def json_response_schema schema_for_instance(:json_response) end |
#messages ⇒ Object
348 349 350 |
# File 'app/models/raif/task.rb', line 348 def [{ "role" => "user", "content" => }] end |
#prepare_for_batch!(batch:, batch_custom_id: nil, skip_prompt_population: false) ⇒ Raif::ModelCompletion
Populates this task's prompts and creates the pending Raif::ModelCompletion that will be sent through the batch. Mirrors Raif::Task#run's default behavior: prompts are rebuilt every call unless skip_prompt_population: true is passed (e.g. for re-prepare flows where the caller has hand-set prompts and wants them preserved).
The default batch_custom_id is "raif_task_<task.id>" — a task-specific identifier. Other producers (non-task) should pass an explicit batch_custom_id when building their own pending completions via Raif::Llm#build_pending_model_completion; the only requirement is uniqueness within the batch.
292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 |
# File 'app/models/raif/task.rb', line 292 def prepare_for_batch!(batch:, batch_custom_id: nil, skip_prompt_population: false) populate_prompts unless skip_prompt_population save! if changed? mc = llm.build_pending_model_completion( **batch_model_completion_attributes, anthropic_prompt_caching_enabled: self.class.anthropic_prompt_caching_enabled, bedrock_prompt_caching_enabled: self.class.bedrock_prompt_caching_enabled, raif_model_completion_batch: batch, batch_custom_id: batch_custom_id.presence || "raif_task_#{id}" ) self.raif_model_completion = mc mc end |
#process_completion!(model_completion) ⇒ self
Wires a (possibly batch-resolved) Raif::ModelCompletion back into this task: links it as the task's raif_model_completion, mirrors raw_response onto the task, processes any tool calls the model made, and transitions the task to completed (or failed, if the underlying completion failed). Called by both the synchronous #run path and the batch completion handler after the provider's per-entry result has been applied.
197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 |
# File 'app/models/raif/task.rb', line 197 def process_completion!(model_completion) self.raif_model_completion = model_completion.becomes(Raif::ModelCompletion) update!(raw_response: raif_model_completion.raw_response) fail_truncated_completion! if self.class.fail_on_truncation if raif_model_completion.failed? # Failure detail (failure_error / failure_reason) lives on the model # completion; the task's `failed_at` is just a state marker. update!(failed_at: Time.current) unless failed_at? else process_model_tool_invocations update!(completed_at: Time.current) unless completed_at? end self end |
#prompt_studio_task_attributes ⇒ Hash
Returns additional attributes to assign when creating tasks in Prompt Studio (reruns, batch runs, and judge tasks). Override in your ApplicationTask or task subclass to include app-specific attributes.
390 391 392 |
# File 'app/models/raif/task.rb', line 390 def prompt_studio_task_attributes {} end |
#re_run(&block) ⇒ Object
183 184 185 186 |
# File 'app/models/raif/task.rb', line 183 def re_run(&block) update_columns(started_at: Time.current) run(skip_prompt_population: true, &block) end |
#refresh_pending_model_completion!(model_completion) ⇒ Raif::ModelCompletion
Rewrites a pending batch completion built by #prepare_for_batch! from this task's current messages, system prompt, and tools, keeping its batch and custom_id. Use it when a host changes the task between batching and submission, so the provider receives what the task now holds, formatted the same way #prepare_for_batch! formats it.
The state checks read the locked row, so a copy loaded before another process submitted or failed the batch is refused. They cannot see a submission whose provider request is still in flight, because submit_batch! stamps the batch only after the provider accepts it, so call this before submit_batch! or from an assert_submittable! override. The batch is not checked through assert_submittable! because such an override would then recurse.
325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 |
# File 'app/models/raif/task.rb', line 325 def refresh_pending_model_completion!(model_completion) model_completion.with_lock do batch = model_completion.raif_model_completion_batch&.reload unless model_completion.source == self && model_completion.pending? && batch&.status == "pending" && batch.provider_batch_id.blank? raise ArgumentError, "Raif::ModelCompletion ##{model_completion.id} is not a pending batch completion of #{self.class.name} ##{id}" end unless batch.llm_model_key == llm_model_key raise ArgumentError, "#{self.class.name} ##{id} uses #{llm_model_key}, but Raif::ModelCompletionBatch ##{batch.id} uses #{batch.llm_model_key}" end model_completion.update!( llm.pending_model_completion_attributes( **batch_model_completion_attributes, raif_model_completion_batch: batch, batch_custom_id: model_completion.batch_custom_id ) ) end model_completion end |
#run(skip_prompt_population: false, &block) ⇒ Object
143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 |
# File 'app/models/raif/task.rb', line 143 def run(skip_prompt_population: false, &block) update_columns(started_at: Time.current) if started_at.nil? populate_prompts unless skip_prompt_population # populate_prompts sets validated attributes (e.g. requested_language_key), so # a task that passed validation on create can be invalid now. Raise before the # LLM request rather than paying for a response that can't be saved. validate! streaming_block = if block_given? proc do |model_completion, delta, sse_event| update_columns(raw_response: model_completion.raw_response, updated_at: Time.current) block.call(model_completion, delta, sse_event) end end mc = llm.chat( messages: , source: self, system_prompt: system_prompt, response_format: response_format.to_sym, available_model_tools: available_model_tools, temperature: self.class.temperature, max_completion_tokens: self.class.max_completion_tokens, stop_sequences: self.class.stop_sequences, anthropic_prompt_caching_enabled: self.class.anthropic_prompt_caching_enabled, bedrock_prompt_caching_enabled: self.class.bedrock_prompt_caching_enabled, open_ai_store_responses: self.class.open_ai_store_responses, open_router_data_collection: self.class.open_router_data_collection, open_router_zdr: self.class.open_router_zdr, &streaming_block ) process_completion!(mc) rescue StandardError fail_without_validation! raise end |
#status ⇒ Object
94 95 96 97 98 99 100 101 102 103 104 |
# File 'app/models/raif/task.rb', line 94 def status if completed_at? :completed elsif failed_at? :failed elsif started_at? :in_progress else :pending end end |