desireeia 0.0.1__tar.gz

desireeia-0.0.1/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: desireeia
+Version: 0.0.1
+Summary: Python wrapper for DesireeIA — local LLM inference engine
+Author: Passaro Francesco Paolo
+License: Proprietary
+Keywords: llm,inference,local,gguf,desireeia
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# desireeia
+
+Python wrapper for **DesireeIA**, a local LLM inference engine (GGUF
+models, CPU/GPU backends). This package ships a thin ctypes binding over
+the native engine, with prebuilt binaries bundled per-platform so it works
+without a separate native install step.
+
+Full documentation, model compatibility notes, and the C++/CLI side of the
+project live in the main repository:
+https://github.com/passaroweb/DesireeIA (see the project README for
+details).
+
+## Install
+
+```
+pip install desireeia
+```
+
+## Bundled platforms
+
+This wheel bundles the native engine for the platforms it was built on.
+Check `desireeia/lib/` in the installed package for the exact list — at
+minimum `win-x64` and `linux-x64` are included. If your platform/arch
+isn't bundled yet, the package will raise a clear error on import rather
+than silently failing.
+
+- **Windows**: the engine DLL and its CUDA runtime (`cudart64_13.dll`,
+  for GPU acceleration) are bundled. It also needs the **Microsoft
+  Visual C++ Redistributable (x64)** on the system — already present on
+  most Windows machines (installed by countless other apps, .NET, GPU
+  drivers, etc.), but not bundled in this package. If import fails with
+  a missing-DLL error, install it from
+  https://aka.ms/vs/17/release/vc_redist.x64.exe and retry.
+- **Linux**: the engine `.so` only depends on `libstdc++`, `libgcc_s`
+  and `glibc` — present on essentially every distribution by default,
+  nothing extra to install. GPU acceleration is not packaged for Linux
+  yet (CPU-only); this is a known gap, not a silent limitation.
+- **macOS**: not built yet (`osx-x64`/`osx-arm64` are not bundled) —
+  importing on macOS will fail with a clear error until a macOS build is
+  produced.
+
+## License
+
+See `LICENSE` — proprietary, no modification or unauthorized integration,
+no AI training/ingestion without explicit written consent from the
+author.

desireeia-0.0.1/README.md

@@ -0,0 +1,46 @@
+# desireeia
+
+Python wrapper for **DesireeIA**, a local LLM inference engine (GGUF
+models, CPU/GPU backends). This package ships a thin ctypes binding over
+the native engine, with prebuilt binaries bundled per-platform so it works
+without a separate native install step.
+
+Full documentation, model compatibility notes, and the C++/CLI side of the
+project live in the main repository:
+https://github.com/passaroweb/DesireeIA (see the project README for
+details).
+
+## Install
+
+```
+pip install desireeia
+```
+
+## Bundled platforms
+
+This wheel bundles the native engine for the platforms it was built on.
+Check `desireeia/lib/` in the installed package for the exact list — at
+minimum `win-x64` and `linux-x64` are included. If your platform/arch
+isn't bundled yet, the package will raise a clear error on import rather
+than silently failing.
+
+- **Windows**: the engine DLL and its CUDA runtime (`cudart64_13.dll`,
+  for GPU acceleration) are bundled. It also needs the **Microsoft
+  Visual C++ Redistributable (x64)** on the system — already present on
+  most Windows machines (installed by countless other apps, .NET, GPU
+  drivers, etc.), but not bundled in this package. If import fails with
+  a missing-DLL error, install it from
+  https://aka.ms/vs/17/release/vc_redist.x64.exe and retry.
+- **Linux**: the engine `.so` only depends on `libstdc++`, `libgcc_s`
+  and `glibc` — present on essentially every distribution by default,
+  nothing extra to install. GPU acceleration is not packaged for Linux
+  yet (CPU-only); this is a known gap, not a silent limitation.
+- **macOS**: not built yet (`osx-x64`/`osx-arm64` are not bundled) —
+  importing on macOS will fail with a clear error until a macOS build is
+  produced.
+
+## License
+
+See `LICENSE` — proprietary, no modification or unauthorized integration,
+no AI training/ingestion without explicit written consent from the
+author.

desireeia-0.0.1/desireeia/__init__.py

@@ -0,0 +1,82 @@
+"""DesireeIA Python wrapper — public API.
+
+Usage::
+
+    import desireeia
+
+    plan = desireeia.build_plan("model.gguf")
+    with desireeia.LocalModel.load("model.gguf", plan) as model:
+        tokens = model.tokenize("Hello, how are you?")
+        for piece in model.chat_stream([("user", "Hello!")]):
+            print(piece, end="", flush=True)
+"""
+
+from .enums import (
+    Backend,
+    Error,
+    InferenceBackend,
+    ModelFormat,
+    Quantization,
+    SsdTierMode,
+    SpecialToken,
+    StreamType,
+)
+from .types import (
+    ExecutionPlan,
+    GenerateOptions,
+    HardwareProfile,
+    SamplingOptions,
+    ToolCall,
+    ToolDefinition,
+    VisionConfig,
+)
+from .engine import (
+    build_plan,
+    detect_hardware,
+    profile_dump,
+    profile_reset,
+    version,
+)
+from .model import LocalModel
+from .vision import VisionImageWrapper
+from .generation import (
+    StopSequenceScanner,
+    ToolCalling,
+    StructuredOutput,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # enums
+    "Backend",
+    "Error",
+    "InferenceBackend",
+    "ModelFormat",
+    "Quantization",
+    "SsdTierMode",
+    "SpecialToken",
+    "StreamType",
+    # types
+    "ExecutionPlan",
+    "GenerateOptions",
+    "HardwareProfile",
+    "SamplingOptions",
+    "ToolCall",
+    "ToolDefinition",
+    "VisionConfig",
+    # engine
+    "build_plan",
+    "detect_hardware",
+    "profile_dump",
+    "profile_reset",
+    "version",
+    # model
+    "LocalModel",
+    # vision
+    "VisionImageWrapper",
+    # generation
+    "StopSequenceScanner",
+    "ToolCalling",
+    "StructuredOutput",
+]

desireeia-0.0.1/desireeia/_native.py

@@ -0,0 +1,389 @@
+"""ctypes bindings to DesireeIALocaleEngine — the C ABI bridge.
+
+Mirrors src/DesireeIA/Native/NativeMethods.cs exactly. Struct field order and
+types MUST stay identical to the C structs in abi.h: this is a sequential
+blit, not a marshalled conversion.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import sys
+import threading
+from ctypes import (
+    POINTER,
+    c_char_p,
+    c_int32,
+    c_int64,
+    c_uint32,
+    c_uint64,
+    c_float,
+    c_void_p,
+    CFUNCTYPE,
+    Structure,
+)
+
+# ---------------------------------------------------------------------------
+# Library loading
+# ---------------------------------------------------------------------------
+
+_LIB_NAMES = {
+    "win32": "DesireeIALocaleEngine.dll",
+    "darwin": "libDesireeIALocaleEngine.dylib",
+    "linux": "libDesireeIALocaleEngine.so",
+}
+
+# Python sys.platform -> (fname suffix, arch candidates in priority order).
+# The bundle ships the engine under desireeia/lib/<RID>/ following the same
+# .NET RID convention used by Build/runtimes/<RID>/native/ (win-x64,
+# linux-x64, osx-x64, osx-arm64, ...).
+_RID_BY_BASE = {
+    "win": "win-{arch}",
+    "osx": "osx-{arch}",
+    "linux": "linux-{arch}",
+}
+
+_ARCH_MAP = {
+    "win":    {"amd64": "x64", "x86_64": "x64", "arm64": "arm64", "aarch64": "arm64"},
+    "osx":    {"arm64": "arm64", "aarch64": "arm64", "x86_64": "x64", "amd64": "x64"},
+    "linux":  {"x86_64": "x64", "amd64": "x64", "aarch64": "arm64", "arm64": "arm64", "armv7l": "arm", "armv8l": "arm64"},
+}
+
+def _candidate_rids() -> list[str]:
+    """The .NET RIDs this machine could match, most specific first."""
+    import platform
+    sysname = platform.system().lower()
+    machine_raw = platform.machine().lower()
+
+    base = None
+    for key in ("win", "osx", "linux", "windows", "darwin"):
+        if sysname == key:
+            base = {"windows": "win", "darwin": "osx"}.get(key, key)
+            break
+    if base is None:
+        return []
+
+    arch_map = _ARCH_MAP.get(base, {})
+    arch = arch_map.get(machine_raw, "")
+    if not arch:
+        return []
+    return [f"{base}-{arch}"]
+
+
+def _find_lib() -> ctypes.CDLL:
+    env = os.environ.get("DESIREEIA_NATIVE_LIB")
+    if env:
+        if not os.path.isfile(env):
+            raise OSError(f"DESIREEIA_NATIVE_LIB points to a missing file: {env}")
+        return _load_with_deps(env)
+
+    name = _LIB_NAMES.get(sys.platform)
+    if name is None:
+        raise OSError(f"Unsupported platform: {sys.platform}")
+
+    pkg_dir = os.path.dirname(os.path.abspath(__file__))
+    search_dirs: list[str] = []
+
+    # 1. Bundled per-platform library: desireeia/lib/<RID>/<fname>
+    for rid in _candidate_rids():
+        search_dirs.append(os.path.join(pkg_dir, "lib", rid))
+
+    # 2. Same directory as this package (development layout)
+    search_dirs.append(pkg_dir)
+
+    # 3. Alongside the Python package root
+    search_dirs.append(os.path.dirname(pkg_dir))
+
+    # 4. Plain ctypes search (system paths, LD_LIBRARY_PATH, PATH, ...)
+    try:
+        return _load_with_deps(name)
+    except OSError:
+        pass
+
+    for d in search_dirs:
+        candidate = os.path.join(d, name)
+        if os.path.isfile(candidate):
+            return _load_with_deps(candidate)
+
+    raise OSError(
+        f"Cannot find {name}. Ship it next to the desireeia package, bundle it "
+        f"under desireeia/lib/<RID>/ (Build/python.ps1 does this automatically), "
+        f"set DESIREEIA_NATIVE_LIB to its path, or add its directory to "
+        f"PATH / LD_LIBRARY_PATH."
+    )
+
+
+def _load_with_deps(path: str) -> ctypes.CDLL:
+    """Load the engine, making sibling runtime DLLs (MinGW: libstdc++-6.dll
+    and friends) discoverable: on Windows the loader does NOT search the
+    engine's own directory for its dependencies, so the bundle dir must be
+    registered as a DLL search dir first."""
+    if sys.platform == "win32":
+        dll_dir = os.path.dirname(os.path.abspath(path))
+        if dll_dir and os.path.isdir(dll_dir):
+            os.add_dll_directory(dll_dir)
+    return ctypes.CDLL(path)
+
+_lib: ctypes.CDLL | None = None
+_lib_lock = threading.Lock()
+
+def get_lib() -> ctypes.CDLL:
+    global _lib
+    if _lib is not None:
+        return _lib
+    with _lib_lock:
+        if _lib is not None:
+            return _lib
+        _lib = _find_lib()
+        _setup_signatures(_lib)
+        return _lib
+
+# ---------------------------------------------------------------------------
+# Log callback type
+# ---------------------------------------------------------------------------
+
+LOG_CB = CFUNCTYPE(None, c_int32, c_char_p, c_void_p)
+
+# ---------------------------------------------------------------------------
+# C structs (sequential layout, matching abi.h exactly)
+# ---------------------------------------------------------------------------
+
+class HwInfo(Structure):
+    _fields_ = [
+        ("cpu_threads",        c_int32),
+        ("cpu_has_avx",        c_int32),
+        ("cpu_has_avx2",       c_int32),
+        ("cpu_has_avx512",     c_int32),
+        ("cpu_has_neon",       c_int32),
+        ("cuda_device_count",  c_int32),
+        ("cuda_total_mb",      c_int32),
+        ("ram_total_mb",       c_uint64),
+        ("ram_free_mb",        c_uint64),
+        ("has_metal",          c_int32),
+        ("has_vulkan",         c_int32),
+        ("intel_gpu_count",    c_int32),
+        ("axelera_device_count", c_int32),
+    ]
+
+class Plan(Structure):
+    _fields_ = [
+        ("backend",                  c_int32),
+        ("format",                   c_int32),
+        ("dense_quant",              c_int32),
+        ("expert_quant",             c_int32),
+        ("n_threads",                c_int32),
+        ("ram_budget_mb",            c_uint64),
+        ("expert_cache_count",       c_int32),
+        ("expert_prefetch_enabled",  c_int32),
+        ("kv_compression_enabled",   c_int32),
+        ("expert_pin_enabled",       c_int32),
+        ("expert_prefetch_depth",    c_int32),
+        ("batch_union_enabled",      c_int32),
+        ("dual_ssd_enabled",         c_int32),
+        ("ssd_tier_mode",            c_int32),
+        ("ssd_tier_cache_mb",        c_uint64),
+    ]
+
+class Sampling(Structure):
+    _fields_ = [
+        ("temperature",      c_float),
+        ("top_k",            c_int32),
+        ("top_p",            c_float),
+        ("penalty_repeat",   c_float),
+        ("penalty_freq",     c_float),
+        ("penalty_present",  c_float),
+        ("penalty_last_n",   c_int32),
+        ("seed",             c_uint32),
+    ]
+
+class VisionImage(Structure):
+    _fields_ = [
+        ("width",    c_uint32),
+        ("height",   c_uint32),
+        ("channels", c_uint32),
+        ("data",     c_void_p),
+    ]
+
+class VisionConfig(Structure):
+    _fields_ = [
+        ("embedding_dim",  c_int32),
+        ("patch_size",     c_int32),
+        ("image_size",     c_int32),
+        ("num_heads",      c_int32),
+        ("num_layers",     c_int32),
+        ("projection_dim", c_int32),
+        ("has_encoder",    c_int32),
+    ]
+
+# ---------------------------------------------------------------------------
+# Function signatures
+# ---------------------------------------------------------------------------
+
+def _setup_signatures(lib: ctypes.CDLL) -> None:
+    # version
+    lib.desireeia_version.argtypes = []
+    lib.desireeia_version.restype = c_char_p
+
+    # logger
+    lib.desireeia_set_logger.argtypes = [LOG_CB, c_void_p]
+    lib.desireeia_set_logger.restype = c_int32
+
+    # hardware probe
+    lib.desireeia_probe_hw.argtypes = [POINTER(HwInfo)]
+    lib.desireeia_probe_hw.restype = c_int32
+
+    # plan
+    lib.desireeia_make_plan.argtypes = [
+        POINTER(HwInfo), c_char_p, POINTER(Plan), POINTER(Plan)
+    ]
+    lib.desireeia_make_plan.restype = c_int32
+
+    # create / destroy
+    lib.desireeia_create.argtypes = [
+        c_char_p, POINTER(Plan), LOG_CB, c_void_p, POINTER(c_void_p)
+    ]
+    lib.desireeia_create.restype = c_int32
+
+    lib.desireeia_destroy.argtypes = [c_void_p]
+    lib.desireeia_destroy.restype = c_int32
+
+    # predict / next_token / context_size
+    lib.desireeia_predict.argtypes = [
+        c_void_p, POINTER(c_int32), c_uint64, POINTER(c_int32)
+    ]
+    lib.desireeia_predict.restype = c_int32
+
+    lib.desireeia_next_token.argtypes = [c_void_p, POINTER(c_int32)]
+    lib.desireeia_next_token.restype = c_int32
+
+    lib.desireeia_context_size.argtypes = [c_void_p]
+    lib.desireeia_context_size.restype = c_uint64
+
+    # tokenize
+    lib.desireeia_tokenize.argtypes = [
+        c_void_p, c_char_p, c_int32,
+        POINTER(c_int32), c_uint64, POINTER(c_uint64)
+    ]
+    lib.desireeia_tokenize.restype = c_int32
+
+    # token_piece
+    lib.desireeia_token_piece.argtypes = [
+        c_void_p, c_int32, POINTER(ctypes.c_char), c_uint64
+    ]
+    lib.desireeia_token_piece.restype = c_int32
+
+    # special_token_id
+    lib.desireeia_special_token_id.argtypes = [
+        c_void_p, c_int32, POINTER(c_int32)
+    ]
+    lib.desireeia_special_token_id.restype = c_int32
+
+    # is_eog_token
+    lib.desireeia_is_eog_token.argtypes = [
+        c_void_p, c_int32, POINTER(c_int32)
+    ]
+    lib.desireeia_is_eog_token.restype = c_int32
+
+    # embed
+    lib.desireeia_embed.argtypes = [
+        c_void_p, POINTER(c_int32), c_uint64,
+        POINTER(c_float), c_uint64, POINTER(c_uint64), POINTER(c_uint32)
+    ]
+    lib.desireeia_embed.restype = c_int32
+
+    # sampling
+    lib.desireeia_set_sampling.argtypes = [c_void_p, POINTER(Sampling)]
+    lib.desireeia_set_sampling.restype = c_int32
+
+    lib.desireeia_get_sampling.argtypes = [c_void_p, POINTER(Sampling)]
+    lib.desireeia_get_sampling.restype = c_int32
+
+    # lora
+    lib.desireeia_load_lora_adapter.argtypes = [c_void_p, c_char_p, c_float]
+    lib.desireeia_load_lora_adapter.restype = c_int32
+
+    lib.desireeia_clear_lora_adapters.argtypes = [c_void_p]
+    lib.desireeia_clear_lora_adapters.restype = c_int32
+
+    # prerouter
+    lib.desireeia_load_prerouter.argtypes = [c_void_p, c_char_p]
+    lib.desireeia_load_prerouter.restype = c_int32
+
+    lib.desireeia_clear_prerouter.argtypes = [c_void_p]
+    lib.desireeia_clear_prerouter.restype = c_int32
+
+    lib.desireeia_set_prerouter_heuristic.argtypes = [c_void_p, c_int32]
+    lib.desireeia_set_prerouter_heuristic.restype = c_int32
+
+    # chat template
+    lib.desireeia_apply_chat_template.argtypes = [
+        c_void_p,
+        POINTER(c_char_p), POINTER(c_char_p), c_uint64, c_int32,
+        POINTER(ctypes.c_char), c_uint64, POINTER(c_uint64)
+    ]
+    lib.desireeia_apply_chat_template.restype = c_int32
+
+    # profiling
+    lib.desireeia_profile_dump.argtypes = [
+        POINTER(ctypes.c_char), c_uint64
+    ]
+    lib.desireeia_profile_dump.restype = None
+
+    lib.desireeia_profile_reset.argtypes = []
+    lib.desireeia_profile_reset.restype = None
+
+    # vision: image load/free
+    lib.desireeia_load_image.argtypes = [
+        c_char_p, c_int32, POINTER(VisionImage)
+    ]
+    lib.desireeia_load_image.restype = c_int32
+
+    lib.desireeia_free_image.argtypes = [POINTER(VisionImage)]
+    lib.desireeia_free_image.restype = None
+
+    # vision: standalone context
+    lib.desireeia_vision_create.argtypes = [c_char_p, LOG_CB, c_void_p]
+    lib.desireeia_vision_create.restype = c_void_p
+
+    lib.desireeia_vision_destroy.argtypes = [c_void_p]
+    lib.desireeia_vision_destroy.restype = None
+
+    lib.desireeia_vision_get_config.argtypes = [
+        c_void_p, POINTER(VisionConfig)
+    ]
+    lib.desireeia_vision_get_config.restype = c_int32
+
+    lib.desireeia_vision_encode.argtypes = [
+        c_void_p, POINTER(VisionImage),
+        POINTER(c_float), c_uint64, POINTER(c_uint64), POINTER(c_uint32)
+    ]
+    lib.desireeia_vision_encode.restype = c_int32
+
+    lib.desireeia_vision_preprocess.argtypes = [
+        POINTER(VisionImage), c_int32,
+        POINTER(c_float), c_uint64, POINTER(c_uint64)
+    ]
+    lib.desireeia_vision_preprocess.restype = c_int32
+
+    # vision: ctx-based multimodal
+    lib.desireeia_has_vision.argtypes = [c_void_p, POINTER(c_int32)]
+    lib.desireeia_has_vision.restype = c_int32
+
+    lib.desireeia_vision_token_count.argtypes = [c_void_p, POINTER(c_int32)]
+    lib.desireeia_vision_token_count.restype = c_int32
+
+    lib.desireeia_vision_image_token.argtypes = [c_void_p, POINTER(c_int32)]
+    lib.desireeia_vision_image_token.restype = c_int32
+
+    lib.desireeia_vision_encode_ctx.argtypes = [
+        c_void_p, POINTER(VisionImage),
+        POINTER(c_float), c_uint64, POINTER(c_uint64), POINTER(c_uint32)
+    ]
+    lib.desireeia_vision_encode_ctx.restype = c_int32
+
+    lib.desireeia_predict_image.argtypes = [
+        c_void_p, POINTER(c_int32), c_uint64,
+        POINTER(c_float), c_uint64, c_int32, POINTER(c_int32)
+    ]
+    lib.desireeia_predict_image.restype = c_int32

desireeia-0.0.1/desireeia/engine.py

@@ -0,0 +1,77 @@
+"""DesireeIAEngine — static entry point. Mirrors C# DesireeIAEngine.cs."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from . import _native as _nat
+from .enums import Error
+from .types import ExecutionPlan, HardwareProfile
+
+
+def version() -> str:
+    """Return the native engine version string."""
+    return _nat.get_lib().desireeia_version().decode("utf-8")
+
+
+def detect_hardware() -> HardwareProfile:
+    """Probe the machine and return a HardwareProfile."""
+    hw = _nat.HwInfo()
+    err = _nat.get_lib().desireeia_probe_hw(hw)
+    if err != Error.OK:
+        raise RuntimeError(f"Hardware probe failed: {Error(err).name}")
+    return HardwareProfile.from_native(hw)
+
+
+def build_plan(
+    model_path: Optional[str] = None,
+    overrides: Optional[ExecutionPlan] = None,
+) -> ExecutionPlan:
+    """Let the native engine auto-detect the best plan, optionally with overrides."""
+    lib = _nat.get_lib()
+
+    hw = _nat.HwInfo()
+    err = lib.desireeia_probe_hw(hw)
+    if err != Error.OK:
+        raise RuntimeError(f"Hardware probe failed: {Error(err).name}")
+
+    # Bug fixed here: this used to construct a blank, all-zero `_nat.Plan()`
+    # and never populate it from `overrides` - `overrides.to_native()` was
+    # never called, so every field a caller explicitly set (thread_count,
+    # kv_compression, batch_union, expert_prefetch, dense_quantization,
+    # ...) was silently discarded and replaced by whatever the native
+    # auto-detect logic picks for a zeroed field. The C# binding
+    # (DesireeIAEngine.cs BuildPlan, `overrides.ToNative()`) always did
+    # this correctly; only this Python wrapper had the gap - which is why
+    # a server built on this wrapper (desireeiaserver) measured
+    # dramatically lower decode throughput than the CLI on the identical
+    # model/hardware, despite requesting the same plan.
+    override_native = overrides.to_native() if overrides is not None else _nat.Plan()
+    override_ptr = _nat.ctypes.pointer(override_native) if overrides is not None else None
+    plan_out = _nat.Plan()
+
+    model_bytes = model_path.encode("utf-8") if model_path else None
+
+    err = lib.desireeia_make_plan(
+        _nat.ctypes.byref(hw),
+        model_bytes,
+        override_ptr,
+        _nat.ctypes.byref(plan_out),
+    )
+    if err != Error.OK:
+        raise RuntimeError(f"Plan build failed: {Error(err).name}")
+
+    return ExecutionPlan.from_native(plan_out)
+
+
+def profile_dump() -> str:
+    """Human-readable cumulative matmul profiling counters."""
+    buf = ( _nat.ctypes.c_char * 2048 )()
+    _nat.get_lib().desireeia_profile_dump(buf, 2048)
+    raw = buf.value
+    return raw.decode("utf-8", errors="replace")
+
+
+def profile_reset() -> None:
+    """Zero the process-global profiling counters."""
+    _nat.get_lib().desireeia_profile_reset()