Logs API Overview

Manage conversation logs and request/response data with the Keywords AI Python SDK

Overview

The Logs API allows you to create, retrieve, and list conversation logs. Logs capture the complete context of interactions including messages, model information, token usage, and metadata.

Key Features

• Create logs for conversations and API requests
• Retrieve specific logs by ID
• List logs with filtering and pagination
• Track token usage and costs
• Store custom metadata for analysis

Quick Start

from keywordsai import KeywordsAI

client = KeywordsAI(api_key="your-api-key")

# Create a log
log = client.logs.create(
    messages=[
        {"role": "user", "content": "What is machine learning?"},
        {"role": "assistant", "content": "Machine learning is a subset of artificial intelligence..."}
    ],
    model="gpt-4",
    prompt_tokens=20,
    completion_tokens=50,
    total_tokens=70
)

print(f"Created log with ID: {log.id}")

Available Methods

Synchronous Methods

Method	Description
create()	Create a new log entry
list()	List logs with optional filtering
get()	Retrieve a specific log by ID

Asynchronous Methods

Method	Description
acreate()	Async version of create
alist()	Async version of list
aget()	Async version of get

Update and delete operations are not supported for logs to maintain data integrity and audit trails.

Log Structure

A log entry contains the following key information:

{
    "id": "log_123456",
    "messages": [
        {"role": "user", "content": "Hello"},
        {"role": "assistant", "content": "Hi there!"}
    ],
    "model": "gpt-4",
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25,
    "cost": 0.0012,
    "latency": 1.5,
    "created_at": "2024-01-15T10:30:00Z",
    "metadata": {
        "user_id": "user_789",
        "session_id": "session_456"
    }
}

Common Use Cases

1. Logging Chat Conversations

# Log a multi-turn conversation
log = client.logs.create(
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What's the weather like?"},
        {"role": "assistant", "content": "I don't have access to real-time weather data."},
        {"role": "user", "content": "How can I check the weather?"},
        {"role": "assistant", "content": "You can check weather apps or websites."}
    ],
    model="gpt-3.5-turbo",
    prompt_tokens=45,
    completion_tokens=32,
    total_tokens=77
)

2. Tracking API Usage

# Log API requests with metadata
log = client.logs.create(
    messages=[{"role": "user", "content": "Summarize this text"}],
    model="gpt-4",
    prompt_tokens=100,
    completion_tokens=50,
    total_tokens=150,
    metadata={
        "api_endpoint": "/summarize",
        "user_id": "user_123",
        "request_id": "req_456"
    }
)

3. Performance Monitoring

# Log with performance metrics
log = client.logs.create(
    messages=[{"role": "user", "content": "Generate code"}],
    model="gpt-4",
    prompt_tokens=50,
    completion_tokens=200,
    total_tokens=250,
    latency=2.3,  # Response time in seconds
    cost=0.005,   # Cost in USD
    metadata={
        "temperature": 0.7,
        "max_tokens": 500
    }
)

Filtering and Search

When listing logs, you can apply various filters:

# Filter by model
logs = client.logs.list(
    model="gpt-4",
    limit=50
)

# Filter by date range
from datetime import datetime, timedelta

end_date = datetime.now()
start_date = end_date - timedelta(days=7)

logs = client.logs.list(
    created_after=start_date.isoformat(),
    created_before=end_date.isoformat(),
    limit=100
)

# Filter by metadata
logs = client.logs.list(
    metadata_filter={"user_id": "user_123"},
    limit=25
)

Best Practices

1. Include Relevant Metadata

# Good - includes context for analysis
log = client.logs.create(
    messages=[...],
    model="gpt-4",
    metadata={
        "user_id": "user_123",
        "session_id": "session_456",
        "feature": "chat_assistant",
        "version": "1.2.0"
    }
)

2. Log Errors and Edge Cases

try:
    # Your AI operation
    response = generate_response(prompt)
    
    log = client.logs.create(
        messages=[{"role": "user", "content": prompt}],
        model="gpt-4",
        status="success",
        metadata={"operation": "text_generation"}
    )
except Exception as e:
    # Log the error
    log = client.logs.create(
        messages=[{"role": "user", "content": prompt}],
        model="gpt-4",
        status="error",
        metadata={
            "operation": "text_generation",
            "error": str(e),
            "error_type": type(e).__name__
        }
    )

3. Use Async for High Volume

import asyncio

async def log_batch(conversations):
    tasks = []
    for conv in conversations:
        task = client.logs.acreate(
            messages=conv["messages"],
            model=conv["model"],
            **conv.get("metadata", {})
        )
        tasks.append(task)
    
    results = await asyncio.gather(*tasks)
    return results

Error Handling

from keywordsai.exceptions import ValidationError, RateLimitError

try:
    log = client.logs.create(
        messages=[{"role": "user", "content": "Hello"}],
        model="gpt-4"
    )
except ValidationError as e:
    print(f"Invalid log data: {e}")
except RateLimitError:
    print("Rate limit exceeded, please retry later")
except Exception as e:
    print(f"Unexpected error: {e}")

Next Steps

• Learn how to create logs
• Explore listing and filtering logs
• Understand how to retrieve specific logs
• See complete examples for real-world usage