CognitivessAI — Cognitivess SDK

The official Python SDK for the CognitivessAI API. The platform is OpenAI- and Anthropic-compatible, so the SDK gives you both ergonomics in one package — client.chat.completions.create() and client.messages.create() — talking to model Cognitivess-1. Sync and async, streaming, structured outputs, typed errors, retries.

Installpip install cognitivess

PyPIpypi.org/project/cognitivess

Sourcegithub.com/Cognitivess/cognitivess-python

Depends onhttpx (only)

Install

pip install cognitivess

Generate an API key (ssh-ed25519 ...) in the dashboard. Then either pass it to the client or export COGNITIVESS_API_KEY.

Quickstart

OpenAI style — chat completions

from cognitivess import Cognitivess

cog = Cognitivess()  # reads COGNITIVESS_API_KEY from env

resp = cog.chat.completions.create(
    model="Cognitivess-1",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello, how are you?"},
    ],
    max_tokens=128,
    temperature=0.7,
)
print(resp.choices[0].message.content)

Anthropic style — messages

msg = cog.messages.create(
    model="Cognitivess-1",
    max_tokens=128,
    system="You are a helpful assistant.",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(msg.content[0].text)

Streaming (sync + async)

# sync
for chunk in cog.chat.completions.create(
    model="Cognitivess-1",
    messages=[{"role": "user", "content": "Count to 5."}],
    max_tokens=64, stream=True,
):
    delta = chunk.choices[0].delta.content
    if delta: print(delta, end="", flush=True)

# async
import asyncio
from cognitivess import AsyncCognitivess

async def main():
    async with AsyncCognitivess() as cog:
        async for chunk in cog.chat.completions.create(
            model="Cognitivess-1",
            messages=[{"role": "user", "content": "Count to 5."}],
            max_tokens=64, stream=True,
        ):
            delta = chunk.choices[0].delta.content
            if delta: print(delta, end="", flush=True)

asyncio.run(main())

Structured Outputs

Pass response_format straight through — the platform enforces your JSON schema on Cognitivess-1.

resp = cog.chat.completions.create(
    model="Cognitivess-1",
    messages=[{"role": "user", "content": "I spent $120 on dinner and $45 on supplies."}],
    max_tokens=512, temperature=0.1,
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "expenses", "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "items": {"type": "array", "items": {"type": "object",
                        "properties": {"description": {"type": "string"}, "amount": {"type": "number"}},
                        "required": ["description", "amount"], "additionalProperties": False}},
                    "total": {"type": "number"},
                },
                "required": ["items", "total"], "additionalProperties": False,
            },
        },
    },
)
print(resp.choices[0].message.content)  # JSON string

Responses API & models

r = cog.responses.create(
    model="Cognitivess-1",
    input="Say hi in one word.",
    max_output_tokens=16,
)
print(r.output_text)

print(cog.models.list().data[0].id)  # Cognitivess-1

Configuration

cog = Cognitivess(
    api_key="...",                # optional, defaults to COGNITIVESS_API_KEY
    base_url="https://api.cognitivess.com/v1",    # override for self-hosted/dev
    timeout=60.0,                # seconds
    max_retries=2,                # retries on 429/5xx/conn errors, with backoff
    default_headers={"X-Tag": "prod"},
)

Error handling

Typed exceptions

from cognitivess import AuthenticationError, RateLimitError, APIStatusError, APITimeoutError

try:
    cog.chat.completions.create(model="Cognitivess-1", messages=[...], max_tokens=64)
except AuthenticationError as e:   # 401 — bad/revoked key
    print("auth:", e.message, e.status_code)
except RateLimitError as e:        # 429 — rate limit / credits
    print("rate:", e.message)
except APITimeoutError:              # timeout
    ...
except APIStatusError as e:        # any other non-2xx
    print("status:", e.status_code, e.message)

Source & docs

Full reference, issues and releases on GitHub; package on PyPI.

GitHub →

Note: this is the SDK library (pip install cognitivess). The cognitivess CLI (installed via curl | sh) is a separate tool — the two coexist; installing the SDK does not register a cognitivess console command.