tavus 0.1.0

data/Rakefile

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+# Define RSpec task
+RSpec::Core::RakeTask.new(:spec)
+
+# Default task
+task default: :spec
+
+# Custom tasks for gem management
+namespace :gem do
+  desc "Build the gem"
+  task :build do
+    sh "gem build tavus.gemspec"
+  end
+
+  desc "Install the gem locally"
+  task install: :build do
+    version = File.read("lib/tavus/version.rb").match(/VERSION = "(.+)"/)[1]
+    sh "gem install ./tavus-#{version}.gem"
+  end
+
+  desc "Uninstall the gem"
+  task :uninstall do
+    version = File.read("lib/tavus/version.rb").match(/VERSION = "(.+)"/)[1]
+    sh "gem uninstall tavus -v #{version}"
+  end
+
+  desc "Clean up built gems"
+  task :clean do
+    sh "rm -f *.gem"
+  end
+
+  desc "Push gem to RubyGems"
+  task push: :build do
+    version = File.read("lib/tavus/version.rb").match(/VERSION = "(.+)"/)[1]
+    sh "gem push tavus-#{version}.gem"
+  end
+end
+
+# Development tasks
+namespace :dev do
+  desc "Run all tests"
+  task :test do
+    sh "bundle exec rspec"
+  end
+
+  desc "Run tests with coverage"
+  task :coverage do
+    ENV['COVERAGE'] = 'true'
+    sh "bundle exec rspec"
+  end
+
+  desc "Run security audit"
+  task :audit do
+    sh "bundle exec bundle-audit check --update"
+  end
+
+  desc "Run all security checks"
+  task :security do
+    Rake::Task["dev:audit"].invoke
+  end
+
+  desc "Update dependencies"
+  task :update do
+    sh "bundle update"
+  end
+
+  desc "Check for outdated dependencies"
+  task :outdated do
+    sh "bundle outdated"
+  end
+end
+
+# Release tasks
+namespace :release do
+  desc "Prepare for release (run tests, lint, build)"
+  task :prepare do
+    puts "🔍 Running tests..."
+    Rake::Task["dev:test"].invoke
+    
+    puts "🔒 Running security checks..."
+    Rake::Task["dev:security"].invoke
+    
+    puts "📦 Building gem..."
+    Rake::Task["gem:build"].invoke
+    
+    puts "✅ Release preparation complete!"
+  end
+
+  desc "Create a new release (tag, build, push)"
+  task :create do
+    version = File.read("lib/tavus/version.rb").match(/VERSION = "(.+)"/)[1]
+    
+    puts "🏷️  Creating git tag v#{version}..."
+    sh "git tag v#{version}"
+    sh "git push origin v#{version}"
+    
+    puts "📦 Building and pushing gem..."
+    Rake::Task["gem:push"].invoke
+    
+    puts "🎉 Release v#{version} created successfully!"
+  end
+
+  desc "Check if ready for release"
+  task :check do
+    version = File.read("lib/tavus/version.rb").match(/VERSION = "(.+)"/)[1]
+    
+    puts "📋 Release Checklist for v#{version}:"
+    puts "  ✓ Version updated in version.rb"
+    puts "  ✓ CHANGELOG.md updated" if File.read("CHANGELOG.md").include?(version)
+    puts "  ✓ All tests passing" if system("bundle exec rspec > /dev/null 2>&1")
+    puts "  ✓ Documentation up to date"
+    puts "  ✓ Ready for release!"
+  end
+end
+
+# Help task
+desc "Show available tasks"
+task :help do
+  puts <<~HELP
+    🎵 ElevenLabs Client Gem - Available Rake Tasks
+
+    📦 Gem Management:
+      rake gem:build          - Build the gem
+      rake gem:install        - Install gem locally
+      rake gem:uninstall      - Uninstall gem
+      rake gem:clean          - Clean up built gems
+      rake gem:push           - Push gem to RubyGems
+
+    🧪 Testing:
+      rake spec               - Run all tests (default)
+      rake test:unit          - Run unit tests only
+      rake test:integration   - Run integration tests only
+      rake test:endpoint[name] - Run tests for specific endpoint
+      rake dev:coverage       - Run tests with coverage
+
+    🔧 Development:
+      rake dev:audit          - Run bundler-audit
+      rake dev:security       - Run security checks
+      rake dev:update         - Update dependencies
+      rake dev:outdated       - Check outdated dependencies
+
+    🚀 Release:
+      rake release:prepare    - Prepare for release
+      rake release:create     - Create new release
+      rake release:check      - Check release readiness
+
+    Use 'rake -T' to see all available tasks.
+  HELP
+end

data/examples/advanced_persona.rb

@@ -0,0 +1,148 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "tavus"
+
+# Configure the client
+client = Tavus::Client.new(api_key: ENV.fetch("TAVUS_API_KEY", "your-api-key-here"))
+
+puts "=== Advanced Persona Configuration Example ===\n\n"
+
+# Create a persona with advanced layer configurations
+puts "Creating an advanced persona with custom layers..."
+
+begin
+  persona = client.personas.create(
+    persona_name: "Customer Support Agent",
+    system_prompt: "You are a helpful customer support agent for a SaaS company. " \
+                   "You help customers with technical issues, billing questions, and general inquiries.",
+    pipeline_mode: "full",
+    context: "The company offers project management software with features including task tracking, " \
+             "team collaboration, and reporting. Pricing plans range from $10-$50 per user per month.",
+    layers: {
+      # Language Model Configuration
+      llm: {
+        model: "tavus-gpt-4o",
+        tools: [
+          {
+            type: "function",
+            function: {
+              name: "check_account_status",
+              description: "Check the status of a customer's account including subscription and usage",
+              parameters: {
+                type: "object",
+                properties: {
+                  account_id: {
+                    type: "string",
+                    description: "The customer's account ID"
+                  }
+                },
+                required: ["account_id"]
+              }
+            }
+          },
+          {
+            type: "function",
+            function: {
+              name: "create_support_ticket",
+              description: "Create a support ticket for issues that need follow-up",
+              parameters: {
+                type: "object",
+                properties: {
+                  title: {
+                    type: "string",
+                    description: "Brief description of the issue"
+                  },
+                  priority: {
+                    type: "string",
+                    enum: ["low", "medium", "high", "urgent"],
+                    description: "Priority level of the ticket"
+                  }
+                },
+                required: ["title", "priority"]
+              }
+            }
+          }
+        ]
+      },
+
+      # Text-to-Speech Configuration
+      tts: {
+        tts_engine: "cartesia",
+        voice_settings: {
+          speed: 1.0,
+          emotion: ["positivity:high", "curiosity:medium"]
+        },
+        tts_emotion_control: "true",
+        tts_model_name: "sonic"
+      },
+
+      # Speech-to-Text Configuration
+      stt: {
+        stt_engine: "tavus-turbo",
+        participant_pause_sensitivity: "medium",
+        participant_interrupt_sensitivity: "low",
+        smart_turn_detection: true,
+        hotwords: "SaaS, API, webhook, integration, dashboard"
+      },
+
+      # Perception Configuration
+      perception: {
+        perception_model: "raven-0",
+        ambient_awareness_queries: [
+          "Does the customer appear frustrated or confused?",
+          "Is the customer showing their screen or pointing at something?"
+        ]
+      }
+    }
+  )
+
+  puts "✓ Created advanced persona: #{persona['persona_id']}"
+  persona_id = persona["persona_id"]
+
+  # Demonstrate updating specific layers
+  puts "\nUpdating TTS emotion settings..."
+  
+  operations = [
+    {
+      op: "replace",
+      path: "/layers/tts/voice_settings/emotion",
+      value: ["positivity:very-high", "enthusiasm:high"]
+    },
+    {
+      op: "replace",
+      path: "/layers/stt/participant_pause_sensitivity",
+      value: "low"
+    }
+  ]
+
+  client.personas.patch(persona_id, operations)
+  puts "✓ Updated persona layers"
+
+  # Get the updated persona details
+  puts "\nRetrieving updated persona..."
+  updated_persona = client.personas.get(persona_id)
+  puts "✓ Persona configuration:"
+  puts "  Name: #{updated_persona['data']&.first&.dig('persona_name')}"
+  puts "  System Prompt: #{updated_persona['data']&.first&.dig('system_prompt')[0..80]}..."
+  
+  tts_settings = updated_persona.dig("data", 0, "layers", "tts")
+  if tts_settings
+    puts "  TTS Engine: #{tts_settings['tts_engine']}"
+    puts "  Emotion Control: #{tts_settings['tts_emotion_control']}"
+  end
+
+  # Cleanup (optional)
+  # puts "\nCleaning up..."
+  # client.personas.delete(persona_id)
+  # puts "✓ Deleted persona"
+
+rescue Tavus::BadRequestError => e
+  puts "✗ Bad request: #{e.message}"
+rescue Tavus::ApiError => e
+  puts "✗ API error: #{e.message}"
+end
+
+puts "\n=== Example Complete ==="
+

data/examples/basic_usage.rb

@@ -0,0 +1,107 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "tavus"
+
+# Configure the client
+Tavus.configure do |config|
+  config.api_key = ENV.fetch("TAVUS_API_KEY", "your-api-key-here")
+end
+
+# Or create a client instance directly
+client = Tavus::Client.new(api_key: ENV.fetch("TAVUS_API_KEY", "your-api-key-here"))
+
+puts "=== Tavus Ruby Client Examples ===\n\n"
+
+# Example 1: Create a Persona
+puts "1. Creating a persona..."
+begin
+  persona = client.personas.create(
+    system_prompt: "You are a friendly sales coach who helps people improve their sales techniques.",
+    persona_name: "Sales Coach",
+    pipeline_mode: "full",
+    context: "You have 10 years of experience in B2B sales."
+  )
+  puts "✓ Created persona: #{persona['persona_id']}"
+  persona_id = persona["persona_id"]
+rescue Tavus::ApiError => e
+  puts "✗ Error creating persona: #{e.message}"
+  exit 1
+end
+
+# Example 2: List Personas
+puts "\n2. Listing personas..."
+begin
+  personas = client.personas.list(limit: 10)
+  puts "✓ Found #{personas['total_count']} personas"
+  personas["data"]&.each do |p|
+    puts "  - #{p['persona_name']} (#{p['persona_id']})"
+  end
+rescue Tavus::ApiError => e
+  puts "✗ Error listing personas: #{e.message}"
+end
+
+# Example 3: Create a Conversation
+puts "\n3. Creating a conversation..."
+begin
+  conversation = client.conversations.create(
+    replica_id: "rfe12d8b9597", # Replace with your replica ID
+    persona_id: persona_id,
+    conversation_name: "Sales Training Session",
+    test_mode: true # Set to false for actual conversation
+  )
+  puts "✓ Created conversation: #{conversation['conversation_id']}"
+  puts "  URL: #{conversation['conversation_url']}"
+  conversation_id = conversation["conversation_id"]
+rescue Tavus::BadRequestError => e
+  puts "✗ Error creating conversation: #{e.message}"
+  puts "  Note: Make sure to use a valid replica_id"
+end
+
+# Example 4: List Conversations
+puts "\n4. Listing conversations..."
+begin
+  conversations = client.conversations.list(status: "active")
+  puts "✓ Found #{conversations['total_count']} active conversations"
+rescue Tavus::ApiError => e
+  puts "✗ Error listing conversations: #{e.message}"
+end
+
+# Example 5: Update Persona
+puts "\n5. Updating persona..."
+begin
+  result = client.personas.update_field(
+    persona_id,
+    "/persona_name",
+    "Expert Sales Coach"
+  )
+  puts "✓ Updated persona name"
+rescue Tavus::ApiError => e
+  puts "✗ Error updating persona: #{e.message}"
+end
+
+# Example 6: Get Persona Details
+puts "\n6. Getting persona details..."
+begin
+  persona_details = client.personas.get(persona_id)
+  puts "✓ Retrieved persona details"
+  puts "  Name: #{persona_details['data']&.first&.dig('persona_name')}"
+rescue Tavus::NotFoundError => e
+  puts "✗ Persona not found: #{e.message}"
+rescue Tavus::ApiError => e
+  puts "✗ Error getting persona: #{e.message}"
+end
+
+# Cleanup (optional)
+puts "\n7. Cleaning up (optional)..."
+# Uncomment to delete the created persona
+# begin
+#   client.personas.delete(persona_id)
+#   puts "✓ Deleted persona"
+# rescue Tavus::ApiError => e
+#   puts "✗ Error deleting persona: #{e.message}"
+# end
+
+puts "\n=== Examples Complete ==="
+

data/examples/complete_workflow.rb

@@ -0,0 +1,200 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "tavus"
+
+# Configure the client
+client = Tavus::Client.new(api_key: ENV.fetch("TAVUS_API_KEY", "your-api-key-here"))
+
+puts "=== Complete Tavus Workflow Example ===\n\n"
+
+# Step 1: Create a Replica
+puts "1. Creating a replica..."
+begin
+  replica = client.replicas.create(
+    train_video_url: "https://your-bucket.s3.amazonaws.com/training-video.mp4",
+    replica_name: "Sales Demo Replica",
+    model_name: "phoenix-3"
+  )
+  puts "✓ Created replica: #{replica['replica_id']}"
+  replica_id = replica["replica_id"]
+rescue Tavus::BadRequestError => e
+  puts "✗ Error creating replica: #{e.message}"
+  puts "  Note: Using placeholder replica_id for demo"
+  replica_id = "rfe12d8b9597"
+end
+
+# Step 2: Upload documents to Knowledge Base
+puts "\n2. Uploading documents to knowledge base..."
+begin
+  document = client.documents.create(
+    document_url: "https://example.com/product-guide.pdf",
+    document_name: "Product Guide",
+    tags: ["product", "sales"],
+    properties: { category: "documentation" }
+  )
+  puts "✓ Uploaded document: #{document['uuid']}"
+  document_id = document["uuid"]
+rescue Tavus::ApiError => e
+  puts "✗ Error uploading document: #{e.message}"
+end
+
+# Step 3: Create Objectives
+puts "\n3. Creating conversation objectives..."
+begin
+  objectives = client.objectives.create(
+    data: [
+      {
+        objective_name: "Qualify Lead",
+        objective_prompt: "Determine if the prospect has budget and authority",
+        confirmation_mode: "automatic",
+        modality: "verbal"
+      }
+    ]
+  )
+  puts "✓ Created objectives: #{objectives['objectives_id']}"
+  objectives_id = objectives["objectives_id"]
+rescue Tavus::ApiError => e
+  puts "✗ Error creating objectives: #{e.message}"
+end
+
+# Step 4: Create Guardrails
+puts "\n4. Creating guardrails..."
+begin
+  guardrails = client.guardrails.create(
+    name: "Sales Compliance Guardrails",
+    data: [
+      {
+        guardrails_prompt: "Never make unrealistic promises or discuss competitor pricing",
+        modality: "verbal"
+      }
+    ]
+  )
+  puts "✓ Created guardrails: #{guardrails['guardrails_id']}"
+  guardrails_id = guardrails["guardrails_id"]
+rescue Tavus::ApiError => e
+  puts "✗ Error creating guardrails: #{e.message}"
+end
+
+# Step 5: Create a Persona
+puts "\n5. Creating a persona..."
+begin
+  persona = client.personas.create(
+    persona_name: "Sales Expert",
+    system_prompt: "You are an expert sales representative who helps qualify leads and answer product questions.",
+    pipeline_mode: "full",
+    context: "You work for a SaaS company selling project management software.",
+    default_replica_id: replica_id,
+    document_ids: document_id ? [document_id] : [],
+    layers: {
+      tts: {
+        tts_engine: "cartesia",
+        voice_settings: {
+          speed: 1.0,
+          emotion: ["positivity:high", "professionalism:high"]
+        }
+      }
+    }
+  )
+  puts "✓ Created persona: #{persona['persona_id']}"
+  persona_id = persona["persona_id"]
+rescue Tavus::ApiError => e
+  puts "✗ Error creating persona: #{e.message}"
+  exit 1
+end
+
+# Step 6: Create a Conversation
+puts "\n6. Creating a conversation..."
+begin
+  conversation = client.conversations.create(
+    replica_id: replica_id,
+    persona_id: persona_id,
+    conversation_name: "Sales Demo Call",
+    test_mode: true
+  )
+  puts "✓ Created conversation: #{conversation['conversation_id']}"
+  puts "  URL: #{conversation['conversation_url']}"
+  conversation_id = conversation["conversation_id"]
+rescue Tavus::ApiError => e
+  puts "✗ Error creating conversation: #{e.message}"
+end
+
+# Step 7: Generate a Video
+puts "\n7. Generating a video..."
+begin
+  video = client.videos.generate_from_text(
+    replica_id: replica_id,
+    script: "Hello! I'm excited to show you how our platform can help your team collaborate better.",
+    video_name: "Sales Demo Video",
+    fast: true
+  )
+  puts "✓ Created video: #{video['video_id']}"
+  puts "  Status: #{video['status']}"
+  puts "  Hosted URL: #{video['hosted_url']}"
+  video_id = video["video_id"]
+rescue Tavus::ApiError => e
+  puts "✗ Error generating video: #{e.message}"
+end
+
+# Step 8: Check status and list resources
+puts "\n8. Checking created resources..."
+begin
+  # List replicas
+  replicas = client.replicas.list(limit: 5)
+  puts "✓ Total replicas: #{replicas['total_count']}"
+
+  # List personas
+  personas = client.personas.list(limit: 5)
+  puts "✓ Total personas: #{personas['total_count']}"
+
+  # List conversations
+  conversations = client.conversations.list(limit: 5)
+  puts "✓ Total conversations: #{conversations['total_count']}"
+
+  # List videos
+  videos = client.videos.list(limit: 5)
+  puts "✓ Total videos: #{videos['total_count']}"
+rescue Tavus::ApiError => e
+  puts "✗ Error listing resources: #{e.message}"
+end
+
+# Step 9: Update resources
+puts "\n9. Updating resources..."
+begin
+  if persona_id
+    client.personas.update_field(
+      persona_id,
+      "/persona_name",
+      "Expert Sales Agent"
+    )
+    puts "✓ Updated persona name"
+  end
+
+  if video_id
+    client.videos.rename(video_id, "Updated Sales Demo")
+    puts "✓ Updated video name"
+  end
+rescue Tavus::ApiError => e
+  puts "✗ Error updating resources: #{e.message}"
+end
+
+# Optional cleanup
+puts "\n10. Cleanup (commented out - uncomment to enable)..."
+# client.conversations.delete(conversation_id) if conversation_id
+# client.videos.delete(video_id) if video_id
+# client.personas.delete(persona_id) if persona_id
+# client.guardrails.delete(guardrails_id) if guardrails_id
+# client.objectives.delete(objectives_id) if objectives_id
+# client.documents.delete(document_id) if document_id
+# puts "✓ Cleaned up all resources"
+
+puts "\n=== Workflow Complete ==="
+puts "\nThis example demonstrated:"
+puts "  • Creating and managing replicas"
+puts "  • Uploading documents to knowledge base"
+puts "  • Setting up objectives and guardrails"
+puts "  • Creating personas with custom configurations"
+puts "  • Starting conversations"
+puts "  • Generating videos"
+puts "  • Listing and updating resources"