# 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
- Embeddings Search
- Translation
- 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>", language_code="<INSERT_CODE>",)
#language_code example 'zul' and together with webhook are optional
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 string) A URL to which the server will send a POST request with the transcription results.
- `language_code`: (Optional string) The language code for the uploaded file
### 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).
### Knowledge Base
##### Create a Knowledge Base (Search)
Create a collection of documents for search:
```python
knowledge_base_result = client.create_knowledgebase("<knowledge base name>")
print("Knowledge Base Creation Result:", knowledge_base_result)
```
##### Get knowledgebases(Search)
```python
knowledgebases = client.get_knowledgebases()
print("Knowledge Bases:", knowledgebases)
```
##### Delete knowledgebase (Search)
```python
delete_result = client.delete_knowledgebase("<knowledgebase id >")
print("Delete Result:", delete_result)
```
##### Create Documents (Search)
Upload a file and extract text to create documents in a collection:
```python
result = client.create_documents(
"<document name>.pdf",
"<knowledgebase id >"
)
print("Upload and Extract Result:", result)
```
##### Get uploaded Documents (Search)
```python
result = client.get_documents("<knowledgebase id>")
print(result)
```
##### Delete document (Search)
```python
delete_result = client.delete_document("<document id>")
print("Delete Result:", delete_result)
```
##### Query (Search)
Perform a search query in a specific language:
```python
result = client.query(knowledgebase_id="2f422c4d-ed93-430a-870e-ce8245397e00",query="active learning",language="en_Us")
print(result)
```
### Translate Text
Translate text from one language to another:
```python
translation_data = {
"input_text": "Lo musho ubhalwe ngesiZulu.",
"source_lang": "zul_Latn",
"target_lang": "eng_Latn"
}
translation_result = client.translate(translation_data)
print("Translation Result:", translation_result)
```
Upload a file and extract text to create documents in a collection:
### 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:
upload_id, 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/d9/8d/c4f00a4e1a50680228c0f49c28fc5a9e2bdc31b3da738a2b109dcf091150/vulavula-0.4.3.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 - Embeddings Search \n - Translation\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>\", language_code=\"<INSERT_CODE>\",)\n#language_code example 'zul' and together with webhook are optional\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 string) A URL to which the server will send a POST request with the transcription results.\n- `language_code`: (Optional string) The language code for the uploaded file\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\n### Knowledge Base\n##### Create a Knowledge Base (Search)\nCreate a collection of documents for search:\n```python\nknowledge_base_result = client.create_knowledgebase(\"<knowledge base name>\")\nprint(\"Knowledge Base Creation Result:\", knowledge_base_result)\n```\n\n##### Get knowledgebases(Search)\n```python\nknowledgebases = client.get_knowledgebases()\nprint(\"Knowledge Bases:\", knowledgebases)\n```\n\n##### Delete knowledgebase (Search)\n```python\ndelete_result = client.delete_knowledgebase(\"<knowledgebase id >\")\nprint(\"Delete Result:\", delete_result)\n```\n\n##### Create Documents (Search)\nUpload a file and extract text to create documents in a collection:\n```python\nresult = client.create_documents(\n \"<document name>.pdf\", \n \"<knowledgebase id >\"\n )\nprint(\"Upload and Extract Result:\", result)\n```\n##### Get uploaded Documents (Search)\n```python\nresult = client.get_documents(\"<knowledgebase id>\")\nprint(result)\n```\n\n##### Delete document (Search)\n```python\ndelete_result = client.delete_document(\"<document id>\")\nprint(\"Delete Result:\", delete_result)\n```\n\n##### Query (Search)\nPerform a search query in a specific language:\n```python\nresult = client.query(knowledgebase_id=\"2f422c4d-ed93-430a-870e-ce8245397e00\",query=\"active learning\",language=\"en_Us\")\nprint(result)\n```\n\n### Translate Text\nTranslate text from one language to another:\n```python\ntranslation_data = {\n \"input_text\": \"Lo musho ubhalwe ngesiZulu.\",\n \"source_lang\": \"zul_Latn\",\n \"target_lang\": \"eng_Latn\"\n}\ntranslation_result = client.translate(translation_data)\nprint(\"Translation Result:\", translation_result)\n```\n\nUpload a file and extract text to create documents in a collection:\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 upload_id, 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\n## Documentation\nFor full documentation on using the VulavulaClient, visit the [official documentation](https://docs.lelapa.ai/).\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The vulavula Python SDK provides access to the Vulavula API.",
"version": "0.4.3",
"project_urls": {
"Homepage": "https://github.com/Lelapa-AI/vulavula-sdk"
},
"split_keywords": [
"lelapa",
" vulavula",
" nlp",
" intent",
" multilingual",
" transcription"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0400bad89d8afdab2137cf9f76736129ec7df5bbf833fbe51fe17f41b8ef25a7",
"md5": "12db8ab7cac3b8e3e9f612edf17c9034",
"sha256": "97e43abc82c76d8904ceea598bf7692f9b54d31ea195250b75ab20d558e45584"
},
"downloads": -1,
"filename": "vulavula-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "12db8ab7cac3b8e3e9f612edf17c9034",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 19695,
"upload_time": "2024-10-01T14:09:30",
"upload_time_iso_8601": "2024-10-01T14:09:30.822100Z",
"url": "https://files.pythonhosted.org/packages/04/00/bad89d8afdab2137cf9f76736129ec7df5bbf833fbe51fe17f41b8ef25a7/vulavula-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d98dc4f00a4e1a50680228c0f49c28fc5a9e2bdc31b3da738a2b109dcf091150",
"md5": "702752f18e0b409e7a239f5c62d5f7eb",
"sha256": "1039de4d4cbcb288b643a060805b266c7b58c8675208f778a209843399dfee8a"
},
"downloads": -1,
"filename": "vulavula-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "702752f18e0b409e7a239f5c62d5f7eb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15645,
"upload_time": "2024-10-01T14:09:32",
"upload_time_iso_8601": "2024-10-01T14:09:32.251473Z",
"url": "https://files.pythonhosted.org/packages/d9/8d/c4f00a4e1a50680228c0f49c28fc5a9e2bdc31b3da738a2b109dcf091150/vulavula-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-01 14:09:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Lelapa-AI",
"github_project": "vulavula-sdk",
"github_not_found": true,
"lcname": "vulavula"
}
JSON
