Class: Tavus::Resources::Personas

Inherits:
Object
  • Object
show all
Defined in:
lib/tavus/resources/personas.rb

Instance Method Summary collapse

Constructor Details

#initialize(client) ⇒ Personas

Returns a new instance of Personas.



6
7
8
 
# File 'lib/tavus/resources/personas.rb', line 6

def initialize(client)
  @client = client
end

Instance Method Details

#build_patch_operation(field, value, operation: "replace") ⇒ Hash

Helper method to build patch operations

Parameters:

  • field (String) —

    The field path (e.g., “/persona_name”, “/layers/llm/model”)

  • value (Object) —

    The value to set

  • operation (String) (defaults to: "replace") —

    The operation type (default: “replace”)

Returns:

  • (Hash) —

    A JSON Patch operation



73
74
75
76
77
 
# File 'lib/tavus/resources/personas.rb', line 73

def build_patch_operation(field, value, operation: "replace")
  op = { op: operation, path: field }
  op[:value] = value unless operation == "remove"
  op
end

#create(system_prompt: nil, **options) ⇒ Hash

Create a new persona

Parameters:

  • system_prompt (String) (defaults to: nil) —

    The system prompt for the LLM (required for full pipeline mode)

  • options (Hash) —

    Additional optional parameters

Options Hash (**options):

  • :persona_name (String) —

    A name for the persona

  • :pipeline_mode (String) —

    Pipeline mode (full, echo)

  • :context (String) —

    Context for the LLM

  • :default_replica_id (String) —

    Default replica ID for the persona

  • :document_ids (Array<String>) —

    Document IDs the persona can access

  • :document_tags (Array<String>) —

    Document tags the persona can access

  • :layers (Hash) —

    Configuration for perception, STT, LLM, TTS layers

Returns:

  • (Hash) —

    The created persona details



21
22
23
24
25
26
 
# File 'lib/tavus/resources/personas.rb', line 21

def create(system_prompt: nil, **options)
  body = options.dup
  body[:system_prompt] = system_prompt if system_prompt

  @client.post("/v2/personas", body: body)
end

#delete(persona_id) ⇒ Hash

Delete a persona

Parameters:

  • persona_id (String) —

    The unique identifier of the persona

Returns:

  • (Hash) —

    Success response



92
93
94
 
# File 'lib/tavus/resources/personas.rb', line 92

def delete(persona_id)
  @client.delete("/v2/personas/#{persona_id}")
end

#get(persona_id) ⇒ Hash

Get a single persona by ID

Parameters:

  • persona_id (String) —

    The unique identifier of the persona

Returns:

  • (Hash) —

    The persona details



31
32
33
 
# File 'lib/tavus/resources/personas.rb', line 31

def get(persona_id)
  @client.get("/v2/personas/#{persona_id}")
end

#list(**options) ⇒ Hash

List all personas

Parameters:

  • options (Hash) —

    Query parameters

Options Hash (**options):

  • :limit (Integer) —

    Number of personas to return per page (default: 10)

  • :page (Integer) —

    Page number to return (default: 1)

  • :persona_type (String) —

    Filter by type (user, system)

Returns:

  • (Hash) —

    List of personas and total count



41
42
43
 
# File 'lib/tavus/resources/personas.rb', line 41

def list(**options)
  @client.get("/v2/personas", params: options)
end

#patch(persona_id, operations) ⇒ Hash

Update a persona using JSON Patch operations

Examples:

operations = [
  { op: "replace", path: "/persona_name", value: "Wellness Advisor" },
  { op: "add", path: "/layers/tts/tts_emotion_control", value: "true" },
  { op: "remove", path: "/layers/stt/hotwords" }
]

Parameters:

  • persona_id (String) —

    The unique identifier of the persona

  • operations (Array<Hash>) —

    Array of JSON Patch operations

Returns:

  • (Hash) —

    Success response

Raises:

  • (ArgumentError) 


55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/tavus/resources/personas.rb', line 55

def patch(persona_id, operations)
  raise ArgumentError, "Operations must be an array" unless operations.is_a?(Array)
  raise ArgumentError, "Operations cannot be empty" if operations.empty?

  # Validate each operation has required fields
  operations.each do |op|
    raise ArgumentError, "Each operation must have 'op' and 'path'" unless op[:op] && op[:path]
    raise ArgumentError, "Operation 'op' must be one of: add, remove, replace, copy, move, test" unless %w[add remove replace copy move test].include?(op[:op])
  end

  @client.patch("/v2/personas/#{persona_id}", body: operations)
end

#update_field(persona_id, field, value) ⇒ Hash

Convenient method to replace a field

Parameters:

  • persona_id (String) —

    The unique identifier of the persona

  • field (String) —

    The field path to update

  • value (Object) —

    The new value

Returns:

  • (Hash) —

    Success response



84
85
86
87
 
# File 'lib/tavus/resources/personas.rb', line 84

def update_field(persona_id, field, value)
  operation = build_patch_operation(field, value, operation: "replace")
  patch(persona_id, [operation])
end