bhashini-client-sdk 0.2.1

Python SDK for Bhashini inference APIs with unified support for ASR, NMT, TTS, OCR, NER, speaker services, normalization, and image-language workflows.

Bhashini Client SDK (Python)

Python SDK for the Bhashini Inference API. It provides a unified BhashiniClient for speech, text, speaker, and image-language services, while keeping validation, model routing, payload construction, and response parsing inside dedicated service modules.

Overview

This SDK wraps the Bhashini API into a clean Python interface. Each service is modular and independently handles:

• input validation
• payload construction
• API dispatch through a shared request handler
• response parsing

Supported service categories:

Category	Services
Speech / Audio	ASR, TTS, Audio Language Detection, Speaker Diarization, Speaker Enrollment, Speaker Verification, Voice Cloning, Denoiser
Text	NMT, Transliteration, Text Language Detection, Text Normalization, Inverse Text Normalization, NER
Vision	OCR, Image Language Detection

Architecture

The main flow is:

User Input -> BhashiniClient -> Service Validation -> Payload Construction -> RequestHandler -> Response Parsing

Core design principles:

• Service isolation: each service owns its own validation and parsing logic.
• Shared transport: HTTP/auth handling is centralized in request_handler.py.
• Model-aware routing: selected services use primary and fallback serviceId routing.
• Flexible inputs: several services accept file paths, base64 data, and URIs.
• Structured SDK errors: services return Input Error:, Validation Error:, or API Error: messages.

Project Structure

bhashini-client/
├── bhashini_client/
│   ├── __init__.py
│   ├── config.py
│   ├── core.py
│   ├── models_info.py
│   ├── services/
│   │   ├── asr_service.py
│   │   ├── nmt_service.py
│   │   ├── tts_service.py
│   │   ├── transliteration_service.py
│   │   ├── language_detection_service.py
│   │   ├── audio_language_detection_service.py
│   │   ├── ner_service.py
│   │   ├── ocr_service.py
│   │   ├── speaker_diarization_service.py
│   │   ├── speaker_enrollment_service.py
│   │   ├── speaker_verification_service.py
│   │   ├── voice_cloning_service.py
│   │   ├── image_lang_detection_service.py
│   │   ├── text_normalization_service.py
│   │   ├── itn_service.py
│   │   ├── denoiser_service.py
│   │   ├── audio_input_utils.py
│   │   └── service_utils.py
│   └── utils/
│       └── request_handler.py
├── tests/
├── demo.py
├── requirements.txt
└── run_all_checks.ps1

Installation

Requirements:

• Python 3.8+

Install dependencies:

pip install -r requirements.txt

Package name:

pip install bhashini-client-sdk

Authentication

The SDK reads the API key from BHASHINI_API_KEY, or you can pass it explicitly when creating the client.

Environment variable:

$env:BHASHINI_API_KEY="your_api_key"

Or in code:

from bhashini_client import BhashiniClient

client = BhashiniClient(api_key="your_api_key")

Quick Start

from bhashini_client import BhashiniClient

client = BhashiniClient()

print(client.text_language_detection("Hello world"))
print(client.nmt("Hello", "en", "hi"))
print(client.tts("Hello from Bhashini", "en", output_file="output.wav"))
print(client.asr("C:\\path\\sample.wav", "hi"))

Demo

Run the end-to-end demo:

python demo.py

Optional sample files:

$env:BHASHINI_SAMPLE_AUDIO="C:\full\path\sample.wav"
$env:BHASHINI_SAMPLE_IMAGE="C:\full\path\sample.png"

The demo exercises text, speech, speaker, normalization, and image-language services from one script.

Services Reference

Public Client Methods

These are the main high-level methods exposed by BhashiniClient:

Method	Purpose	Return Type
client.asr(audio_input, source_lang)	Speech to text	str transcription
client.nmt(text, source_lang, target_lang)	Translation	str translated text
client.tts(text, source_lang, gender="female", output_file="output.wav")	Text to speech	output file path str
client.transliteration(text, source_lang, target_lang)	Script conversion	transliterated text str
client.text_language_detection(text)	Text language detection	language code str
client.audio_language_detection(audio_input)	Audio language detection	language code str
client.ocr(image_path, source_lang)	OCR from local image	extracted text str
client.ner(text, source_lang)	Named entity recognition	dict with entities
client.speaker_diarization(audio_input)	Speaker segmentation	list of speaker blocks
client.speaker_enrollment(audio_input, speaker_name)	Speaker profile creation	speaker ID str
client.speaker_verification(audio_input, speaker_id)	Speaker verification	verification result
client.voice_cloning(text, ref_text, ref_audio_input, source_lang="te", output_file="voice_clone_output.wav")	Voice cloning	output file path str
client.image_language_detection(image_input)	Image language detection	language code str
client.text_normalization(text, source_lang="en")	Text normalization	normalized text str
client.inverse_text_normalization(text, source_lang="en")	ITN	normalized text str
client.denoiser(audio_input, output_file="denoised_output.wav")	Audio denoising	output file path str or audio URI str

Speech / Audio

ASR

• Converts speech to text.
• Supports local WAV input, base64 audio, and audio URI input.
• Validates sampling rate, mono audio, speech presence, and processor values.
• Supports optional audio metadata like audio_format, sampling_rate, and encoding through client.asr_service.transcribe(...).
• Supports ASR pre-processors: vad, denoiser
• Supports ASR post-processors: itn, punctuation

TTS

• Synthesizes speech from input text.
• Public method writes output to a file path.
• Advanced service call supports optional speed, speaker_name, text_normalization, profanity_filter, and return_base64.
• Advanced usage is available through client.tts_service.synthesize(...).

Audio Language Detection

• Detects spoken language from audio input.
• Supports local WAV input, base64 audio, and audio URI input.
• Uses default and fallback service routing internally.

Speaker Diarization

• Splits audio into speaker segments with timestamps.
• Supports validated audio input and optional pre-processors.

Speaker Enrollment

• Enrolls a speaker from local audio, base64 audio, or audio URI input.
• Returns a reusable speaker ID.

Speaker Verification

• Verifies whether a voice sample matches an enrolled speaker.
• Supports local audio, base64 audio, and audio URI input.
• Handles nested verification response shapes.

Voice Cloning

• Generates speech from reference text and reference audio.
• Writes cloned audio output to a file.

Denoiser

• Removes noise from audio input.
• Supports local audio, base64 audio, and audio URI input.

Text

NMT

• Translates text between supported language pairs.
• Validates source and target languages through the model registry.
• Uses primary/fallback routing internally.
• Advanced service call supports:
  • glossary
  • domain
  • gender
  • enable_number_translation
  • profanity_filter
  • pre_processors=["html"]
  • post_processors=["glossary"]
• Advanced usage is available through client.nmt_service.translate(...).

Transliteration

• Converts text across scripts without translation.
• Supports suggestion count, sentence mode, and numeric_transliteration in the service layer.

Text Language Detection

• Detects the top language from input text.
• Public methods:
  • client.text_language_detection(text)
  • client.language_detection(text)

Text Normalization

• Normalizes text using a dedicated endpoint.
• Public method returns normalized text.

Inverse Text Normalization

• Converts spoken-style text into normalized written text.
• Public method returns normalized text.

NER

• Extracts entities from text.
• Returns a normalized dictionary with entities.

Vision

OCR

• Extracts text from a local image file.
• Validates file existence and converts the image to base64 internally.

Image Language Detection

• Detects language from:
  • local image path
  • public image URL
  • base64 image content

Advanced Features

Input Flexibility

The SDK supports different input styles depending on the service:

Input Type	Supported In
Local file path	audio, OCR image, image language detection
Base64 string	audio services, image language detection
Remote URI	ASR, Audio Language Detection, Speaker Enrollment, Speaker Verification, Denoiser, Image Language Detection

Model Registry

models_info.py is the central model catalog for service IDs, supported languages, and filtering.

Available helpers:

from bhashini_client import get_models_info, get_available_models

print(get_models_info("asr"))
print(get_available_models("asr", language="hi"))
print(get_available_models("nmt", language=("en", "hi")))
print(get_available_models("tts", language="en"))

Shared Request Layer

• bhashini_client/utils/request_handler.py centralizes HTTP request handling.
• bhashini_client/config.py defines:
  • BASE_URL
  • BHASHINI_API_KEY
  • default timeout
  • default headers

Error Handling

The SDK returns structured string errors from service methods:

Error Prefix	Meaning
Input Error:	Missing input, wrong type, wrong format, unsupported processor, invalid path, or invalid local media
Validation Error:	Unsupported service, model, or language configuration
API Error:	Empty, malformed, or invalid backend response

Examples:

• missing file path
• unsupported language pair
• invalid sampling rate
• malformed API response

Testing

Run the full suite:

python -m pytest tests -v

Run a specific service:

python -m pytest tests\test_asr.py -v

Run the full check script:

.\run_all_checks.ps1

Test outputs are logged into:

• final_bhashini_test_results.xlsx

Design Decisions

• One file per service keeps changes isolated and easier to test.
• request_handler.py keeps transport logic centralized.
• models_info.py keeps service IDs and language support centralized.
• demo.py acts as an end-to-end smoke test across major services.

Known Limitations

• Public BhashiniClient methods expose a simple interface; some advanced parameters are available through the underlying service objects instead of the top-level methods.
• Most service methods return strings, file paths, lists, or dictionaries rather than custom exception objects or typed response classes.
• Some compatibility parameters remain in service signatures even when they are no longer active in payload construction.
• Calls are synchronous through the current request layer.

Package Contents

• bhashini_client.BhashiniClient
• bhashini_client.get_models_info
• bhashini_client.get_available_models

License

MIT