ik-llama-cpp-python 0.1.0__cp310-cp310-win_amd64.whl

ik_llama_cpp/__init__.py

@@ -0,0 +1,7 @@
+"""ik-llama-cpp-python — Python bindings for ik_llama.cpp."""
+
+from .llama import IkLlama
+from .quantize import find_quantize_bin, quantize, quantize_from_hf
+
+__version__ = "0.1.0"
+__all__ = ["IkLlama", "find_quantize_bin", "quantize", "quantize_from_hf"]

ik_llama_cpp/_ctypes_api.py

@@ -0,0 +1,418 @@
+"""Low-level ctypes bindings for the ik_llama.cpp C API (llama.h).
+
+NOTE: ik_llama.cpp uses an older-style API compared to upstream llama.cpp:
+  - Sampling is direct (llama_sample_*) instead of sampler-chain objects
+  - Model free is llama_free_model (not llama_model_free)
+  - Timings use llama_get_timings / llama_print_timings / llama_reset_timings
+  - Struct layouts differ significantly
+"""
+
+from __future__ import annotations
+
+import ctypes
+import functools
+from typing import Any, Callable, List, Optional, TypeVar
+
+from ._lib_loader import load_shared_library
+
+# ---------------------------------------------------------------------------
+# Load shared library
+# ---------------------------------------------------------------------------
+
+_lib = load_shared_library()
+
+# ---------------------------------------------------------------------------
+# Decorator — binds a Python stub to a C symbol in the shared library
+# ---------------------------------------------------------------------------
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _cfunc(name: str, argtypes: List[Any], restype: Any):
+    def decorator(f: F) -> F:
+        func = getattr(_lib, name)
+        func.argtypes = argtypes
+        func.restype = restype
+        functools.wraps(f)(func)
+        return func  # type: ignore[return-value]
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# Type aliases
+# ---------------------------------------------------------------------------
+
+llama_model_p = ctypes.c_void_p
+llama_context_p = ctypes.c_void_p
+llama_vocab_p = ctypes.c_void_p
+
+llama_token = ctypes.c_int32
+llama_token_p = ctypes.POINTER(llama_token)
+llama_pos = ctypes.c_int32
+llama_seq_id = ctypes.c_int32
+
+# Callback types
+llama_progress_callback = ctypes.CFUNCTYPE(
+    ctypes.c_bool, ctypes.c_float, ctypes.c_void_p
+)
+ggml_backend_sched_eval_callback = ctypes.CFUNCTYPE(
+    ctypes.c_bool, ctypes.c_void_p, ctypes.c_bool, ctypes.c_void_p
+)
+ggml_abort_callback = ctypes.CFUNCTYPE(ctypes.c_bool, ctypes.c_void_p)
+
+# ---------------------------------------------------------------------------
+# Structures (matching ik_llama.cpp fork layouts)
+# ---------------------------------------------------------------------------
+
+
+class llama_model_kv_override_value(ctypes.Union):
+    _fields_ = [
+        ("val_i64", ctypes.c_int64),
+        ("val_f64", ctypes.c_double),
+        ("val_bool", ctypes.c_bool),
+        ("val_str", ctypes.c_char * 128),
+    ]
+
+
+class llama_model_kv_override(ctypes.Structure):
+    _fields_ = [
+        ("tag", ctypes.c_int),
+        ("key", ctypes.c_char * 128),
+        ("value", llama_model_kv_override_value),
+    ]
+
+
+class llama_model_params(ctypes.Structure):
+    """ik_llama.cpp llama_model_params — differs from upstream."""
+    _fields_ = [
+        ("devices", ctypes.c_char_p),
+        ("n_gpu_layers", ctypes.c_int32),
+        ("mla", ctypes.c_int32),
+        ("split_mode", ctypes.c_int),
+        ("main_gpu", ctypes.c_int32),
+        ("max_gpu", ctypes.c_int32),
+        ("ncmoe", ctypes.c_int32),
+        ("type_k", ctypes.c_int),
+        ("type_v", ctypes.c_int),
+        ("max_ctx_size", ctypes.c_uint32),
+        ("n_seq_max", ctypes.c_int32),
+        ("n_ubatch", ctypes.c_int32),
+        ("amb", ctypes.c_int32),
+        ("fit_margin", ctypes.c_int32),
+        ("fit", ctypes.c_bool),
+        ("worst_graph_tokens", ctypes.c_int32),
+        ("type_k_first", ctypes.c_int),
+        ("type_k_last", ctypes.c_int),
+        ("type_v_first", ctypes.c_int),
+        ("type_v_last", ctypes.c_int),
+        ("n_k_first", ctypes.c_int32),
+        ("n_k_last", ctypes.c_int32),
+        ("n_v_first", ctypes.c_int32),
+        ("n_v_last", ctypes.c_int32),
+        ("tensor_split", ctypes.POINTER(ctypes.c_float)),
+        ("rpc_servers", ctypes.c_char_p),
+        ("progress_callback", llama_progress_callback),
+        ("progress_callback_user_data", ctypes.c_void_p),
+        ("kv_overrides", ctypes.POINTER(llama_model_kv_override)),
+        ("tensor_buft_overrides", ctypes.c_void_p),
+        ("vocab_only", ctypes.c_bool),
+        ("use_mmap", ctypes.c_bool),
+        ("use_mlock", ctypes.c_bool),
+        ("check_tensors", ctypes.c_bool),
+        ("repack_tensors", ctypes.c_bool),
+        ("use_thp", ctypes.c_bool),
+        ("validate_quants", ctypes.c_bool),
+        ("merge_qkv", ctypes.c_bool),
+        ("merge_up_gate_exps", ctypes.c_bool),
+        ("mtp", ctypes.c_bool),
+        ("dry_run", ctypes.c_bool),
+        ("flash_attn", ctypes.c_bool),
+    ]
+
+
+class llama_context_params(ctypes.Structure):
+    """ik_llama.cpp llama_context_params — differs from upstream."""
+    _fields_ = [
+        ("seed", ctypes.c_uint32),
+        ("n_ctx", ctypes.c_uint32),
+        ("n_batch", ctypes.c_uint32),
+        ("n_ubatch", ctypes.c_uint32),
+        ("n_seq_max", ctypes.c_uint32),
+        ("n_threads", ctypes.c_uint32),
+        ("n_threads_batch", ctypes.c_uint32),
+        ("max_extra_alloc", ctypes.c_int32),
+        ("worst_case_tokens", ctypes.c_int32),
+        ("rope_scaling_type", ctypes.c_int),
+        ("pooling_type", ctypes.c_int),
+        ("attention_type", ctypes.c_int),
+        ("rope_freq_base", ctypes.c_float),
+        ("rope_freq_scale", ctypes.c_float),
+        ("yarn_ext_factor", ctypes.c_float),
+        ("yarn_attn_factor", ctypes.c_float),
+        ("yarn_beta_fast", ctypes.c_float),
+        ("yarn_beta_slow", ctypes.c_float),
+        ("yarn_orig_ctx", ctypes.c_uint32),
+        ("defrag_thold", ctypes.c_float),
+        ("cb_eval", ggml_backend_sched_eval_callback),
+        ("cb_eval_user_data", ctypes.c_void_p),
+        ("type_k", ctypes.c_int),
+        ("type_v", ctypes.c_int),
+        ("type_reduce", ctypes.c_int),
+        ("type_k_first", ctypes.c_int),
+        ("type_k_last", ctypes.c_int),
+        ("type_v_first", ctypes.c_int),
+        ("type_v_last", ctypes.c_int),
+        ("n_k_first", ctypes.c_int32),
+        ("n_k_last", ctypes.c_int32),
+        ("n_v_first", ctypes.c_int32),
+        ("n_v_last", ctypes.c_int32),
+        ("logits_all", ctypes.c_bool),
+        ("embeddings", ctypes.c_bool),
+        ("offload_kqv", ctypes.c_bool),
+        ("flash_attn", ctypes.c_bool),
+        ("mla_attn", ctypes.c_int),
+        ("attn_max_batch", ctypes.c_int),
+        ("fused_moe_up_gate", ctypes.c_bool),
+        ("grouped_expert_routing", ctypes.c_bool),
+        ("fused_up_gate", ctypes.c_bool),
+        ("fused_mmad", ctypes.c_bool),
+        ("rope_cache", ctypes.c_bool),
+        ("graph_reuse", ctypes.c_bool),
+        ("min_experts", ctypes.c_int),
+        ("thresh_experts", ctypes.c_float),
+        ("only_active_experts", ctypes.c_bool),
+        ("k_cache_hadamard", ctypes.c_bool),
+        ("v_cache_hadamard", ctypes.c_bool),
+        ("split_mode_graph_scheduling", ctypes.c_bool),
+        ("scheduler_async", ctypes.c_bool),
+        ("mtp", ctypes.c_bool),
+        ("mtp_op_type", ctypes.c_int),
+        ("abort_callback", ggml_abort_callback),
+        ("abort_callback_data", ctypes.c_void_p),
+        ("offload_policy", ctypes.c_void_p),
+        ("cuda_params", ctypes.c_void_p),
+    ]
+
+
+class llama_batch(ctypes.Structure):
+    _fields_ = [
+        ("n_tokens", ctypes.c_int32),
+        ("token", ctypes.POINTER(llama_token)),
+        ("embd", ctypes.POINTER(ctypes.c_float)),
+        ("pos", ctypes.POINTER(llama_pos)),
+        ("n_seq_id", ctypes.POINTER(ctypes.c_int32)),
+        ("seq_id", ctypes.POINTER(ctypes.POINTER(llama_seq_id))),
+        ("logits", ctypes.POINTER(ctypes.c_int8)),
+        ("all_pos_0", llama_pos),
+        ("all_pos_1", llama_pos),
+        ("all_seq_id", llama_seq_id),
+    ]
+
+
+class llama_token_data(ctypes.Structure):
+    _fields_ = [
+        ("id", llama_token),
+        ("logit", ctypes.c_float),
+        ("p", ctypes.c_float),
+    ]
+
+
+class llama_token_data_array(ctypes.Structure):
+    _fields_ = [
+        ("data", ctypes.POINTER(llama_token_data)),
+        ("size", ctypes.c_size_t),
+        ("selected", ctypes.c_int64),
+        ("sorted", ctypes.c_bool),
+    ]
+
+
+class llama_timings(ctypes.Structure):
+    """ik_llama.cpp uses llama_timings instead of llama_perf_context_data."""
+    _fields_ = [
+        ("t_start_ms", ctypes.c_double),
+        ("t_end_ms", ctypes.c_double),
+        ("t_load_ms", ctypes.c_double),
+        ("t_sample_ms", ctypes.c_double),
+        ("t_p_eval_ms", ctypes.c_double),
+        ("t_eval_ms", ctypes.c_double),
+        ("n_sample", ctypes.c_int32),
+        ("n_p_eval", ctypes.c_int32),
+        ("n_eval", ctypes.c_int32),
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Function bindings
+# ---------------------------------------------------------------------------
+
+# -- Backend lifecycle --
+
+@_cfunc("llama_backend_init", [], None)
+def llama_backend_init() -> None: ...
+
+
+@_cfunc("llama_backend_free", [], None)
+def llama_backend_free() -> None: ...
+
+
+# -- Default params --
+
+@_cfunc("llama_model_default_params", [], llama_model_params)
+def llama_model_default_params() -> llama_model_params: ...
+
+
+@_cfunc("llama_context_default_params", [], llama_context_params)
+def llama_context_default_params() -> llama_context_params: ...
+
+
+# -- Model load / free --
+
+@_cfunc("llama_model_load_from_file", [ctypes.c_char_p, llama_model_params], ctypes.c_void_p)
+def llama_model_load_from_file(path: bytes, params: llama_model_params) -> Optional[int]: ...
+
+
+@_cfunc("llama_free_model", [ctypes.c_void_p], None)
+def llama_free_model(model: int) -> None: ...
+
+
+@_cfunc("llama_model_desc", [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_size_t], ctypes.c_int32)
+def llama_model_desc(model: int, buf: Any, buf_size: int) -> int: ...
+
+
+# -- Context init / free --
+
+@_cfunc("llama_init_from_model", [ctypes.c_void_p, llama_context_params], ctypes.c_void_p)
+def llama_init_from_model(model: int, params: llama_context_params) -> Optional[int]: ...
+
+
+@_cfunc("llama_free", [ctypes.c_void_p], None)
+def llama_free(ctx: int) -> None: ...
+
+
+# -- Vocab --
+
+@_cfunc("llama_model_get_vocab", [ctypes.c_void_p], ctypes.c_void_p)
+def llama_model_get_vocab(model: int) -> Optional[int]: ...
+
+
+@_cfunc("llama_vocab_n_tokens", [ctypes.c_void_p], ctypes.c_int32)
+def llama_vocab_n_tokens(vocab: int) -> int: ...
+
+
+# -- Tokenize / Detokenize --
+
+@_cfunc(
+    "llama_tokenize",
+    [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_int32,
+     llama_token_p, ctypes.c_int32, ctypes.c_bool, ctypes.c_bool],
+    ctypes.c_int32,
+)
+def llama_tokenize(
+    vocab: int, text: bytes, text_len: int,
+    tokens: Any, n_tokens_max: int,
+    add_special: bool, parse_special: bool,
+) -> int: ...
+
+
+@_cfunc(
+    "llama_token_to_piece",
+    [ctypes.c_void_p, llama_token, ctypes.c_char_p,
+     ctypes.c_int32, ctypes.c_int32, ctypes.c_bool],
+    ctypes.c_int32,
+)
+def llama_token_to_piece(
+    vocab: int, token: int, buf: Any,
+    length: int, lstrip: int, special: bool,
+) -> int: ...
+
+
+# -- Batch --
+
+@_cfunc("llama_batch_init", [ctypes.c_int32, ctypes.c_int32, ctypes.c_int32], llama_batch)
+def llama_batch_init(n_tokens: int, embd: int, n_seq_max: int) -> llama_batch: ...
+
+
+@_cfunc("llama_batch_free", [llama_batch], None)
+def llama_batch_free(batch: llama_batch) -> None: ...
+
+
+# -- Decode --
+
+@_cfunc("llama_decode", [ctypes.c_void_p, llama_batch], ctypes.c_int32)
+def llama_decode(ctx: int, batch: llama_batch) -> int: ...
+
+
+# -- Logits --
+
+@_cfunc("llama_get_logits_ith", [ctypes.c_void_p, ctypes.c_int32], ctypes.POINTER(ctypes.c_float))
+def llama_get_logits_ith(ctx: int, i: int) -> Any: ...
+
+
+# -- EOG detection --
+
+@_cfunc("llama_token_is_eog", [ctypes.c_void_p, llama_token], ctypes.c_bool)
+def llama_token_is_eog(model: int, token: int) -> bool: ...
+
+
+# -- Direct sampling (ik_llama.cpp style — no sampler chain) --
+
+@_cfunc(
+    "llama_sample_top_k",
+    [ctypes.c_void_p, ctypes.POINTER(llama_token_data_array), ctypes.c_int32, ctypes.c_size_t],
+    None,
+)
+def llama_sample_top_k(ctx: int, candidates: Any, k: int, min_keep: int) -> None: ...
+
+
+@_cfunc(
+    "llama_sample_top_p",
+    [ctypes.c_void_p, ctypes.POINTER(llama_token_data_array), ctypes.c_float, ctypes.c_size_t],
+    None,
+)
+def llama_sample_top_p(ctx: int, candidates: Any, p: float, min_keep: int) -> None: ...
+
+
+@_cfunc(
+    "llama_sample_temp",
+    [ctypes.c_void_p, ctypes.POINTER(llama_token_data_array), ctypes.c_float],
+    None,
+)
+def llama_sample_temp(ctx: int, candidates: Any, temp: float) -> None: ...
+
+
+@_cfunc(
+    "llama_sample_softmax",
+    [ctypes.c_void_p, ctypes.POINTER(llama_token_data_array)],
+    None,
+)
+def llama_sample_softmax(ctx: int, candidates: Any) -> None: ...
+
+
+@_cfunc(
+    "llama_sample_token_greedy",
+    [ctypes.c_void_p, ctypes.POINTER(llama_token_data_array)],
+    llama_token,
+)
+def llama_sample_token_greedy(ctx: int, candidates: Any) -> int: ...
+
+
+@_cfunc(
+    "llama_sample_token",
+    [ctypes.c_void_p, ctypes.POINTER(llama_token_data_array)],
+    llama_token,
+)
+def llama_sample_token(ctx: int, candidates: Any) -> int: ...
+
+
+# -- Timings (ik_llama.cpp style) --
+
+@_cfunc("llama_get_timings", [ctypes.c_void_p], llama_timings)
+def llama_get_timings(ctx: int) -> llama_timings: ...
+
+
+@_cfunc("llama_print_timings", [ctypes.c_void_p], None)
+def llama_print_timings(ctx: int) -> None: ...
+
+
+@_cfunc("llama_reset_timings", [ctypes.c_void_p], None)
+def llama_reset_timings(ctx: int) -> None: ...

ik_llama_cpp/_internals.py

@@ -0,0 +1,192 @@
+"""RAII wrappers for ik_llama.cpp C objects."""
+
+from __future__ import annotations
+
+import ctypes
+from typing import Optional
+
+from . import _ctypes_api as C
+
+
+class IkModel:
+    """Wraps a llama_model pointer with automatic cleanup."""
+
+    def __init__(self, path: str, *, use_mmap: bool = True, use_mlock: bool = False,
+                 n_gpu_layers: int = 0):
+        C.llama_backend_init()
+
+        params = C.llama_model_default_params()
+        params.use_mmap = use_mmap
+        params.use_mlock = use_mlock
+        params.n_gpu_layers = n_gpu_layers
+
+        self._model = C.llama_model_load_from_file(path.encode("utf-8"), params)
+        if not self._model:
+            raise RuntimeError(f"Failed to load model: {path}")
+
+        self._vocab = C.llama_model_get_vocab(self._model)
+        self.n_vocab = C.llama_vocab_n_tokens(self._vocab)
+
+    @property
+    def model(self):
+        return self._model
+
+    @property
+    def vocab(self):
+        return self._vocab
+
+    @property
+    def desc(self) -> str:
+        """Model description string (e.g. 'gemma4 2B IQ4_KT - 4.0 bpw')."""
+        buf = ctypes.create_string_buffer(256)
+        C.llama_model_desc(self._model, buf, 256)
+        return buf.value.decode("utf-8", errors="replace")
+
+    def tokenize(self, text: str, *, add_bos: bool = True, special: bool = False) -> list[int]:
+        text_bytes = text.encode("utf-8")
+        # First call to get required size (ik_llama.cpp takes model*, not vocab*)
+        n = C.llama_tokenize(
+            self._model, text_bytes, len(text_bytes),
+            None, 0, add_bos, special,
+        )
+        n = abs(n)
+        buf = (C.llama_token * n)()
+        n_actual = C.llama_tokenize(
+            self._model, text_bytes, len(text_bytes),
+            buf, n, add_bos, special,
+        )
+        return list(buf[:n_actual])
+
+    def detokenize(self, tokens: list[int], *, special: bool = False) -> str:
+        pieces = []
+        buf = ctypes.create_string_buffer(256)
+        for tok in tokens:
+            n = C.llama_token_to_piece(self._model, tok, buf, 256, 0, special)
+            if n > 0:
+                pieces.append(buf.value[:n].decode("utf-8", errors="replace"))
+        return "".join(pieces)
+
+    def close(self):
+        if self._model:
+            C.llama_free_model(self._model)
+            self._model = None
+
+    def __del__(self):
+        self.close()
+
+
+class IkContext:
+    """Wraps a llama_context pointer with automatic cleanup."""
+
+    def __init__(self, model: IkModel, *, n_ctx: int = 4096, n_threads: int = 0,
+                 flash_attn: bool = True):
+        params = C.llama_context_default_params()
+        params.n_ctx = n_ctx
+        params.n_batch = n_ctx
+        if n_threads > 0:
+            params.n_threads = n_threads
+            params.n_threads_batch = n_threads
+        params.flash_attn = flash_attn
+
+        self._ctx = C.llama_init_from_model(model.model, params)
+        if not self._ctx:
+            raise RuntimeError("Failed to create context")
+        self._model = model
+        self._n_ubatch = params.n_ubatch or 512
+
+    @property
+    def ctx(self):
+        return self._ctx
+
+    @property
+    def model(self) -> IkModel:
+        return self._model
+
+    def decode(self, batch: C.llama_batch) -> int:
+        return C.llama_decode(self._ctx, batch)
+
+    def get_logits(self, idx: int = -1):
+        return C.llama_get_logits_ith(self._ctx, idx)
+
+    def perf(self) -> dict:
+        data = C.llama_get_timings(self._ctx)
+        return {
+            "t_p_eval_ms": data.t_p_eval_ms,
+            "t_eval_ms": data.t_eval_ms,
+            "n_p_eval": data.n_p_eval,
+            "n_eval": data.n_eval,
+        }
+
+    def perf_reset(self):
+        C.llama_reset_timings(self._ctx)
+
+    def sample(self, idx: int, *, temperature: float = 0.0,
+               top_k: int = 40, top_p: float = 0.95) -> int:
+        """Sample a token from logits at position idx using direct sampling."""
+        n_vocab = self._model.n_vocab
+        logits = C.llama_get_logits_ith(self._ctx, idx)
+
+        # Build candidate array
+        candidates_data = (C.llama_token_data * n_vocab)()
+        for i in range(n_vocab):
+            candidates_data[i].id = i
+            candidates_data[i].logit = logits[i]
+            candidates_data[i].p = 0.0
+
+        candidates = C.llama_token_data_array()
+        candidates.data = candidates_data
+        candidates.size = n_vocab
+        candidates.selected = -1
+        candidates.sorted = False
+
+        candidates_p = ctypes.pointer(candidates)
+
+        if temperature <= 0:
+            return C.llama_sample_token_greedy(self._ctx, candidates_p)
+        else:
+            C.llama_sample_top_k(self._ctx, candidates_p, top_k, 1)
+            C.llama_sample_top_p(self._ctx, candidates_p, top_p, 1)
+            C.llama_sample_temp(self._ctx, candidates_p, temperature)
+            return C.llama_sample_token(self._ctx, candidates_p)
+
+    def close(self):
+        if self._ctx:
+            C.llama_free(self._ctx)
+            self._ctx = None
+
+    def __del__(self):
+        self.close()
+
+
+def make_batch(tokens: list[int], *, logits_last: bool = True) -> C.llama_batch:
+    """Create a llama_batch from a token list (positions start at 0)."""
+    return make_batch_range(tokens, pos_start=0, logits_last=logits_last)
+
+
+def make_batch_range(tokens: list[int], *, pos_start: int = 0,
+                     logits_last: bool = True) -> C.llama_batch:
+    """Create a llama_batch from a token list with explicit position offset."""
+    n = len(tokens)
+    batch = C.llama_batch_init(n, 0, 1)
+    batch.n_tokens = n
+
+    for i, tok in enumerate(tokens):
+        batch.token[i] = tok
+        batch.pos[i] = pos_start + i
+        batch.n_seq_id[i] = 1
+        batch.seq_id[i][0] = 0
+        batch.logits[i] = 1 if (logits_last and i == n - 1) else 0
+
+    return batch
+
+
+def make_batch_single(token: int, pos: int) -> C.llama_batch:
+    """Create a single-token batch for autoregressive generation."""
+    batch = C.llama_batch_init(1, 0, 1)
+    batch.n_tokens = 1
+    batch.token[0] = token
+    batch.pos[0] = pos
+    batch.n_seq_id[0] = 1
+    batch.seq_id[0][0] = 0
+    batch.logits[0] = 1
+    return batch

ik_llama_cpp/_lib_loader.py

@@ -0,0 +1,62 @@
+"""Shared library loader for ik_llama.cpp."""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import platform
+import sys
+from pathlib import Path
+
+
+def _lib_names() -> list[str]:
+    system = platform.system()
+    if system == "Windows":
+        return ["llama.dll"]
+    elif system == "Darwin":
+        return ["libllama.dylib"]
+    else:
+        return ["libllama.so"]
+
+
+def load_shared_library() -> ctypes.CDLL:
+    """Find and load the ik_llama shared library.
+
+    Search order:
+    1. ``IK_LLAMA_CPP_LIB_PATH`` env var (exact path to .dll/.so/.dylib)
+    2. ``ik_llama_cpp/lib/`` directory next to this file (pip-installed)
+    """
+    # 1. Explicit override
+    override = os.environ.get("IK_LLAMA_CPP_LIB_PATH")
+    if override:
+        p = Path(override)
+        if p.is_file():
+            return _load(p)
+        raise FileNotFoundError(f"IK_LLAMA_CPP_LIB_PATH points to missing file: {p}")
+
+    # 2. Package lib/ directory (source tree or site-packages)
+    search_dirs = [Path(__file__).parent / "lib"]
+
+    # Also check site-packages (editable installs put DLLs there)
+    for sp in sys.path:
+        sp_lib = Path(sp) / "ik_llama_cpp" / "lib"
+        if sp_lib != search_dirs[0] and sp_lib.is_dir():
+            search_dirs.append(sp_lib)
+
+    for lib_dir in search_dirs:
+        for name in _lib_names():
+            candidate = lib_dir / name
+            if candidate.exists():
+                return _load(candidate)
+
+    raise FileNotFoundError(
+        f"Cannot find ik_llama shared library. Searched: {search_dirs}. "
+        "Set IK_LLAMA_CPP_LIB_PATH or rebuild with: pip install -e ."
+    )
+
+
+def _load(path: Path) -> ctypes.CDLL:
+    # On Windows, add the library directory to DLL search path
+    if platform.system() == "Windows":
+        os.add_dll_directory(str(path.parent))
+    return ctypes.CDLL(str(path))