Details

Adds support for base64-encoded strings in the Attachment.data field, fixing the "File name too long" error (OSError [Errno 63]) that occurred when users passed base64 strings.

Implementation Strategy:

• Try file path first
• Otherwise base64 decode with base64.b64decode(validate=True)
• On binascii.Error, fall back to treating string as file path for backwards compatibility
• Decoded bytes are written to temp file and marked for deletion
• Full backward compatibility maintained - existing file path behavior unchanged

Key Changes:

• converters.py: Added base64 detection and decoding logic in attachment_to_message()
• attachment.py: Updated docstring to document base64 string support
• test_converters.py: Added focused test for base64 string handling

Change checklist

• User facing
• Documentation update

Issues

• OPIK-3828
• [Bug]: Manually logging attachments as base64 strings results in error #4719

Testing

Unit Tests: All 15 tests passing (14 existing + 1 new)

• ✅ test_attachment_to_message__base64_string - Verifies base64 decoding, temp file creation, content preservation, and cleanup flags
• ✅ All existing tests pass without modification - confirms backward compatibility

Test Coverage:

• Base64 string decoding and temp file creation
• Content integrity after decode
• Proper delete_after_upload flag setting
• MIME type inference from file_name
• Fallback to file path for non-base64 strings

Manual Testing:
Tested with Google ADK use case (base64-encoded images from Gemini API):

import opik
import base64

image_bytes = open("image.png", "rb").read()
base64_string = base64.b64encode(image_bytes).decode("utf-8")

opik.track(
    attachments=[opik.Attachment(data=base64_string, file_name="image.png")]
)

Documentation

Updated:

• Attachment class docstring now explicitly documents base64 string support

User-facing change: Users can now pass base64-encoded strings directly to Attachment.data without errors.