tavus 0.1.0

data/lib/tavus/client.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module Tavus
+  class Client
+    attr_reader :configuration
+
+    def initialize(api_key: nil, base_url: nil, timeout: nil)
+      @configuration = Configuration.new
+      @configuration.api_key = api_key || Tavus.configuration.api_key
+      @configuration.base_url = base_url || Tavus.configuration.base_url
+      @configuration.timeout = timeout || Tavus.configuration.timeout
+
+      validate_configuration!
+    end
+
+    def conversations
+      @conversations ||= Resources::Conversations.new(self)
+    end
+
+    def personas
+      @personas ||= Resources::Personas.new(self)
+    end
+
+    def replicas
+      @replicas ||= Resources::Replicas.new(self)
+    end
+
+    def objectives
+      @objectives ||= Resources::Objectives.new(self)
+    end
+
+    def guardrails
+      @guardrails ||= Resources::Guardrails.new(self)
+    end
+
+    def documents
+      @documents ||= Resources::Documents.new(self)
+    end
+
+    def videos
+      @videos ||= Resources::Videos.new(self)
+    end
+
+    def get(path, params: {})
+      request(:get, path, params: params)
+    end
+
+    def post(path, body: {}, params: {})
+      request(:post, path, body: body, params: params)
+    end
+
+    def patch(path, body: {}, params: {})
+      request(:patch, path, body: body, params: params)
+    end
+
+    def delete(path, params: {})
+      request(:delete, path, params: params)
+    end
+
+    private
+
+    def validate_configuration!
+      raise ConfigurationError, "API key is required" unless configuration.valid?
+    end
+
+    def request(method, path, body: {}, params: {})
+      uri = build_uri(path, params)
+      http = build_http(uri)
+      request = build_request(method, uri, body)
+
+      response = http.request(request)
+      handle_response(response)
+    rescue StandardError => e
+      raise ApiError, "Request failed: #{e.message}"
+    end
+
+    def build_uri(path, params)
+      uri = configuration.base_uri.dup
+      uri.path = path
+      uri.query = URI.encode_www_form(params) unless params.empty?
+      uri
+    end
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.read_timeout = configuration.timeout
+      http.open_timeout = configuration.timeout
+      http
+    end
+
+    def build_request(method, uri, body)
+      request_class = case method
+                      when :get then Net::HTTP::Get
+                      when :post then Net::HTTP::Post
+                      when :patch then Net::HTTP::Patch
+                      when :delete then Net::HTTP::Delete
+                      else raise ArgumentError, "Unsupported HTTP method: #{method}"
+                      end
+
+      request = request_class.new(uri)
+      request["x-api-key"] = configuration.api_key
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "application/json"
+
+      if [:post, :patch].include?(method) && !body.empty?
+        request.body = JSON.generate(body)
+      end
+
+      request
+    end
+
+    def handle_response(response)
+      case response.code.to_i
+      when 200, 201
+        parse_json_response(response)
+      when 204
+        { success: true }
+      when 400
+        error = parse_json_response(response)
+        raise BadRequestError, error["error"] || error["message"] || "Bad request"
+      when 401
+        error = parse_json_response(response)
+        raise AuthenticationError, error["message"] || "Invalid access token"
+      when 404
+        raise NotFoundError, "Resource not found"
+      when 422
+        error = parse_json_response(response)
+        raise ValidationError, error["error"] || error["message"] || "Validation failed"
+      when 429
+        raise RateLimitError, "Rate limit exceeded"
+      when 500..599
+        raise ServerError, "Server error: #{response.code}"
+      else
+        raise ApiError, "Unexpected response: #{response.code}"
+      end
+    end
+
+    def parse_json_response(response)
+      return {} if response.body.nil? || response.body.empty?
+
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      { "raw_body" => response.body }
+    end
+  end
+end

data/lib/tavus/configuration.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Tavus
+  class Configuration
+    attr_accessor :api_key, :base_url, :timeout
+
+    DEFAULT_BASE_URL = "https://tavusapi.com"
+    DEFAULT_TIMEOUT = 30
+
+    def initialize
+      @api_key = nil
+      @base_url = DEFAULT_BASE_URL
+      @timeout = DEFAULT_TIMEOUT
+    end
+
+    def valid?
+      !api_key.nil? && !api_key.empty?
+    end
+
+    def base_uri
+      URI.parse(base_url)
+    end
+  end
+end

data/lib/tavus/errors.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Tavus
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class ApiError < Error; end
+  class AuthenticationError < ApiError; end
+  class BadRequestError < ApiError; end
+  class NotFoundError < ApiError; end
+  class ValidationError < ApiError; end
+  class RateLimitError < ApiError; end
+  class ServerError < ApiError; end
+end

data/lib/tavus/resources/conversations.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Tavus
+  module Resources
+    class Conversations
+      def initialize(client)
+        @client = client
+      end
+
+      # Create a new conversation
+      # @param replica_id [String] The unique identifier for the replica
+      # @param persona_id [String] The unique identifier for the persona
+      # @param options [Hash] Additional optional parameters
+      # @option options [Boolean] :audio_only Specifies whether the interaction should be voice-only
+      # @option options [String] :callback_url A URL that will receive webhooks
+      # @option options [String] :conversation_name A name for the conversation
+      # @option options [String] :conversational_context Optional context for the conversation
+      # @option options [String] :custom_greeting Custom greeting for the replica
+      # @option options [Array<String>] :memory_stores Memory stores to use for the conversation
+      # @option options [Array<String>] :document_ids Document IDs the persona can access
+      # @option options [String] :document_retrieval_strategy Strategy for document retrieval (speed, quality, balanced)
+      # @option options [Array<String>] :document_tags Document tags the replica can access
+      # @option options [Boolean] :test_mode If true, conversation created but replica won't join
+      # @option options [Hash] :properties Optional properties to customize the conversation
+      # @return [Hash] The created conversation details
+      def create(replica_id: nil, persona_id: nil, **options)
+        body = options.dup
+        body[:replica_id] = replica_id if replica_id
+        body[:persona_id] = persona_id if persona_id
+
+        @client.post("/v2/conversations", body: body)
+      end
+
+      # Get a single conversation by ID
+      # @param conversation_id [String] The unique identifier of the conversation
+      # @return [Hash] The conversation details
+      def get(conversation_id)
+        @client.get("/v2/conversations/#{conversation_id}")
+      end
+
+      # List all conversations
+      # @param options [Hash] Query parameters
+      # @option options [Integer] :limit Number of conversations to return per page (default: 10)
+      # @option options [Integer] :page Page number to return (default: 1)
+      # @option options [String] :status Filter by status (active, ended)
+      # @return [Hash] List of conversations and total count
+      def list(**options)
+        @client.get("/v2/conversations", params: options)
+      end
+
+      # End a conversation
+      # @param conversation_id [String] The unique identifier of the conversation
+      # @return [Hash] Success response
+      def end(conversation_id)
+        @client.post("/v2/conversations/#{conversation_id}/end")
+      end
+
+      # Delete a conversation
+      # @param conversation_id [String] The unique identifier of the conversation
+      # @return [Hash] Success response
+      def delete(conversation_id)
+        @client.delete("/v2/conversations/#{conversation_id}")
+      end
+    end
+  end
+end

data/lib/tavus/resources/documents.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Tavus
+  module Resources
+    class Documents
+      def initialize(client)
+        @client = client
+      end
+
+      # Create a new document in the knowledge base
+      # @param document_url [String] The URL of the document to be processed (required)
+      # @param options [Hash] Additional optional parameters
+      # @option options [String] :document_name Optional name for the document
+      # @option options [String] :callback_url Optional URL for status updates
+      # @option options [Hash] :properties Optional key-value pairs for additional properties
+      # @option options [Array<String>] :tags Optional array of tags to categorize the document
+      # @return [Hash] The created document details
+      def create(document_url:, **options)
+        body = options.merge(document_url: document_url)
+        @client.post("/v2/documents", body: body)
+      end
+
+      # Get a single document by ID
+      # @param document_id [String] The unique identifier of the document
+      # @return [Hash] The document details
+      def get(document_id)
+        @client.get("/v2/documents/#{document_id}")
+      end
+
+      # List all documents
+      # @param options [Hash] Query parameters
+      # @option options [Integer] :limit Number of documents to return per page (default: 10)
+      # @option options [Integer] :page Page number for pagination (0-based, default: 0)
+      # @option options [String] :sort Sort direction (ascending, descending)
+      # @option options [String] :status Filter documents by status
+      # @option options [String] :name_or_uuid Search by name or UUID
+      # @option options [String] :tags Comma-separated list of tags to filter by
+      # @return [Hash] List of documents with pagination info
+      def list(**options)
+        @client.get("/v2/documents", params: options)
+      end
+
+      # Update a document's metadata
+      # @param document_id [String] The unique identifier of the document
+      # @param options [Hash] Update parameters
+      # @option options [String] :document_name New name for the document
+      # @option options [Array<String>] :tags New array of tags (overwrites existing)
+      # @return [Hash] The updated document details
+      def update(document_id, **options)
+        @client.patch("/v2/documents/#{document_id}", body: options)
+      end
+
+      # Delete a document
+      # @param document_id [String] The unique identifier of the document
+      # @return [Hash] Success response
+      def delete(document_id)
+        @client.delete("/v2/documents/#{document_id}")
+      end
+    end
+  end
+end

data/lib/tavus/resources/guardrails.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Tavus
+  module Resources
+    class Guardrails
+      def initialize(client)
+        @client = client
+      end
+
+      # Create new guardrails
+      # @param name [String] Descriptive name for the collection of guardrails
+      # @param data [Array<Hash>] Array of individual guardrails
+      # @return [Hash] The created guardrails details
+      def create(name: nil, data: [])
+        body = {}
+        body[:name] = name if name
+        body[:data] = data unless data.empty?
+
+        @client.post("/v2/guardrails", body: body)
+      end
+
+      # Get a single set of guardrails by ID
+      # @param guardrails_id [String] The unique identifier of the guardrails
+      # @return [Hash] The guardrails details
+      def get(guardrails_id)
+        @client.get("/v2/guardrails/#{guardrails_id}")
+      end
+
+      # List all guardrails
+      # @param options [Hash] Query parameters
+      # @option options [Integer] :limit Number of guardrails to return per page (default: 10)
+      # @option options [Integer] :page Page number to return (default: 1)
+      # @return [Hash] List of guardrails and total count
+      def list(**options)
+        @client.get("/v2/guardrails", params: options)
+      end
+
+      # Update guardrails using JSON Patch operations
+      # @param guardrails_id [String] The unique identifier of the guardrails
+      # @param operations [Array<Hash>] Array of JSON Patch operations
+      # @example
+      #   operations = [
+      #     { op: "replace", path: "/data/0/guardrails_prompt", value: "Your updated prompt" },
+      #     { op: "add", path: "/data/0/callback_url", value: "https://your-server.com/webhook" }
+      #   ]
+      # @return [Hash] Success response
+      def patch(guardrails_id, operations)
+        raise ArgumentError, "Operations must be an array" unless operations.is_a?(Array)
+        raise ArgumentError, "Operations cannot be empty" if operations.empty?
+
+        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/guardrails/#{guardrails_id}", body: operations)
+      end
+
+      # Helper method to build patch operations
+      # @param field [String] The field path
+      # @param value [Object] The value to set
+      # @param operation [String] The operation type (default: "replace")
+      # @return [Hash] A JSON Patch operation
+      def build_patch_operation(field, value, operation: "replace")
+        op = { op: operation, path: field }
+        op[:value] = value unless operation == "remove"
+        op
+      end
+
+      # Convenient method to update a field
+      # @param guardrails_id [String] The unique identifier of the guardrails
+      # @param field [String] The field path to update
+      # @param value [Object] The new value
+      # @return [Hash] Success response
+      def update_field(guardrails_id, field, value)
+        operation = build_patch_operation(field, value, operation: "replace")
+        patch(guardrails_id, [operation])
+      end
+
+      # Delete guardrails
+      # @param guardrails_id [String] The unique identifier of the guardrails
+      # @return [Hash] Success response
+      def delete(guardrails_id)
+        @client.delete("/v2/guardrails/#{guardrails_id}")
+      end
+    end
+  end
+end

data/lib/tavus/resources/objectives.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Tavus
+  module Resources
+    class Objectives
+      def initialize(client)
+        @client = client
+      end
+
+      # Create new objectives
+      # @param data [Array<Hash>] Array of objectives to create
+      # @return [Hash] The created objective details
+      def create(data:)
+        raise ArgumentError, "data must be an array" unless data.is_a?(Array)
+        raise ArgumentError, "data cannot be empty" if data.empty?
+
+        @client.post("/v2/objectives", body: { data: data })
+      end
+
+      # Get a single objective by ID
+      # @param objectives_id [String] The unique identifier of the objective
+      # @return [Hash] The objective details
+      def get(objectives_id)
+        @client.get("/v2/objectives/#{objectives_id}")
+      end
+
+      # List all objectives
+      # @param options [Hash] Query parameters
+      # @option options [Integer] :limit Number of objectives to return per page (default: 10)
+      # @option options [Integer] :page Page number to return (default: 1)
+      # @return [Hash] List of objectives and total count
+      def list(**options)
+        @client.get("/v2/objectives", params: options)
+      end
+
+      # Update an objective using JSON Patch operations
+      # @param objectives_id [String] The unique identifier of the objective
+      # @param operations [Array<Hash>] Array of JSON Patch operations
+      # @example
+      #   operations = [
+      #     { op: "replace", path: "/data/0/objective_name", value: "updated_objective_name" },
+      #     { op: "replace", path: "/data/0/objective_prompt", value: "Updated prompt" },
+      #     { op: "add", path: "/data/0/output_variables", value: ["new_variable"] }
+      #   ]
+      # @return [Hash] Success response
+      def patch(objectives_id, operations)
+        raise ArgumentError, "Operations must be an array" unless operations.is_a?(Array)
+        raise ArgumentError, "Operations cannot be empty" if operations.empty?
+
+        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/objectives/#{objectives_id}", body: operations)
+      end
+
+      # Helper method to build patch operations
+      # @param field [String] The field path
+      # @param value [Object] The value to set
+      # @param operation [String] The operation type (default: "replace")
+      # @return [Hash] A JSON Patch operation
+      def build_patch_operation(field, value, operation: "replace")
+        op = { op: operation, path: field }
+        op[:value] = value unless operation == "remove"
+        op
+      end
+
+      # Convenient method to update a field
+      # @param objectives_id [String] The unique identifier of the objective
+      # @param field [String] The field path to update
+      # @param value [Object] The new value
+      # @return [Hash] Success response
+      def update_field(objectives_id, field, value)
+        operation = build_patch_operation(field, value, operation: "replace")
+        patch(objectives_id, [operation])
+      end
+
+      # Delete an objective
+      # @param objectives_id [String] The unique identifier of the objective
+      # @return [Hash] Success response
+      def delete(objectives_id)
+        @client.delete("/v2/objectives/#{objectives_id}")
+      end
+    end
+  end
+end

data/lib/tavus/resources/personas.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Tavus
+  module Resources
+    class Personas
+      def initialize(client)
+        @client = client
+      end
+
+      # Create a new persona
+      # @param system_prompt [String] The system prompt for the LLM (required for full pipeline mode)
+      # @param options [Hash] Additional optional parameters
+      # @option options [String] :persona_name A name for the persona
+      # @option options [String] :pipeline_mode Pipeline mode (full, echo)
+      # @option options [String] :context Context for the LLM
+      # @option options [String] :default_replica_id Default replica ID for the persona
+      # @option options [Array<String>] :document_ids Document IDs the persona can access
+      # @option options [Array<String>] :document_tags Document tags the persona can access
+      # @option options [Hash] :layers Configuration for perception, STT, LLM, TTS layers
+      # @return [Hash] The created persona details
+      def create(system_prompt: nil, **options)
+        body = options.dup
+        body[:system_prompt] = system_prompt if system_prompt
+
+        @client.post("/v2/personas", body: body)
+      end
+
+      # Get a single persona by ID
+      # @param persona_id [String] The unique identifier of the persona
+      # @return [Hash] The persona details
+      def get(persona_id)
+        @client.get("/v2/personas/#{persona_id}")
+      end
+
+      # List all personas
+      # @param options [Hash] Query parameters
+      # @option options [Integer] :limit Number of personas to return per page (default: 10)
+      # @option options [Integer] :page Page number to return (default: 1)
+      # @option options [String] :persona_type Filter by type (user, system)
+      # @return [Hash] List of personas and total count
+      def list(**options)
+        @client.get("/v2/personas", params: options)
+      end
+
+      # Update a persona using JSON Patch operations
+      # @param persona_id [String] The unique identifier of the persona
+      # @param operations [Array<Hash>] Array of JSON Patch operations
+      # @example
+      #   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" }
+      #   ]
+      # @return [Hash] Success response
+      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
+
+      # Helper method to build patch operations
+      # @param field [String] The field path (e.g., "/persona_name", "/layers/llm/model")
+      # @param value [Object] The value to set
+      # @param operation [String] The operation type (default: "replace")
+      # @return [Hash] A JSON Patch operation
+      def build_patch_operation(field, value, operation: "replace")
+        op = { op: operation, path: field }
+        op[:value] = value unless operation == "remove"
+        op
+      end
+
+      # Convenient method to replace a field
+      # @param persona_id [String] The unique identifier of the persona
+      # @param field [String] The field path to update
+      # @param value [Object] The new value
+      # @return [Hash] Success response
+      def update_field(persona_id, field, value)
+        operation = build_patch_operation(field, value, operation: "replace")
+        patch(persona_id, [operation])
+      end
+
+      # Delete a persona
+      # @param persona_id [String] The unique identifier of the persona
+      # @return [Hash] Success response
+      def delete(persona_id)
+        @client.delete("/v2/personas/#{persona_id}")
+      end
+    end
+  end
+end

data/lib/tavus/resources/replicas.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Tavus
+  module Resources
+    class Replicas
+      def initialize(client)
+        @client = client
+      end
+
+      # Create a new replica
+      # @param train_video_url [String] Direct link to training video (required)
+      # @param options [Hash] Additional optional parameters
+      # @option options [String] :consent_video_url Direct link to consent video
+      # @option options [String] :callback_url URL to receive callbacks on completion
+      # @option options [String] :replica_name Name for the replica
+      # @option options [String] :model_name Phoenix model version (default: phoenix-3)
+      # @option options [Hash] :properties Additional properties
+      # @return [Hash] The created replica details
+      def create(train_video_url:, **options)
+        body = options.merge(train_video_url: train_video_url)
+        @client.post("/v2/replicas", body: body)
+      end
+
+      # Get a single replica by ID
+      # @param replica_id [String] The unique identifier of the replica
+      # @param verbose [Boolean] Include additional replica data (default: false)
+      # @return [Hash] The replica details
+      def get(replica_id, verbose: false)
+        params = verbose ? { verbose: true } : {}
+        @client.get("/v2/replicas/#{replica_id}", params: params)
+      end
+
+      # List all replicas
+      # @param options [Hash] Query parameters
+      # @option options [Integer] :limit Number of replicas to return per page
+      # @option options [Integer] :page Page number to return
+      # @option options [Boolean] :verbose Include additional replica data
+      # @option options [String] :replica_type Filter by type (user, system)
+      # @option options [String] :replica_ids Comma-separated list of replica IDs to filter
+      # @return [Hash] List of replicas and total count
+      def list(**options)
+        @client.get("/v2/replicas", params: options)
+      end
+
+      # Delete a replica
+      # @param replica_id [String] The unique identifier of the replica
+      # @param hard [Boolean] If true, hard delete replica and assets (irreversible)
+      # @return [Hash] Success response
+      def delete(replica_id, hard: false)
+        params = hard ? { hard: true } : {}
+        @client.delete("/v2/replicas/#{replica_id}", params: params)
+      end
+
+      # Rename a replica
+      # @param replica_id [String] The unique identifier of the replica
+      # @param replica_name [String] New name for the replica
+      # @return [Hash] Success response
+      def rename(replica_id, replica_name)
+        @client.patch("/v2/replicas/#{replica_id}/name", body: { replica_name: replica_name })
+      end
+    end
+  end
+end
+