cygnisai-sdk-python 1.0.0

Official Python SDK for the CygnisAI API

CygnisAI Python SDK

The simplest, fastest way to integrate CygnisAI language models into your Python projects.

Note: API access is currently in private beta. Key creation is not yet open to the public.

---

Installation

pip install git+https://github.com/Simonc44/cygnisai_sdk_python.git

---

Quick Start

import cygnisai_sdk_python as cygnis

cygnis.configure(api_key="YOUR_API_KEY")

model = cygnis.GenerativeModel("alpha2")
response = model.generate_content("Give me a Python tip.")
print(response.text)

Environment variable

Set CYGNIS_API_KEY and call configure() without arguments:

import cygnisai_sdk_python as cygnis

cygnis.configure()          # reads CYGNIS_API_KEY automatically
model = cygnis.GenerativeModel("alpha2")

---

Streaming

stream = model.generate_content("Tell me a story.", stream=True)

import asyncio

async def main():
    async for token in stream:
        print(token, end="", flush=True)

asyncio.run(main())

---

Async usage

import asyncio
import cygnisai_sdk_python as cygnis

cygnis.configure(api_key="YOUR_API_KEY")
model = cygnis.GenerativeModel("alpha2")

async def main():
    response = await model.async_generate_content("Hello!")
    print(response.text)
    print(f"Latency: {response.latency_ms} ms")
    print(f"Tokens used: {response.usage.total_tokens}")

asyncio.run(main())

---

Low-level client

import asyncio
from cygnisai_sdk_python import CygnisAIClient, ChatRequest, Message

async def main():
    async with CygnisAIClient(api_key="YOUR_KEY") as client:
        request = ChatRequest(
            model="alpha2",
            prompt="What is 2+2?",
            messages=[Message(role="user", content="What is 2+2?")],
        )
        response = await client.chat(request)
        print(response.response)

asyncio.run(main())

---

Error handling

import cygnisai_sdk_python as cygnis

cygnis.configure(api_key="YOUR_KEY")
model = cygnis.GenerativeModel("alpha2")

try:
    response = model.generate_content("Hello!")
except cygnis.AuthenticationError:
    print("Invalid API key.")
except cygnis.RateLimitError:
    print("Too many requests — slow down.")
except cygnis.ServerError as e:
    print(f"Server error {e.status_code}: {e.message}")
except cygnis.NetworkError:
    print("Could not reach the API.")
except cygnis.CygnisAIError as e:
    print(f"Unexpected SDK error: {e}")

---

Configuration options

Parameter	Type	Default	Description
api_key	str	CYGNIS_API_KEY env var	Your secret API key
base_url	str	production URL	Override the API base URL
timeout	float	30.0	HTTP timeout in seconds
max_retries	int	3	Retries on transient errors (429, 5xx)

---

Available Models

Model	Description	Status
alpha_v01	Initial test version, lightweight prototyping	Stable
alpha1	Balanced, optimised for response speed	Stable
alpha2	Most capable, recommended for complex reasoning	Stable

---

Feature Status

• Simple interface (GenerativeModel)
• Streaming (stream=True)
• Async-native client with context manager
• Automatic retries with exponential backoff
• Environment-variable API key
• Typed exceptions (AuthenticationError, RateLimitError, …)
• Pydantic v2 validation
• py.typed marker (PEP 561)
• Public access (closed beta)

---

Development

pip install -e ".[dev]"
pytest tests/ -v

---

Licence

MIT — see LICENCE for details.