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 (iter_text()), structured outputs, typed errors, retries, and automatic .env loading — no python-dotenv required.

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, export COGNITIVESS_API_KEY, or put it in a .env file — the SDK loads .env automatically (no python-dotenv needed).

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())

Just want the text? iter_text() streams internally and yields only content strings (sync for / async async for):

for text in cog.chat.completions.iter_text(  # streams under the hood, no stream=True needed
    model="Cognitivess-1",
    messages=[{"role": "user", "content": "Count to 5."}],
    max_tokens=64,
):
    print(text, end="", flush=True)
# 1 2 3 4 5

Production-ready streaming (.env + iter_text())

The SDK reads .env on its own, and iter_text() yields only the content strings — it already skips chunks with empty choices (metadata / keepalive) and reads content safely, so there's no load_dotenv() and no getattr boilerplate.

# .env  (in your project root)
# COGNITIVESS_API_KEY=ssh-ed25519 AAAA...

from cognitivess import Cognitivess  # no load_dotenv() needed

cog = Cognitivess()  # picks up COGNITIVESS_API_KEY from .env automatically

# iter_text() streams under the hood — it sets stream=True for you and
# yields only the content strings (empty/metadata chunks are skipped).
for text in cog.chat.completions.iter_text(
    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(text, end="", flush=True)

# console (tokens arrive as they're generated):
# I'm doing well, thanks! How can I help you today?

Don't pass stream=True to iter_text() — it streams already (passing it would error). Prefer raw chunks? Use create(..., stream=True) and read chunk.choices[0].delta.content as shown above. iter_text() works async too: async for text in cog.chat.completions.iter_text(...).

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

# single model
print(cog.models.retrieve("Cognitivess-1").id)

Configuration

cog = Cognitivess(
    api_key="...",                # optional, defaults to COGNITIVESS_API_KEY
    base_url="https://api.cognitivess.com/v1",    # optional, defaults to COGNITIVESS_BASE_URL then the API
    timeout=60.0,                # seconds
    max_retries=2,                # retries on 429/5xx/conn errors, honors Retry-After
    default_headers={"X-Tag": "prod"},
    env_file=".env",               # auto-load .env (default); None to disable
)

# per-request timeout override (not sent in the JSON body):
cog.chat.completions.create(..., timeout=120)

api_key and base_url both resolve from the environment / .env as a fallback — an explicit argument always wins. Retries honor the gateway's Retry-After header on 429.

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.