castleguard-sdk 0.25

A Python SDK for interacting with CastleGuard APIs

CastleGuard Python SDK

The CastleGuard Python SDK provides a convenient interface to interact with CastleGuard's API. This SDK allows you to authenticate, log messages, interact with the chatbot, translate text, perform named entity recognition (NER), transcribe audio files, manage document collections, work with vision-based models, and more.

Features

• Authentication: Easily authenticate and retrieve an access token to interact with CastleGuard APIs.
• Logging: Send log messages to CastleGuard's logging endpoint.
• Chatbot Integration: Interact with CastleGuard's chatbot to generate responses based on input prompts, with or without document collections.
• Translation: Translate text between languages, supporting English and French.
• Named Entity Recognition (NER): Perform NER on text to extract important entities.
• Vision: Perform image-based tasks using a vision model by uploading an image with a descriptive prompt.
• Transcription: Upload and transcribe audio files, and download SRT subtitles.
• Collections: Manage document collections by creating, uploading, and retrieving the status of files.
• Heartbeat: Fetch the health status of various system components.
• Text Extraction: Extract paragraphs from raw text or extract text from a document file.

Installation

Install the package via pip:

pip install castleguard-sdk

Usage

Initialization

To begin, initialize the CastleGuard class with your API credentials:

from castleguard_sdk import CastleGuard

cg = CastleGuard(base_url='https://your-castleguard-url', username='your-username', password='your-password')

Authentication

The class automatically handles authentication. The access token is retrieved upon initialization and used for subsequent API requests.

Logging

Log a message with a specific log level (default is 1):

cg.log("This is a log message", logLevel=2)

Chatbot Interaction

Send a prompt to the chatbot and get a response:

response, chat_id = cg.chat("What is the weather today?")
print(response)

You can also chat within the context of a document collection:

response, chat_id = cg.chat_with_collection("Summarize the document", collection_id="your-collection-id")
print(response)

Translation

1. Instant Text Translation

Translate a single text with translate_text:

translated_text = cg.translate_text("Hello, how are you?", source_lang="en", target_lang="fr")
print(translated_text)

Parameters

• text: The text string to be translated.
• source_lang: Source language code.
• target_lang: Target language code.

Returns

• The translated text. Returns None if an error occurs.

2. Multiple Text Translations

Translate multiple texts simultaneously with translate_texts:

texts = ["Hello", "Goodbye"]
source_langs = ["en", "eng"]
target_langs = ["fr", "deu"]
translated_texts = cg.translate_texts(texts, source_langs, target_langs)
print(translated_texts)

Parameters

• texts: List of text strings to translate.
• source_langs: List of source language codes, one for each text.
• target_langs: List of target language codes, one for each text.

Returns

• A list of dictionaries, where each dictionary contains:

  • originalText: The original text provided.
  • translatedText: The translated text.
  • sourceLanguageCode: The source language code.
  • targetLanguageCode: The target language code.

  Returns None if an error occurs.

Note: The lists for texts, source_langs, and target_langs must be of equal length.

3. Document Translation

Upload an audio file and translate it:

document_id = cg.translate_document("path/to/file", source_lang="en", target_lang="fr")
print(f"Document ID: {document_id}")

Parameters

• file_path: Path to the file to be translated. This path can be relative to the file where this function is called (e.g., . or ../) or an absolute path.
• source_lang: Source language code.
• target_lang: Target language code.
• keep_original: Whether to retain the original document (default is True).

Returns

• A document_id for the created document. None if an error occurs.

4. Translate Multiple Documents

Translate multiple documents:

file_paths = ["/path/tofile1.txt", "/path/tofile2.docx"]
document_ids = cg.translate_documents(file_paths, source_lang="en", target_lang="fr")
print(f"Document IDs: {document_ids}")

Parameters

• file_path_list: List of file paths to be translated. Like the single-file method, each path can be relative to the file where this function is called (e.g., . or ../) or an absolute path.

• source_lang: Source language code.

• target_lang: Target language code.

• keep_original: Whether to retain the original document (default is True).

Returns

The function returns a list of dictionaries, each corresponding to a document. Each dictionary contains the following keys:

• document_id: A unique identifier for the document.
• status: The outcome of the translation, either "fail" or "success".
• status_code: A numerical status code (e.g., 2 for finished).
• status_name: A descriptive status name (e.g., "finished").

In case of an error, the function will return None.

5. Downloading Documents

Original Document

saved_original_path = cg.download_translation_original(document_id, save_path="./downloads", file_name="original_file.txt")

Translated Document

saved_translated_path = cg.download_translation_translated(document_id, save_path="./downloads", file_name="translated_file.txt")

Parameters

• document_id: The ID of the document.
• save_path: The path where the document will be saved. This can be either a relative path (e.g., . or ../) or an absolute path. If not provided, the file will be saved in the current working directory by default.
• file_name: The name of the file to save the document as. If not provided, the default file name will be auto-generated based on the original file name, source and target languages, and document type (e.g., 'original' or 'translated').

Returns

• The path where the document will be saved. If any error occurs, it will return None.

6. Get Translation Document Status

Single Document

Check the status of a single document:

status_code = cg.get_translation_document_status(document_id)
print(status_code)

Parameters

• document_id: The ID of the document.

Returns

• The status code (e.g., "success", "failed") if successful, None if an error occurs.

Multiple Documents

Check the status of multiple documents at once:

document_ids = [document_id1, document_id2]
statuses = cg.get_translation_documents_status(document_ids)
print(statuses)

Parameters

• document_ids: A list of document IDs to check the status for.

Returns

• A list of dictionaries, each containing:
  • "document_id": Unique identifier for the document.
  • "status": Translation outcome, either "fail" or "success".
  • "status_code": Numerical status code (e.g., 2 for finished, 0 for queued).
  • "status_name": Status description (e.g., "finished", "queued").
• In case of an error, the function will return None.

Named Entity Recognition (NER)

Perform NER on text to extract entities:

2. Process Text

entities = cg.named_entity_recognition("John Doe works at Google in Mountain View.")
print(entities)

Parameters

• text: The input text for performing NER. The function will analyze the provided text to identify entities such as names, locations, dates, and other key terms.

Returns

• A dictionary containing the original text and a list of extracted entities. The entities are structured as dictionaries with:
  • entityType: The type of entity (e.g., "PERSON", "GPE", "DATE", "ORG").
  • value: The actual entity extracted from the text.
  • startPosition: The start index of the entity in the text.
  • endPosition: The end index of the entity in the text.

Process Multiple Texts

To process multiple texts at once:

texts = ["John Doe works at Google.", "Jane Smith is a doctor in New York."]
entities_list = cg.named_entity_recognition_multiple_text(texts)
print(entities_list)

Parameters

• text_list: A list of input texts for performing NER on multiple documents.

Returns

• A list of dictionaries, where each dictionary contains:
  • The text field with the original text.
  • The entities field, which is a list of extracted entities for that text.

Vision

Upload an image file and provide a descriptive prompt to perform vision-based tasks:

vision_result = cg.vision(prompt="Detect objects in this image", file_path="/path/to/image.jpg")
print(vision_result)

Transcription

1. Document Translation

Upload an audio file and transcribe it:

document_id = cg.transcribe("/path/to/audiofile.mp3")

Parameters

• file_path: Path to the audio file to transcribe. This path can be relative to the file where this function is called (e.g., . or ../) or an absolute path.
• diarization_config: (Optional) Diarization configuration. Default is 1.

Returns

• A document_id for the created document. None if an error occurs.

2. Transcribe Multiple Documents

Transcribe multiple documents:

file_paths = ["/path/to/audiofile1.mp3", "/path/to/audiofile2.mp3"]
transcription_status = cg.transcribe_multiple(file_paths)
print(transcription_status)

Parameters

• file_path_list: List of paths to the audio files to transcribe. Like the single-file method, each path can be relative to the file where this function is called (e.g., . or ../) or an absolute path.

• diarization_config: (Optional) Diarization configuration. Default is 1.

Returns

The function returns a list of dictionaries, each corresponding to a document. Each dictionary contains the following keys:

• document_id: A unique identifier for the document.
• status: The outcome of the translation, either "fail" or "success".
• status_code: A numerical status code (e.g., 2 for finished).
• status_name: A descriptive status name (e.g., "finished").

In case of an error, the function will return None.

3. Downloading Documents

Original Document

saved_file_path = cg.download_transcription_original_file(document_id, save_path="./transcriptions")

SRT Document

saved_srt_path = cg.download_srt_file(document_id, save_path="./subtitles")

Transcription Document

transcription_text_path = cg.download_transcription_file(document_id, save_path="./transcriptions")

Parameters

• document_id: The ID of the document.
• save_path: The path where the document will be saved. This can be either a relative path (e.g., . or ../) or an absolute path. If not provided, the file will be saved in the current working directory by default.
• file_name: Name for the saved file. If not provided, it will be auto-generated based on the original file name and document type (e.g., 'original' or 'SRT').

Returns

• The path where the document will be saved. If any error occurs, it will return None.

4. Download SRT Text Directly

To download the SRT text directly without saving it to a file, use download_srt:

srt_text = cg.download_srt(document_id)
print(srt_text)

Parameters

• document_id: The ID of the transcription document.

Returns

• The SRT text if successful, None if an error occurs.

5. Get Transcription Document Status

Single Document

Check the status of a single document:

status_code = cg.get_transcription_document_status(document_id)
print(status_code)

Parameters

• document_id: The ID of the document.

Returns

• The status code (e.g., "success", "failed") if successful, None if an error occurs.

Multiple Documents

Check the status of multiple documents at once:

document_ids = [document_id1, document_id2]
statuses = cg.get_transcription_documents_status(document_ids)
print(statuses)

Parameters

• document_ids: A list of document IDs to check the status for.

Returns

• A list of dictionaries, each containing:
  • "document_id": Unique identifier for the document.
  • "status": Translation outcome, either "fail" or "success".
  • "status_code": Numerical status code (e.g., 2 for finished, 0 for queued).
  • "status_name": Status description (e.g., "finished", "queued").
• In case of an error, the function will return None.

Anonymizer

1. Anonymize Document

Upload an file and anonymize it:

document_id = cg.anonymize_document(
    '/path/to/file1.txt',
    [EntityType.ADDRESS.value],
)

Parameters

• file_path: Path to the file to anonymize. This path can be relative to the file where this function is called (e.g., . or ../) or an absolute path.
• options: List of EntityType values to anonymize. If not provided, no entity-based anonymization will be performed.
• regex: Regular expression to match and anonymize additional custom data. If not provided, no regex-based anonymization will be performed.

Returns

• A document_id for the created document. None if an error occurs.

2. Anonymize Multiple Documents

Anonymize multiple documents:

documents_status = cg.anonymize_documents(
    ['/path/to/file1.txt', '/path/to/file2.txt',],
    [EntityType.PERSON.value, EntityType.WORK_OF_ART.value],
    "\\b2019\\b"
)

Parameters

• file_path_list: List of paths to the files to anonymize. Like the single-file method, each path can be relative to the file where this function is called (e.g., . or ../) or an absolute path.
• options: List of EntityType values to anonymize. If not provided, no entity-based anonymization will be performed.
• regex: Regular expression to match and anonymize additional custom data. If not provided, no regex-based anonymization will be performed.

Returns

The function returns a list of dictionaries, each corresponding to a document. Each dictionary contains the following keys:

• document_id: A unique identifier for the document.
• status: The outcome of the translation, either "fail" or "success".
• status_code: A numerical status code (e.g., 2 for finished).
• status_name: A descriptive status name (e.g., "finished").

In case of an error, the function will return None.

Entity Types for Anonymization

The following EntityType values are available for anonymization. You can specify a list of these entities when calling the anonymization methods:

EntityType.ADDRESS
EntityType.CARDINAL
EntityType.COMPANY
EntityType.CRYPTO
EntityType.DATE
EntityType.DNS
EntityType.EMAIL
EntityType.EVENT
EntityType.FAC
EntityType.GPE
EntityType.IP
EntityType.LANGUAGE
EntityType.LAW
EntityType.LOC
EntityType.MONEY
EntityType.NORP
EntityType.ORDINAL
EntityType.ORG
EntityType.PERCENT
EntityType.PERSON
EntityType.PHONE
EntityType.PRODUCT
EntityType.QUANTITY
EntityType.TIME
EntityType.WORK_OF_ART

3. Downloading Documents

Original Document

saved_file_path = cg.download_anonymized_original_documnet(document_id, save_path="./downloads",file_name="original")

Anonymized Document

saved_srt_path = cg.download_anonymized_documnet(document_id, save_path="./subtitles",file_name="original")

Parameters

• document_id: The ID of the document.
• save_path: The path where the document will be saved. This can be either a relative path (e.g., . or ../) or an absolute path. If not provided, the file will be saved in the current working directory by default.
• file_name: Name for the saved file. If not provided, it will be auto-generated based on the original file name and document type (e.g., 'original' or 'anonymized').

Returns

• The path where the document will be saved. If any error occurs, it will return None.

5. Get Anonymized Document Status

Single Document

Check the status of a single document:

document_status = cg.get_anonymized_document_status(document_id)
print(document_status)

Parameters

• document_id: The ID of the document.

Returns

• The status code (e.g., "success", "failed") if successful, None if an error occurs.

Multiple Documents

Check the status of multiple documents at once:

document_ids = [document_id1, document_id2]
statuses = cg.get_anonymized_documents_status(document_ids)
print(statuses)

Parameters

• document_ids: A list of document IDs to check the status for.

Returns

• A list of dictionaries, each containing:
  • "document_id": Unique identifier for the document.
  • "status": Translation outcome, either "fail" or "success".
  • "status_code": Numerical status code (e.g., 2 for finished, 0 for queued).
  • "status_name": Status description (e.g., "finished", "queued").
• In case of an error, the function will return None.

Document Collections

Create a new document collection:

collection_id = cg.create_collection(name="My Collection", description="A collection of legal documents")
print(f"Collection created with ID: {collection_id}")

Upload a document to the collection:

upload_success = cg.upload_to_collection(collection_id, "/path/to/document.pdf")
print(f"Upload successful: {upload_success}")

Heartbeat

Fetch the health status of various system components:

heartbeat_status = cg.heartbeat()
print(heartbeat_status)

Parameters:

• None

Returns:

• Dictionary: A dictionary with the status of each component. Each key represents a system component (e.g., "SQL Server", "Oracle DB") and contains the following fields:
  • status: The health status of the component, typically "UP" or "DOWN".
  • message: A message providing more details about the component's health.
  • sinceTimestamp: A timestamp indicating when the status was last updated.

health_status = cg.healthcheck()
print(health_status)

Parameters:

• None

Returns:

• List of Tuples: The returned list contains tuples where each tuple represents a system resource and its health status. Each tuple contains:
  • resource name: The name of the resource (e.g., "SQL Server", "Oracle DB", "Training GRPC", "Triton Grpc Server").
  • status: The health status of the resource, which can be either "UP" (healthy) or "DOWN" (unhealthy).

Example Response Structure:

[
  ("SQL Server", "UP"),
  ("Oracle DB", "UP"),
  ("Training GRPC", "DOWN"),
  ("Triton Grpc Server", "UP")
]

Text Extraction

Extract paragraphs from raw text:

paragraphs = cg.text_extraction("This is a sample text that needs to be divided into paragraphs.")
print(paragraphs)

Extract text from a document file:

extracted_text = cg.text_extraction_from_document("/path/to/document.pdf")
print(extracted_text)

Text Embedding

Generate embeddings from raw text:

result = cg.get_text_embedding("This is a sample text.")
print(result)

Contributing

Contributions are welcome! Please fork the repository and submit a pull request.

License

This project is licensed under the MIT License.