Best Practices¶

Guidelines for optimal usage of the CosmicMind Python SDK.

User ID Management¶

Always use consistent user_id values to maintain continuous context:

# Good - same user_id across sessions
response1 = client.chat.send("My favorite color is blue", user_id="alice_123")
response2 = client.chat.send("What's my favorite color?", user_id="alice_123")

# Bad - different user_ids lose context
response1 = client.chat.send("My favorite color is blue", user_id="alice_1")
response2 = client.chat.send("What's my favorite color?", user_id="alice_2")

Tips: - Use a consistent ID format (e.g., {service}_{user_id}) - Store user IDs in your database/user system - Don't generate random IDs for each request

Choosing the Right LLM¶

Select LLM providers based on your use case:

Fast responses: Use Cerebras Llama models
Complex reasoning: Use GPT-4 or Claude Opus
Cost optimization: Use Cerebras or GPT-3.5-turbo
Long context: Use Claude models (200K tokens)
Web-grounded: Use Perplexity for real-time information

Avatar Design¶

When creating avatars, follow these guidelines:

Give Avatars Specific Expertise Domains¶

# Good - specific domains
avatar = client.avatars.create({
    "name": "Python Expert",
    "knowledge_domains": ["python", "fastapi", "pydantic", "async-programming"]
})
# avatar["avatar_id"] contains the generated UUID

# Bad - too generic
avatar = client.avatars.create({
    "name": "Programmer",
    "knowledge_domains": ["coding"]
})

Define Clear Personalities¶

# Good - clear personality traits
avatar = client.avatars.create({
    "name": "Mentor",
    "personality": {
        "traits": ["patient", "encouraging", "supportive"],
        "speaking_style": "Uses examples and asks clarifying questions"
    }
})
# avatar["avatar_id"] contains the generated UUID

Use Communication Styles¶

avatar = client.avatars.create({
    "name": "Tech Support",
    "communication_patterns": [
        {
            "pattern_type": "greeting",
            "pattern": "Hi! I'm here to help with your technical questions."
        },
        {
            "pattern_type": "closing",
            "pattern": "Feel free to ask if you need more help!"
        }
    ]
})
# avatar["avatar_id"] contains the generated UUID

Error Handling¶

Always implement proper error handling:

from cosmicmind import (
    CosmicMindClient,
    AuthenticationError,
    RateLimitError,
    ValidationError,
    ServerError
)

try:
    response = client.chat.send("Hello!")
except AuthenticationError:
    # Handle invalid API key
    logger.error("Authentication failed")
except RateLimitError as e:
    # Handle rate limiting - implement backoff
    time.sleep(e.retry_after)
except ValidationError as e:
    # Handle invalid request data
    logger.error(f"Invalid request: {e}")
except ServerError:
    # Handle server errors - implement retry logic
    logger.error("Server error occurred")

Type Safety¶

Use Pydantic models for better type safety and validation:

from cosmicmind.models import ChatRequest, ChatResponse

# Type-safe request
request = ChatRequest(
    messages=["Hello!"],
    user_id="alice_123",
    llm="cerebras"
)

# Typed response
response: ChatResponse = client.chat.send(request)

# IDE autocomplete works!
print(response.message)
print(response.request_id)

Performance Optimization¶

If you need to make multiple related requests, consider batching:

# Instead of multiple separate requests
responses = []
for message in messages:
    response = client.chat.send(message, user_id="user_123")
    responses.append(response)

# Consider if your use case allows batching at the API level

Cache Avatar Data¶

Cache avatar information to avoid repeated API calls:

# Cache avatar list
avatars_cache = {}
if avatar_id not in avatars_cache:
    avatars_cache[avatar_id] = client.avatars.get(avatar_id)

Security Best Practices¶

Never commit API keys - Use environment variables
Rotate API keys regularly
Use different API keys for different environments
Monitor token usage to detect anomalies

import os

client = CosmicMindClient(
    api_key=os.getenv("COSMICMIND_API_KEY"),
    base_url=os.getenv("COSMICMIND_BASE_URL", "https://cosmicmind.pansynapse.com/api")
)

Monitoring and Logging¶

Track usage and errors:

import logging

logger = logging.getLogger(__name__)

try:
    response = client.chat.send(message, user_id=user_id)
    logger.info(f"Request successful: {response.request_id}")
    logger.debug(f"Tokens used: {response.token_usage['total_tokens']}")
except Exception as e:
    logger.error(f"Request failed: {e}", exc_info=True)

Version Management¶

Keep your SDK version up to date:

pip install --upgrade cosmicmind

Check the current version:

import cosmicmind
print(cosmicmind.__version__)