0
# Utility Functions
1

2
Helper functions for loading and encoding media files from various sources. Provides convenient methods for preparing images and other binary data for use in multimodal prompts.
3

4
## Capabilities
5

6
### File Loading Functions
7

8
Load binary files and encode them as base64 strings for API consumption.
9

10
```python { .api }
11
def load_base64_from_file(path_and_filename: str) -> str:
12
    """
13
    Load a file from disk and return the base64 encoded content.
14
    
15
    Parameters:
16
    - path_and_filename: Path to the file to load
17
    
18
    Returns:
19
    Base64 encoded string representation of the file contents
20
    
21
    Example:
22
    >>> encoded = load_base64_from_file("./images/photo.jpg")
23
    >>> image = Image(base_64=encoded)
24
    """
25

26
def load_base64_from_url(url: str) -> str:
27
    """
28
    Download a file from URL and return the base64 encoded content.
29
    
30
    Parameters:
31
    - url: URL of the file to download
32
    
33
    Returns:
34
    Base64 encoded string representation of the downloaded file
35
    
36
    Example:
37
    >>> encoded = load_base64_from_url("https://example.com/image.png")
38
    >>> image = Image(base_64=encoded)
39
    """
40
```
41

42
### Usage Examples
43

44
Loading images and files for multimodal prompts:
45

46
```python
47
from aleph_alpha_client import (
48
    load_base64_from_file, 
49
    load_base64_from_url,
50
    Image, 
51
    Prompt,
52
    Text,
53
    Client,
54
    CompletionRequest
55
)
56

57
client = Client(token="your-api-token")
58

59
# Load image from local file
60
local_image_data = load_base64_from_file("./photos/vacation.jpg")
61
local_image = Image(base_64=local_image_data)
62

63
# Create multimodal prompt with local image
64
prompt = Prompt([
65
    Text.from_text("Describe what you see in this vacation photo:"),
66
    local_image
67
])
68

69
request = CompletionRequest(
70
    prompt=prompt,
71
    maximum_tokens=150,
72
    temperature=0.5
73
)
74

75
response = client.complete(request, model="luminous-extended")
76
print("Local image description:")
77
print(response.completions[0].completion)
78

79
# Load image from URL
80
web_image_data = load_base64_from_url("https://example.com/chart.png")
81
web_image = Image(base_64=web_image_data)
82

83
# Analyze web image
84
web_prompt = Prompt([
85
    Text.from_text("Analyze this chart and extract the key insights:"),
86
    web_image
87
])
88

89
web_request = CompletionRequest(
90
    prompt=web_prompt,
91
    maximum_tokens=200,
92
    temperature=0.3
93
)
94

95
web_response = client.complete(web_request, model="luminous-extended")
96
print("Chart analysis:")
97
print(web_response.completions[0].completion)
98

99
# Load multiple images for comparison
100
image1_data = load_base64_from_file("./images/before.jpg")
101
image2_data = load_base64_from_file("./images/after.jpg")
102

103
comparison_prompt = Prompt([
104
    Text.from_text("Compare these two images and describe the differences:"),
105
    Text.from_text("\nImage 1 (Before):"),
106
    Image(base_64=image1_data),
107
    Text.from_text("\nImage 2 (After):"),
108
    Image(base_64=image2_data)
109
])
110

111
comparison_request = CompletionRequest(
112
    prompt=comparison_prompt,
113
    maximum_tokens=250,
114
    temperature=0.4
115
)
116

117
comparison_response = client.complete(comparison_request, model="luminous-extended")
118
print("Image comparison:")
119
print(comparison_response.completions[0].completion)
120

121
# Load document or PDF for analysis
122
# Note: This works for any binary file that can be base64 encoded
123
document_data = load_base64_from_file("./documents/report.pdf")
124

125
# Error handling for file operations
126
import os
127

128
def safe_load_image(path: str) -> Image:
129
    """Safely load an image with error handling."""
130
    try:
131
        if not os.path.exists(path):
132
            raise FileNotFoundError(f"Image file not found: {path}")
133
        
134
        image_data = load_base64_from_file(path)
135
        return Image(base_64=image_data)
136
    except Exception as e:
137
        print(f"Error loading image {path}: {e}")
138
        return None
139

140
# Use with error handling
141
image_paths = ["./images/img1.jpg", "./images/img2.png", "./images/missing.jpg"]
142

143
for path in image_paths:
144
    image = safe_load_image(path)
145
    if image:
146
        prompt = Prompt([
147
            Text.from_text(f"Describe the image from {path}:"),
148
            image
149
        ])
150
        
151
        request = CompletionRequest(
152
            prompt=prompt,
153
            maximum_tokens=100,
154
            temperature=0.5
155
        )
156
        
157
        try:
158
            response = client.complete(request, model="luminous-extended")
159
            print(f"\nDescription of {path}:")
160
            print(response.completions[0].completion)
161
        except Exception as e:
162
            print(f"Error processing {path}: {e}")
163

164
# Batch loading for efficiency
165
def load_images_batch(image_paths: list) -> list:
166
    """Load multiple images efficiently."""
167
    images = []
168
    for path in image_paths:
169
        try:
170
            if path.startswith('http'):
171
                data = load_base64_from_url(path)
172
            else:
173
                data = load_base64_from_file(path)
174
            images.append(Image(base_64=data))
175
        except Exception as e:
176
            print(f"Failed to load {path}: {e}")
177
            images.append(None)
178
    return images
179

180
# Example batch usage
181
mixed_sources = [
182
    "./local/image1.jpg",
183
    "https://example.com/image2.png", 
184
    "./local/image3.jpg"
185
]
186

187
loaded_images = load_images_batch(mixed_sources)
188
valid_images = [img for img in loaded_images if img is not None]
189

190
print(f"Successfully loaded {len(valid_images)} out of {len(mixed_sources)} images")
191
```