Python Client
This document provides information about how to use Private AI's Python client to interact with the container or cloud API. In addition to this guide, you might find the Github repository helpful. It contains further examples and usage options.
Installation
The Python client is available for download on pypi.org or with pip:
pip install privateai_client
Quick Start
from privateai_client import PAIClient
from privateai_client import request_objects
client = PAIClient(url="http://localhost:8080")
text_request = request_objects.process_text_obj(text=["My sample name is John Smith"])
response = client.process_text(text_request)
print(text_request.text)
print(response.processed_text)
Output:
['My sample name is John Smith']
['My sample name is [NAME_1]']
Working with the Client
Initializing the Client for self-hosted container
The PAI client requires a scheme, host, and optional port to initialize.
Alternatively, a full url can be used.
Once created, the connection can be tested with the client's ping
function
from privateai_client import PAIClient
scheme = 'http'
host = 'localhost'
port= '8080'
client = PAIClient(scheme, host, port)
client.ping()
url = "http://localhost:8080"
client = PAIClient(url=url)
client.ping()
Output:
True
True
Note: The container is hosted with your provisioned application license and does not manage authentication to the API or authorization of API requests. Access to the container is at the discretion of the user. For recommendations on how to deploy in an enterprise context including authorized use, please contact us.
Initializing the Client for our cloud-API offering
To access the cloud API, you need to authenticate with your API key. You can get one from the customer portal.
from privateai_client import PAIClient
# Adding credentials on initialization
client = PAIClient(url="https://api.private-ai.com/community/", api_key='<YOUR API KEY>')
# Adding credentials after initialization
client = PAIClient(url="https://api.private-ai.com/community/")
client.ping()
client.add_api_key('<YOUR API KEY>')
client.ping()
Output:
The request returned with a 401 Unauthorized
True
Making Requests
Once initialized the client can be used to make any request listed in the API documentation.
Available requests:
Client Function | Endpoint |
---|---|
get_version() |
/ |
ping() |
/healthz |
get_metrics() |
/metrics |
get_diagnostics() |
/diagnostics |
ner_text() |
/ner/text |
process_text() |
/process/text |
process_files_uri() |
/process/files/uri |
process_files_base64() |
/process/files/base64 |
bleep() |
/bleep |
Requests can be made using dictionaries:
sample_text = ["This is John Smith's sample dictionary request"]
text_dict_request = {"text": sample_text}
response = client.process_text(text_dict_request)
print(response.processed_text)
Output:
["This is [NAME_1]'s sample dictionary request"]
or using built-in request objects:
from privateai_client import request_objects
sample_text = "This is John Smith's sample process text object request"
text_request_object = request_objects.process_text_obj(text=[sample_text])
response = client.process_text(text_request_object)
print(response.processed_text)
Output:
["This is [NAME_1]'s sample process text object request"]
Request Objects
Request objects are a simple way of creating request bodies without the tediousness of writing dictionaries. Every POST request (as listed in the Private AI API documentation) has its own request own request object.
from privateai_client import request_objects
sample_obj = request_objects.file_uri_obj(uri='path/to/file.jpg')
sample_obj.uri
Output:
'path/to/file.jpg'
Additionally there are request objects for each nested dictionary of a request:
from privateai_client import request_objects
sample_text = "This is John Smith's sample process text object request where names won't be removed"
# sub-dictionary of entity_detection
sample_entity_type_selector = request_objects.entity_type_selector_obj(type="DISABLE", value=['NAME', 'NAME_GIVEN', 'NAME_FAMILY'])
# sub-dictionary of a process text request
sample_entity_detection = request_objects.entity_detection_obj(entity_types=[sample_entity_type_selector])
# request object created using the sub-dictionaries
sample_request = request_objects.process_text_obj(text=[sample_text], entity_detection=sample_entity_detection)
response = client.process_text(sample_request)
print(response.processed_text)
Output:
["This is John Smith's sample process text object request where names won't be removed"]
Building Request Objects
Request objects can initialized by passing in all the required values needed for the request as arguments or from a dictionary, using the object's fromdict()
function:
# Passing arguments
sample_data = "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoc2FtcGxlKQovUHJvZHVj..."
sample_content_type = "application/pdf"
sample_file_obj = request_objects.file_obj(data=sample_data, content_type=sample_content_type)
# Passing a dictionary using .fromdict()
sample_dict = {"data": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoc2FtcGxlKQovUHJvZHVj...",
"content_type": "application/pdf"}
sample_file_obj2 = request_objects.file_obj.fromdict(sample_dict)
Request objects also can be formatted as dictionaries, using the request object's to_dict()
function:
from privateai_client import request_objects
sample_text = "Sample text."
# Create the nested request objects
sample_entity_type_selector = request_objects.entity_type_selector_obj(type="DISABLE", value=['HIPAA_SAFE_HARBOR'])
sample_entity_detection = request_objects.entity_detection_obj(entity_types=[sample_entity_type_selector])
# Create the request object
sample_request = request_objects.process_text_obj(text=[sample_text], entity_detection=sample_entity_detection)
# All nested request objects are also formatted
print(sample_request.to_dict())
Output:
{
'text': ['Sample text.'],
'link_batch': False,
'entity_detection': {'accuracy': 'high', 'entity_types': [{'type': 'DISABLE', 'value': ['HIPAA_SAFE_HARBOR']}], 'filter': [], 'return_entity': True},
'processed_text': {'type': 'MARKER', 'pattern': '[UNIQUE_NUMBERED_ENTITY_TYPE]'}
}
Sample Use
Processing a directory of files with URI route
from privateai_client import PAIClient
from privateai_client.objects import request_objects
import os
import logging
file_dir = "/path/to/file/directory"
client = PAIClient(url="http://localhost:8080")
for file_name in os.listdir(file_dir):
filepath = os.path.join(file_dir, file_name)
if not os.path.isfile(filepath):
continue
req_obj = request_objects.file_uri_obj(uri=filepath)
# NOTE this method of file processing requires the container to have an the input and output directories mounted
resp = client.process_files_uri(req_obj)
if not resp.ok:
logging.error(f"response for file {file_name} returned with {resp.status_code}")
Processing a file with Base64 route
from privateai_client import PAIClient
from privateai_client.objects import request_objects
import base64
import os
import logging
file_dir = "/path/to/your/file"
file_name = 'sample_file.pdf'
filepath = os.path.join(file_dir,file_name)
file_type= "type/of_file" #eg. application/pdf
client = PAIClient(url="http://localhost:8080")
# Read from file
with open(filepath, "rb") as b64_file:
file_data = base64.b64encode(b64_file.read())
file_data = file_data.decode("ascii")
# Make the request
file_obj = request_objects.file_obj(data=file_data, content_type=file_type)
request_obj = request_objects.file_base64_obj(file=file_obj)
resp = client.process_files_base64(request_object=request_obj)
if not resp.ok:
logging.error(f"response for file {file_name} returned with {resp.status_code}")
# Write to file
with open(os.path.join(file_dir,f"redacted-{file_name}"), 'wb') as redacted_file:
processed_file = resp.processed_file.encode("ascii")
processed_file = base64.b64decode(processed_file, validate=True)
redacted_file.write(processed_file)
Bleep an audio file
from privateai_client import PAIClient
from privateai_client.objects import request_objects
import base64
import os
import logging
file_dir = "/path/to/your/file"
file_name = 'sample_file.pdf'
filepath = os.path.join(file_dir,file_name)
file_type= "type/of_file" #eg. audio/mp3 or audio/wav
client = PAIClient(url="http://localhost:8080")
file_dir = "/home/adam/workstation/file_processing/test_audio"
file_name = "test_audio.mp3"
filepath = os.path.join(file_dir,file_name)
file_type = "audio/mp3"
with open(filepath, "rb") as b64_file:
file_data = base64.b64encode(b64_file.read())
file_data = file_data.decode("ascii")
file_obj = request_objects.file_obj(data=file_data, content_type=file_type)
timestamp = request_objects.timestamp_obj(start=1.12, end=2.14)
request_obj = request_objects.bleep_obj(file=file_obj, timestamps=[timestamp])
resp = client.bleep(request_object=request_obj)
if not resp.ok:
logging.error(f"response for file {file_name} returned with {resp.status_code}")
with open(os.path.join(file_dir,f"redacted-{file_name}"), 'wb') as redacted_file:
processed_file = resp.bleeped_file.encode("ascii")
processed_file = base64.b64decode(processed_file, validate=True)
redacted_file.write(processed_file)