Documents | Boosted.ai

Documents allow you to analyze your own data using Alfa workplans. This guide explains how to upload documents, list them, and reference them in your workplan prompts.

Uploading documents

You can upload your own documents (PDFs, Word files, Excel spreadsheets, etc.) to be processed and made available to your workplans.

import requests
BASE_URL = "https://alfa.boosted.ai/client"
API_KEY = "YOUR_API_KEY_HERE"
headers = {"x-api-key": API_KEY}  # No Content-Type for multipart uploads
def upload_documents(file_paths):
    """
    Upload one or more documents for use with workplans.
    
    Args:
        file_paths (list): List of paths to files you want to upload
        
    Returns:
        dict: Response with uploaded document details
    """
    url = f"{BASE_URL}/v2/documents/add-documents"
    
    # Prepare files for multipart upload
    files = []
    for path in file_paths:
        file_name = path.split("/")[-1]
        files.append(("files", (file_name, open(path, "rb"))))
    
    # Make the request without Content-Type header (it's set automatically)
    response = requests.post(
        url,
        headers={"x-api-key": API_KEY},
        files=files
    )
    
    # Close all file handles
    for _, (_, file_obj) in files:
        file_obj.close()
    
    if response.status_code == 202:
        return response.json()
    else:
        print(f"Error uploading documents: {response.status_code}, {response.text}")
        return None
# Example usage
file_paths = [
    "/path/to/quarterly_report.pdf",
    "/path/to/market_analysis.docx"
]
upload_result = upload_documents(file_paths)
if upload_result and upload_result.get("success"):
    print(f"Successfully uploaded {len(upload_result.get('added_listings', []))} documents")
    for doc in upload_result.get("added_listings", []):
        print(f"Document ID: {doc['file_id']}")
        print(f"Name: {doc['name']}")
        print(f"Size: {doc['size']} bytes")
        print("---")

Example: Uploading quarterly reports

Prepare your documents

Gather the documents you want to analyze (PDFs, Excel files, Word documents, etc.)

Upload the documents

# Upload Q1 and Q2 reports to a designated folder
quarterly_reports = [
    "Q1_2023_Financials.pdf",
    "Q2_2023_Financials.pdf"
]
result = upload_documents(quarterly_reports)
# Store document IDs for later use
document_ids = {}
if result and result.get("success"):
    for doc in result.get("added_listings", []):
        document_ids[doc["name"]] = doc["file_id"]
        print(f"Uploaded: {doc['name']} (ID: {doc['file_id']})")

For large documents, the upload process may take some time as the system processes and indexes the content for searching.

Listing documents

To view all documents that you’ve uploaded:

def list_documents():
    """
    List all documents in your workspace.
    
    Returns:
        list: List of document objects with their details
    """
    url = f"{BASE_URL}/v2/documents/list_documents"
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        return data.get("documents", [])
    else:
        print(f"Error listing documents: {response.status_code}, {response.text}")
        return []
# Get and display all documents
documents = list_documents()
print(f"Found {len(documents)} documents:")
for doc in documents:
    print(f"ID: {doc['file_id']}")
    print(f"Name: {doc['name']}")
    print(f"Type: {doc['type']}")
    print(f"Upload time: {doc['upload_time']}")
    print("---")

Creating workplans with documents

You can reference documents in your workplan prompts using a special syntax. The workplan will then be able to read and analyze these documents.

def create_workplan_with_document(prompt, document_id):
    """
    Create an workplan that references a document.
    
    Args:
        prompt (str): The prompt with {doc} placeholder
        document_id (str): The ID of the document to reference
        
    Returns:
        str: The workplan ID if successful, empty string otherwise
    """
    url = f"{BASE_URL}/v2/workplans/create
    
    # Create the request payload with the document reference
    payload = {
        "prompt": prompt,
        "args": {
            "doc": {
                "id": document_id,
                "type": "custom_document"
            }
        }
    }
    
    response = requests.post(url, headers=headers, json=payload)
    
    if response.status_code == 201:
        data = response.json()
        workplan_id = data.get("workplan_id")
        print(f"workplan created with ID: {workplan_id}")
        return workplan_id
    else:
        print(f"Error creating workplan: {response.status_code}, {response.text}")
        return ""
# Example: Create an workplan to analyze a quarterly report
document_id = "6fcc0ae7-809b-498c-b35b-4ced1114438b"  # ID from a previous upload
prompt = "Read the document {doc} and summarize its key points. Format the summary to be easy to read."
workplan_id = create_workplan_with_document(prompt, document_id)

The {doc} placeholder in your prompt will be replaced with the actual document content when the workplan processes it.

Understanding the document reference format

The payload for creating an workplan with a document reference follows this structure:

{
  "prompt": "Read the document {doc} and summarize its key points. Format the summary to be easy to read.",
  "args": {
    "doc": {
      "id": "6fcc0ae7-809b-498c-b35b-4ced1114438b",
      "type": "custom_document"
    }
  }
}

prompt: Your instruction with the {doc} placeholder
args: A dictionary mapping placeholders to their values
doc: The placeholder name that matches what you used in the prompt
id: The unique ID of the document (obtained when uploading or listing documents)
type: Must be “custom_document” to indicate you’re referencing a document