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:
    # Usage quota exceeded (HTTP 429) - wait for the next period, then retry
    logger.warning("Usage quota exceeded for the current period")
    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")

Usage Quota¶

Your account has a single usage quota — a maximum number of requests per period (for example, 10,000 requests / day) that applies across all of your API keys, not per key. When you exceed it, the API returns HTTP 429 with a message like:

Usage quota exceeded for the current day period.

The SDK raises RateLimitError in this case. There is no separate per-minute rate limit or burst limit enforced at the API layer — the only limit is your account's request quota for the current period.

Guidelines:

Handle 429 gracefully. Treat RateLimitError as "you've used your quota for this period" and back off until the period resets, rather than retrying immediately in a tight loop.
Quota counting is eventually consistent. The usage counter catches up shortly after each request, so a short burst may momentarily go slightly over your quota before the counter settles. Don't rely on the exact cutoff being enforced to the single request.
Spread work across the period where possible, rather than sending your entire day's volume in one spike.
Need more headroom? You can request a quota increase from your dashboard. Pick from the available preset tiers; increases are reviewed and approved by the PanSynapse team.

from cosmicmind import RateLimitError

try:
    response = client.chat.send("Hello!", user_id="alice_123")
except RateLimitError:
    # Over quota for the current period - back off and retry later
    logger.warning("Usage quota exceeded; retry after the period resets")

Bringing Your Own LLM Key¶

Requests that invoke an LLM — chat and document ingest/upload — are billed against the LLM provider. Which key is used depends on your plan:

Free plan (free trial): Your first requests run on PanSynapse's LLM provider keys, up to a fixed number of calls (currently 100). After that, you supply your own key.
Paid plans (Starter / Growth / Scale): You supply your own LLM provider API key on every request.

Pass the key in the llm_api_key field (JSON body on chat and document ingest; the llm_api_key form field on /documents/upload). It is used only for that request and is not stored by PanSynapse.

response = client.chat.send(
    message="Explain quantum computing",
    user_id="alice_123",
    llm="openai",
    llm_api_key="sk-..."  # used only for this request, never stored
)

Guidelines:

Keep your key server-side. Pull it from a secret store or environment variable at request time; never hard-code or commit it.
Handle 402 gracefully. A 402 Payment Required means the request needs your own key. Two codes are returned:
llm_key_required — on a paid plan, when no llm_api_key was provided.
free_trial_exhausted — on the Free plan, once your trial calls are used up.

In both cases, retry with your own llm_api_key. This is distinct from the usage quota 429.

import requests

try:
    response = client.chat.send("Hello!", user_id="alice_123", llm_api_key=my_key)
except requests.HTTPError as e:
    if e.response.status_code == 402:
        code = e.response.json().get("detail", {}).get("code")
        if code == "free_trial_exhausted":
            logger.warning("Free trial used up - supply your own llm_api_key")
        elif code == "llm_key_required":
            logger.warning("Paid plan requires your own llm_api_key")

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 - Generate, rotate, and revoke keys yourself from the dashboard; the key secret is shown only once at creation, so store it immediately
Use different API keys for different environments - Issue a separate key per environment so you can revoke one without affecting the others
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__)