Metadata-Version: 2.4
Name: cognitivess
Version: 0.1.7
Summary: Official Python SDK for the CognitivessAI API (OpenAI- and Anthropic-compatible).
Author-email: CognitivessAI <hello@cognitivess.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/cognitivessai/cognitivess-python
Project-URL: Documentation, https://api.cognitivess.com/docs
Keywords: cognitivess,llm,ai,openai,anthropic,sdk,cognitivess-1
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: typing_extensions>=4.0.0; python_version < "3.11"
Dynamic: license-file

# 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**.

```bash
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`](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):

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

```dotenv
# .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

```python
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

```python
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

```python
# 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.

```python
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
```

```python
# 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

```python
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

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

### List models

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

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

## Configuration

```python
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

```python
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
