# ai-healthcheck
[](https://pypi.org/project/ai-healthcheck/)
[](https://github.com/skytin1004/ai-healthcheck/blob/main/LICENSE)
[](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",
)
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",
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/43/13/232a7346d4030d64032f53f1dba9333d75b7ec7e231eec53512b6056755b/ai_healthcheck-0.1.0.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\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)\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 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.0",
"project_urls": {
"Repository": "https://github.com/skytin1004/ai-healthcheck"
},
"split_keywords": [
"openai",
" healthcheck",
" monitoring"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ff5bfb40ed901d76ad17e95b5c1d44d4c17e17e0f5ac9d1293773efa697914a7",
"md5": "df81e521ddbe3ab019e1ae008fd6d197",
"sha256": "6f8ae74048994e9eae52bb4cc3f3ce2c60a088f32a6bd69cd62d3f6e60a89a92"
},
"downloads": -1,
"filename": "ai_healthcheck-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "df81e521ddbe3ab019e1ae008fd6d197",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 5221,
"upload_time": "2025-08-28T04:26:16",
"upload_time_iso_8601": "2025-08-28T04:26:16.468729Z",
"url": "https://files.pythonhosted.org/packages/ff/5b/fb40ed901d76ad17e95b5c1d44d4c17e17e0f5ac9d1293773efa697914a7/ai_healthcheck-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4313232a7346d4030d64032f53f1dba9333d75b7ec7e231eec53512b6056755b",
"md5": "4319c5423c8144409de6d833a09230f8",
"sha256": "8f65687bd29b0d274a9f97d9167979a86ea4453ef98a8aab8a49984f5232d2ee"
},
"downloads": -1,
"filename": "ai_healthcheck-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "4319c5423c8144409de6d833a09230f8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 3903,
"upload_time": "2025-08-28T04:26:17",
"upload_time_iso_8601": "2025-08-28T04:26:17.187319Z",
"url": "https://files.pythonhosted.org/packages/43/13/232a7346d4030d64032f53f1dba9333d75b7ec7e231eec53512b6056755b/ai_healthcheck-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 04:26:17",
"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
