Skip to main content

Apna GenAI Python SDK

OpenAI-style Python SDK for the Gen AI Gateway API.

Install

pip install apna-genai

From source:

pip install -e ".[dev]"

Quickstart (sync)

from apna_genai import ApnaGenAI

client = ApnaGenAI(
    base_url="http://localhost:8080",
    api_key="tenant-token",
    scope="job_search",
)

resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)

print(resp.choices[0].message.content)

Quickstart (async)

from apna_genai import AsyncApnaGenAI

async def main() -> None:
    async with AsyncApnaGenAI(
        base_url="http://localhost:8080",
        api_key="tenant-token",
        scope="job_search",
    ) as client:
        resp = await client.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": "Hello"}],
        )
        print(resp.choices[0].message.content)

Final usage in an application

For production app code, this is the simplest setup pattern:

  1. Install SDK:
pip install apna-genai
  1. Configure environment once (recommended):
export APNA_GENAI_BASE_URL="https://stage-gateway.example.com"
export APNA_GENAI_API_KEY="tenant-token"
export APNA_GENAI_SCOPE="job_search"
  1. Use the client in code:
from apna_genai import ApnaGenAI

client = ApnaGenAI()  # reads env vars above
resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Give me 3 interview tips"}],
)
print(resp.choices[0].message.content)

Async variant:

from apna_genai import AsyncApnaGenAI

async def main() -> None:
    async with AsyncApnaGenAI() as client:
        resp = await client.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": "Give me 3 interview tips"}],
        )
        print(resp.choices[0].message.content)

Namespace layout

  • Chat completions: client.chat.completions.create(...)
  • Health check: client.health_check() / await client.health_check()

Environment selection (stage/prod)

The SDK does not auto-detect stage or prod. It uses this precedence for base_url:

  1. explicit base_url passed to constructor
  2. environment="stage"|"prod" mapped via:
    • APNA_GENAI_STAGE_BASE_URL
    • APNA_GENAI_PROD_BASE_URL
  3. APNA_GENAI_BASE_URL environment variable
  4. built-in default (http://localhost:8080)

Example:

export APNA_GENAI_BASE_URL="https://stage-gateway.example.com"
export APNA_GENAI_API_KEY="tenant-token"
export APNA_GENAI_SCOPE="job_search"
from apna_genai import ApnaGenAI

client = ApnaGenAI()  # picks APNA_GENAI_BASE_URL

Or with explicit environment selector:

from apna_genai import ApnaGenAI

client = ApnaGenAI(environment="stage")  # requires APNA_GENAI_STAGE_BASE_URL

Auth and required headers

  • Tenant chat calls require scope and either:
    • Bearer auth (Authorization: Bearer <token>) or
    • API key header (X-API-Key: <token>) when auth_mode="x_api_key".
  • Header/auth precedence is:
    1. per-request override
    2. client configuration
    3. environment fallback (APNA_GENAI_API_KEY, APNA_GENAI_SCOPE)

Per-request auth override

resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hi"}],
    api_key="override-token",
    scope="job_search",
)

Request options and retries

Use with_options(...) for scoped overrides:

fast_client = client.with_options(timeout=5.0, max_retries=5)
resp = fast_client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Ping"}],
)

Direct per-request overrides are also supported:

resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    timeout=5.0,
    max_retries=3,
    headers={"X-Request-Source": "my-service"},
)

Retry policy applies to:

  • network/connection errors
  • timeout errors
  • HTTP 408, 409, 429, and >=500

Default timeout is explicit (60s) and retries default to 2.

Error handling

from apna_genai import APIConnectionError, APIStatusError, RateLimitError

try:
    client.chat.completions.create(model="gpt-4o", messages=[{"role": "user", "content": "Hi"}])
except RateLimitError:
    print("Retry later")
except APIConnectionError:
    print("Network issue")
except APIStatusError as err:
    print(err.status_code, err.request_id, err.body)

Status-specific exceptions include: BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError.

Raw response access

For advanced users who need headers and the original httpx.Response:

raw = client.chat.completions.with_raw_response.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)

print(raw.parsed.choices[0].message.content)
print(raw.cost_quota_warning)
print(raw.http_response.status_code)

Request-level options (timeout, max_retries, headers, base_url, api_key, scope, auth_mode, provider) are applied to transport/auth only and are not included in the JSON API payload.

Model routing note

Provider selection is server-side and inferred from model prefix (for example gpt-*, gemini-*, mixtral-*). The SDK passes model through without duplicating routing logic.

Streaming caveat

The SDK includes the stream request field for compatibility, but this gateway does not currently support end-to-end SSE streaming.

API surface

  • Chat completions: POST /v1/chat/completions
  • Health check: GET /health-check

API contract and examples

Metadata

Release files for apna-genai 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for apna-genai 0.1.0
File Size Uploaded Provenance Actions
apna_genai-0.1.0.tar.gz 19.7 kB Without provenance Details for apna_genai-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for apna-genai 0.1.0
File Interpreter ABI Platform Actions
apna_genai-0.1.0-py3-none-any.whl Python 3 none any Details for apna_genai-0.1.0-py3-none-any.whl

Total release size: 39.7 kB

Release files / apna_genai-0.1.0.tar.gz

Download URL apna_genai-0.1.0.tar.gz
Size 19.7 kB
Tags Source
SHA-256 checksum
How to use checksums
292aec9326d40247210df89c7288114b88df4bf6f8aa7a51d4944fae68621ffe
BLAKE2b-256 checksum
How to use checksums
21c0c819e50fda3f38bd558f7f93636dd65acfeffb4143bee796fb7bee4bbc5a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Release files / apna_genai-0.1.0-py3-none-any.whl

Download URL apna_genai-0.1.0-py3-none-any.whl
Size 20.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a15be3739afbbcdf0c4c61e36b20544d908927cbc0a9d3d4de43b7963b4ddf65
BLAKE2b-256 checksum
How to use checksums
52e4151356cbcf14903280f58ca588028f81e2b192f362b5c28c6138d1654df9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.8

Security for apna-genai 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page