nxuskit-py: Python SDK for nxusKit

Pure Python library for the nxusKit polyglot SDK. The public distribution package is nxuskit-py and imports as nxuskit. Pure-Python provider APIs work directly from the package-index wheel; native/FFI engine APIs require an installed compatible nxusKit SDK bundle. Z3 solver and ZEN decision table workflows require nxusKit SDK Pro plus a valid Pro entitlement.

Features

• 11 LLM Providers — Claude, OpenAI, Ollama, xAI Grok, Groq, Mistral, Fireworks, Together, OpenRouter, Perplexity, LM Studio
• Per-Request Model Override — Switch models on any chat() call: provider.chat(messages, model="gpt-4o-mini")
• Tool Calling / Function Calling — Pass tool definitions, receive structured tool call responses
• Streaming — Iterator-based streaming with is_final() completion detection
• Vision / Multimodal — Image input via URL, base64, or file path with auto-detected MIME types
• Model Discovery — list_models() with supports_vision(), modalities(), max_images() helpers
• Typed Error Handling — TimeoutError, NetworkError, RateLimitError, AuthenticationError, ProviderError
• Retry Utilities — RetryConfig, retry_with_backoff, AdaptiveRateLimiter
• CLIPS / BN / Solver / ZEN — FFI access to nxusKit reasoning engines (native library required; Solver and ZEN require Pro)

Dependencies: requests, cffi (loaded only by FFI paths), keyring (credential storage), PyJWT[crypto] (license tokens)

Installation

Install the pure-Python package from PyPI:

python -m pip install nxuskit-py==1.0.5
python -c "import nxuskit; print(nxuskit.__version__)"

nxuskit-py is the distribution package and nxuskit is the Python import package. The package-index wheel installs the pure-Python package only; it does not install native libnxuskit engines, SDK bundles, or Pro command modules.

The Python package is also shipped inside nxusKit SDK bundles for offline or bundle-local use:

export NXUSKIT_SDK_DIR="$HOME/.nxuskit/sdk/current"
export PYTHONPATH="$NXUSKIT_SDK_DIR/python/src:${PYTHONPATH:-}"
python -c "import nxuskit; print(nxuskit.__version__)"

For FFI-backed features (CLIPS, BN, Solver, ZEN), install the nxusKit SDK and set NXUSKIT_SDK_DIR, NXUSKIT_LIB_DIR, or install the SDK at ~/.nxuskit/sdk/current/. CLIPS and Bayesian inference are Community Edition features where supported by the installed SDK; Solver and ZEN require Pro SDK features and Pro entitlement.

Quick Start

import nxuskit

# Create a provider (auto-discovers API key from environment)
provider = nxuskit.Provider.claude()

# Simple chat
response = provider.chat([nxuskit.Message.user("What is 2 + 2?")])
print(response.content)
print(f"Tokens: {response.usage.total_tokens}")

Provider is the public factory for concrete provider clients. LLMProvider is the protocol/type contract implemented by provider clients and exported for type checking and custom providers; it is intentionally separate from the Provider factory.

Capability Manifest Preview

The Python package exposes public capability manifest projection types. The public shape carries status values and reviewed-on metadata only; internal evidence records, model overrides, and provider-specific details stay private to the engine registry.

import nxuskit

manifest = nxuskit.PublicCapabilityManifest(
    schema_version="capability-manifest-v2-public-preview/1",
    posture=nxuskit.ManifestPublicationPosture.SPLIT,
    providers=[
        nxuskit.PublicProviderCapability(
            name="openai",
            display_name="OpenAI",
            last_reviewed_on="2026-05-09",
            provider_status="unknown",
            capabilities={
                "json_schema_strict": nxuskit.CapabilityStatus.SUPPORTED,
                "rerank": nxuskit.CapabilityStatus.FUTURE,
            },
        )
    ],
)

print(nxuskit.PUBLIC_CAPABILITY_FIELDS)
print(manifest.to_dict()["providers"][0]["capabilities"]["json_schema_strict"])

Per-Request Model Override

provider = nxuskit.Provider.openai()  # default: gpt-4o

# Override model for a single call
response = provider.chat(
    [nxuskit.Message.user("Hello")],
    model="gpt-4o-mini",
    temperature=0.5,
)

Streaming

for chunk in provider.chat_stream([nxuskit.Message.user("Tell me a story")]):
    print(chunk.delta, end="", flush=True)
    if chunk.is_final():
        print(f"\nTokens: {chunk.usage.total_tokens}")

Streaming Logprobs (v0.9.4+)

Per-chunk logprob deltas are now surfaced on streaming responses for providers that support them (OpenAI). Check the capability flag before issuing the call; non-supporting providers always emit chunk.logprobs is None on every chunk (FR-007 — no phantom data).

from nxuskit import Provider, ChatRequest, Role
import asyncio

async def main():
    provider = Provider.openai()

    if not provider.capabilities().supports_streaming_logprobs:
        print("Provider does not support streaming logprobs.")

    req = ChatRequest(
        model="gpt-5.4",
        messages=[{"role": Role.USER, "content": "Say hello."}],
        logprobs=True,
        top_logprobs=3,
    )

    async for chunk in provider.chat_stream(req):
        print(chunk.delta, end="")
        if chunk.logprobs is not None:
            for tok in chunk.logprobs.content:
                print(f"  token={tok.token!r} logprob={tok.logprob:.4f}")

asyncio.run(main())

Tool Calling

weather_tool = nxuskit.ToolDefinition.create(
    name="get_weather",
    description="Get weather for a location",
    parameters={
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"],
    },
)

response = provider.chat(
    [nxuskit.Message.user("What's the weather in Tokyo?")],
    tools=[weather_tool],
    tool_choice=nxuskit.tool_choice_auto(),
)

if response.tool_calls:
    for call in response.tool_calls:
        print(f"Call: {call.function.name}({call.function.arguments})")

Vision

msg = nxuskit.Message.user("What's in this image?").with_image_file("photo.png")
response = provider.chat([msg], model="gpt-4o")

Error Handling

try:
    response = provider.chat([nxuskit.Message.user("Hello")])
except nxuskit.TimeoutError:
    print("Request timed out — try a faster model")
except nxuskit.NetworkError:
    print("Network issue — check connection")
except nxuskit.RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except nxuskit.AuthenticationError:
    print("Check your API key")

Model Discovery

models = provider.list_models()
for m in models:
    vision = "vision" if m.supports_vision() else "text-only"
    print(f"  {m.name}: {vision}")

Providers

CLIPS Session API

For direct CLIPS rule engine access (requires native library):

from nxuskit.clips import ClipsSession

with ClipsSession() as s:
    s.load_json(rules_json)
    s.reset()
    s.fact_assert_string('(sensor (name "temp") (value 200))')
    fired = s.run()

FFI Provider Note

When using FFI-backed features, always use context managers (with statement) for reliable cleanup:

from nxuskit._ffi_provider import create_ffi_provider

with create_ffi_provider({"provider_type": "openai", "api_key": "sk-..."}) as p:
    response = p.chat({"model": "gpt-4o", "messages": [...]})

Development

pip install -e ".[dev]"
pytest tests/
ruff check src/ && ruff format --check .

License

Dual-licensed under MIT and Apache 2.0. See the MIT and Apache 2.0 license texts.

See also: nxusKit-examples for runnable examples.