Chat Examples

Examples demonstrating chat functionality with the CosmicMind SDK.

Simple Chat

from cosmicmind import CosmicMindClient

client = CosmicMindClient(
    api_key="your_org_id.your_api_key",
    base_url="https://cosmicmind.pansynapse.com/api"
)

response = client.chat.send("Hello, how are you?")
print(response.message)

Context-Aware Conversations

CosmicMind maintains context across conversations:

from cosmicmind import CosmicMindClient

client = CosmicMindClient(
    api_key="your_org_id.your_api_key",
    base_url="https://cosmicmind.pansynapse.com/api"
)

# First conversation - establishing context
response = client.chat.send(
    message="I work at Google as a software engineer",
    user_id="user_123"
)

# Later conversation - CosmicMind injects relevant context
response = client.chat.send(
    message="What company do I work for?",
    user_id="user_123"
)
print(response.message)  # References Google from previous conversation

Multi-LLM Support

Use different LLM providers for different use cases:

Cerebras (Fast, Affordable)

response = client.chat.send(
    message="Explain quantum computing",
    llm="cerebras",
    llm_model="llama-3.3-70b"
)

OpenAI GPT-4

response = client.chat.send(
    message="Write a detailed business plan",
    llm="openai",
    llm_model="gpt-4"
)

Anthropic Claude

response = client.chat.send(
    message="Analyze this research paper",
    llm="anthropic",
    llm_model="claude-3-sonnet-20240229"
)

Google Gemini

response = client.chat.send(
    message="Summarize this article",
    llm="google",
    llm_model="gemini-2.0-flash-exp"
)

Bringing Your Own LLM Key

Chat requests are billed against the LLM provider. On paid plans you supply your own provider API key on every request; on the Free plan your first 100 calls run on PanSynapse's keys, after which your own key is required. Pass it in llm_api_key — it is used only for that request and is not stored.

response = client.chat.send(
    message="Explain quantum computing",
    user_id="user_123",
    llm="openai",
    llm_model="gpt-4",
    llm_api_key="sk-..."  # your provider key, used only for this request
)
print(response.message)

The equivalent raw request body:

{
    "messages": ["Explain quantum computing"],
    "user_id": "user_123",
    "llm": "openai",
    "llm_model": "gpt-4",
    "llm_api_key": "sk-..."
}

If your own key is required but missing, the API returns HTTP 402 — see Error Handling below.

Token Usage and Cost Tracking

response = client.chat.send(
    message="Explain machine learning",
    user_id="user_123"
)

# Access usage metrics
print(f"Input tokens: {response.token_usage['input_tokens']}")
print(f"Output tokens: {response.token_usage['output_tokens']}")
print(f"Total tokens: {response.token_usage['total_tokens']}")
print(f"Cost: ${response.token_usage['cost_usd']:.6f}")
print(f"Energy: {response.token_usage['energy_wh']:.2f} Wh")

Error Handling

from cosmicmind import (
    CosmicMindClient,
    AuthenticationError,
    RateLimitError,
    ServiceNotAvailableError
)

client = CosmicMindClient(
    api_key="your_org_id.your_api_key",
    base_url="https://cosmicmind.pansynapse.com/api"
)

try:
    response = client.chat.send("Hello!")
except AuthenticationError:
    print("Invalid API key - check your credentials")
except RateLimitError as e:
    print(f"Usage quota exceeded for the current period - retry after {e.retry_after} seconds")
except ServiceNotAvailableError:
    print("This service is not included in your plan")
except Exception as e:
    print(f"Unexpected error: {e}")

Handling "bring your own key" errors (HTTP 402)

When a chat request needs your own LLM provider key and none was supplied, the API returns HTTP 402 Payment Required with a detail.code:

• llm_key_required — on a paid plan, when no llm_api_key was provided:

  {"detail": {"code": "llm_key_required", "message": "Your plan requires your own LLM provider API key. Include it as 'llm_api_key' in your request to continue."}}
  

• free_trial_exhausted — on the Free plan, once your 100 trial requests are used up:

  {"detail": {"code": "free_trial_exhausted", "message": "Your free trial of 100 requests is used up. Include your own LLM provider API key as 'llm_api_key' in your request to continue."}}
  

Retry the request with your own llm_api_key set. (This is separate from the usage-quota 429.)

Type-Safe Requests

Use Pydantic models for type safety:

from cosmicmind import CosmicMindClient
from cosmicmind.models import ChatRequest, ChatResponse

client = CosmicMindClient(
    api_key="your_org_id.your_api_key",
    base_url="https://cosmicmind.pansynapse.com/api"
)

request = ChatRequest(
    messages=["Hello, who am I?"],
    user_id="alice_123",
    llm="cerebras",
    llm_model="llama-3.3-70b"
)

response: ChatResponse = client.chat.send(request)
print(response.message)
print(f"Request ID: {response.request_id}")