ai-healthcheck 0.1.1a1

Lightweight health checks for OpenAI

ai-healthcheck

Lightweight health checks for OpenAI — no heavy SDKs required.

• Minimal data-plane calls with tiny payloads and short timeouts
• Clear, predictable behavior (always returns HealthResult)
• Small install footprint (uses requests only)
• Perfect for application startup probes and CI/CD smoke tests

Installation

pip install ai-healthcheck

Quickstart

Set your credentials (example using environment variables), then call the check.

import os
from ai_healthcheck import check_openai

res = check_openai(
    endpoint=os.environ["OPENAI_ENDPOINT"],  # e.g., https://api.openai.com
    api_key=os.environ["OPENAI_API_KEY"],
    model="gpt-4o-mini",
    # Optional: scope to an organization if your account uses one
    # org_id=os.environ.get("OPENAI_ORG_ID"),
)
print(res)

Sample output

# HealthResult(provider='openai',
#              endpoint='https://api.openai.com',
#              ok=True,
#              status_code=200,
#              message='OpenAI reachable. Credentials and model appear valid.')

Usage

from ai_healthcheck import check_openai

res = check_openai(
    endpoint="https://api.openai.com",
    api_key="***",
    model="gpt-4o-mini",
    # Optional organization header
    # org_id="org_12345",
    timeout=10.0,
)
print(res.ok, res.status_code, res.message)

Behavior:

• 200 -> ok=True
• else (401/403 and other non-2xx, or network errors) -> ok=False with details

Notes

• Uses requests only; no SDK dependency.
• No custom User-Agent header is set (keep requests minimal).

Troubleshooting

• 404: API key may be valid, but the endpoint/path or model name is likely incorrect. Verify the endpoint (e.g., include /v1 only once) and the model.
• 401/403: Authentication/permission errors. Check API key and account access.

CI/CD and startup probes

Use these checks in your pipelines or app startup to fail fast with clear guidance.

def app_startup_probe():
    from ai_healthcheck import check_openai
    res = check_openai(endpoint=..., api_key=..., model=...)
    if not res.ok:
        raise RuntimeError(f"OpenAI health check failed: {res.message}")

Contributing

Contributions are welcome! Please open issues and pull requests on GitHub.