> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nijta.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

# Voice Harbor API

This service provides a comprehensive solution for managing jobs and handling file transfers securely. It allows you to easily create and manage jobs, ensuring that all your multimedia and configuration files are processed reliably.

## Highlevel-workflow:

* **Job Managment:** Create a job, select parameters and add your files.
* **Submit File and Job:** Submit your job and files.
* **Download final results:** Download results for submitted files.

## Key features include:

* **Job Management:** Create new jobs and track job details effortlessly.
* **Secure File Transfers:** Upload and download files safely through temporary, secure access links.
* **Encryption:** All data is encrypted during transit and rest.
* **Flexible File Support:** Handle various file formats, ensuring compatibility with your project needs.
* **User-Friendly Interface:** Benefit from a modern web interface that simplifies job and file management.
* **Robust Access Control:** Enjoy secure interactions with verified tokens for both users and administrators.

# Voice Harbor Python SDK

A Python client for interacting with the [Voice Harbor API](#). This client handles job creation, file uploads, and result downloads through secure signed URLs. It supports audio file formats.
The client is designed to provide an end-to-end solution for managing voice processing jobs with the Voice Harbor API, offering both ease of use as a CLI tool and flexibility for integration into larger Python projects.

## Features

* **Job Management:** Create new jobs and retrieve job details.
* **File Parsing & Validation:** Automatically scans an input directory and filters files by supported formats (.wav, .mp3, ...).
* **Secure File Uploads:** Uses signed URLs to securely upload files via HTTP PUT requests.
* **Job Submission:** Generates a YAML job file with all job parameters and uploads it securely.
* **Polling & Result Downloading:** Downloads both processed files and their corresponding JSON metadata concurrently.
* **Logging & Error Handling:** Provides a CLI with customizable options for API URL, authorization token, input/output directories, timeout settings, agents, and more.
* **Command-Line Interface (CLI):** Offers detailed logging of operations and robust error management for easier troubleshooting.

## Supported File Formats

The client currently supports the following file types as stereo and mono:

* `.wav`
* `.mp3`
* `.flac`
* `.ogg`
* `.m4a`

## Requirements

* Python 3.6 or higher

### Python Dependencies

The client depends on the following Python packages:

* `requests`
* `PyYAML`
* `tqdm`

You can install these dependencies with pip. For example, in your terminal you might run:

pip install requests pyyaml tqdm

## Installation

### From Source

1. Clone the repository from GitHub.
2. Change into the project directory.
3. Install the package in editable mode using pip:

```bash theme={null}
  pip install -e .
```

## Usage

### Command-Line Interface (CLI)

After installation, the CLI is available as `voice-harbor-client`. The tool accepts several parameters:

* **--base-url:** (Required) The base URL of the Voice Harbor API.
* **--token:** (Required) Your authorization token.
* **--inputs-dir:** (Required) Directory containing input files to be processed.
* **--output-dir:** Directory where the downloaded results will be stored (default: `./results`).
* **--timeout:** Timeout in seconds for waiting on file availability (default: 600).
* **--interval:** Polling interval in seconds to check file status (default: 10).
* **--agents:** List of agents to use for processing (default: `health-generic`).
* **--prefix:** An optional prefix to include files containing prefix in their name.

**Example Usage:**

You can run the tool from the command line like this:

```bash theme={null}
python voice_harbor_client.py \
    --base-url https://voiceharbor.ai \
    --token YOUR_AUTH_TOKEN \
    --inputs-dir /path/to/input_files \
    --output-dir /path/to/output_results \
    --timeout 600 \
    --interval 10 \
    --agents health-generic clinical \
    --prefix "optional-prefix"
```

### Programmatic Admin Usage

You will be provided with a ADMIN token by [sales@nijta.com](mailto:sales@nijta.com).

Generate a developer token:

```python theme={null}
BASE_URL = "https://voiceharbor.ai"
admin_token = "TOKEN"
usage_token = VoiceHarborClient.create_developer_token(BASE_URL, admin_token)
# Received developer token stored below: ./credentials/VoiceHarbor_Developer.credential.<date>.yaml.
```

#### Get Job's and finilized results overview

List all developer tokens generated by admin.

```python theme={null}
usage_tokens = VoiceHarborClient.get_developer_tokens(BASE_URL, ADMIN_TOKEN)
```

List total global usage generated by all developer tokens.

```python theme={null}
BASE_URL = "https://voiceharbor.ai"
for token_metadata in usage_tokens:
    jobs_metadata = VoiceHarborClient.get_jobs(BASE_URL, token_metadata['usage_token'])
    for job_metadata in jobs_metadata:
        print (VoiceHarborClient.get_job_content(BASE_URL, usage_token, job_metadata['job_id']))
```

The output is a JSON response represented as a dictionary with the following fields:

```bash theme={null}
id: A unique integer identifier for the audio record.
job_id: A unique string representing the job associated with the audio file.
file_name: The name of the audio file.
audio_duration: The duration of the audio file in seconds.
created_at: An ISO 8601 timestamp indicating when the audio file was created.
```

### Programmatic Developer Usage

The client can also be used as a Python module. For example:

#### Immediate Job Submission and Results Download

```python theme={null}
BASE_URL = "https://voiceharbor.ai"
usage_token = "TOKEN"
# Create a new job on the server via the class method.
# Create a new job immediately.
job_id = VoiceHarborClient.create_job(BASE_URL, usage_token)
print(f"Job created with ID: {job_id}")

# Initialize the client with the new job_id and input directory.
client = VoiceHarborClient(
    base_url=BASE_URL,
    job_id=job_id,
    token=AUTH_TOKEN,
    inputs_dir="./inputs"
)

# Build job parameters (e.g., list of agents and any other details).
job_params = {
    "agents": ["health-generic"],
    "files": []  # The submit_files method will append uploaded file names.
}

# Upload input files.
job_params = client.submit_files(job_params)

# Immediately submit the job file (YAML)
job_file = client.submit_job(job_params)
print(f"Job file submitted: {job_file}")

# Wait for and download the processed results.
downloaded_results = client.download_results(output_dir="./results")
print("Downloaded results:", downloaded_results)
```

#### Delayed Job Start

```python theme={null}
BASE_URL = "https://voiceharbor.ai"
usage_token = "TOKEN"

# Create a new job.
job_id = VoiceHarborClient.create_job(BASE_URL, usage_token)
print(f"Job created with ID: {job_id}")

# Initialize the client with the new job_id.
client = VoiceHarborClient(
    base_url=BASE_URL,
    job_id=job_id,
    token=AUTH_TOKEN,
    inputs_dir="./inputs"
)

# Upload input files without submitting the job file immediately.
job_params = {
    "agents": ["health-generic"],
    "files": []
}
job_params = client.submit_files(job_params)

# Store the job parameters locally for later submission.
job_params_file = f"{job_id}_job_params.json"
with open(job_params_file, "w") as f:
    json.dump(job_params, f)
print(f"Job parameters stored for later submission: {job_params_file}")
```

Simulate a delay (e.g., waiting until tomorrow to submit the job file).

```python theme={null}
# Later, load the stored job parameters and submit the job file.
with open(job_params_file, "r") as f:
    delayed_job_params = json.load(f)
job_file = client.submit_job(delayed_job_params)
print(f"Delayed job file submitted: {job_file}")

# Download the results when processing is complete.
downloaded_results = client.download_results(output_dir="./results")
print("Downloaded results:", downloaded_results)
```

#### Scheduled Download Use Case

In this scenario, you create and submit a job as usual. The job file (a YAML file named using the job\_id) is saved locally. Then, at a later time (for example, the next day), you reinitialize your client using the same job\_id and trigger the download of results.

***Step 1:*** Job Creation and Submission (Today).
Run the following script to create a job, upload input files, and submit the job file. This script also stores the job parameters locally (optionally) and writes the YAML file (named with the job\_id) which can be used later to trigger the download.

```python theme={null}
BASE_URL = "https://voiceharbor.ai"
usage_token = "TOKEN"
# Create a new job.
job_id = VoiceHarborClient.create_job(BASE_URL, usage_token)
logger.info(f"Job created with ID: {job_id}")

# Initialize the client with the new job_id and input directory.
client = VoiceHarborClient(
    base_url=BASE_URL,
    job_id=job_id,
    token=AUTH_TOKEN,
    inputs_dir="./inputs"  # Directory containing files to be uploaded.
)

# Build job parameters. For example, specify which agents to use.
job_params = {
    "agents": ["health-generic"],
    "files": []  # The submit_files method will append the names of uploaded files.
}

# Upload input files.
job_params = client.submit_files(job_params)

# Submit the job file (this writes a YAML file named as {job_id}.yaml).
job_file = client.submit_job(job_params)
logger.info(f"Job file submitted and saved locally as: {job_file}")  # <--- JOB_FILE_PATH
```

***Step 2:*** Scheduled Download (Tomorrow)

When you're ready to download the results—say, tomorrow—you can run a separate script that reinitializes the client with the known job\_id (from the YAML file name) and then calls the download function to retrieve the processed results.

```python theme={null}
BASE_URL = "https://voiceharbor.ai"
usage_token = "TOKEN"

# Use a existing job_id.
JOB_ID = "<job_id>" # <--- JOB_ID 

# Reinitialize the client with the same job_id (inputs_dir is not required for download).
client = VoiceHarborClient(
    base_url=BASE_URL,
    job_id=JOB_ID,
    token=AUTH_TOKEN,
    inputs_dir=""  # No need for input files when only downloading results.
)

# Download the processed results, pass the yaml file created during last step.
downloaded_results = client.download_results(output_dir="./results", yaml=job_file)
logger.info(f"Downloaded results for job {JOB_ID}: {downloaded_results}")
```