Skip to main content
Honcho’s file upload feature allows you to convert documents into messages automatically. Upload PDFs, text files, or JSON documents, and Honcho will extract the text content, split it into appropriately sized chunks, and create messages that become part of your peer’s representation or session context. This feature is perfect for ingesting documents, reports, research papers, or any text-based content that you want your AI agents to understand and reference.

How It Works

When you upload a file, Honcho:
  1. Extracts text from the file using specialized processors based on file type
  2. Creates messages with the extracted content split into chunks that fit within message limits (messages are limited to 50,000 characters)
  3. Queues processing for background analysis and insight derivation like any other message
The file content becomes part of the peer’s representation, making it available for natural language queries and context retrieval.

Supported File Types

Honcho currently supports the following file types with more to come:
  • PDF files (application/pdf) - Text extraction with page numbers
  • Text files (text/*) - Plain text, markdown, code files, etc.
  • JSON files (application/json) - Structured data converted to readable format
Files are processed in memory and not stored on disk. Only the extracted text content is preserved in Honcho’s message system.

Basic Usage

Upload Parameters

The upload methods accept the following parameters:

File Processing Details

Text Extraction

PDF Files: Text is extracted page by page with page numbers preserved:
Text Files: Content is decoded using UTF-8, UTF-16, or Latin-1 encoding as needed. JSON Files: Structured data is converted to string format.

Chunking Strategy

Large files are automatically split into chunks of ~49,500 characters. The system seeks to break at natural boundaries if present:
  1. Paragraph breaks (\n\n)
  2. Line breaks (\n)
  3. Sentence endings (. )
  4. Word boundaries ( )
Each chunk becomes a separate message, maintaining the original document structure.

Querying Uploaded Content

Once files are uploaded, you can query the content using Honcho’s natural language interface:

Error Handling

Unsupported File Types

Files with unsupported content types will raise an exception:

Missing Required Fields

Session uploads require a peer_id parameter:

Complete Example: Document Analysis Assistant

Here’s a complete example of building a document analysis assistant:

Error Handling

  • Always wrap uploads in try-catch blocks for robust error handling
  • Validate file types before upload to avoid processing errors
  • Handle large files gracefully with progress indicators
  • Implement retry logic for network failures