hatchet-sdk 0.6.0 → 0.7.0

data/lib/hatchet/durable_context.rb

@@ -5,14 +5,12 @@ require "securerandom"
 
 module Hatchet
   # Extended context for durable tasks that supports sleep and event-waiting
-  # across task suspensions.
+  # across task suspensions. All methods and attributes of {Context} are also
+  # available.
   #
   # Durable tasks can be suspended and resumed by the Hatchet engine,
   # allowing long-running workflows that survive process restarts.
   #
-  # Uses V1::V1Dispatcher for registering and listening for durable events
-  # via bidirectional gRPC streaming.
-  #
   # @example Sleep for a duration
   #   hatchet.durable_task(name: "my_task") do |input, ctx|
   #     ctx.sleep_for(duration: 60) # sleep for 60 seconds
@@ -42,10 +40,8 @@ module Hatchet
     attr_accessor :engine_version
 
     # Sleep for a specified duration. The task is suspended and resumed
-    # by the engine after the duration expires.
-    #
-    # Delegates to {#wait_for} with a {Hatchet::SleepCondition} so that both
-    # sleeps and event waits share a single registration / eviction path.
+    # by the engine after the duration expires, so no worker slot is blocked
+    # while sleeping (subject to the task's eviction policy).
     #
     # @param duration [Integer, String] Duration in seconds, or a duration string (e.g. "60s")
     # @param label [String, nil] Optional wait label shown in durable event logs.
@@ -62,11 +58,8 @@ module Hatchet
     # Wait for a condition to be met (event or sleep).
     # The task is suspended and resumed when the condition is satisfied.
     #
-    # Register the durable wait with ``send_event`` first, then start eviction
-    # tracking only while blocked on ``wait_for_callback``.
-    #
     # @param key [String] A unique key for this wait operation
-    # @param condition [Object] The condition to wait for (UserEventCondition, SleepCondition, Hash, etc.)
+    # @param condition [UserEventCondition, SleepCondition, OrCondition] The condition to wait for
     # @param label [String, nil] Optional wait label shown in durable event logs.
     # @return [Hash] Result from the wait, including which condition was satisfied
     def wait_for(key, condition, label: nil)

data/lib/hatchet/features/cel.rb

@@ -23,7 +23,7 @@ module Hatchet
     # CEL (Common Expression Language) expressions used in filters and conditions.
     #
     # @example Debugging a CEL expression
-    #   result = cel_client.debug(
+    #   result = hatchet.cel.debug(
     #     expression: 'input.value > 10',
     #     input: { value: 15 }
     #   )
@@ -59,7 +59,7 @@ module Hatchet
       # @raise [RuntimeError] If no response is received from the CEL debug API
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   result = cel_client.debug(
+      #   result = hatchet.cel.debug(
       #     expression: 'input.count > 5 && metadata.env == "prod"',
       #     input: { count: 10 },
       #     additional_metadata: { env: 'prod' }

data/lib/hatchet/features/cron.rb

@@ -8,7 +8,7 @@ module Hatchet
     # listing, and retrieving cron workflow triggers.
     #
     # @example Creating a cron trigger
-    #   cron = cron_client.create(
+    #   cron = hatchet.cron.create(
     #     workflow_name: "my-workflow",
     #     cron_name: "daily-run",
     #     expression: "0 0 * * *",
@@ -45,7 +45,7 @@ module Hatchet
       # @raise [ArgumentError] If the cron expression is invalid
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   cron = cron_client.create(
+      #   cron = hatchet.cron.create(
       #     workflow_name: "my-workflow",
       #     cron_name: "hourly-run",
       #     expression: "0 * * * *",
@@ -76,7 +76,7 @@ module Hatchet
       # @return [void]
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   cron_client.delete("cron-123")
+      #   hatchet.cron.delete("cron-123")
       def delete(cron_id)
         @workflow_api.workflow_cron_delete(@config.tenant_id, cron_id.to_s)
       end
@@ -94,7 +94,7 @@ module Hatchet
       # @return [Object] A list of cron workflows
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   crons = cron_client.list(limit: 10, workflow_name: "my-workflow")
+      #   crons = hatchet.cron.list(limit: 10, workflow_name: "my-workflow")
       def list(offset: nil, limit: nil, workflow_id: nil, additional_metadata: nil,
                order_by_field: nil, order_by_direction: nil, workflow_name: nil, cron_name: nil)
         @workflow_api.cron_workflow_list(
@@ -118,7 +118,7 @@ module Hatchet
       # @return [Object] The requested cron workflow instance
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   cron = cron_client.get("cron-123")
+      #   cron = hatchet.cron.get("cron-123")
       def get(cron_id)
         @workflow_api.workflow_cron_get(@config.tenant_id, cron_id.to_s)
       end

data/lib/hatchet/features/events.rb

@@ -11,9 +11,9 @@ module Hatchet
     # the REST API for read operations (list, get, etc.).
     #
     # @example Creating an event
-    #   response = events.push(
-    #     key: "user-login",
-    #     data: { user_id: 123, action: "login" },
+    #   response = hatchet.events.push(
+    #     "user-login",
+    #     { user_id: 123, action: "login" },
     #     additional_metadata: { ip_address: "192.168.1.1" }
     #   )
     #
@@ -53,7 +53,7 @@ module Hatchet
       # @raise [ArgumentError] If required parameters are missing
       # @raise [Hatchet::Error] If the API request fails or returns an error
       # @example Creating a simple event
-      #   response = events.create(
+      #   response = hatchet.events.create(
       #     key: "user-login",
       #     data: { user_id: 123, action: "login" },
       #     additional_metadata: { ip_address: "192.168.1.1" }
@@ -80,7 +80,7 @@ module Hatchet
       # @return [Object] The gRPC response containing the created event details
       # @raise [Hatchet::Error] If the API request fails or returns an error
       # @example Push a simple event
-      #   response = events.push(
+      #   response = hatchet.events.push(
       #     "user-signup",
       #     { user_id: 456, email: "user@example.com" },
       #     additional_metadata: { source: "web" }
@@ -106,7 +106,7 @@ module Hatchet
       #     { key: "user-signup", data: { user_id: 1 } },
       #     { key: "user-login", data: { user_id: 1 }, priority: 1 }
       #   ]
-      #   response = events.bulk_push(events_data)
+      #   response = hatchet.events.bulk_push(events_data)
       def bulk_push(events, namespace: nil)
         grpc_events = events.map do |event|
           {
@@ -135,7 +135,7 @@ module Hatchet
       # @return [HatchetSdkRest::V1EventList] List of events matching the filters
       # @raise [Hatchet::Error] If the API request fails or returns an error
       # @example List recent events
-      #   events = events_client.list(
+      #   events = hatchet.events.list(
       #     limit: 10,
       #     since: Time.now - 24 * 60 * 60,
       #     keys: ["user-signup", "user-login"]

data/lib/hatchet/features/filters.rb

@@ -8,10 +8,10 @@ module Hatchet
     # listing, updating, and deleting filters in the Hatchet system.
     #
     # @example Listing filters
-    #   filters = filters_client.list(limit: 10, workflow_ids: ["wf-1"])
+    #   filters = hatchet.filters.list(limit: 10, workflow_ids: ["wf-1"])
     #
     # @example Creating a filter
-    #   filter = filters_client.create(
+    #   filter = hatchet.filters.create(
     #     workflow_id: "wf-1",
     #     expression: 'input.priority > 5',
     #     scope: "high-priority"
@@ -40,7 +40,7 @@ module Hatchet
       # @return [Object] A list of filters matching the specified criteria
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   filters = filters_client.list(limit: 10, workflow_ids: ["wf-1"])
+      #   filters = hatchet.filters.list(limit: 10, workflow_ids: ["wf-1"])
       def list(limit: nil, offset: nil, workflow_ids: nil, scopes: nil)
         @filter_api.v1_filter_list(
           @config.tenant_id,
@@ -59,7 +59,7 @@ module Hatchet
       # @return [Object] The filter details
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   filter = filters_client.get("filter-123")
+      #   filter = hatchet.filters.get("filter-123")
       def get(filter_id)
         @filter_api.v1_filter_get(@config.tenant_id, filter_id)
       end
@@ -73,7 +73,7 @@ module Hatchet
       # @return [Object] The created filter
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   filter = filters_client.create(
+      #   filter = hatchet.filters.create(
       #     workflow_id: "wf-1",
       #     expression: 'input.value > 10',
       #     scope: "my-scope",
@@ -95,7 +95,7 @@ module Hatchet
       # @return [Object] The deleted filter
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   filters_client.delete("filter-123")
+      #   hatchet.filters.delete("filter-123")
       def delete(filter_id)
         @filter_api.v1_filter_delete(@config.tenant_id, filter_id)
       end
@@ -107,7 +107,7 @@ module Hatchet
       # @return [Object] The updated filter
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   filters_client.update("filter-123", { expression: 'input.value > 20' })
+      #   hatchet.filters.update("filter-123", { expression: 'input.value > 20' })
       def update(filter_id, updates)
         update_request = HatchetSdkRest::V1UpdateFilterRequest.new(updates)
         @filter_api.v1_filter_update(@config.tenant_id, filter_id, update_request)

data/lib/hatchet/features/logs.rb

@@ -10,7 +10,7 @@ module Hatchet
     # associated with task runs in the Hatchet system.
     #
     # @example Listing logs for a task run
-    #   logs = logs_client.list("task-run-id", limit: 100)
+    #   logs = hatchet.logs.list("task-run-id", limit: 100)
     #
     # @since 0.1.0
     class Logs
@@ -35,7 +35,7 @@ module Hatchet
       # @return [Object] A list of log lines for the specified task run
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   logs = logs_client.list("task-run-123", limit: 500, since: Time.now - 3600)
+      #   logs = hatchet.logs.list("task-run-123", limit: 500, since: Time.now - 3600)
       def list(task_run_id, limit: 1000, since: nil, until_time: nil)
         @log_api.v1_log_line_list(
           task_run_id,

data/lib/hatchet/features/metrics.rb

@@ -13,10 +13,10 @@ module Hatchet
     # Prometheus metrics, task statistics, and task metrics from the Hatchet system.
     #
     # @example Getting queue metrics
-    #   metrics = metrics_client.get_queue_metrics
+    #   metrics = hatchet.metrics.get_queue_metrics
     #
     # @example Getting task metrics
-    #   task_metrics = metrics_client.get_task_metrics(
+    #   task_metrics = hatchet.metrics.get_task_metrics(
     #     since: Time.now - 86400,
     #     workflow_ids: ["wf-1"]
     #   )
@@ -41,7 +41,7 @@ module Hatchet
       # @return [Hash] The current queue metrics
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   queues = metrics_client.get_queue_metrics
+      #   queues = hatchet.metrics.get_queue_metrics
       def get_queue_metrics
         result = @tenant_api.tenant_get_step_run_queue_metrics(@config.tenant_id)
         result.queues || {}
@@ -52,7 +52,7 @@ module Hatchet
       # @return [String] The metrics in Prometheus text format
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   prometheus_text = metrics_client.scrape_tenant_prometheus_metrics
+      #   prometheus_text = hatchet.metrics.scrape_tenant_prometheus_metrics
       def scrape_tenant_prometheus_metrics
         @tenant_api.tenant_get_prometheus_metrics(@config.tenant_id)
       end
@@ -62,7 +62,7 @@ module Hatchet
       # @return [Object] The task statistics
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   stats = metrics_client.get_task_stats
+      #   stats = hatchet.metrics.get_task_stats
       def get_task_stats
         @tenant_api.tenant_get_task_stats(@config.tenant_id)
       end
@@ -77,7 +77,7 @@ module Hatchet
       # @return [TaskMetrics] Task metrics with counts per status
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   metrics = metrics_client.get_task_metrics(
+      #   metrics = hatchet.metrics.get_task_metrics(
       #     since: Time.now - 86400,
       #     workflow_ids: ["wf-1"]
       #   )

data/lib/hatchet/features/rate_limits.rb

@@ -8,7 +8,7 @@ module Hatchet
     # rate limits using the gRPC Admin client.
     #
     # @example Setting a rate limit
-    #   rate_limits_client.put(key: "api-calls", limit: 100, duration: :SECOND)
+    #   hatchet.rate_limits.put(key: "api-calls", limit: 100, duration: :SECOND)
     #
     # @since 0.1.0
     class RateLimits
@@ -31,7 +31,7 @@ module Hatchet
       # @return [void]
       # @raise [GRPC::BadStatus] If the gRPC request fails
       # @example
-      #   rate_limits_client.put(key: "api-calls", limit: 100, duration: :SECOND)
+      #   hatchet.rate_limits.put(key: "api-calls", limit: 100, duration: :SECOND)
       def put(key:, limit:, duration: :SECOND)
         @admin_grpc.put_rate_limit(key: key, limit: limit, duration: duration)
       end

data/lib/hatchet/features/runs.rb

@@ -72,8 +72,7 @@ module Hatchet
     # convenient Ruby interface.
     #
     # @example Creating a workflow run
-    #   runs = Features::Runs.new(rest_client, config)
-    #   response = runs.create(
+    #   response = hatchet.runs.create(
     #     name: "my-workflow",
     #     input: { key: "value" },
     #     additional_metadata: { source: "api" }
@@ -289,7 +288,7 @@ module Hatchet
       # @raise [ArgumentError] If the workflow_name or input parameters are nil or invalid
       # @raise [Hatchet::Error] If the API request fails or returns an error
       # @example Creating a workflow run
-      #   response = runs.create(
+      #   response = hatchet.runs.create(
       #     name: "simple-workflow",
       #     input: { user_id: 123, action: "process_data" },
       #     additional_metadata: { source: "api", priority: "high" }
@@ -446,9 +445,9 @@ module Hatchet
       # @raise [Timeout::Error] If the timeout is reached before completion
       # @raise [Hatchet::Error] If the API request fails or returns an error
       # @example Poll with default settings (1s interval, no timeout)
-      #   result = runs.poll("workflow-run-123")
+      #   result = hatchet.runs.poll("workflow-run-123")
       # @example Poll with custom interval and timeout
-      #   result = runs.poll("workflow-run-123", interval: 2.0, timeout: 30.0)
+      #   result = hatchet.runs.poll("workflow-run-123", interval: 2.0, timeout: 30.0)
       # @since 0.1.0
       def poll(workflow_run_id, interval: 1.0, timeout: nil)
         start_time = Time.now

data/lib/hatchet/features/scheduled.rb

@@ -10,7 +10,7 @@ module Hatchet
     # updating, bulk operations, listing, and retrieving scheduled workflow runs.
     #
     # @example Creating a scheduled workflow
-    #   scheduled = scheduled_client.create(
+    #   scheduled = hatchet.scheduled.create(
     #     workflow_name: "my-workflow",
     #     trigger_at: Time.now + 3600,
     #     input: { key: "value" },
@@ -44,7 +44,7 @@ module Hatchet
       # @return [Object] The created scheduled workflow instance
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   scheduled = scheduled_client.create(
+      #   scheduled = hatchet.scheduled.create(
       #     workflow_name: "my-workflow",
       #     trigger_at: Time.now + 3600,
       #     input: { key: "value" },
@@ -70,7 +70,7 @@ module Hatchet
       # @return [void]
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   scheduled_client.delete("scheduled-123")
+      #   hatchet.scheduled.delete("scheduled-123")
       def delete(scheduled_id)
         @workflow_api.workflow_scheduled_delete(@config.tenant_id, scheduled_id)
       end
@@ -85,7 +85,7 @@ module Hatchet
       # @return [Object] The updated scheduled workflow instance
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   scheduled_client.update("scheduled-123", trigger_at: Time.now + 7200)
+      #   hatchet.scheduled.update("scheduled-123", trigger_at: Time.now + 7200)
       def update(scheduled_id, trigger_at:)
         request = HatchetSdkRest::UpdateScheduledWorkflowRunRequest.new(
           trigger_at: trigger_at.utc.iso8601,
@@ -139,7 +139,7 @@ module Hatchet
       # @return [Object] The bulk update response containing updated IDs and per-item errors
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   scheduled_client.bulk_update([
+      #   hatchet.scheduled.bulk_update([
       #     { id: "scheduled-1", trigger_at: Time.now + 3600 },
       #     { id: "scheduled-2", trigger_at: Time.now + 7200 }
       #   ])
@@ -171,7 +171,7 @@ module Hatchet
       # @return [Object] A list of scheduled workflows matching the provided filters
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   scheduled = scheduled_client.list(limit: 10, workflow_id: "wf-1")
+      #   scheduled = hatchet.scheduled.list(limit: 10, workflow_id: "wf-1")
       def list(offset: nil, limit: nil, workflow_id: nil, parent_workflow_run_id: nil,
                statuses: nil, additional_metadata: nil, order_by_field: nil, order_by_direction: nil)
         @workflow_api.workflow_scheduled_list(
@@ -195,7 +195,7 @@ module Hatchet
       # @return [Object] The requested scheduled workflow instance
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   scheduled = scheduled_client.get("scheduled-123")
+      #   scheduled = hatchet.scheduled.get("scheduled-123")
       def get(scheduled_id)
         @workflow_api.workflow_scheduled_get(@config.tenant_id, scheduled_id)
       end

data/lib/hatchet/features/tenant.rb

@@ -8,7 +8,7 @@ module Hatchet
     # from the Hatchet system.
     #
     # @example Getting the current tenant
-    #   tenant_info = tenant_client.get
+    #   tenant_info = hatchet.tenant.get
     #
     # @since 0.1.0
     class Tenant
@@ -29,7 +29,7 @@ module Hatchet
       # @return [Object] The tenant details
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   tenant = tenant_client.get
+      #   tenant = hatchet.tenant.get
       def get
         @tenant_api.tenant_get(@config.tenant_id)
       end

data/lib/hatchet/features/workers.rb

@@ -8,10 +8,10 @@ module Hatchet
     # updating workers in the Hatchet system.
     #
     # @example Getting a worker
-    #   worker = workers_client.get("worker-id")
+    #   worker = hatchet.workers.get("worker-id")
     #
     # @example Listing all workers
-    #   workers = workers_client.list
+    #   workers = hatchet.workers.list
     #
     # @since 0.1.0
     class Workers
@@ -33,7 +33,7 @@ module Hatchet
       # @return [Object] The worker details
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   worker = workers_client.get("worker-123")
+      #   worker = hatchet.workers.get("worker-123")
       def get(worker_id)
         @worker_api.worker_get(worker_id)
       end
@@ -43,7 +43,7 @@ module Hatchet
       # @return [Object] A list of workers
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   workers = workers_client.list
+      #   workers = hatchet.workers.list
       def list
         @worker_api.worker_list(@config.tenant_id)
       end
@@ -55,7 +55,7 @@ module Hatchet
       # @return [Object] The updated worker
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   updated = workers_client.update("worker-123", { is_paused: true })
+      #   updated = hatchet.workers.update("worker-123", { is_paused: true })
       def update(worker_id, opts)
         update_request = HatchetSdkRest::UpdateWorkerRequest.new(opts)
         @worker_api.worker_update(worker_id, update_request)

data/lib/hatchet/features/workflows.rb

@@ -8,10 +8,10 @@ module Hatchet
     # If you're looking for runs, use the Runs client instead.
     #
     # @example Getting a workflow
-    #   workflow = workflows_client.get("workflow-id")
+    #   workflow = hatchet.workflows.get("workflow-id")
     #
     # @example Listing workflows
-    #   workflows = workflows_client.list(workflow_name: "my-workflow", limit: 10)
+    #   workflows = hatchet.workflows.list(workflow_name: "my-workflow", limit: 10)
     #
     # @since 0.1.0
     class Workflows
@@ -33,7 +33,7 @@ module Hatchet
       # @return [Object] The workflow details
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   workflow = workflows_client.get("workflow-123")
+      #   workflow = hatchet.workflows.get("workflow-123")
       def get(workflow_id)
         @workflow_api.workflow_get(workflow_id)
       end
@@ -46,7 +46,7 @@ module Hatchet
       # @return [Object] A list of workflows
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   workflows = workflows_client.list(workflow_name: "my-workflow", limit: 10, offset: 0)
+      #   workflows = hatchet.workflows.list(workflow_name: "my-workflow", limit: 10, offset: 0)
       def list(workflow_name: nil, limit: nil, offset: nil)
         @workflow_api.workflow_list(
           @config.tenant_id,
@@ -65,7 +65,7 @@ module Hatchet
       # @return [Object] The workflow version
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   version = workflows_client.get_version("workflow-123", version: "v2")
+      #   version = hatchet.workflows.get_version("workflow-123", version: "v2")
       def get_version(workflow_id, version: nil)
         @workflow_api.workflow_version_get(workflow_id, { version: version })
       end
@@ -78,7 +78,7 @@ module Hatchet
       # @return [void]
       # @raise [HatchetSdkRest::ApiError] If the API request fails
       # @example
-      #   workflows_client.delete("workflow-123")
+      #   hatchet.workflows.delete("workflow-123")
       def delete(workflow_id)
         @workflow_api.workflow_delete(workflow_id)
       end

data/lib/hatchet/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hatchet
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/hatchet/workflow.rb

@@ -98,10 +98,23 @@ module Hatchet
       @id ||= resolve_workflow_id
     end
 
-    # Define a task within this workflow
+    # Define a task within this workflow. The block receives the workflow input
+    # and a {Context} object, and its return value (a Hash) becomes the task
+    # output.
     #
-    # @param name [Symbol, String] Task name
-    # @param opts [Hash] Task options (parents:, execution_timeout:, retries:, etc.)
+    # @param name [Symbol, String] The name of the task
+    # @option opts [Array<Task, Symbol>] :parents ([]) A list of tasks that are parents of the task. Note: parents must be defined before their children
+    # @option opts [Integer, String, nil] :execution_timeout (nil) The maximum time to wait for the task to complete, in seconds or as a duration string (e.g. "60s")
+    # @option opts [Integer, String, nil] :schedule_timeout (nil) The maximum time to wait for the task to be scheduled
+    # @option opts [Integer, nil] :retries (nil) The number of times to retry the task before failing
+    # @option opts [Float, nil] :backoff_factor (nil) The backoff factor for controlling exponential backoff in retries
+    # @option opts [Integer, nil] :backoff_max_seconds (nil) The maximum number of seconds to allow retries with exponential backoff to continue
+    # @option opts [Array<RateLimit>] :rate_limits ([]) A list of rate limit configurations for the task
+    # @option opts [ConcurrencyExpression, Array<ConcurrencyExpression>, nil] :concurrency (nil) A concurrency expression (or list of them) controlling the concurrency settings for this task
+    # @option opts [Hash, nil] :desired_worker_labels (nil) A hash of desired worker labels that determine to which worker the task should be assigned
+    # @option opts [Array] :wait_for ([]) A list of conditions that must be met before the task can run
+    # @option opts [Array] :skip_if ([]) A list of conditions that, if met, will cause the task to be skipped
+    # @option opts [Hash, nil] :deps (nil) Dependency providers to inject into the task's context
     # @yield [input, ctx] The task execution block
     # @return [Task] The created task
     def task(name, **opts, &)
@@ -238,55 +251,65 @@ module Hatchet
       ::V1::CreateWorkflowVersionRequest.new(**args)
     end
 
-    # Run this workflow synchronously
+    # Run this workflow synchronously and wait for it to complete.
     #
-    # @param input [Hash] Workflow input
-    # @param options [TriggerWorkflowOptions, nil] Trigger options
-    # @return [Hash] The workflow run output
+    # @param input [Hash] The input data for the workflow
+    # @param options [TriggerWorkflowOptions, nil] Additional options for workflow execution, such as +additional_metadata:+ and +priority:+
+    # @return [Hash] The workflow run output, keyed by task name (e.g. `{"step1" => {...}, "step2" => {...}}`)
+    # @raise [Hatchet::Error] If no client is associated with the workflow
+    # @raise [Hatchet::FailedRunError] If the workflow run failed
     def run(input = {}, options: nil)
       raise Error, "No client associated with workflow #{@name}" unless @client
 
       @client.admin.trigger_workflow(self, input, options: options)
     end
 
-    # Run this workflow without waiting for the result
+    # Trigger a workflow run without waiting for it to complete. Useful for
+    # starting a run and immediately returning a reference to it without
+    # blocking while the workflow runs.
     #
-    # @param input [Hash] Workflow input
-    # @param options [TriggerWorkflowOptions, nil] Trigger options
-    # @return [WorkflowRunRef]
+    # @param input [Hash] The input data for the workflow
+    # @param options [TriggerWorkflowOptions, nil] Additional options for workflow execution
+    # @return [WorkflowRunRef] A reference to the workflow run, whose +result+ method blocks until the run completes
+    # @raise [Hatchet::Error] If no client is associated with the workflow
     def run_no_wait(input = {}, options: nil)
       raise Error, "No client associated with workflow #{@name}" unless @client
 
       @client.admin.trigger_workflow_no_wait(self, input, options: options)
     end
 
-    # Run many instances of this workflow in bulk
+    # Run this workflow in bulk and wait for all runs to complete. Runs are
+    # triggered via bulk gRPC triggering (batched by 1000) and results are
+    # collected concurrently.
     #
-    # @param items [Array<Hash>] Bulk run items
-    # @param return_exceptions [Boolean] Return exceptions instead of raising
-    # @return [Array] Results
+    # @param items [Array<Hash>] A list of bulk run items, as created by {#create_bulk_run_item}
+    # @param return_exceptions [Boolean] If +true+, exceptions are returned as part of the results instead of being raised
+    # @return [Array] A list of results for each workflow run
+    # @raise [Hatchet::Error] If no client is associated with the workflow
     def run_many(items, return_exceptions: false)
       raise Error, "No client associated with workflow #{@name}" unless @client
 
       @client.admin.trigger_workflow_many(self, items, return_exceptions: return_exceptions)
     end
 
-    # Run many instances without waiting for results
+    # Run this workflow in bulk without waiting for the runs to complete.
     #
-    # @param items [Array<Hash>] Bulk run items
-    # @return [Array<WorkflowRunRef>]
+    # @param items [Array<Hash>] A list of bulk run items, as created by {#create_bulk_run_item}
+    # @return [Array<WorkflowRunRef>] A list of references to the triggered workflow runs
+    # @raise [Hatchet::Error] If no client is associated with the workflow
     def run_many_no_wait(items)
       raise Error, "No client associated with workflow #{@name}" unless @client
 
       @client.admin.trigger_workflow_many_no_wait(self, items)
     end
 
-    # Create a bulk run item for use with run_many
+    # Create a bulk run item for this workflow, intended to be used with the
+    # {#run_many} methods.
     #
-    # @param input [Hash] Input data
-    # @param key [String, nil] Deduplication key
-    # @param options [TriggerWorkflowOptions, nil] Trigger options
-    # @return [Hash] Bulk run item
+    # @param input [Hash] The input data for the workflow
+    # @param key [String, nil] The key for the workflow run, used for identification and deduplication
+    # @param options [TriggerWorkflowOptions, nil] Additional options for the workflow run
+    # @return [Hash] A bulk run item that can be passed to the +run_many+ methods
     def create_bulk_run_item(input: {}, key: nil, options: nil)
       item = { input: input }
       item[:key] = key if key
@@ -294,24 +317,26 @@ module Hatchet
       item
     end
 
-    # Schedule this workflow for future execution
+    # Schedule this workflow to run at a specific time.
     #
-    # @param time [Time] When to execute
-    # @param input [Hash] Workflow input
-    # @param options [ScheduleTriggerWorkflowOptions, nil] Schedule options
-    # @return [Object] Schedule result
+    # @param time [Time] When to execute the workflow
+    # @param input [Hash] The input data for the workflow
+    # @param options [ScheduleTriggerWorkflowOptions, nil] Additional schedule options
+    # @return [Object] The schedule response from the Hatchet engine
+    # @raise [Hatchet::Error] If no client is associated with the workflow
     def schedule(time, input: {}, options: nil)
       raise Error, "No client associated with workflow #{@name}" unless @client
 
       @client.admin.schedule_workflow(self, time, input: input, options: options)
     end
 
-    # Create a cron trigger for this workflow
+    # Create a cron trigger for this workflow.
     #
-    # @param cron_name [String] Name for the cron
-    # @param expression [String] Cron expression
-    # @param input [Hash] Workflow input
-    # @return [Object] Cron result
+    # @param cron_name [String] The name of the cron job
+    # @param expression [String] The cron expression that defines the schedule
+    # @param input [Hash] The input data for the workflow
+    # @return [Object] The created cron workflow trigger
+    # @raise [Hatchet::Error] If no client is associated with the workflow
     def create_cron(cron_name, expression, input: {})
       raise Error, "No client associated with workflow #{@name}" unless @client