Skip to content

Quick Start Guide

Get started with CosmicMind Python SDK in minutes.

Prerequisites

  • Python 3.8 or higher
  • A CosmicMind API key (see "Getting an API Key" below)

Getting an API Key

To get started with CosmicMind, first request an account by submitting a signup request. Once your account is approved, you generate and manage your API keys yourself from the dashboard.

Submit a Signup Request

Make a POST request to the signup endpoint with your contact information:

import requests

signup_data = {
    "contact_email": "your-email@example.com",
    "contact_name": "Your Name",
    "requested_services": ["cosmicmind"],  # Optional: list of services you're interested in
    "contact_phone": "+1234567890",  # Optional
    "organization_name": "Your Company",  # Optional
    "intended_use_case": "Building an AI assistant"  # Optional
}

response = requests.post(
    "https://cosmicmind.pansynapse.com/api/signup-requests",
    json=signup_data
)

if response.status_code == 200:
    print("Signup request submitted successfully!")
    print("You'll be notified when your account is ready.")
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Required Fields: - contact_email: Your email address (must be a valid email format) - contact_name: Your full name

Optional Fields: - requested_services: List of services you're interested in (e.g., ["cosmicmind"]) - contact_phone: Your phone number - organization_name: Your company or organization name - intended_use_case: Brief description of how you plan to use CosmicMind

Once your account is active, sign in to the dashboard to generate an API key. You can create, rotate, and revoke keys yourself at any time. Keys have the format {org_id}.{token} and the secret is shown only once at creation, so copy and store it securely. With your key in hand, proceed with the installation and usage steps below.

Installation

pip install cosmicmind

Basic Usage

1. Initialize the Client

from cosmicmind import CosmicMindClient

client = CosmicMindClient(
    api_key="your_org_id.your_api_key",
    base_url="https://cosmicmind.pansynapse.com/api",  # Must include /api
    api_version="v1"  # API version (defaults to v1) - sent in X-API-Version header
)

Note: API versioning is handled via the X-API-Version HTTP header, not in request payloads. The api_version parameter sets this header for all requests made by the client.

2. Send Your First Message

# Send a chat message - context is automatically managed
response = client.chat.send(
    message="My name is Alice and I love hiking",
    user_id="alice_123"
)
print(response.message)

3. Continue the Conversation

CosmicMind remembers previous context:

# Later conversation - CosmicMind remembers!
response = client.chat.send(
    message="What outdoor activities do I enjoy?",
    user_id="alice_123"
)
print(response.message)  # Will reference hiking preference

Three Ways to Send Requests

The SDK supports multiple input styles:

from cosmicmind.models import ChatRequest

request = ChatRequest(
    messages=["Hello!"],
    user_id="alice",
    llm="cerebras",
    llm_model="llama-3.3-70b"
)
response = client.chat.send(request)

Style 2: Dictionary (Validates Internally)

response = client.chat.send({
    "messages": ["Hello!"],
    "user_id": "alice",
    "llm": "cerebras"
})

Style 3: Legacy Parameters (Backward Compatible)

response = client.chat.send(
    message="Hello!",
    user_id="alice",
    llm="cerebras"
)

Authentication

Once you have your API key (see "Getting an API Key" above), you can use it in one of the following ways:

  1. Pass it directly to the client: 

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

  2. Set environment variable: 

    export COSMICMIND_API_KEY="your_org_id.your_api_key"


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

Bringing Your Own LLM Key

Requests that call an LLM — chat and document ingest/upload — are billed against the LLM provider directly. How that key is supplied depends on your plan:

  • Free plan (free trial): Your first requests run on PanSynapse's own LLM provider keys, up to a fixed number of calls (currently 100). This lets you try CosmicMind without signing up for an LLM provider. Once those trial calls are used up, you must supply your own key.
  • Paid plans (Starter / Growth / Scale): You supply your own LLM provider API key on every request, from the start.

Supplying your key

Pass your LLM provider API key in the llm_api_key field on the request:

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

The key is used only for that single request and is not stored by PanSynapse. Send it on each request that needs it.

For document ingest and upload, pass llm_api_key the same way (as a JSON field on ingest, or a form field on upload — see the API Reference).

When a key is required (HTTP 402)

If a request needs your own key and you didn't supply one, the API returns HTTP 402 Payment Required with one of these codes:

  • 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 trial calls 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."}}

In both cases, retry the request with your own llm_api_key to continue. This is separate from the usage quota, which returns HTTP 429.

Next Steps