Metadata-Version: 2.4
Name: bhashini-client-sdk
Version: 0.2.1
Summary: Python SDK for Bhashini inference APIs with unified support for ASR, NMT, TTS, OCR, NER, speaker services, normalization, and image-language workflows.
Home-page: https://github.com/bhashini-dibd/Bhashini-client-python-library.git
Author: Nidhi Jha
License: MIT
Project-URL: Homepage, https://github.com/bhashini-dibd/Bhashini-client-python-library.git
Project-URL: Source, https://github.com/bhashini-dibd/Bhashini-client-python-library.git
Project-URL: Issues, https://github.com/bhashini-dibd/Bhashini-client-python-library.git
Keywords: bhashini,asr,nmt,tts,ocr,ner,translation,speech
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: openpyxl>=3.1.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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

```text
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:

```bash
pip install -r requirements.txt
```

Package name:

```bash
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:

```powershell
$env:BHASHINI_API_KEY="your_api_key"
```

Or in code:

```python
from bhashini_client import BhashiniClient

client = BhashiniClient(api_key="your_api_key")
```

## Quick Start

```python
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:

```powershell
python demo.py
```

Optional sample files:

```powershell
$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:

```python
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:

```powershell
python -m pytest tests -v
```

Run a specific service:

```powershell
python -m pytest tests\test_asr.py -v
```

Run the full check script:

```powershell
.\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
