README

A comprehensive Laravel SDK for Sarvam AI - India's Indigenous Language AI Platform. This package provides seamless integration with Sarvam AI's APIs for speech-to-text, text-to-speech, translation, chat completion, and more across 22+ Indian languages.

🌟 Features

🎤 Speech-to-Text: Convert audio to text in multiple Indian languages
🔊 Text-to-Speech: Generate natural-sounding speech from text
🌐 Translation: Translate between 22+ Indian languages and English
💬 Chat Completion: Multi-lingual conversational AI
📝 Transliteration: Convert text between different scripts
🔍 Language Detection: Automatically identify languages
📄 PDF Parsing: Extract structured data from PDFs
📑 Document Translation: Translate entire documents
⚡ Streaming Support: Real-time streaming for chat and TTS
🔄 Batch Processing: Process multiple requests efficiently
💾 Caching Support: Built-in response caching
📊 Comprehensive Logging: Debug and monitor API calls

📋 Requirements

PHP 8.0 or higher
Laravel 9.0, 10.0, or 11.0
Sarvam AI API Key (Get it here)

🚀 Installation

Install the package via Composer:

composer require sarvam/laravel-sdk

⚙️ Configuration

Publish the configuration file:

php artisan vendor:publish --provider="Sarvam\Laravel\SarvamServiceProvider" --tag="sarvam-config"

Add your API key to `.env`:

SARVAM_API_KEY=your_api_key_here

# Optional configurations
SARVAM_BASE_URL=https://api.sarvam.ai
SARVAM_TIMEOUT=60
SARVAM_RETRY_TIMES=3
SARVAM_CACHE_ENABLED=false
SARVAM_LOGGING_ENABLED=false

📖 Quick Start

Basic Usage

use Sarvam\Laravel\Facades\Sarvam;

// Translate text
$translation = Sarvam::text()->translate('Hello World', 'hi-IN');
echo $translation->getTranslatedText(); // "नमस्ते दुनिया"

// Text-to-Speech
$audio = Sarvam::speech()->fromText('नमस्ते', 'hi-IN');
$audio->saveToFile('output.wav');

// Speech-to-Text
$transcript = Sarvam::speech()->toText('audio.wav');
echo $transcript->getTranscript();

// Chat completion
$response = Sarvam::chat()->completion('Tell me about India in Hindi');
echo $response->getContent();

🎯 Detailed Usage Examples

📝 Text Services

Translation

use Sarvam\Laravel\Facades\Sarvam;

// Simple translation
$result = Sarvam::text()->translate('Good morning', 'hi-IN');
echo $result->getTranslatedText(); // "सुप्रभात"

// Translation with options
$result = Sarvam::text()->translate('Your EMI of Rs. 3000 is pending', 'hi-IN', [
    'source_language' => 'en-IN',
    'mode' => 'formal', // formal, colloquial
    'enable_preprocessing' => true,
    'speaker_gender' => 'Female',
]);

// Batch translation
$texts = ['Hello', 'How are you?', 'Good bye'];
$results = Sarvam::text()->batchTranslate($texts, 'ta-IN');

Transliteration

// Convert between scripts
$result = Sarvam::text()->transliterate(
    'मुझे कल 9:30am को appointment है',
    'hi-IN',
    'hi-IN',
    ['format' => 'latin']
);
echo $result->getTransliteratedText(); // "mujhe kal 9:30am ko appointment hai"

// Spoken form transliteration
$result = Sarvam::text()->transliterate('मुझे कल appointment है', 'hi-IN', 'hi-IN', [
    'spoken_form' => true,
    'spoken_form_numerals_language' => 'english',
]);

Language Detection

$result = Sarvam::text()->detectLanguage('आप कैसे हैं?');
echo $result->getLanguageCode(); // "hi-IN"
echo $result->getLanguageName(); // "Hindi"
echo $result->getConfidence(); // 0.98
echo $result->getScript(); // "Devanagari"

🎤 Speech Services

Speech-to-Text (Transcription)

// Basic transcription
$result = Sarvam::speech()->toText('audio.wav');
echo $result->getTranscript();
echo $result->getLanguageCode();

// With options
$result = Sarvam::speech()->toText('meeting.wav', [
    'model' => 'saarika:v2.5',
    'language_code' => 'hi-IN',
    'with_timestamps' => true,
    'with_diarization' => true,
    'num_speakers' => 2,
]);

// Access diarized transcript
if ($result->hasDiarization()) {
    foreach ($result->getDiarizedTranscript() as $entry) {
        echo "Speaker {$entry['speaker_id']}: {$entry['transcript']}\n";
        echo "Time: {$entry['start_time_seconds']}s - {$entry['end_time_seconds']}s\n";
    }
}

// Get transcript by speaker
$speaker1Transcript = $result->getTranscriptBySpeaker('SPEAKER_01');

Speech-to-Text with Translation

// Transcribe and translate to English in one step
$result = Sarvam::speech()->toTextTranslate('hindi_audio.wav');
echo $result->getTranscript(); // English translation
echo $result->getSourceLanguage(); // "hi-IN"

Text-to-Speech

// Basic TTS
$result = Sarvam::speech()->fromText('Hello World', 'en-IN');
$result->saveToFile('output.wav');

// With voice customization
$result = Sarvam::speech()->fromText('नमस्ते दुनिया', 'hi-IN', [
    'speaker' => 'Anushka', // Female voice
    'pitch' => 0.2,        // -0.75 to 0.75
    'pace' => 1.2,         // 0.5 to 2.0
    'loudness' => 1.0,     // 0.3 to 3.0
    'sample_rate' => 22050,
    'audio_format' => 'mp3',
]);

// Save to Laravel storage
$result->saveToFile('audio/greeting.mp3', 's3');

// Stream directly to browser
return $result->stream('download.mp3');

// Get available speakers
$speakers = Sarvam::speech()->getAvailableSpeakers();
// Female: ['Anushka', 'Manisha', 'Vidya', 'Arya']
// Male: ['Abhilash', 'Karun', 'Hitesh']

💬 Chat Services

Chat Completion

// Simple chat
$response = Sarvam::chat()->completion('What is the capital of India?');
echo $response->getContent();

// With conversation history
$messages = [
    ['role' => 'system', 'content' => 'You are a helpful assistant that speaks Hindi.'],
    ['role' => 'user', 'content' => 'Tell me about Indian festivals'],
    ['role' => 'assistant', 'content' => 'भारत में कई त्योहार मनाए जाते हैं...'],
    ['role' => 'user', 'content' => 'Tell me more about Diwali']
];

$response = Sarvam::chat()->completion($messages, [
    'temperature' => 0.7,
    'max_tokens' => 500,
    'wiki_grounding' => true, // Use Wikipedia for factual accuracy
]);

echo $response->getContent();
echo "Tokens used: " . $response->getTotalTokens();

Streaming Chat

// Stream responses for real-time display
Sarvam::chat()->streamCompletion(
    'Write a story about ancient India',
    function ($chunk) {
        // Process each chunk as it arrives
        if (isset($chunk['choices'][0]['delta']['content'])) {
            echo $chunk['choices'][0]['delta']['content'];
            flush(); // Send to browser immediately
        }
    },
    ['max_tokens' => 1000]
);

Multi-turn Conversation

$conversation = [
    'Tell me about the Taj Mahal',
    'When was it built?',
    'Who built it and why?'
];

$responses = Sarvam::chat()->conversation($conversation);

foreach ($responses as $index => $response) {
    echo "Q: {$conversation[$index]}\n";
    echo "A: {$response->getContent()}\n\n";
}

📄 Parse Services

PDF Parsing

// Parse a single page
$result = Sarvam::parse()->parsePdf('document.pdf', 1);
$html = $result->getDecodedHtml();
$text = $result->getText();

// Extract structured data
$tables = $result->getTables();
foreach ($tables as $table) {
    $headers = $table['headers'];
    $rows = $table['rows'];
    // Process table data
}

$headings = $result->getHeadings();
foreach ($headings as $heading) {
    echo "H{$heading['level']}: {$heading['text']}\n";
}

// Parse entire PDF
$allPages = Sarvam::parse()->parseFullPdf('document.pdf', [
    'max_pages' => 50
]);

Document Translation

$result = Sarvam::parse()->translateDocument('document.pdf', 'hi-IN', [
    'source_language' => 'en-IN'
]);

// Save translated document
$result->saveToFile('translated_document.pdf');

// Stream to browser
return $result->stream('translated.pdf');

🧪 Testing

Test your SDK configuration:

# Test all services
php artisan sarvam:test

# Test specific service
php artisan sarvam:test --service=text
php artisan sarvam:test --service=speech
php artisan sarvam:test --service=chat
php artisan sarvam:test --service=parse

# Test with custom text
php artisan sarvam:test --text="Your custom text here" --language=hi-IN

🎨 Advanced Features

Caching Responses

Enable caching in your config to reduce API calls:

// config/sarvam.php
'cache' => [
    'enabled' => true,
    'ttl' => 3600, // 1 hour
],

Logging

Enable logging to debug API interactions:

// config/sarvam.php
'logging' => [
    'enabled' => true,
    'channel' => 'sarvam', // Define in config/logging.php
],

Error Handling

use Sarvam\Laravel\Exceptions\SarvamException;

try {
    $result = Sarvam::text()->translate('Hello', 'hi-IN');
} catch (SarvamException $e) {
    if ($e->isInvalidApiKey()) {
        // Handle invalid API key
    } elseif ($e->isInsufficientQuota()) {
        // Handle quota exceeded
    } elseif ($e->isRateLimitError()) {
        // Handle rate limiting
    } else {
        // Handle other errors
        echo $e->getUserMessage();
    }
}

WebSocket Support (Coming Soon)

// Real-time TTS streaming
Sarvam::speech()->streamFromText($text, $language, function($audioChunk) {
    // Process audio chunks in real-time
});

// Real-time STT
Sarvam::speech()->streamToText($audioStream, function($transcript) {
    // Process transcript in real-time
});

🌍 Supported Languages

The SDK supports the following Indian languages:

English (en-IN)
Hindi (hi-IN)
Bengali (bn-IN)
Gujarati (gu-IN)
Kannada (kn-IN)
Malayalam (ml-IN)
Marathi (mr-IN)
Odia (od-IN)
Punjabi (pa-IN)
Tamil (ta-IN)
Telugu (te-IN)
Assamese (as-IN)
Bodo (brx-IN)
Dogri (doi-IN)
Konkani (gom-IN)
Kashmiri (ks-IN)
Maithili (mai-IN)
Manipuri (mni-IN)
Nepali (ne-IN)
Sanskrit (sa-IN)
Sindhi (sd-IN)
Urdu (ur-IN)

🔧 Troubleshooting

Common Issues

Invalid API Key Error
- Verify your API key in the .env file
- Check if the key is active in your Sarvam Dashboard
Quota Exceeded
- Check your usage in the dashboard
- Upgrade your plan if needed
Audio File Issues
- Ensure audio files are in supported formats (WAV, MP3, etc.)
- For best results, use 16kHz sample rate
Language Not Detected
- Provide more text for better detection
- Specify the language explicitly when known

📚 Documentation

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

This package is open-sourced software licensed under the MIT license.

🔗 Links

💡 Support

For support, email developer@sarvam.ai or join our Discord community.

Made with ❤️ for the Indian AI community

mepsd / sarvam-laravel-sdk

Maintainers

Details