# vulavula
`vulavula` is a Python client SDK designed to interact with the Vulavula API. It simplifies making requests to endpoints such as transcription, file uploads, sentiment analysis, and entity recognition. The SDK also handles network communications, error handling, and response parsing, providing a friendlier interface for developers.
## Features
- Simple and intuitive API methods for:
- Transcribing audio files
- Uploading files
- Entity recognition
- Sentiment analysis
- Custom error handling
- Supports Python 3.8 and newer
## Installation
You can install the `vulavula` using pip:
```bash
pip install vulavula
```
For developers using PDM, add it directly to your project:
```bash
pdm add vulavula
```
## Usage
Here's a quick example to get you started:
```python
from vulavula import VulavulaClient
# Initialize the client with your API token
client = VulavulaClient("<INSERT_TOKEN>")
```
### Transcribe an audio file
Transcribe an audio file by specifying the file path and optionally providing a webhook URL for asynchronous result delivery:
```python
transcription_result = client.transcribe("path/to/your/audio/file.wav", webhook="<INSERT_URL>")
print("Transcription Submit Success:", transcription_result) #A success message, data is sent to webhook
```
#### Inputs:
- `file_path`: A string path to the audio file you want to transcribe.
- `webhook`: Optional. A URL to which the server will send a POST request with the transcription results.
### Upload a file
Upload audio file to the server and receive an upload ID:
```python
upload_result = client.upload_file('path/to/your/file')
print(upload_result)
```
#### Inputs:
- `file_path`: The path to the file you wish to upload.
### Perform sentiment analysis
Analyze the sentiment of a piece of text:
```python
sentiment_result = client.get_sentiments({'encoded_text': 'Ngijabulile!'})
print(sentiment_result)
```
#### Inputs:
- `data`: A dictionary with a key `encoded_text` that contains the text to analyze.
### Perform entity recognition on text data
Perform entity recognition to identify named entities within the text, such as people, places, and organizations.
```python
entity_result = client.get_entities({'text': 'President Ramaphosa gaan loop by Emfuleni Municipality.'})
print("Entity Recognition Output:", entity_result)
```
#### Inputs:
- `data`: A dictionary with a key `encoded_text` that contains the text for entity recognition.
### Intent Classification
Train the model with examples and classify new inputs to determine the intent behind each input sentence.
```python
classification_data = {
"examples": [
{"intent": "greeting", "example": "Hello!"},
{"intent": "greeting", "example": "Hi there!"},
{"intent": "goodbye", "example": "Goodbye!"},
{"intent": "goodbye", "example": "See you later!"}
],
"inputs": [
"Hey, how are you?",
"I must be going now."
]
}
classification_results = client.classify(classification_data)
print("Classification Results:", classification_results)
```
#### Inputs:
- `data`: A dictionary containing two keys:
- `examples`: A list of dictionaries where each dictionary represents a training example with an `intent` and an `example` text.
- `inputs`: A list of strings, each a new sentence to classify based on the trained model.
#### Classification Results:
- The output is a list of dictionaries, each corresponding to an input sentence.
- Each dictionary contains a list of `probabilities`, where each item is another dictionary detailing an `intent` and its associated `score` (a confidence level).
### Error Handling
This section covers how to handle errors gracefully when using the Vulavula API.
#### Handling Specific Errors with VulavulaError
The `VulavulaError` is a custom exception class designed to provide detailed information about errors encountered during API interactions. It includes a human-readable message and a structured JSON object containing additional error details. <br>
Here’s an example of how to handle `VulavulaError`:
```python
try:
entity_result = client.get_entities({'text': 'President Ramaphosa gaan loop by Emfuleni Municipality.'})
print("Entity Recognition Output:", entity_result)
except VulavulaError as e:
print("An error occurred:", e.message)
if 'details' in e.error_data:
print("Error Details:", e.error_data['details'])
else:
print("No additional error details are available.")
except Exception as e:
print("An unexpected error occurred:", str(e))
```
#### General Exception Handling
While `VulavulaError` handles expected API-related errors, your application might encounter other unexpected exceptions. It's important to prepare for these to ensure your application can recover gracefully.
Here's a general approach to handle unexpected exceptions:
```python
try:
response = client.transcribe()
print("Action Succeeded:", response)
except VulavulaError as e:
print("Handled VulavulaError:", e.message)
if 'details' in e.error_data:
print("Detailed Error Information:", e.error_data['details'])
except Exception as e:
print("Unhandled Exception:", str(e))
```
## Documentation
For full documentation on using the VulavulaClient, visit the [official documentation](https://docs.lelapa.ai/).
Raw data
{
"_id": null,
"home_page": null,
"name": "vulavula",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "lelapa, vulavula, nlp, intent, multilingual, transcription",
"author": null,
"author_email": "Raphael Karanja <raphael.karanja@lelapa.ai>",
"download_url": "https://files.pythonhosted.org/packages/9f/ae/df186d16f87fa59c4c5343f8746e7ccf80ea09c6613bd7b5b1da83e7aa2a/vulavula-0.1.1.tar.gz",
"platform": null,
"description": "# vulavula\n`vulavula` is a Python client SDK designed to interact with the Vulavula API. It simplifies making requests to endpoints such as transcription, file uploads, sentiment analysis, and entity recognition. The SDK also handles network communications, error handling, and response parsing, providing a friendlier interface for developers.\n\n## Features\n\n- Simple and intuitive API methods for:\n - Transcribing audio files\n - Uploading files\n - Entity recognition\n - Sentiment analysis\n- Custom error handling\n- Supports Python 3.8 and newer\n\n## Installation\n\nYou can install the `vulavula` using pip:\n\n```bash\npip install vulavula\n```\n\nFor developers using PDM, add it directly to your project:\n\n```bash\npdm add vulavula\n```\n\n## Usage\nHere's a quick example to get you started:\n\n```python\nfrom vulavula import VulavulaClient\n\n# Initialize the client with your API token\nclient = VulavulaClient(\"<INSERT_TOKEN>\")\n\n```\n\n### Transcribe an audio file\nTranscribe an audio file by specifying the file path and optionally providing a webhook URL for asynchronous result delivery:\n```python\ntranscription_result = client.transcribe(\"path/to/your/audio/file.wav\", webhook=\"<INSERT_URL>\")\nprint(\"Transcription Submit Success:\", transcription_result) #A success message, data is sent to webhook\n```\n\n#### Inputs:\n\n- `file_path`: A string path to the audio file you want to transcribe.\n- `webhook`: Optional. A URL to which the server will send a POST request with the transcription results.\n\n### Upload a file\nUpload audio file to the server and receive an upload ID:\n```python\nupload_result = client.upload_file('path/to/your/file')\nprint(upload_result)\n```\n#### Inputs:\n- `file_path`: The path to the file you wish to upload.\n\n### Perform sentiment analysis\nAnalyze the sentiment of a piece of text:\n```python\nsentiment_result = client.get_sentiments({'encoded_text': 'Ngijabulile!'})\nprint(sentiment_result)\n```\n#### Inputs:\n- `data`: A dictionary with a key `encoded_text` that contains the text to analyze.\n\n### Perform entity recognition on text data\nPerform entity recognition to identify named entities within the text, such as people, places, and organizations.\n```python\nentity_result = client.get_entities({'text': 'President Ramaphosa gaan loop by Emfuleni Municipality.'})\nprint(\"Entity Recognition Output:\", entity_result)\n```\n#### Inputs:\n- `data`: A dictionary with a key `encoded_text` that contains the text for entity recognition.\n\n### Intent Classification\nTrain the model with examples and classify new inputs to determine the intent behind each input sentence.\n```python\nclassification_data = {\n \"examples\": [\n {\"intent\": \"greeting\", \"example\": \"Hello!\"},\n {\"intent\": \"greeting\", \"example\": \"Hi there!\"},\n {\"intent\": \"goodbye\", \"example\": \"Goodbye!\"},\n {\"intent\": \"goodbye\", \"example\": \"See you later!\"}\n ],\n \"inputs\": [\n \"Hey, how are you?\",\n \"I must be going now.\"\n ]\n}\nclassification_results = client.classify(classification_data)\nprint(\"Classification Results:\", classification_results)\n```\n#### Inputs:\n- `data`: A dictionary containing two keys:\n - `examples`: A list of dictionaries where each dictionary represents a training example with an `intent` and an `example` text.\n - `inputs`: A list of strings, each a new sentence to classify based on the trained model.\n\n#### Classification Results:\n- The output is a list of dictionaries, each corresponding to an input sentence.\n- Each dictionary contains a list of `probabilities`, where each item is another dictionary detailing an `intent` and its associated `score` (a confidence level).\n\n### Error Handling\nThis section covers how to handle errors gracefully when using the Vulavula API.\n\n#### Handling Specific Errors with VulavulaError\nThe `VulavulaError` is a custom exception class designed to provide detailed information about errors encountered during API interactions. It includes a human-readable message and a structured JSON object containing additional error details. <br>\nHere\u2019s an example of how to handle `VulavulaError`:\n```python\ntry:\n entity_result = client.get_entities({'text': 'President Ramaphosa gaan loop by Emfuleni Municipality.'})\n print(\"Entity Recognition Output:\", entity_result)\nexcept VulavulaError as e:\n print(\"An error occurred:\", e.message)\n if 'details' in e.error_data:\n print(\"Error Details:\", e.error_data['details'])\n else:\n print(\"No additional error details are available.\")\nexcept Exception as e:\n print(\"An unexpected error occurred:\", str(e))\n\n```\n\n#### General Exception Handling\nWhile `VulavulaError` handles expected API-related errors, your application might encounter other unexpected exceptions. It's important to prepare for these to ensure your application can recover gracefully. \n\nHere's a general approach to handle unexpected exceptions:\n```python\ntry:\n response = client.transcribe()\n print(\"Action Succeeded:\", response)\nexcept VulavulaError as e:\n print(\"Handled VulavulaError:\", e.message)\n if 'details' in e.error_data:\n print(\"Detailed Error Information:\", e.error_data['details'])\nexcept Exception as e:\n print(\"Unhandled Exception:\", str(e))\n\n```\n\n## Documentation\nFor full documentation on using the VulavulaClient, visit the [official documentation](https://docs.lelapa.ai/).",
"bugtrack_url": null,
"license": "MIT",
"summary": "The vulavula Python SDK provides access to the Vulavula API.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/Lelapa-AI/vulavula-sdk"
},
"split_keywords": [
"lelapa",
" vulavula",
" nlp",
" intent",
" multilingual",
" transcription"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "17da32ae817e77c15a099032999ca9ea55cdfb82558789a9cc10725dc77a7c70",
"md5": "87259ce142d72d20affdb3fc66413889",
"sha256": "cf12bc27cc45a05fb17cab2e390e5cce6cac68061083eaeeb4e6c35a4b39be66"
},
"downloads": -1,
"filename": "vulavula-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "87259ce142d72d20affdb3fc66413889",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 15235,
"upload_time": "2024-05-02T11:16:54",
"upload_time_iso_8601": "2024-05-02T11:16:54.697080Z",
"url": "https://files.pythonhosted.org/packages/17/da/32ae817e77c15a099032999ca9ea55cdfb82558789a9cc10725dc77a7c70/vulavula-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9faedf186d16f87fa59c4c5343f8746e7ccf80ea09c6613bd7b5b1da83e7aa2a",
"md5": "7e39699c1bf24dbf4b8da60d2e4e9369",
"sha256": "d43487748b6d39b97c57277a12d56aaeee4d4c1556cfb2a14dff2e8120c613d9"
},
"downloads": -1,
"filename": "vulavula-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "7e39699c1bf24dbf4b8da60d2e4e9369",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13075,
"upload_time": "2024-05-02T11:16:56",
"upload_time_iso_8601": "2024-05-02T11:16:56.983471Z",
"url": "https://files.pythonhosted.org/packages/9f/ae/df186d16f87fa59c4c5343f8746e7ccf80ea09c6613bd7b5b1da83e7aa2a/vulavula-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-02 11:16:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Lelapa-AI",
"github_project": "vulavula-sdk",
"github_not_found": true,
"lcname": "vulavula"
}
JSON
