SEG Python SDK

The official Python library for the SovereignEG (SEG) API, a MENA-first, OpenAI-compatible AI inference platform. It provides typed synchronous and asynchronous clients for chat completions, embeddings, image generation, moderation, model listing, and decisions, built on httpx2 and Pydantic.

Installation

pip install seg-sdk

Requires Python 3.10 or newer. The distribution is seg-sdk; the import name is seg.

Usage

Create an API key in the SovereignEG dashboard and export it:

export SEG_API_KEY="sk-..."

from seg import SEG

client = SEG()  # reads SEG_API_KEY from the environment

completion = client.chat.completions.create(
    model="llama-3.1-8b-instruct",
    messages=[{"role": "user", "content": "Say hello in one short sentence."}],
    max_tokens=300,
)
print(completion.choices[0].message.content)

Pick a model from client.models.list(); the catalog depends on your plan. Reasoning models may spend the max_tokens budget thinking before answering, and expose that thinking as extra fields on the message (reasoning / reasoning_details, or reasoning_content depending on the serving provider).

Client options

api_key may also be a callable that returns the key; it is called before every request, which is useful for keys that rotate.

from seg import SEG

client = SEG(api_key="sk-...", base_url="http://127.0.0.1:8000/v1", timeout=30.0, max_retries=3)

Every option can also be set at module level for quick scripts:

import seg

seg.api_key = "sk-..."
print(seg.models.list().data[0].id)

Async usage

Import AsyncSEG and await each call:

import asyncio
from seg import AsyncSEG

client = AsyncSEG()


async def main() -> None:
    completion = await client.chat.completions.create(
        model="llama-3.1-8b-instruct",
        messages=[{"role": "user", "content": "Say hello"}],
    )
    print(completion.choices[0].message.content)


asyncio.run(main())

Install seg-sdk[aiohttp] and pass http_client=DefaultAioHttpClient() to use aiohttp instead of httpx2.

Streaming

Pass stream=True to receive Server-Sent Events as they are produced:

stream = client.chat.completions.create(
    model="llama-3.1-8b-instruct",
    messages=[{"role": "user", "content": "Count from 1 to 5."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

The async client works the same way with async for.

Structured outputs and tools

client.chat.completions.parse() turns a Pydantic model into a JSON schema, sends it as response_format, and parses the reply back into your model. seg.pydantic_function_tool() does the same for tool calls. See helpers.md for the full guide, including streaming helpers.

from pydantic import BaseModel
from seg import SEG


class Answer(BaseModel):
    city: str
    country: str


client = SEG()
completion = client.chat.completions.parse(
    model="llama-3.1-8b-instruct",
    messages=[{"role": "user", "content": "Where is the Great Pyramid?"}],
    response_format=Answer,
)
print(completion.choices[0].message.parsed)

Other resources

# Embeddings
client.embeddings.create(model="<embedding-model>", input="Cairo at night")

# Image generation
client.images.generate(model="<image-model>", prompt="A felucca on the Nile at sunset")

# Moderation
client.moderations.create(input="Some user text")

# Models
client.models.list()
client.models.retrieve("llama-3.1-8b-instruct")

# Decisions: typed questions about one input
client.decisions.create(
    model="<decision-model>",
    input="The package arrived late and the box was damaged.",
    questions=[
        {
            "type": "predicate",
            "name": "is_complaint",
            "instructions": "Is the customer complaining?",
        },
        {
            "type": "choice",
            "name": "sentiment",
            "instructions": "Overall sentiment?",
            "choices": [{"value": "positive"}, {"value": "neutral"}, {"value": "negative"}],
        },
    ],
)

The complete list of methods, parameters, and return types is in api.md.

Errors

Connection failures raise seg.APIConnectionError; non-2xx responses raise a subclass of seg.APIStatusError carrying status_code, request_id, and the decoded error body.

import seg
from seg import SEG

client = SEG()
try:
    client.chat.completions.create(model="missing-model", messages=[{"role": "user", "content": "hi"}])
except seg.RateLimitError:
    print("Slow down")
except seg.APIStatusError as e:
    print(e.status_code, e.request_id, e.body)

Every response carries an X-Request-Id header, and inference responses (chat, embeddings, images, moderations, decisions) also carry rate-limit headers such as X-RateLimit-Remaining-Requests; read them through with_raw_response.

Retries and timeouts

Connection errors, 408, 409, 429, and 5xx responses are retried twice with exponential backoff by default. Requests time out after 10 minutes. Both can be changed per client or per request:

client = SEG(max_retries=0, timeout=20.0)
client.with_options(max_retries=5, timeout=60.0).chat.completions.create(...)

Advanced

Raw responses and headers

response = client.chat.completions.with_raw_response.create(
    model="llama-3.1-8b-instruct",
    messages=[{"role": "user", "content": "hi"}],
)
print(response.headers.get("X-Request-Id"))
completion = response.parse()  # the parsed ChatCompletion

with_streaming_response does the same without reading the body eagerly; use it inside a with block.

Undocumented requests and parameters

client.get, client.post, and friends send arbitrary requests. Every method also accepts extra_query, extra_body, and extra_headers for parameters the SDK does not know about yet.

Custom HTTP client

import httpx2
from seg import SEG, DefaultHttpxClient

client = SEG(
    base_url="http://localhost:8000/v1",
    http_client=DefaultHttpxClient(
        proxy="http://my.proxy:3128", transport=httpx2.HTTPTransport(local_address="0.0.0.0")
    ),
)

Use the client as a context manager (with SEG() as client:) or call client.close() to release connections.

Logging

Set SEG_LOG=debug to log each request's method, response status, retries, and request id. Headers, bodies, and the API key are never written to the log.

Supported API surface

Versioning

This package follows SemVer. Changes that only affect static types, internal modules (prefixed with _), or that fix bugs are not considered breaking.

Requirements

Python 3.10 or higher.

Contributing

See CONTRIBUTING.md.

License

Apache License 2.0. This SDK is derived from the openai-python client, Copyright OpenAI, used under the same license; see NOTICE for attributions.