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:
- Install SDK:
pip install apna-genai
- 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"
- 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:
- explicit
base_urlpassed to constructor environment="stage"|"prod"mapped via:APNA_GENAI_STAGE_BASE_URLAPNA_GENAI_PROD_BASE_URL
APNA_GENAI_BASE_URLenvironment variable- 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
scopeand either:- Bearer auth (
Authorization: Bearer <token>) or - API key header (
X-API-Key: <token>) whenauth_mode="x_api_key".
- Bearer auth (
- Header/auth precedence is:
- per-request override
- client configuration
- 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
- SDK API reference:
api.md - Runnable examples:
examples/ - Environment routing example:
examples/environment_routing.py
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.