nxuskit-py 1.0.3__py3-none-any.whl

nxuskit/__init__.py

@@ -0,0 +1,287 @@
+"""nxuskit - Pure Python library mirroring nxusKit Rust API."""
+
+from nxuskit._ffi_errors import (
+    EditionInsufficientError,
+    FeatureUnavailableError,
+    LicenseExpiredError,
+    LicenseRequiredError,
+    NxuskitError,
+)
+from nxuskit._version import __author__, __license__, __version__
+from nxuskit.errors import (
+    AuthenticationError,
+    LLMError,
+    NetworkError,
+    ProviderError,
+    RateLimitError,
+    TimeoutError,
+)
+from nxuskit.message import Message
+from nxuskit.provider import LLMProvider
+from nxuskit.providers import Provider
+from nxuskit.retry import (
+    AdaptiveRateLimiter,
+    RetryConfig,
+    RetryIterator,
+    retry_on_rate_limit,
+    retry_with_backoff,
+    should_retry,
+)
+from nxuskit.security import (
+    SecurityIssue,
+    SecuritySeverity,
+    SecurityValidationResult,
+    SecurityValidator,
+)
+from nxuskit.solver_types import (
+    ConstraintDef,
+    ConstraintType,
+    DomainDef,
+    MultiObjectiveMode,
+    ObjectiveDef,
+    ObjectiveDirection,
+    SessionStatus,
+    SolverCapabilities,
+    SolverConfig,
+    SolveResult,
+    SolverExplanation,
+    SolverStats,
+    SolverValue,
+    SolveStatus,
+    VariableDef,
+    VariableType,
+)
+from nxuskit.streaming import (
+    StreamBuffer,
+    collect_stream,
+    stream_to_file,
+    stream_with_callback,
+)
+from nxuskit.tools import (
+    FunctionCall,
+    FunctionDefinition,
+    ToolCall,
+    ToolDefinition,
+    ToolResultMessage,
+    tool_choice_auto,
+    tool_choice_named,
+    tool_choice_none,
+    tool_choice_required,
+)
+from nxuskit.types import (
+    PUBLIC_CAPABILITY_FIELDS,
+    CapabilityStatus,
+    ChatRequest,
+    ChatResponse,
+    ImageSource,
+    ImageSourceType,
+    LogprobsData,
+    ManifestPublicationPosture,
+    ModelInfo,
+    PublicCapabilityManifest,
+    PublicProviderCapability,
+    ResponseFormat,
+    Role,
+    StreamChunk,
+    TokenLogprob,
+    TokenUsage,
+    TopLogprob,
+)
+from nxuskit.vision import (
+    ImageLoader,
+    add_images_to_message,
+    detect_image_type,
+    image_to_data_url,
+    is_base64,
+    is_valid_url,
+    load_image_base64,
+)
+
+# FFI-dependent modules are imported lazily to allow pure-Python usage
+# (unit tests, type inspection) without the native library present.
+# These modules load libnxuskit at import time via _ffi.py.
+_FFI_NAMES = {
+    # auth_oauth
+    "OAuthResult",
+    "OAuthStatus",
+    "oauth_start",
+    "oauth_status",
+    "oauth_revoke",
+    # clips
+    "ClipsSession",
+    "ClipsError",
+    # license
+    "ActivationResult",
+    "LicenseResolution",
+    "TokenInfo",
+    "TrialResult",
+    "license_activate",
+    "license_deactivate",
+    "license_machine_id",
+    "license_resolve",
+    "license_trial_activate",
+    "license_trial_issue",
+    "license_validate",
+    # solver (stream chunk requires _solver_ffi)
+    "SolverStreamChunk",
+    # zen
+    "zen_evaluate",
+    "zen_evaluate_async",
+}
+
+_FFI_MODULE_MAP = {
+    "OAuthResult": "nxuskit.auth_oauth",
+    "OAuthStatus": "nxuskit.auth_oauth",
+    "oauth_start": "nxuskit.auth_oauth",
+    "oauth_status": "nxuskit.auth_oauth",
+    "oauth_revoke": "nxuskit.auth_oauth",
+    "ClipsSession": "nxuskit.clips",
+    "ClipsError": "nxuskit.clips",
+    "ActivationResult": "nxuskit.license",
+    "LicenseResolution": "nxuskit.license",
+    "TokenInfo": "nxuskit.license",
+    "TrialResult": "nxuskit.license",
+    "license_activate": "nxuskit.license",
+    "license_deactivate": "nxuskit.license",
+    "license_machine_id": "nxuskit.license",
+    "license_resolve": "nxuskit.license",
+    "license_trial_activate": "nxuskit.license",
+    "license_trial_issue": "nxuskit.license",
+    "license_validate": "nxuskit.license",
+    "SolverStreamChunk": "nxuskit.solver",
+    "zen_evaluate": "nxuskit.zen",
+    "zen_evaluate_async": "nxuskit.zen",
+}
+
+
+def __getattr__(name: str):
+    if name in _FFI_NAMES:
+        import importlib
+
+        module = importlib.import_module(_FFI_MODULE_MAP[name])
+        value = getattr(module, name)
+        # Cache in module namespace for subsequent access
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module 'nxuskit' has no attribute {name!r}")
+
+
+__all__ = [
+    "__version__",
+    "__author__",
+    "__license__",
+    # Types
+    "Role",
+    "ImageSourceType",
+    "ImageSource",
+    "TokenUsage",
+    "ChatRequest",
+    "ChatResponse",
+    "StreamChunk",
+    "ModelInfo",
+    "ResponseFormat",
+    "CapabilityStatus",
+    "ManifestPublicationPosture",
+    "PUBLIC_CAPABILITY_FIELDS",
+    "PublicProviderCapability",
+    "PublicCapabilityManifest",
+    "LogprobsData",
+    "TokenLogprob",
+    "TopLogprob",
+    # Message
+    "Message",
+    # Errors
+    "LLMError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NetworkError",
+    "ProviderError",
+    "TimeoutError",
+    # FFI / entitlement errors
+    "NxuskitError",
+    "FeatureUnavailableError",
+    "LicenseRequiredError",
+    "LicenseExpiredError",
+    "EditionInsufficientError",
+    # Provider protocol
+    "LLMProvider",
+    # Provider factory
+    "Provider",
+    # Streaming utilities
+    "collect_stream",
+    "stream_with_callback",
+    "stream_to_file",
+    "StreamBuffer",
+    # Vision utilities
+    "load_image_base64",
+    "detect_image_type",
+    "is_valid_url",
+    "is_base64",
+    "add_images_to_message",
+    "image_to_data_url",
+    "ImageLoader",
+    # Retry utilities
+    "RetryConfig",
+    "should_retry",
+    "retry_with_backoff",
+    "retry_on_rate_limit",
+    "RetryIterator",
+    "AdaptiveRateLimiter",
+    # Solver types
+    "SolverStreamChunk",
+    "VariableType",
+    "VariableDef",
+    "DomainDef",
+    "ConstraintType",
+    "ConstraintDef",
+    "ObjectiveDirection",
+    "ObjectiveDef",
+    "MultiObjectiveMode",
+    "SolverConfig",
+    "SolveStatus",
+    "SolverValue",
+    "SolverStats",
+    "SolverExplanation",
+    "SolveResult",
+    "SolverCapabilities",
+    "SessionStatus",
+    # Tool calling
+    "ToolDefinition",
+    "FunctionDefinition",
+    "ToolCall",
+    "FunctionCall",
+    "ToolResultMessage",
+    "tool_choice_auto",
+    "tool_choice_none",
+    "tool_choice_required",
+    "tool_choice_named",
+    # CLIPS Session (FFI-dependent, lazy-loaded)
+    "ClipsSession",
+    "ClipsError",
+    # License management (FFI-dependent, lazy-loaded)
+    "ActivationResult",
+    "LicenseResolution",
+    "TokenInfo",
+    "TrialResult",
+    "license_activate",
+    "license_deactivate",
+    "license_machine_id",
+    "license_resolve",
+    "license_trial_activate",
+    "license_trial_issue",
+    "license_validate",
+    # OAuth authentication (FFI-dependent, lazy-loaded)
+    "OAuthResult",
+    "OAuthStatus",
+    "oauth_start",
+    "oauth_status",
+    "oauth_revoke",
+    # ZEN evaluation (FFI-dependent, lazy-loaded)
+    "zen_evaluate",
+    "zen_evaluate_async",
+    # Security validation
+    "SecurityValidator",
+    "SecurityValidationResult",
+    "SecurityIssue",
+    "SecuritySeverity",
+]

nxuskit/__init__.pyi

@@ -0,0 +1,248 @@
+"""PEP 561 type stubs for the nxuskit package."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Iterator, Optional, Protocol, Union
+
+# ── Core Types ──────────────────────────────────────────────────
+
+class CapabilityStatus(str, Enum):
+    SUPPORTED: str
+    UNSUPPORTED: str
+    RECOGNIZED: str
+    PROVIDER_SPECIFIC: str
+    FUTURE: str
+    UNKNOWN: str
+
+class ManifestPublicationPosture(str, Enum):
+    SPLIT: str
+
+PUBLIC_CAPABILITY_FIELDS: tuple[str, ...]
+
+@dataclass
+class PublicProviderCapability:
+    name: str
+    display_name: str
+    last_reviewed_on: str
+    provider_status: str
+    capabilities: dict[str, CapabilityStatus]
+    def to_dict(self) -> dict[str, Any]: ...
+
+@dataclass
+class PublicCapabilityManifest:
+    schema_version: str
+    posture: ManifestPublicationPosture
+    providers: list[PublicProviderCapability]
+    def to_dict(self) -> dict[str, Any]: ...
+
+@dataclass
+class TokenUsage:
+    input_tokens: int
+    output_tokens: int
+    total_tokens: int
+    @property
+    def prompt_tokens(self) -> int: ...
+    @property
+    def completion_tokens(self) -> int: ...
+
+@dataclass
+class ChatResponse:
+    content: Optional[str]
+    usage: TokenUsage
+    model: str
+    finish_reason: Optional[str]
+    tool_calls: Optional[list]
+    provider: Optional[str]
+    warnings: list[str]
+    @property
+    def stop_reason(self) -> Optional[str]: ...
+
+@dataclass
+class StreamChunk:
+    delta: str
+    model: Optional[str]
+    finish_reason: Optional[str]
+    thinking: Optional[str]
+    usage: Optional[TokenUsage]
+    tool_calls: Optional[list]
+    def is_final(self) -> bool: ...
+    def has_thinking(self) -> bool: ...
+    def has_tool_calls(self) -> bool: ...
+
+@dataclass
+class ModelInfo:
+    id: str
+    name: str
+    description: Optional[str]
+    size_bytes: Optional[int]
+    context_window: Optional[int]
+    provider: str
+    metadata: dict[str, str]
+    def supports_vision(self) -> bool: ...
+    def modalities(self) -> list[str]: ...
+    def max_images(self) -> Optional[int]: ...
+    @classmethod
+    def from_dict(cls, data: dict) -> "ModelInfo": ...
+
+@dataclass
+class ImageSource:
+    source_type: Any  # ImageSourceType enum
+    data: str
+    media_type: Optional[str]
+
+# ── Message ─────────────────────────────────────────────────────
+
+@dataclass
+class Message:
+    role: Any  # Role enum
+    content: str
+    images: list[ImageSource]
+    @staticmethod
+    def user(content: str) -> "Message": ...
+    @staticmethod
+    def assistant(content: str) -> "Message": ...
+    @staticmethod
+    def system(content: str) -> "Message": ...
+    def with_image_url(self, url: str) -> "Message": ...
+    def with_image_base64(self, data: str) -> "Message": ...
+    def with_image_file(self, path: str) -> "Message": ...
+
+# ── Tool Calling ────────────────────────────────────────────────
+
+@dataclass
+class FunctionDefinition:
+    name: str
+    description: str
+    parameters: dict
+
+@dataclass
+class ToolDefinition:
+    type: str
+    function: FunctionDefinition
+    @staticmethod
+    def create(name: str, description: str, parameters: dict) -> "ToolDefinition": ...
+    def to_dict(self) -> dict: ...
+
+@dataclass
+class FunctionCall:
+    name: str
+    arguments: str
+
+@dataclass
+class ToolCall:
+    id: str
+    type: str
+    function: FunctionCall
+    @classmethod
+    def from_dict(cls, data: dict) -> "ToolCall": ...
+
+def tool_choice_auto() -> str: ...
+def tool_choice_none() -> str: ...
+def tool_choice_required() -> str: ...
+def tool_choice_named(name: str) -> dict: ...
+
+# ── Provider Protocol ───────────────────────────────────────────
+
+class LLMProvider(Protocol):
+    @property
+    def model(self) -> str: ...
+    @property
+    def provider_name(self) -> str: ...
+    def chat(
+        self,
+        messages: list[Message],
+        *,
+        model: Optional[str] = ...,
+        temperature: Optional[float] = ...,
+        max_tokens: Optional[int] = ...,
+        top_p: Optional[float] = ...,
+        stop: Optional[Union[str, list[str]]] = ...,
+        response_format: Optional[Any] = ...,
+        tools: Optional[list[ToolDefinition]] = ...,
+        tool_choice: Optional[Any] = ...,
+    ) -> ChatResponse: ...
+    def chat_stream(
+        self,
+        messages: list[Message],
+        *,
+        model: Optional[str] = ...,
+        temperature: Optional[float] = ...,
+        max_tokens: Optional[int] = ...,
+        top_p: Optional[float] = ...,
+        stop: Optional[Union[str, list[str]]] = ...,
+        response_format: Optional[Any] = ...,
+        tools: Optional[list[ToolDefinition]] = ...,
+        tool_choice: Optional[Any] = ...,
+    ) -> Iterator[StreamChunk]: ...
+    def list_models(self) -> list[ModelInfo]: ...
+
+# ── Provider Factory ────────────────────────────────────────────
+
+class Provider:
+    @staticmethod
+    def claude(*, model: str = ..., api_key: Optional[str] = ..., **kwargs: Any) -> Any: ...
+    @staticmethod
+    def openai(*, model: str = ..., api_key: Optional[str] = ..., **kwargs: Any) -> Any: ...
+    @staticmethod
+    def ollama(*, model: str = ..., **kwargs: Any) -> Any: ...
+    @staticmethod
+    def groq(*, model: str = ..., api_key: Optional[str] = ..., **kwargs: Any) -> Any: ...
+    @staticmethod
+    def xai(*, model: str = ..., api_key: Optional[str] = ..., **kwargs: Any) -> Any: ...
+    @staticmethod
+    def mistral(*, model: str = ..., api_key: Optional[str] = ..., **kwargs: Any) -> Any: ...
+    @staticmethod
+    def fireworks(*, model: str = ..., api_key: Optional[str] = ..., **kwargs: Any) -> Any: ...
+    @staticmethod
+    def together(*, model: str = ..., api_key: Optional[str] = ..., **kwargs: Any) -> Any: ...
+    @staticmethod
+    def openrouter(*, model: str = ..., api_key: Optional[str] = ..., **kwargs: Any) -> Any: ...
+    @staticmethod
+    def perplexity(*, model: str = ..., api_key: Optional[str] = ..., **kwargs: Any) -> Any: ...
+    @staticmethod
+    def lmstudio(*, model: str = ..., **kwargs: Any) -> Any: ...
+
+# ── Errors ──────────────────────────────────────────────────────
+
+class LLMError(Exception):
+    status_code: Optional[int]
+    provider: Optional[str]
+    model: Optional[str]
+    @property
+    def is_retryable(self) -> bool: ...
+
+class AuthenticationError(LLMError): ...
+
+class RateLimitError(LLMError):
+    retry_after: Optional[float]
+
+class NetworkError(LLMError): ...
+class TimeoutError(LLMError): ...
+class ProviderError(LLMError): ...
+
+# FFI errors
+class NxuskitError(Exception):
+    error_type: str
+    message: str
+    provider: Optional[str]
+    feature: Optional[str]
+
+class ConfigError(NxuskitError): ...
+class FeatureUnavailableError(NxuskitError): ...
+class LicenseRequiredError(NxuskitError): ...
+class LicenseExpiredError(NxuskitError): ...
+
+class EditionInsufficientError(NxuskitError):
+    required_edition: Optional[str]
+
+# ── FFI Provider ────────────────────────────────────────────────
+
+class FFIProvider:
+    def chat(self, request: dict[str, Any]) -> ChatResponse: ...
+    def stream(self, request: dict[str, Any]) -> Iterator[StreamChunk]: ...
+    def list_models(self) -> list[ModelInfo]: ...
+    def close(self) -> None: ...
+    def __enter__(self) -> "FFIProvider": ...
+    def __exit__(self, *args: Any) -> None: ...
+
+def create_ffi_provider(config: dict[str, Any]) -> FFIProvider: ...

nxuskit/_bn_ffi.py

@@ -0,0 +1,64 @@
+"""Low-level cffi bindings for the Bayesian Network C ABI.
+
+Uses the shared FFI instance and library handle from _ffi.py.
+Higher-level Python wrappers are in bn.py.
+"""
+
+from __future__ import annotations
+
+
+class BnLibraryNotFoundError(RuntimeError):
+    """Raised when the nxuskit native library cannot be found."""
+
+
+# Lazy reference — populated on first _get_lib() call.
+_bn_lib = None
+
+
+def _get_lib():
+    """Get the shared library handle for BN functions."""
+    global _bn_lib
+    if _bn_lib is not None:
+        return _bn_lib
+    try:
+        from nxuskit._ffi import lib
+
+        _bn_lib = lib
+        return _bn_lib
+    except Exception as e:
+        raise BnLibraryNotFoundError(
+            f"Failed to load nxuskit native library: {e}. "
+            "Set NXUSKIT_LIB_DIR, NXUSKIT_SDK_DIR, or install at ~/.nxuskit/sdk/current/."
+        ) from e
+
+
+def last_error() -> str:
+    """Read the thread-local error message from the C ABI."""
+    from nxuskit._ffi import ffi
+
+    lib = _get_lib()
+    ptr = lib.nxuskit_last_error()
+    if ptr == ffi.NULL:
+        return ""
+    return ffi.string(ptr).decode("utf-8", errors="replace")
+
+
+def read_and_free_string(ptr) -> str:
+    """Convert a C string to Python, free the C memory."""
+    from nxuskit._ffi import ffi
+
+    lib = _get_lib()
+    if ptr == ffi.NULL:
+        err = last_error()
+        raise RuntimeError(f"nxuskit bn: NULL string returned: {err}")
+    s = ffi.string(ptr).decode("utf-8")
+    lib.nxuskit_free_string(ptr)
+    return s
+
+
+# Backward compat: code that imported bn_ffi directly can still use it
+# for callback definitions. Point to the shared ffi instance.
+try:
+    from nxuskit._ffi import ffi as bn_ffi
+except Exception:
+    bn_ffi = None  # type: ignore[assignment]

nxuskit/_clips_ffi.py

@@ -0,0 +1,61 @@
+"""Low-level cffi bindings for the CLIPS Session C ABI.
+
+Uses the shared FFI instance and library handle from _ffi.py.
+Higher-level Python wrappers are in clips.py.
+"""
+
+from __future__ import annotations
+
+
+class ClipsLibraryNotFoundError(RuntimeError):
+    """Raised when the nxuskit native library cannot be found."""
+
+
+_clips_lib = None
+
+
+def _get_lib():
+    """Get the shared library handle for CLIPS functions."""
+    global _clips_lib
+    if _clips_lib is not None:
+        return _clips_lib
+    try:
+        from nxuskit._ffi import lib
+
+        _clips_lib = lib
+        return _clips_lib
+    except Exception as e:
+        raise ClipsLibraryNotFoundError(
+            f"Failed to load nxuskit native library: {e}. "
+            "Set NXUSKIT_LIB_DIR, NXUSKIT_SDK_DIR, or install at ~/.nxuskit/sdk/current/."
+        ) from e
+
+
+def last_error() -> str:
+    """Read the thread-local error message from the C ABI."""
+    from nxuskit._ffi import ffi
+
+    lib = _get_lib()
+    ptr = lib.nxuskit_last_error()
+    if ptr == ffi.NULL:
+        return ""
+    return ffi.string(ptr).decode("utf-8", errors="replace")
+
+
+def read_and_free_string(ptr) -> str:
+    """Convert a C string to Python, free the C memory."""
+    from nxuskit._ffi import ffi
+
+    lib = _get_lib()
+    if ptr == ffi.NULL:
+        err = last_error()
+        raise RuntimeError(f"nxuskit clips: NULL string returned: {err}")
+    s = ffi.string(ptr).decode("utf-8")
+    lib.nxuskit_free_string(ptr)
+    return s
+
+
+try:
+    from nxuskit._ffi import ffi as clips_ffi
+except Exception:
+    clips_ffi = None  # type: ignore[assignment]