Skip to main content

nimstatus

A dependency-free Python 3.11+ library that replaces hardcoded NVIDIA model IDs with aliases: fast, general, code, tools, and json.

Install

After the first PyPI release:

python -m pip install nimstatus

To install from a local checkout:

python -m pip install ./clients/python

After these files have been pushed to GitHub:

python -m pip install "nimstatus @ git+https://github.com/Jaykay73/free-models.git@main#subdirectory=clients/python"

For reproducible application builds, replace main with a reviewed commit SHA. This pins the client implementation; model selections still refresh dynamically. Use the client in your application environment. Use a separate environment if you also install the monitor, which shares the nimstatus import name.

Use without model IDs

from nimstatus import ModelRouter

router = ModelRouter()
print(router.primary("fast"))
print(router.resolve("code"))

The default directory is https://jaykay73.github.io/free-models/status.json. No network request occurs when constructing the router. Calls refresh its process-local cache at most once every five minutes.

For inference, install the OpenAI SDK in your application and provide your key only to that SDK:

import os
from openai import OpenAI
from nimstatus import ModelRouter

api = OpenAI(
    base_url="https://integrate.api.nvidia.com/v1",
    api_key=os.environ["NVIDIA_API_KEY"],
    max_retries=0,
    timeout=30,
)
router = ModelRouter(max_attempts=3)

answer = router.call("fast", lambda model: api.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "Explain what a dictionary is."}],
    max_tokens=256,
))
print(answer.choices[0].message.content)

Only the alias stays in application code. Each call resolves current routing through the cache; 429, 5xx and recognized connection/timeout failures try the next model. Auth and bad-request errors propagate immediately. Unknown errors are not retried. Override classification with ModelRouter(retryable=...) for other SDKs. SDK retrying is disabled in the example so attempts remain bounded.

This library sends no inference traffic and accepts no API key. Your callback calls NVIDIA directly. The monitor uses a separate maintainer key for probes.

Outages and limits

Expired status and failed refreshes retain the last good in-memory document with a warning. Optional defaults={alias: [...]} can provide emergency model names, but is not required. Without defaults or a prior cache, a failed first fetch means resolve returns an empty list and primary/call raise NoModelsAvailable. The cache does not survive process restarts. No library can discover a model during an outage without some available source of model names.

Only synchronous calls are supported. Fallback handles failures raised by the callback, not errors while consuming a returned streaming iterator. The current urllib timeout is three seconds per blocking operation, not a strict total deadline. Defaults are used when no route is available, not appended after an otherwise nonempty remote route. Stale routing can currently be retained indefinitely. Do not depend on a successful directory fetch to start your app.

Consumers need no NVIDIA model IDs; the monitor maintainer still classifies models in models.yml. New unclassified models never enter aliases until tagged.

Metadata

Release files for nimstatus 0.1.0

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

Built distribution (wheel)

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

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

Download URL nimstatus-0.1.0-py3-none-any.whl
Size 6.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
092597e7d0c9307547d323b1382af2900f70d4042c58c2beda084f5871532fc8
BLAKE2b-256 checksum
How to use checksums
f338dd8e0463114673b6030d7aacd11bcb6e95184c53ad0537f731122da4e2cc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for nimstatus 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.

Full provenance

1 file in this release has been uploaded with provenance metadata.

Attestation for nimstatus-0.1.0-py3-none-any.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

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

1 release file Full 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