A Python library for building AI agents for Box. This toolkit provides functionalities for authenticating with Box using OAuth and CCG, interacting with Box files and folders, managing document generation operations, and handling metadata templates.
- Authentication: Authenticate with Box using OAuth or CCG.
- Box API Interactions: Interact with Box files and folders.
- File Upload & Download: Easily upload files to and download files from Box.
- Document Generation (DocGen): Create and manage document generation jobs and templates.
- Metadata Templates: Create, list, update, and delete metadata templates.
- AI Capabilities: Ask AI questions about files or Box hubs and extract information from file contents.
To install the toolkit, run:
pip install box-ai-agents-toolkit
Create a .env
file with:
BOX_CLIENT_ID = "your client id"
BOX_CLIENT_SECRET = "your client secret"
BOX_SUBJECT_TYPE = "user/enterprise"
BOX_SUBJECT_ID = "user id/enterprise id"
Then authenticate:
from box_ai_agents_toolkit import get_ccg_client
client = get_ccg_client()
Create a .env
file with:
BOX_CLIENT_ID = "your client id"
BOX_CLIENT_SECRET = "your client secret"
BOX_REDIRECT_URL = "http://localhost:8000/callback"
Then authenticate:
from box_ai_agents_toolkit import get_oauth_client
client = get_oauth_client()
Get File by ID:
from box_ai_agents_toolkit import box_file_get_by_id
file = box_file_get_by_id(client, file_id="12345")
Extract Text from File:
from box_ai_agents_toolkit import box_file_text_extract
text = box_file_text_extract(client, file_id="12345")
Upload a File:
from box_ai_agents_toolkit import box_upload_file
content = "This is a test file content."
result = box_upload_file(client, content, file_name="test_upload.txt", folder_id="0")
print("Uploaded File Info:", result)
Download a File:
from box_ai_agents_toolkit import box_file_download
path_saved, file_content, mime_type = box_file_download(client, file_id="12345", save_file=True)
print("File saved to:", path_saved)
Mark a File as a DocGen Template:
from box_ai_agents_toolkit import box_docgen_template_create
template = box_docgen_template_create(client, file_id="template_file_id")
print("Created DocGen Template:", template)
List DocGen Templates:
from box_ai_agents_toolkit import box_docgen_template_list
templates = box_docgen_template_list(client, marker='x', limit=10)
print("DocGen Templates:", templates)
Delete a DocGen Template:
from box_ai_agents_toolkit import box_docgen_template_delete
box_docgen_template_delete(client, template_id="template_file_id")
print("Template deleted")
Retrieve a DocGen Template by ID:
from box_ai_agents_toolkit import box_docgen_template_get_by_id
template_details = box_docgen_template_get_by_id(client, template_id="template_file_id")
print("Template details:", template_details)
List Template Tags and Jobs:
from box_ai_agents_toolkit import box_docgen_template_list_tags, box_docgen_template_list_jobs
tags = box_docgen_template_list_tags(client, template_id="template_file_id", template_version_id='v1', marker='m', limit=5)
jobs = box_docgen_template_list_jobs(client, template_id="template_file_id", marker='m2', limit=3)
print("Template tags:", tags)
print("Template jobs:", jobs)
Create a Document Generation Batch:
from box_ai_agents_toolkit import box_docgen_create_batch
data_input = [
{"generated_file_name": "file1", "user_input": {"a": "b"}},
{"generated_file_name": "file2", "user_input": {"x": "y"}}
]
batch = box_docgen_create_batch(client, file_id="f1", input_source="api", destination_folder_id="dest", output_type="pdf", document_generation_data=data_input)
print("Batch job created:", batch)
Alternatively, you can create a batch from raw user input:
from box_ai_agents_toolkit import box_docgen_create_batch_from_user_input
batch = box_docgen_create_batch_from_user_input(client, file_id="f1", destination_folder_id="dest", user_input='{"key":"value"}', generated_file_name="Output File", output_type="pdf")
print("Batch job created from user input:", batch)
Create a Metadata Template:
from box_ai_agents_toolkit import box_metadata_template_create
template = box_metadata_template_create(
client,
scope="enterprise",
display_name="My Template",
template_key="tmpl1",
hidden=True,
fields=[{"key": "a", "type": "string"}],
copy_instance_on_item_copy=False,
)
print("Created Metadata Template:", template)
List Metadata Templates:
from box_ai_agents_toolkit import box_metadata_template_list
templates = box_metadata_template_list(client, scope="enterprise", marker="m", limit=5)
print("Metadata Templates:", templates)
Retrieve a Metadata Template:
from box_ai_agents_toolkit import box_metadata_template_get
template = box_metadata_template_get(client, scope="enterprise", template_key="tmpl1")
print("Metadata Template Details:", template)
Update a Metadata Template:
from box_ai_agents_toolkit import box_metadata_template_update
updated_template = box_metadata_template_update(client, scope="global", template_key="tmpl1", request_body=[{"op": "replace", "path": "/displayName", "value": "New Name"}])
print("Updated Metadata Template:", updated_template)
Delete a Metadata Template:
from box_ai_agents_toolkit import box_metadata_template_delete
box_metadata_template_delete(client, scope="enterprise", template_key="tmpl1")
print("Metadata Template deleted")
List Metadata Templates by Instance ID:
from box_ai_agents_toolkit import box_metadata_template_list_by_instance_id
templates = box_metadata_template_list_by_instance_id(client, metadata_instance_id="inst1", marker="a", limit=3)
print("Templates by Instance ID:", templates)
Ask AI a Question about a File:
from box_ai_agents_toolkit import box_file_ai_ask
response = box_file_ai_ask(client, file_id="12345", prompt="What is this file about?")
print("AI Response:", response)
Ask AI a Question about a Box Hub:
from box_ai_agents_toolkit import box_hubs_ai_ask
response = box_hubs_ai_ask(client, hubs_id="12345", prompt="What is the current policy on parental leave?")
print("AI Response:", response)
Extract Information from a File using AI:
from box_ai_agents_toolkit import box_file_ai_extract
response = box_file_ai_extract(client, file_id="12345", prompt="Extract date, name, and contract number from this file.")
print("AI Extract Response:", response)
-
Clone the repository:
git clone https://github.com/box-community/box-ai-agents-toolkit.git cd box-ai-agents-toolkit
-
Install dependencies:
pip install -e .[dev]
To run the tests, use:
pytest
This project is licensed under the MIT License. See the LICENSE file for details.
Contributions are welcome! Please open an issue or submit a pull request for any enhancements or bug fixes.
For questions or issues, open an issue on the GitHub repository.