Metadata-Version: 2.4
Name: golynx
Version: 1.0.1983.post1
Summary: LYNX — Clean-room object detection SDK
Home-page: https://www.golynx.ai
Author: Synetic
Author-email: feedback@synetic.ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10,<3.15
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Provides-Extra: cli
Requires-Dist: opencv-python>=4.5; extra == "cli"
Provides-Extra: dev
Requires-Dist: onnx>=1.12; extra == "dev"
Requires-Dist: pillow; extra == "dev"
Requires-Dist: pynacl>=1.5; extra == "dev"
Requires-Dist: cryptography>=41.0; extra == "dev"
Provides-Extra: altbackends
Requires-Dist: onnxruntime>=1.12; extra == "altbackends"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# LYNX SDK â€” language bindings (shims)

Idiomatic bindings for the LYNX SDK: **Python, Swift, Kotlin, Java (JVM), Node, React
Native**. These are thin marshalling layers over the LYNX **C core** â€” all recognition
logic lives in the core; the bindings only marshal calls and results.

The C core lives in a separate repo: **[Syneticai/LYNX-SDK](https://github.com/Syneticai/LYNX-SDK)**.
It builds + obfuscates the core, runs the harness, and publishes the obfuscated C SDK
(`lynx.h` + per-platform libs) as a GitHub Release (`build.yml` â†’ `s8_publish_core`).
This repo **consumes that Release artifact** to build the wrappers/wheels.

## Layout
- `lynx/` â€” the Python package (`_api.py`, `cli.py`, â€¦) + per-language bindings
  (`python/`, `swift/`, `kotlin/`, `jvm/`, `node/`, `react-native/`).
- `setup.py` / `pyproject.toml` â€” Python wheel build.
- `Package.swift` â€” Swift package.
- `.github/workflows/` â€” mobile/android/perf/qa workflows.
- `.github/build-stages.yml.saved` â€” the wrap/wheel/verify/publish JOBS lifted from the
  C repo's `build.yml`; these become this repo's primary build (rewire their `needs:`
  to **download the C SDK Release** instead of building the core in-tree).

## Status â€” pending wiring
Initial snapshot, split from the C repo. **Not yet buildable standalone:** `setup.py`
still expects `lynx/core` (source or `LYNX_PREBUILT_CORE`). The migration step is to
point the build at the published C SDK artifact:
1. C repo `s8_publish_core` publishes `lynx.h` + libs as a versioned Release.
2. Here: build downloads + unpacks that Release, sets `LYNX_PREBUILT_CORE` (and the
   include path to the shipped `lynx.h`), then builds the wheels/wraps.
3. Turn `build-stages.yml.saved` into `.github/workflows/build.yml`, rewired to (1).


# golynx

Object detection where every measurement arrives with its own provenance — so you can
always tell a measured metre from an assumed one.

```bash
pip install golynx
```

```python
import lynx

with lynx.open_standard("yolo26n.onnx") as model:
    frame = model.predict("street.jpg")
    for d in frame.detections:
        print(d.class_name, d.box.trust.confidence)
```

The distribution is `golynx`; the module is `lynx`.

## Two ways in

**A model you already have** — `.lnx`, `.lnxp`, or a raw ONNX export. No registry, no
network. Dispatches on the file's contents, not its extension:

```python
model = lynx.open_standard("yolo26n.onnx")
```

**A catalogue model by slug** — fetched, licence-checked, cached:

```python
model = lynx.open("your-model-slug")
```

Metadata a foreign graph doesn't carry is deduced when it opens. `probe_config()` works out
what an unfamiliar export needs by running it. `autotune()` returns ranked evidence without
applying anything, so a coin-flip stays visibly a coin-flip.

## Every value carries a Trust

The same fields on a box, a depth, a mask and a keypoint:

| field | meaning |
|---|---|
| `confidence` | a belief in [0, 1] |
| `margin` | plus-or-minus in the value's own units — `None` when nothing reports one, never `0`, because `0` reads as exact |
| `raw` | the value before the SDK adjusted it |
| `source` | where the number came from |
| `derivations` | every derivation that went into it |

`source` separates what the model was trained to report (`TRAINED`, `TRAINED_RELATIVE`,
`TRAINED_SIZE`, `TRAINED_RANGE`) from what the SDK worked out for you (`DERIVED_DEPTH`,
`DERIVED_DECLARED_HEIGHT`, `DERIVED_ASSUMED_FOCAL`, `DERIVED_POPULATION`,
`DERIVED_ASSUMED_POSTURE`).

A bare detection export has no depth head, yet every detection still reports a depth —
because the SDK knows roughly how big a bus is. That reading is honest about itself: it
comes back `DERIVED_ASSUMED_FOCAL` with a wide margin. Hand it camera intrinsics and the
same reading becomes `DERIVED_DECLARED_HEIGHT` with a much tighter one.

## Heads

`BOUNDING_BOX`, `ORIENTED_BOUNDING_BOX`, `SEGMENTATION`, `INSTANCE_SEGMENTATION`, `DEPTH`,
`POSE`, `CLASSIFICATION`, `REID`, `TEXT_RECOGNITION`, `AMODAL_BOX`, `YAW_3D`, `METRIC_SIZE`,
`RANGE`, `DENSITY`. A model exposes what it declares; ask for the tasks you want.

## Geometry

```python
cam = lynx.Intrinsics(fx=800, fy=800, cx=405, cy=540)

for d in frame.detections:
    p = d.position_3d(cam)          # metres, +z forward
    print(d.class_name, p.z, d.depth.value, d.depth.trust.source)
```

Depth, 3D position, real-world size and surface-to-surface distance are computed in the SDK
rather than left to the caller.

## Platforms

Python 3.10 – 3.14 on Linux x86-64 (`manylinux_2_34`), macOS Apple silicon, and Windows x64.

CUDA and Jetson JetPack 6 builds are too large for PyPI and are served separately:

```bash
pip install --extra-index-url https://syneticai.github.io/lynx/simple golynx-gpu
```

---

© Synetic AI
