Class: Cadenya::Client

Inherits:
Internal::Transport::BaseClient show all
Defined in:
lib/cadenya/client.rb,
sig/cadenya/client.rbs

Constant Summary collapse

DEFAULT_MAX_RETRIES =

Default max number of retries to attempt after a failed retryable request.

Returns:

  • (0) 
0
DEFAULT_TIMEOUT_IN_SECONDS =

Default per-request timeout.

Returns:

  • (Float) 
60.0
DEFAULT_INITIAL_RETRY_DELAY =

Default initial retry delay in seconds. Overall delay is calculated using exponential backoff + jitter.

Returns:

  • (Float) 
0.5
DEFAULT_MAX_RETRY_DELAY =

Default max retry delay in seconds.

Returns:

  • (Float) 
8.0

Constants inherited from Internal::Transport::BaseClient

Internal::Transport::BaseClient::Cadenya, Internal::Transport::BaseClient::MAX_REDIRECTS, Internal::Transport::BaseClient::PLATFORM_HEADERS

Instance Attribute Summary collapse

Attributes inherited from Internal::Transport::BaseClient

#base_url, #headers, #idempotency_header, #initial_retry_delay, #max_retries, #max_retry_delay, #requester, #timeout

Instance Method Summary collapse

Methods inherited from Internal::Transport::BaseClient

follow_redirect, #inspect, reap_connection!, #request, #send_request, should_retry?, validate!

Methods included from Internal::Util::SorbetRuntimeSupport

#const_missing, #define_sorbet_constant!, #sorbet_constant_defined?, #to_sorbet_type, to_sorbet_type

Constructor Details

#initialize(api_key: ENV["CADENYA_API_KEY"], workspace_id: ENV["CADENYA_WORKSPACE_ID"], webhook_key: ENV["CADENYA_WEBHOOK_KEY"], base_url: ENV["CADENYA_BASE_URL"], max_retries: self.class::DEFAULT_MAX_RETRIES, timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS, initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY, max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY) ⇒ Client

Creates and returns a new client for interacting with the API.

workspace-scoped endpoints unless overridden per request. Defaults to ENV["CADENYA_WORKSPACE_ID"]

"https://api.example.com/v2/". Defaults to ENV["CADENYA_BASE_URL"]

Parameters:

  • api_key (String, nil) (defaults to: ENV["CADENYA_API_KEY"]) —

    Defaults to ENV["CADENYA_API_KEY"]

  • workspace_id (String, nil) (defaults to: ENV["CADENYA_WORKSPACE_ID"]) —

    Workspace to operate on. Fills the workspaceId path parameter on

  • webhook_key (String, nil) (defaults to: ENV["CADENYA_WEBHOOK_KEY"]) —

    Defaults to ENV["CADENYA_WEBHOOK_KEY"]

  • base_url (String, nil) (defaults to: ENV["CADENYA_BASE_URL"]) —

    Override the default base URL for the API, e.g.,

  • max_retries (Integer) (defaults to: self.class::DEFAULT_MAX_RETRIES) —

    Max number of retries to attempt after a failed retryable request.

  • timeout (Float) (defaults to: self.class::DEFAULT_TIMEOUT_IN_SECONDS)
  • initial_retry_delay (Float) (defaults to: self.class::DEFAULT_INITIAL_RETRY_DELAY)
  • max_retry_delay (Float) (defaults to: self.class::DEFAULT_MAX_RETRY_DELAY) 


164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/cadenya/client.rb', line 164

def initialize(
  api_key: ENV["CADENYA_API_KEY"],
  workspace_id: ENV["CADENYA_WORKSPACE_ID"],
  webhook_key: ENV["CADENYA_WEBHOOK_KEY"],
  base_url: ENV["CADENYA_BASE_URL"],
  max_retries: self.class::DEFAULT_MAX_RETRIES,
  timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS,
  initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,
  max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY
)
  base_url ||= "https://api.cadenya.com"

  if api_key.nil?
    raise ArgumentError.new("api_key is required, and can be set via environ: \"CADENYA_API_KEY\"")
  end

  headers = {}
  custom_headers_env = ENV["CADENYA_CUSTOM_HEADERS"]
  unless custom_headers_env.nil?
    parsed = {}
    custom_headers_env.split("\n").each do |line|
      colon = line.index(":")
      unless colon.nil?
        parsed[line[0...colon].strip] = line[(colon + 1)..].strip
      end
    end
    headers = parsed.merge(headers)
  end

  @workspace_id = workspace_id&.to_s
  @api_key = api_key.to_s
  @webhook_key = webhook_key&.to_s

  super(
    base_url: base_url,
    timeout: timeout,
    max_retries: max_retries,
    initial_retry_delay: initial_retry_delay,
    max_retry_delay: max_retry_delay,
    headers: headers
  )

  @ai_provider_keys = Cadenya::Resources::AIProviderKeys.new(client: self)
  @account = Cadenya::Resources::Account.new(client: self)
  @profiles = Cadenya::Resources::Profiles.new(client: self)
  @agents = Cadenya::Resources::Agents.new(client: self)
  @objectives = Cadenya::Resources::Objectives.new(client: self)
  @memory_layers = Cadenya::Resources::MemoryLayers.new(client: self)
  @uploads = Cadenya::Resources::Uploads.new(client: self)
  @models = Cadenya::Resources::Models.new(client: self)
  @search = Cadenya::Resources::Search.new(client: self)
  @tool_sets = Cadenya::Resources::ToolSets.new(client: self)
  @api_keys = Cadenya::Resources::APIKeys.new(client: self)
  @global_api_key = Cadenya::Resources::GlobalAPIKey.new(client: self)
  @workspace_secrets = Cadenya::Resources::WorkspaceSecrets.new(client: self)
  @workspaces = Cadenya::Resources::Workspaces.new(client: self)
  @workspace_admin = Cadenya::Resources::WorkspaceAdmin.new(client: self)
  @webhooks = Cadenya::Resources::Webhooks.new(client: self)
  @widgets = Cadenya::Resources::Widgets.new(client: self)
  @tenants = Cadenya::Resources::Tenants.new(client: self)
  @widget_sessions = Cadenya::Resources::WidgetSessions.new(client: self)
end

Instance Attribute Details

#account ⇒ Cadenya::Resources::Account (readonly)

Manage the authenticated account. Accounts are the top-level organizational unit and contain one or more workspaces.

Returns:



35
36
37
 
# File 'lib/cadenya/client.rb', line 35

def 
  @account
end

#agents ⇒ Cadenya::Resources::Agents (readonly)

Manage AI agents within a workspace. Agents define AI behavior and tool access.

Returns:



44
45
46
 
# File 'lib/cadenya/client.rb', line 44

def agents
  @agents
end

#ai_provider_keys ⇒ Cadenya::Resources::AIProviderKeys (readonly)

Returns:



30
31
32
 
# File 'lib/cadenya/client.rb', line 30

def ai_provider_keys
  @ai_provider_keys
end

#api_key ⇒ String (readonly)

Returns:

  • (String) 


19
20
21
 
# File 'lib/cadenya/client.rb', line 19

def api_key
  @api_key
end

#api_keys ⇒ Cadenya::Resources::APIKeys (readonly)

Issue, rotate, disable, and revoke a workspace's API keys. Every key belongs to exactly one workspace; the system-managed global account key is managed via GlobalAPIKeyService instead.

Returns:



83
84
85
 
# File 'lib/cadenya/client.rb', line 83

def api_keys
  @api_keys
end

#global_api_key ⇒ Cadenya::Resources::GlobalAPIKey (readonly)

Manage the account's system-provisioned global API key. The global key is the only key that spans every workspace; it is created by the system and cannot be deleted, so the surface is retrieve, rotate, and the disable/enable kill switch.

Returns:



89
90
91
 
# File 'lib/cadenya/client.rb', line 89

def global_api_key
  @global_api_key
end

#memory_layers ⇒ Cadenya::Resources::MemoryLayers (readonly)

Manage memory layers and their entries. Layers are named containers that can be composed into an objective's memory cascade; entries are the keyed values within a layer. System-managed layers (e.g., episodic layers created by the runtime) cannot be mutated through this API.

Returns:



54
55
56
 
# File 'lib/cadenya/client.rb', line 54

def memory_layers
  @memory_layers
end

#models ⇒ Cadenya::Resources::Models (readonly)

Manage LLM models available to a workspace. Models represent provider and family pairs (e.g., "anthropic/claude-sonnet-4.6"). Workspaces are seeded with the supported models and you can enable or disable each one.

Returns:



66
67
68
 
# File 'lib/cadenya/client.rb', line 66

def models
  @models
end

#objectives ⇒ Cadenya::Resources::Objectives (readonly)

Returns:



47
48
49
 
# File 'lib/cadenya/client.rb', line 47

def objectives
  @objectives
end

#profiles ⇒ Cadenya::Resources::Profiles (readonly)

Operations on profiles, the account-level principals (users, API keys, system) that authenticate against the API.

Returns:



40
41
42
 
# File 'lib/cadenya/client.rb', line 40

def profiles
  @profiles
end

#search ⇒ Cadenya::Resources::Search (readonly)

Returns:



69
70
71
 
# File 'lib/cadenya/client.rb', line 69

def search
  @search
end

#tenants ⇒ Cadenya::Resources::Tenants (readonly)

Read and erase tenants and the subjects under them. Tenants and subjects are created by assertion — on objective creation or widget session mint — never directly, so this service has no create or update: it exists to enumerate what assertions have produced, and to destroy it on request.

Returns:



126
127
128
 
# File 'lib/cadenya/client.rb', line 126

def tenants
  @tenants
end

#tool_sets ⇒ Cadenya::Resources::ToolSets (readonly)

Manage tool sets and the tools they contain. Tool sets group related tools, and tools define specific capabilities available to agents.

When a tool set is managed, only API key actors can modify its tools; human (profile) actors cannot.

Returns:



77
78
79
 
# File 'lib/cadenya/client.rb', line 77

def tool_sets
  @tool_sets
end

#uploads ⇒ Cadenya::Resources::Uploads (readonly)

Issue short-lived presigned URLs for direct client-to-object-storage uploads. Created uploads can be referenced by id when creating or updating resources that accept binary content (e.g., MemoryEntry).

Returns:



60
61
62
 
# File 'lib/cadenya/client.rb', line 60

def uploads
  @uploads
end

#webhook_key ⇒ String? (readonly)

Returns:

  • (String, nil) 


22
23
24
 
# File 'lib/cadenya/client.rb', line 22

def webhook_key
  @webhook_key
end

#webhooks ⇒ Cadenya::Resources::Webhooks (readonly)

Returns:



113
114
115
 
# File 'lib/cadenya/client.rb', line 113

def webhooks
  @webhooks
end

#widget_sessions ⇒ Cadenya::Resources::WidgetSessions (readonly)

Mint and manage widget sessions. Session creation is server-to-server only: the customer's backend authenticates its visitor, asserts tenant/subject context, attaches any per-visitor secrets, and receives a short-lived bearer token the browser uses against the widget host.

Returns:



133
134
135
 
# File 'lib/cadenya/client.rb', line 133

def widget_sessions
  @widget_sessions
end

#widgets ⇒ Cadenya::Resources::Widgets (readonly)

Manage embeddable chat widgets. A widget binds an agent to a globally unique hostname with a per-widget origin allowlist; browsers reach it with session tokens minted via WidgetSessionService.

Returns:



119
120
121
 
# File 'lib/cadenya/client.rb', line 119

def widgets
  @widgets
end

#workspace_admin ⇒ Cadenya::Resources::WorkspaceAdmin (readonly)

Administer workspaces across the account: create and archive workspaces and manage their membership. These operations are account-scoped and require the admin role (a token whose profile holds the WorkOS admin role); they live under /v1/account/workspaces rather than the workspace-scoped /v1/workspaces tree so an admin can manage any workspace in the account, including ones they are not themselves a member of.

Returns:



110
111
112
 
# File 'lib/cadenya/client.rb', line 110

def workspace_admin
  @workspace_admin
end

#workspace_id ⇒ String? (readonly)

Workspace to operate on. Fills the workspaceId path parameter on workspace-scoped endpoints unless overridden per request.

Returns:

  • (String, nil) 


27
28
29
 
# File 'lib/cadenya/client.rb', line 27

def workspace_id
  @workspace_id
end

#workspace_secrets ⇒ Cadenya::Resources::WorkspaceSecrets (readonly)

Returns:



92
93
94
 
# File 'lib/cadenya/client.rb', line 92

def workspace_secrets
  @workspace_secrets
end

#workspaces ⇒ Cadenya::Resources::Workspaces (readonly)

Manage workspaces within an account. Workspaces provide organizational grouping and isolation for resources such as agents, tools, and API keys.

This is the workspace-scoped, end-user surface. Administrative operations (create / archive workspaces, manage members) live in WorkspaceAdminService under /v1/account/workspaces and require the admin role.

Returns:



101
102
103
 
# File 'lib/cadenya/client.rb', line 101

def workspaces
  @workspaces
end