Files API Overview

from incredible_python import Incredible

client = Incredible(api_key="YOUR_API_KEY")

# Upload a file - SDK handles everything automatically
with open("report.pdf", "rb") as f:
    file = client.files.upload(file=f)

# Use the file_id in any endpoint
print(f"File uploaded! ID: {file.file_id}")

# Now use it with Agent, Conversation, or Answer endpoints
response = client.agent(
    messages=[{"role": "user", "content": "Summarize this", "file_ids": [file.file_id]}],
    tools=[...]
)

# Example: File library implementation
from incredible_python import Incredible
from datetime import datetime

class FileLibrary:
    """
    Manages file uploads and reuse for Incredible API.
    Upload once, store file_id, reuse forever.
    """
    
    def __init__(self, api_key, database):
        self.client = Incredible(api_key=api_key)
        self.db = database
    
    def upload_file(self, user_id, file_path, filename):
        """
        Upload a file ONCE and store the file_id.
        Call this only when user first adds a file.
        """
        # Check if file already uploaded
        existing = self.db.get_file_by_name(user_id, filename)
        if existing:
            print(f"✓ File already uploaded, reusing file_id: {existing['file_id']}")
            return existing['file_id']
        
        # Upload using SDK - handles all steps automatically!
        with open(file_path, 'rb') as f:
            file = self.client.files.upload(file=f)
        
        # Store file_id in database (CRITICAL!)
        self.db.save_file({
            "user_id": user_id,
            "file_id": file.file_id,
            "filename": filename,
            "uploaded_at": datetime.now()
        })
        
        print(f"✓ File uploaded successfully: {file.file_id}")
        return file.file_id
    
    def get_user_files(self, user_id):
        """
        Retrieve all files for a user.
        Show these in your UI so users can reuse them.
        """
        return self.db.get_files_by_user(user_id)
    
    def answer_with_files(self, message, file_ids):
        """
        Use stored file_ids for Q&A - no re-uploading!
        """
        return self.client.answer(query=message, file_ids=file_ids)
    
    def conversation_with_files(self, messages):
        """
        Use stored file_ids in conversation - no re-uploading!
        Messages can include file_ids in user messages.
        """
        return self.client.conversation(messages=messages)

# Usage Example:
library = FileLibrary(api_key="ik_...", database=db)

# Upload once (only when user first adds file)
file_id = library.upload_file(
    user_id="user123",
    file_path="report.pdf",
    filename="Q4_Report.pdf"
)

# Later: Show user their file library
user_files = library.get_user_files("user123")
print("Your files:")
for file in user_files:
    print(f"  - {file['filename']} (ID: {file['file_id']})")

# Use file in unlimited requests (no re-upload needed!)
response1 = library.answer_with_files(
    message="Summarize this report",
    file_ids=[file_id]
)
print(response1.answer)

# Or use in a conversation with file context
response2 = library.conversation_with_files(
    messages=[
        {"role": "user", "content": "What are the key metrics?", "file_ids": [file_id]}
    ]
)
print(response2.response)  # ← Same file_id, instant access!

{
  "messages": [
    {
      "role": "user",
      "content": "Analyze the sales data and create a chart",
      "file_ids": ["550e8400-...", "660e8400-..."]
    }
  ]
}

# The agent can write Python code like this:
import pandas as pd
import matplotlib.pyplot as plt

# Files are automatically available in the sandbox
df = pd.read_csv("data.csv")
summary = df.describe()

plt.plot(df['date'], df['sales'])
plt.savefig("chart.png")