Skip to content

c_api_stability.md

Latest commit

 

History

History
72 lines (57 loc) · 3.75 KB

c_api_stability.md

File metadata and controls

72 lines (57 loc) · 3.75 KB
Raw

UAII C API Stability Guarantees

Surface: include/uaii/c_api/uaii.h
API version macros: include/uaii/c_api/version.h
Current C API: UAII_C_API_VERSION = 0.4.0 (pre-1.0; struct_size required)

Semantic versioning

Bump When
MAJOR Removed/renamed symbols, changed struct layouts, changed semantics of existing functions
MINOR New functions/fields (callers compiled against older minors keep working)
PATCH Bug fixes that preserve documented behavior

Package version (uaii_get_version / CMake PROJECT_VERSION) may advance independently when only C++ internals change. Bindings should gate on uaii_get_c_api_version.

Compatibility rules (v1)

  1. Opaque handles (uaii_session*) — never dereference fields from client code.
  2. All functions return uaii_status; details via uaii_last_error().
  3. String arguments are UTF-8 paths / names; ownership stays with the caller.
  4. uaii_session_options may grow at the end in minor releases; always call uaii_session_options_init and set/keep struct_size = sizeof(uaii_session_options).
  5. Defaults are fail-closed: weight_init = NONE (no silent Ones fill).
  6. Plugin ABI (UAII_PLUGIN_ABI_VERSION) is separate from the C API version.

uaii_session_options (0.4.0)

Field Default Notes
struct_size sizeof(...) Required; reject if 0 or larger than library
backend "cpu"
weights_dir NULL
weight_init UAII_WEIGHT_INIT_NONE Fail closed
enable_fusion / enable_memory_reuse 1
enable_profiler 0
profile_trace_path NULL
budget_bytes 0 Unlimited
enable_streaming 0 Host staging; CUDA native may async H2D
allow_missing_weights 0
weights_sandbox NULL
compute_dtype UAII_COMPUTE_DTYPE_F32 Added at end of struct (0.3.0)
keep_quantized_weights 1 GGUF block-quant packed path
max_context 0 0 = graph metadata / unlimited generate bound
kv_window 0 Appended in 0.4.0. 0 = grow until max_context
kv_sink 4 Attention-sink tokens kept when the window slides
pin_layers 0 First N transformer layers kept resident
expert_cache_bytes 0 MoE expert LRU budget
max_threads 0 0 = hardware concurrency. Phone sets 4
single_staging 0 Non-zero = one staging buffer (phone)

Callers built against an older header with a smaller struct_size continue to work: the library zero-initializes defaults then copies only struct_size bytes.

Added in 0.4.0

Symbol Role
uaii_memory_preset_info Resolved preset. Set struct_size before uaii_resolve_memory_preset
uaii_resolve_memory_preset laptop / desktop / server / phone / none. Phone caps at half of free RAM. The others keep their target unless it exceeds free RAM
uaii_session_options_apply_preset Copy that preset onto uaii_session_options
uaii_system_available_bytes Bytes the OS can still give this process (0 if unknown)
uaii_process_rss_bytes Current process RSS
uaii_session_request_cancel generate / run return cancelled. generate clears this at entry
uaii_session_set_background Non-zero: generate / run return paused: app backgrounded until cleared
uaii_session_memory_warning Drop the KV cache between steps. Streamed weights stay on the plan. The longrope scale length is kept

Shared library

The CMake target uaii_capi builds the ABI-stable shared library (uaii_capi.dll / libuaii_capi.so / libuaii_capi.dylib).

Deprecation

Symbols may be marked deprecated in a MINOR release and removed only in the next MAJOR.