cognitivess — Python SDK

Official Python SDK for the CognitivessAI API. The platform is OpenAI- and Anthropic-compatible, so this SDK gives you both ergonomics in one package, talking to model Cognitivess-1.

pip install cognitivess

• Sync and async clients (Cognitivess / AsyncCognitivess)
• Streaming (SSE) for chat, messages and responses, plus an iter_text() helper that yields just the content strings
• Structured Outputs (response_format) pass-through
• Typed exceptions, retries with backoff (honors Retry-After), per-request timeout override
• Reads .env automatically — COGNITIVESS_API_KEY and COGNITIVESS_BASE_URL (no python-dotenv dependency)
• models.list() and models.retrieve(id)
• Zero heavy deps — only httpx · ships py.typed

See CHANGELOG.md for what's new per version.

Setup

Generate an API key in your CognitivessAI dashboard (looks like ssh-ed25519 AAAA...). It's shown only once. Then either pass it explicitly, export it, or put it in a .env file — the SDK reads .env automatically (no python-dotenv / load_dotenv() needed):

export COGNITIVESS_API_KEY="ssh-ed25519 AAAA..."

# .env  (in your project root / cwd)
COGNITIVESS_API_KEY=ssh-ed25519 AAAA...
# COGNITIVESS_BASE_URL=https://api.cognitivess.com/v1   # optional, for self-hosted/dev

The .env fallback only fills in variables that aren't already set in the environment, so explicit env vars or api_key= always win. Disable it with Cognitivess(env_file=None), or point elsewhere with Cognitivess(env_file="config/.env").

Quickstart

OpenAI style — chat completions

from cognitivess import Cognitivess

cog = Cognitivess()  # reads COGNITIVESS_API_KEY

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 — raw chunks
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)

iter_text() — convenience that streams under the hood (it sets stream=True for you) and yields just the content strings, skipping metadata / empty chunks. Sync (for) and async (async for). Don't pass stream=True to it — it streams already.

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

# 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

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

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

List models

print(cog.models.list().data[0].id)

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

Configuration

cog = Cognitivess(
    api_key="...",            # optional, defaults to COGNITIVESS_API_KEY
    base_url="...",           # optional, defaults to COGNITIVESS_BASE_URL then the API
    timeout=60.0,             # seconds
    max_retries=2,            # retries on 429/5xx/conn errors, with backoff
    default_headers={"X-Tag": "prod"},  # merged into every request
    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)

Error handling

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)

Notes

• This package is the SDK library. The cognitivess CLI (installed via curl | sh) is a separate tool; installing this SDK does not register a cognitivess console command, so the two coexist without conflict.
• base_url already includes /v1. The SDK calls /chat/completions, /messages, /models, /responses relative to it. It defaults to COGNITIVESS_BASE_URL (env / .env) then https://api.cognitivess.com/v1. For self-hosted/dev, point it at e.g. http://localhost:8000/v1.
• Responses objects are attribute-accessible (resp.choices[0].message.content) via a light wrapper — no Pydantic dependency. A py.typed marker is shipped.

License

MIT