# ai-healthcheck
[](https://pypi.org/project/ai-healthcheck/)
[](https://github.com/skytin1004/ai-healthcheck/blob/main/LICENSE)
[](https://pepy.tech/project/ai-healthcheck)
[](https://pepy.tech/project/ai-healthcheck)
[](https://GitHub.com/skytin1004/ai-healthcheck/graphs/contributors/)
[](https://GitHub.com/skytin1004/ai-healthcheck/issues/)
[](https://GitHub.com/skytin1004/ai-healthcheck/pulls/)
[](http://makeapullrequest.com)
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
```bash
pip install ai-healthcheck
```
## Quickstart
Set your credentials (example using environment variables), then call the check.
```python
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
```python
# HealthResult(provider='openai',
# endpoint='https://api.openai.com',
# ok=True,
# status_code=200,
# message='OpenAI reachable. Credentials and model appear valid.')
```
## Usage
```python
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.
```python
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.
Raw data
{
"_id": null,
"home_page": null,
"name": "ai-healthcheck",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "openai, healthcheck, monitoring",
"author": "Minseok Song",
"author_email": "minseok.song@mssong.com",
"download_url": "https://files.pythonhosted.org/packages/2b/f9/f5fed3009b2d109919841cb5e15703cec4b513db9dfc6eee6292baeaca67/ai_healthcheck-0.1.1.tar.gz",
"platform": null,
"description": "# ai-healthcheck\n\n[](https://pypi.org/project/ai-healthcheck/)\n[](https://github.com/skytin1004/ai-healthcheck/blob/main/LICENSE)\n[](https://pepy.tech/project/ai-healthcheck)\n[](https://pepy.tech/project/ai-healthcheck)\n\n[](https://GitHub.com/skytin1004/ai-healthcheck/graphs/contributors/)\n[](https://GitHub.com/skytin1004/ai-healthcheck/issues/)\n[](https://GitHub.com/skytin1004/ai-healthcheck/pulls/)\n[](http://makeapullrequest.com)\n\nLightweight health checks for OpenAI \u2014 no heavy SDKs required.\n\n- Minimal data-plane calls with tiny payloads and short timeouts\n- Clear, predictable behavior (always returns `HealthResult`)\n- Small install footprint (uses `requests` only)\n- Perfect for application startup probes and CI/CD smoke tests\n\n## Installation\n\n```bash\npip install ai-healthcheck\n```\n\n## Quickstart\n\nSet your credentials (example using environment variables), then call the check.\n\n```python\nimport os\nfrom ai_healthcheck import check_openai\n\nres = check_openai(\n endpoint=os.environ[\"OPENAI_ENDPOINT\"], # e.g., https://api.openai.com\n api_key=os.environ[\"OPENAI_API_KEY\"],\n model=\"gpt-4o-mini\",\n # Optional: scope to an organization if your account uses one\n # org_id=os.environ.get(\"OPENAI_ORG_ID\"),\n)\nprint(res)\n```\n\n### Sample output\n\n```python\n# HealthResult(provider='openai',\n# endpoint='https://api.openai.com',\n# ok=True,\n# status_code=200,\n# message='OpenAI reachable. Credentials and model appear valid.')\n```\n\n## Usage\n\n```python\nfrom ai_healthcheck import check_openai\n\nres = check_openai(\n endpoint=\"https://api.openai.com\",\n api_key=\"***\",\n model=\"gpt-4o-mini\",\n # Optional organization header\n # org_id=\"org_12345\",\n timeout=10.0,\n)\nprint(res.ok, res.status_code, res.message)\n```\n\nBehavior:\n- 200 -> ok=True\n- else (401/403 and other non-2xx, or network errors) -> ok=False with details\n\n## Notes\n\n- Uses `requests` only; no SDK dependency.\n- No custom User-Agent header is set (keep requests minimal).\n\n## Troubleshooting\n\n- 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.\n- 401/403: Authentication/permission errors. Check API key and account access.\n\n## CI/CD and startup probes\n\nUse these checks in your pipelines or app startup to fail fast with clear guidance.\n\n```python\ndef app_startup_probe():\n from ai_healthcheck import check_openai\n res = check_openai(endpoint=..., api_key=..., model=...)\n if not res.ok:\n raise RuntimeError(f\"OpenAI health check failed: {res.message}\")\n```\n\n## Contributing\n\nContributions are welcome! Please open issues and pull requests on GitHub.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Lightweight health checks for OpenAI",
"version": "0.1.1",
"project_urls": {
"Repository": "https://github.com/skytin1004/ai-healthcheck"
},
"split_keywords": [
"openai",
" healthcheck",
" monitoring"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "43ce604e7f386db8e6cb61d4bc288f14187724f2ce20cb09bd9a73ef032fbd80",
"md5": "84318086517da8cf5dad4581eb2a47c4",
"sha256": "7f2a4356ec1b4381edb167a822cb459101aa04b2f674fffeee61823fd623704a"
},
"downloads": -1,
"filename": "ai_healthcheck-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "84318086517da8cf5dad4581eb2a47c4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 5386,
"upload_time": "2025-09-02T10:37:09",
"upload_time_iso_8601": "2025-09-02T10:37:09.473484Z",
"url": "https://files.pythonhosted.org/packages/43/ce/604e7f386db8e6cb61d4bc288f14187724f2ce20cb09bd9a73ef032fbd80/ai_healthcheck-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2bf9f5fed3009b2d109919841cb5e15703cec4b513db9dfc6eee6292baeaca67",
"md5": "f383934a177ecc24b4e71da9df40a25c",
"sha256": "ca008be5d11428a0150a28c95a8933ffce13729e4550d5fec1f47d6572dd71f1"
},
"downloads": -1,
"filename": "ai_healthcheck-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "f383934a177ecc24b4e71da9df40a25c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 4060,
"upload_time": "2025-09-02T10:37:10",
"upload_time_iso_8601": "2025-09-02T10:37:10.642432Z",
"url": "https://files.pythonhosted.org/packages/2b/f9/f5fed3009b2d109919841cb5e15703cec4b513db9dfc6eee6292baeaca67/ai_healthcheck-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-02 10:37:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "skytin1004",
"github_project": "ai-healthcheck",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ai-healthcheck"
}
JSON
