Metadata-Version: 2.5
Name: struct-sdk-native
Version: 0.1.13
Summary: Native capture runtime for the Struct observability SDK
Project-URL: Homepage, https://struct.ai
Project-URL: Documentation, https://struct.ai/docs
Project-URL: Issues, https://struct.ai/support
Author-email: Struct <support@struct.ai>
License-Expression: Apache-2.0
License-File: native/LICENSE
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# struct-sdk-native

Native capture runtime for the [Struct](https://struct.ai) observability SDK. `struct-sdk`
installs it automatically; you do not need to install or import it yourself.

Public `struct.init(api_url=...)` composes authenticated Observation configuration with native
function-boundary hooks, boundary-plan lowering and the ordinary-function lifecycle. The SDK
emits outputs through OpenTelemetry and owns export and health. Capability depends on the
interpreter, platform and verified adapter:

```python
from struct_sdk_native import capability_report

capability_report().available  # True only on a supported, verified native build
```

The internal lifecycle disarms inherited hooks after fork and requires explicit
`initialize(fresh_consumer)` in each worker. It supplies synchronous `suppress_capture()` scopes
and `shutdown(deadline)` using an absolute `time.monotonic()` deadline. The native outcome counts
describe consumer handoff, not export acknowledgement. Initialization establishes the process-owned
cleanup worker; shutdown and cleanup retries never start threads on the deadline-bound caller.
Retain the lifecycle and output adapter while cleanup is pending: active spans keep terminal hooks
until their original function returns and restores context, even after the delivery deadline.
Public `struct.init()` owns this composition; call it explicitly in each forked worker and call
`struct.shutdown()` during application teardown. This native package installs no signal or exit handler.

CPython 3.12 on Linux glibc (x86_64, ARM64, glibc 2.28 or newer) and macOS arm64 installs a
compiled wheel. Every other platform, including Python 3.13 and musl, installs a pure Python
wheel that reports the capability as unavailable. Neither case needs a Rust compiler, and no
source distribution is published.

The server's publication path uses `struct_sdk_native.sil.prepare_definition(bytes)` to revalidate
immutable stored artifacts outside database locks, then a fresh `configuration_index()` to check
every enabled observation's prepared versions together. Preparation preserves existing identities;
the index retains only target/metric signatures. Both call the shared Rust compiler with the GIL
released and report typed refusals. The customer SDK never imports this compiler surface.
