# File Uploads

Handle file uploads with paths and file-like objects.

## 📁 Upload Files by Path

### **Single File**

{% tabs %}
{% tab title="Python" %}
```python
from glaip_sdk import Client

client = Client()
agent = client.create_agent(
    name="file-processor",
    instruction="Process uploaded files and provide insights."
)

# Upload file by path
response = agent.run(
    "Analyze this document",
    files=["document.pdf"]
)
```
{% endtab %}

{% tab title="CLI" %}
```bash
# Upload file by path
aip agents run <AGENT_ID> \
  --input "Analyze this document" \
  --file "document.pdf"
```
{% endtab %}
{% endtabs %}

### **Multiple Files**

{% tabs %}
{% tab title="Python" %}
```python
# Upload multiple files
response = agent.run(
    "Compare these documents",
    files=["doc1.pdf", "doc2.pdf", "doc3.pdf"]
)
```
{% endtab %}

{% tab title="CLI" %}
```bash
# Upload multiple files (repeatable --file flags)
aip agents run <AGENT_ID> \
  --input "Compare these documents" \
  --file "doc1.pdf" \
  --file "doc2.pdf" \
  --file "doc3.pdf"

# Alternative: use repeated --file flags
aip agents run <AGENT_ID> \
  --input "Compare these documents" \
  --file "doc1.pdf" \
  --file "doc2.pdf" \
  --file "doc3.pdf"
```
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**CLI File Format**: Use repeatable `--file` flags (`--file "a" --file "b" --file "c"`). Each file is specified with a separate `--file` flag.
{% endhint %}

## 📂 Upload File-Like Objects

### **File Handles**

{% tabs %}
{% tab title="Python" %}
```python
# Upload file-like objects
with open("resume.pdf", "rb") as f:
    response = agent.run(
        "Summarize this resume",
        files=[f]
    )
```
{% endtab %}

{% tab title="CLI" %}
```bash
# CLI doesn't support file-like objects directly
# Use file paths instead
aip agents run <AGENT_ID> \
  --input "Summarize this resume" \
  --file "resume.pdf"
```
{% endtab %}
{% endtabs %}

### **Bytes and IO Objects**

{% tabs %}
{% tab title="Python" %}
```python
import io

# Upload from bytes
file_content = b"Hello, this is file content"
file_obj = io.BytesIO(file_content)
file_obj.name = "example.txt"

response = agent.run(
    "Process this text file",
    files=[file_obj]
)

# Upload from BytesIO
import io
text_content = "This is text content"
text_obj = io.BytesIO(text_content.encode("utf-8"))
text_obj.name = "text.txt"

response = agent.run(
    "Analyze this text",
    files=[text_obj]
)
```
{% endtab %}

{% tab title="CLI" %}
```bash
# CLI doesn't support IO objects directly
# Save to file first, then upload
echo "This is text content" > text.txt
aip agents run <AGENT_ID> \
  --input "Analyze this text" \
  --file "text.txt"
```
{% endtab %}
{% endtabs %}

## 🔧 File Upload Configuration

### **Supported File Types**

| File Type     | Extensions                     | Description              |
| ------------- | ------------------------------ | ------------------------ |
| **Documents** | `.pdf`, `.docx`, `.txt`, `.md` | Text and document files  |
| **Images**    | `.jpg`, `.png`, `.gif`, `.svg` | Image files for analysis |
| **Data**      | `.csv`, `.json`, `.xml`        | Structured data files    |
| **Code**      | `.py`, `.js`, `.java`, `.cpp`  | Source code files        |
| **Archives**  | `.zip`, `.tar.gz`              | Compressed files         |

### **File Size Limits**

* **Maximum file size**: 100 MB per file (default)
* **Total upload limit**: 500 MB per request (default)
* **File count limit**: 10 files per request (default)

{% hint style="info" %}
**Note**: These are default limits that may be configured differently on your server. Check with your system administrator for specific limits.
{% endhint %}

{% hint style="warning" %}
Large files may take longer to process. Consider compressing files when possible.
{% endhint %}

### **Shell Considerations**

{% hint style="info" %}
**Glob Expansion**: On Linux/macOS, shell glob expansion works automatically (e.g., `*.pdf`). On Windows PowerShell, use explicit file lists instead of glob patterns.
{% endhint %}

## 📊 File Processing Examples

### **Document Analysis**

{% tabs %}
{% tab title="Python" %}
```python
# Analyze PDF document
response = agent.run(
    "Extract key information from this document",
    files=["report.pdf"]
)

# Process multiple documents
response = agent.run(
    "Compare the main points in these reports",
    files=["report1.pdf", "report2.pdf", "report3.pdf"]
)
```
{% endtab %}

{% tab title="CLI" %}
```bash
# Analyze PDF document
aip agents run <AGENT_ID> \
  --input "Extract key information from this document" \
  --file "report.pdf"

# Process multiple documents
aip agents run <AGENT_ID> \
  --input "Compare the main points in these reports" \
  --file "report1.pdf" --file "report2.pdf" --file "report3.pdf"
```
{% endtab %}
{% endtabs %}

### **Image Analysis**

{% tabs %}
{% tab title="Python" %}
```python
# Analyze image content
response = agent.run(
    "Describe what you see in this image",
    files=["photo.jpg"]
)

# Compare multiple images
response = agent.run(
    "Find differences between these images",
    files=["image1.png", "image2.png"]
)
```
{% endtab %}

{% tab title="CLI" %}
```bash
# Analyze image content
aip agents run <AGENT_ID> \
  --input "Describe what you see in this image" \
  --file "photo.jpg"

# Compare multiple images
aip agents run <AGENT_ID> \
  --input "Find differences between these images" \
  --file "image1.png" --file "image2.png"
```
{% endtab %}
{% endtabs %}

### **Data Analysis**

{% tabs %}
{% tab title="Python" %}
```python
# Analyze CSV data
response = agent.run(
    "Summarize the trends in this dataset",
    files=["sales_data.csv"]
)

# Process JSON configuration
response = agent.run(
    "Validate this configuration file",
    files=["config.json"]
)
```
{% endtab %}

{% tab title="CLI" %}
```bash
# Analyze CSV data
aip agents run <AGENT_ID> \
  --input "Summarize the trends in this dataset" \
  --file "sales_data.csv"

# Process JSON configuration
aip agents run <AGENT_ID> \
  --input "Validate this configuration file" \
  --file "config.json"
```
{% endtab %}
{% endtabs %}

### **Code Review**

{% tabs %}
{% tab title="Python" %}
```python
# Review Python code
response = agent.run(
    "Review this code for best practices",
    files=["main.py"]
)

# Analyze multiple source files
response = agent.run(
    "Find potential issues in this codebase",
    files=["main.py", "utils.py", "tests.py"]
)
```
{% endtab %}

{% tab title="CLI" %}
```bash
# Review Python code
aip agents run <AGENT_ID> \
  --input "Review this code for best practices" \
  --file "main.py"

# Analyze multiple source files
aip agents run <AGENT_ID> \
  --input "Find potential issues in this codebase" \
  --file "main.py" --file "utils.py" --file "tests.py"
```
{% endtab %}
{% endtabs %}

## 🔄 Advanced File Handling

### **Dynamic File Selection**

{% tabs %}
{% tab title="Python" %}
```python
import os
import glob

# Upload all PDF files in a directory
pdf_files = glob.glob("documents/*.pdf")
response = agent.run(
    "Process all PDF documents",
    files=pdf_files
)

# Upload files based on pattern
txt_files = glob.glob("data/*.txt")
response = agent.run(
    "Analyze all text files",
    files=txt_files
)
```
{% endtab %}

{% tab title="CLI" %}
```bash
# Upload all PDF files in a directory
aip agents run <AGENT_ID> \
  --input "Process all PDF documents" \
  --file "documents/*.pdf"

# Upload files based on pattern
aip agents run <AGENT_ID> \
  --input "Analyze all text files" \
  --file "data/*.txt"
```
{% endtab %}
{% endtabs %}

### **File Validation**

{% tabs %}
{% tab title="Python" %}
```python
import os

def validate_files(file_paths):
    """Validate files before upload."""
    valid_files = []
    for path in file_paths:
        if os.path.exists(path):
            file_size = os.path.getsize(path)
            if file_size <= 100 * 1024 * 1024:  # 100 MB
                valid_files.append(path)
            else:
                print(f"File too large: {path}")
        else:
            print(f"File not found: {path}")
    return valid_files

# Validate and upload
file_paths = ["doc1.pdf", "doc2.pdf", "doc3.pdf"]
valid_files = validate_files(file_paths)

if valid_files:
    response = agent.run(
        "Process valid documents",
        files=valid_files
    )
```
{% endtab %}

{% tab title="CLI" %}
```bash
# Check file existence and size
ls -la documents/
du -h documents/*.pdf

# Upload only existing files
aip agents run <AGENT_ID> \
  --input "Process documents" \
  --file "doc1.pdf" --file "doc2.pdf" --file "doc3.pdf"
```
{% endtab %}
{% endtabs %}

### **File Limits**

{% tabs %}
{% tab title="Python" %}
```python
# File size validation
import os

def check_file_size(file_path):
    file_size = os.path.getsize(file_path)
    max_size = 100 * 1024 * 1024  # 100 MB
    return file_size <= max_size

# Check before upload
if check_file_size("large_file.pdf"):
    response = agent.run("Process file", files=["large_file.pdf"])
else:
    print("File too large")
```
{% endtab %}

{% tab title="CLI" %}
```bash
# Check file size before upload
ls -lh large_file.pdf

# Upload if within limits
aip agents run <AGENT_ID> \
  --input "Process file" \
  --file "large_file.pdf"
```
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Note**: File size limits (100 MB) are server defaults and may vary by deployment. Check with your AIP administrator for specific limits.
{% endhint %}

## 🎯 Best Practices

### **File Preparation**

* **Compress large files**: Use ZIP or TAR for multiple files
* **Validate file types**: Ensure files are in supported formats
* **Check file sizes**: Stay within upload limits
* **Organize files**: Use descriptive filenames and organize in directories

### **Upload Strategy**

* **Batch processing**: Upload related files together
* **Progressive uploads**: Start with small files to test
* **Error handling**: Handle upload failures gracefully
* **Cleanup**: Remove temporary files after processing

### **Performance Optimization**

* **File size**: Keep files under 50 MB when possible
* **File count**: Limit to 5-10 files per request
* **Format selection**: Use efficient formats (e.g., CSV over Excel)
* **Compression**: Compress text-based files

## 🚀 Next Steps

* **Tools**: Learn about Tools for processing uploaded files
* **MCPs**: Connect external services via MCPs
* **Streaming**: Use Streaming & Renderers for real-time file processing
* **Scripting**: Automate file workflows with Output & Scripting

## 💡 Pro Tips

* **Start Small**: Test with small files before uploading large ones
* **Use Paths**: File paths are simpler than file objects for most use cases
* **Validate First**: Check file existence and size before upload
* **Organize Files**: Keep related files in organized directories
* **Monitor Progress**: Large files may take time to process
* **Handle Errors**: Implement proper error handling for file operations

Ready to handle file uploads? Start with simple documents and gradually work with more complex file types!
