optycode-sdk 2.0

A simple Python SDK for interacting with the optycode API.

optycode SDK

A lightweight Python SDK to interact with the optycode API for logging model interactions and analytics.

Installation

pip install optycode-sdk

Getting Started

Authentication

To use the optycode SDK, you'll need an authentication token and model ID. Both can be obtained from your optycode account dashboard.

1. Auth Token: Your API authentication token (available in your optycode account)
2. Model ID: The identifier for your model (available in your optycode account)

Basic Usage

from optycode_sdk import OptycodeAPI

# Initialize the client with your auth token
client = OptycodeAPI(auth_token="your-auth-token-here")

# Log a simple interaction
client.log_data(
    user_question="What is machine learning?",
    model_answer="Machine learning is a subset of artificial intelligence...",
    model_id="your-model-id-here"
)

Parameters

The log_data and log_data_async methods accept the following parameters:

• user_question (required): The user's question or input
• model_answer (required): The model's response
• model_id (required): Your model identifier from optycode account
• session_id (optional): Session identifier for grouping related interactions
• model_input (optional): The actual input sent to the model (defaults to user_question if not provided)
• question_id (optional): Unique identifier for the question
• rag_elements (optional): RAG (Retrieval-Augmented Generation) elements used
• attachment (optional): Binary attachment data (e.g., images, documents)
• signed_url (optional): only if attachement is not present, it's retourned from the upload_attachement function

Production Usage

Using log_data_async for Production

For production environments, always use log_data_async instead of log_data. The async method:

• Uses a very short timeout to avoid blocking your application
• Doesn't wait for the server response, improving performance
• Is designed for high-throughput scenarios where you don't need immediate confirmation

We also recommend always logging a session_id and a question_id, for better visualizations in the dashboard

from optycode_sdk import OptycodeAPI

client = OptycodeAPI(auth_token="your-auth-token-here")

# Production-ready async logging
client.log_data_async(
    user_question="What is the weather today?",
    model_answer="The weather is sunny with a high of 75°F.",
    model_id="your-model-id-here",
    session_id="session-123",
    question_id=42
)

Handling Attachments Separately

If your attachment processing happens in a different part of your codebase than your model processing, use upload_attachment to upload the file first, then pass the returned signed_url to log_data_async.

Use case: You process attachments in one service/module, and log model interactions in another.

from optycode_sdk import OptycodeAPI

client = OptycodeAPI(auth_token="your-auth-token-here")

# Upload attachment separately (e.g., in a different service/module)
with open("document.pdf", "rb") as f:
    attachment_data = f.read()

signed_url = client.upload_attachement(
    attachment=attachment_data,
    model_id="your-model-id-here",
    question_id=42,
    session_id="session-123"
)

# Later, in a different part of your code, log the interaction with the signed URL
client.log_data_async(
    user_question="Analyze this document",
    model_answer="The document contains...",
    model_id="your-model-id-here",
    session_id="session-123",
    question_id=42,
    signed_url=signed_url  # Use the pre-uploaded attachment
)

Complete Example with Attachment

If you have the attachment available at the same time as logging:

from optycode_sdk import OptycodeAPI

client = OptycodeAPI(auth_token="your-auth-token-here")

# Read attachment
with open("image.png", "rb") as f:
    image_data = f.read()

# Log with attachment (handled automatically)
client.log_data_async(
    user_question="What's in this image?",
    model_answer="The image shows a cat sitting on a mat.",
    model_id="your-model-id-here",
    session_id="session-123",
    question_id=42,
    attachment=image_data
)

OptycodeMCP — Remote setup management

The OptycodeMCP client lets you manage optycode setups remotely (create systems and models). It uses the same auth token as OptycodeAPI; once initialized, you don't pass the token again for each call.

When you create a new system with create_stystem, the API returns a response whose data field contains the created system(s). You can get the new system's ID from that response (e.g. response["data"][0]["id"]) and pass it as system_id when calling create_model.

from optycode_sdk import OptycodeMCP

client = OptycodeMCP(auth_token="your-auth-token-here")

# Create a system
response = client.create_stystem(name="my_system", type="my_type")
system_id = response["data"][0]["id"]  # Use this when creating models

# Create a model under that system
client.create_model(
    system_id=system_id,
    name="my_model",
    type="chat",
    prompt="You are a helpful assistant."
)

OptycodeMCP methods

• create_stystem(name, type) — Creates a system. Returns a response with data (list of created system objects); use response["data"][0]["id"] to get the new system ID.
• create_model(system_id, name, type, prompt) — Creates a model under the given system. Requires the system_id returned from create_stystem.

Error Handling

The SDK will raise exceptions if:

• The authentication token is invalid
• The API request fails
• Required parameters are missing

Always wrap your calls in try-except blocks for production code:

try:
    client.log_data_async(
        user_question="Test question",
        model_answer="Test answer",
        model_id="your-model-id-here"
    )
except Exception as e:
    # Handle error appropriately
    print(f"Failed to log data: {e}")

Notes

• The SDK automatically verifies your token upon initialization
• All timestamps are automatically generated
• The log_data_async method is fire-and-forget, so it won't block your application
• For best performance in production, always use log_data_async