Metadata-Version: 2.4
Name: nxuskit-py
Version: 1.0.5
Summary: Python SDK for nxusKit — pure-Python providers with optional SDK-bundle native engines
Project-URL: Homepage, https://nxus.systems
Project-URL: Documentation, https://docs.nxus.systems/nxuskit/
Project-URL: Repository, https://github.com/nxus-SYSTEMS/nxusKit
Project-URL: Issues, https://github.com/nxus-SYSTEMS/nxusKit/issues
Project-URL: Changelog, https://github.com/nxus-SYSTEMS/nxusKit/blob/main/CHANGELOG.md
Project-URL: SDK Downloads, https://github.com/nxus-SYSTEMS/nxusKit/releases
Project-URL: Examples, https://docs.nxus.systems/nxuskit/examples/
Author: nxusKit Contributors
License-Expression: MIT OR Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: api,bayesian,claude,clips,fireworks,function-calling,grok,groq,llm,mistral,ollama,openai,perplexity,solver,streaming,together,tool-calling,vision,xai
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: cffi>=2.0.0
Requires-Dist: keyring>=25.7.0
Requires-Dist: pyjwt[crypto]>=2.12.0
Requires-Dist: requests>=2.32.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
Requires-Dist: pytest-httpserver>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=9.0.0; extra == 'dev'
Requires-Dist: ruff>=0.15.0; extra == 'dev'
Description-Content-Type: text/markdown

# nxuskit-py: Python SDK for nxusKit

[![SDK bundle](https://img.shields.io/badge/distribution-SDK%20bundle-blue.svg)](https://github.com/nxus-SYSTEMS/nxusKit/releases)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](https://github.com/nxus-SYSTEMS/nxusKit/blob/sdk-v1.0.5/LICENSE)

Pure Python library for the [nxusKit](https://github.com/nxus-SYSTEMS/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:

```bash
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:

```bash
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](https://github.com/nxus-SYSTEMS/nxusKit/releases) 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

```python
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.

```python
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

```python
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

```python
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).

```python
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

```python
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

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

## Error Handling

```python
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

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

## Providers

| Provider | Factory | Environment Variable |
|----------|---------|---------------------|
| Claude | `Provider.claude()` | `ANTHROPIC_API_KEY` |
| OpenAI | `Provider.openai()` | `OPENAI_API_KEY` |
| Ollama | `Provider.ollama()` | None (local) |
| xAI Grok | `Provider.xai()` | `XAI_API_KEY` |
| Groq | `Provider.groq()` | `GROQ_API_KEY` |
| Mistral | `Provider.mistral()` | `MISTRAL_API_KEY` |
| Fireworks | `Provider.fireworks()` | `FIREWORKS_API_KEY` |
| Together | `Provider.together()` | `TOGETHER_API_KEY` |
| OpenRouter | `Provider.openrouter()` | `OPENROUTER_API_KEY` |
| Perplexity | `Provider.perplexity()` | `PERPLEXITY_API_KEY` |
| LM Studio | `Provider.lmstudio()` | None (local) |

## CLIPS Session API

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

```python
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:

```python
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

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

## License

Dual-licensed under MIT and Apache 2.0. See the
[MIT](https://github.com/nxus-SYSTEMS/nxusKit/blob/sdk-v1.0.5/LICENSE-MIT)
and
[Apache 2.0](https://github.com/nxus-SYSTEMS/nxusKit/blob/sdk-v1.0.5/LICENSE-APACHE)
license texts.

See also: [nxusKit-examples](https://github.com/nxus-SYSTEMS/nxusKit-examples) for runnable examples.
