Metadata-Version: 2.4
Name: gobbo
Version: 2.0.0
Summary: Gobbo 9D Voxel Datum and STAMP Technology — universal positioning (octree paths), pairwise STAMP / E-STAMP helpers, and optional HTTP client for Secure Envelope APIs. Copyright Gobbo Datum Labs; inventor: Adam Gobbo.
Author: Adam Gobbo
Author-email: Gobbo Datum Labs <support@gobbodatumlabs.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/gobbo-datum-labs/gobbo
Project-URL: Documentation, https://github.com/gobbo-datum-labs/gobbo
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: http
Requires-Dist: requests>=2.28.0; extra == "http"
Provides-Extra: http-strict
Requires-Dist: requests>=2.28.0; extra == "http-strict"
Requires-Dist: pydantic>=2.4.0; extra == "http-strict"
Provides-Extra: geospatial
Requires-Dist: pyproj; extra == "geospatial"
Requires-Dist: mgrs; extra == "geospatial"
Requires-Dist: packaging; extra == "geospatial"
Requires-Dist: laspy; extra == "geospatial"
Requires-Dist: rasterio; extra == "geospatial"
Requires-Dist: shapely; extra == "geospatial"
Requires-Dist: mpmath; extra == "geospatial"
Provides-Extra: gnss
Requires-Dist: numpy>=1.19; extra == "gnss"
Provides-Extra: nav
Requires-Dist: numpy>=1.19; extra == "nav"
Requires-Dist: ultralytics; extra == "nav"
Requires-Dist: opencv-python-headless; extra == "nav"
Dynamic: license-file

# gobbo — Gobbo 9D Voxel Datum + STAMP Technology

**Copyright 2026 Gobbo Datum Labs.** **Gobbo 9D Voxel Datum** with **STAMP Technology** — **inventor: Adam Gobbo.** Licensed under **Apache-2.0**; retain `LICENSE`, `NOTICE`, `ATTRIBUTION.md`, and **`EULA.md`** when redistributing. See `ATTRIBUTION.md` for citation text and goodwill rules.

**Binding supplemental terms:** By **downloading, installing, or using** this package, you agree to **`EULA.md`** (marks, **Permitted Gobbo Designations**, **STAMP** / **STAMP Format** naming). *Delaware counsel should finalize before enforcement.*

**Open source:** install from PyPI with `pip install gobbo`. Source and issues live at **[github.com/gobbo-datum-labs/gobbo](https://github.com/gobbo-datum-labs/gobbo)**. Writing STAMPs with this SDK is free; **reading/querying** the hosted Secure Envelope collection remains a paid service on [www.secure-envelope.com](https://www.secure-envelope.com).

Universal positioning framework for converting spatial data to Gobbo octree paths. "The one datum to rule them all."

## Installation

```bash
pip install gobbo
```

```python
import gobbo
```

That is the only install line and the only import name. The core package is
dependency-free standard-library Python.

**Optional dependency groups:**

```bash
pip install "gobbo[geospatial]"   # pyproj, laspy, rasterio, shapely, mpmath, mgrs — UTM/MGRS + file parsers
pip install "gobbo[gnss]"         # NumPy — PPP helpers in gobbo.core.gnss
pip install "gobbo[nav]"          # YOLO / OpenCV — map-scene and nav da3_yolo
pip install "gobbo[http]"         # requests — GobboClient for hosted /api/stamps/*
pip install "gobbo[http-strict]"  # requests + pydantic — typed HTTP responses
```

## Learn it (training course ships in the package)

A complete beginner-to-formal course is bundled inside the wheel:

- **`gobbo/docs/training/README.md`** — Lessons 0–8: why Gobbo, the nine
  dimensions, G-Line / H-Plane / N-Line, depth + Sphere-in-Cube, STAMP
  Technology, a hands-on first-stamp tutorial, 2TD vs GHN angles, the
  identity epoch, and collections.
- **`gobbo/docs/formal/PRIMER.md`** — faithful condensed formal primer with
  pointers to the frozen normative specifications.
- **`gobbo/examples/`** — runnable scripts (`01_lla_to_voxel.py`,
  `02_create_stamp.py`, `03_ghn_and_2td.py`).

Locate them after install:

```python
import gobbo, pathlib
print(pathlib.Path(gobbo.__file__).parent / "docs" / "training")
```

## Quick start

```python
import gobbo

# Position → voxel identity (identity epoch v2, exact on every platform)
path_int, depth = gobbo.gobbo_from_lla(40.6413, -73.7781, 4.0, depth=30)
print(gobbo.path_int_to_path_oct(path_int, depth))

# Honest depth from GPS precision (Sphere-in-Cube rule)
d = gobbo.gobbo_depth_for_precision_lla(40.6413, -73.7781, 4.0, 5.0)

# Mint an immutable STAMP fact (stampv:2 content-addressed id + frozen sentence)
stamp = gobbo.create_stamp(
    lat=40.6413, lon=-73.7781, alt=4.0, depth=30,
    temporal=1752444000, assignment="sensor:jfk-roof-1",
    metric="temperature_c", point=22.5, source="quickstart",
)
print(stamp.stamp_id)
print(stamp.sentence)
```

## Features

- Convert ECEF, LLA, UTM, MGRS to Gobbo paths; decode paths back to
  centers/bounds (LBF lattice doctrine).
- **Exact identity core** (`gobbo.core.gobbo_exact`): BigInt fixed-point
  WGS-84 transform, picometer voxel grid, deterministic trig — bit-identical
  voxel identity across Python / TypeScript / Kotlin / Swift (identity
  epoch v2).
- **STAMP minting** (`gobbo.create_stamp`) with the frozen `stampv:2`
  canonical serialization and SHA-256 `stamp_id`.
- **GHN frame** (`gobbo.gobbo_ghn_basis`): G-Line / H-Plane / N-Line local
  NED basis at any voxel center.
- **Pairwise STAMP interaction math:** line counts C(n,2), Gobbo Azimuth /
  Tilt / distance (2TD) from ECEF deltas, linear E-STAMP along a segment,
  1/8 parent mean and partial-n mean over children (see
  `docs/PAIRWISE_LINES_AND_ENRICHMENTS.md`).
- Parse LAS, GeoJSON, SRTM to voxel lists when the `geospatial` extra is
  installed.
- Spatial ops: overlap, diff, fuse, distance.
- CLI entry point: `gobbo` (see `gobbo/core/cli.py`).

## HTTP client (Secure Envelope STAMP API)

For calling a deployed API (`/api/stamps/push`, `by-voxel`, E-STAMP routes),
install the **`http`** extra and use `gobbo.http_client.GobboClient`:

```python
from gobbo.http_client import GobboClient

client = GobboClient(
    "https://your-deployment.example",
    bearer_token="...",  # optional for public routes
    api_key="...",       # optional if the server enables x-api-key
)
rows = client.get_stamps_by_voxel(path_int="123", depth=23)
```

Strict response parsing (Pydantic):

```python
from gobbo.http_client import GobboClient
from gobbo.stamp_http_models import parse_by_voxel_response

client = GobboClient("https://example.com", bearer_token="…")
data = client.get_stamps_by_voxel(path_int="1", depth=10)
typed = parse_by_voxel_response(data)
```

TypeScript equivalents: npm **`gobbo-stamp-sdk`** (HTTP) and
**`gobbo-datum-ts-sdk`** (canonical `path_int` / STAMP math). Method parity
is checked in CI (`scripts/sdk-http-surface.json`, `npm run check:sdk-parity`).

## Deterministic STAMP utilities

**`fact_kind` (B.12)** must be one of: `raw_measurement`,
`derived_measurement`, `estimate`, `label`, `correction` — same as the hosted
API schema. Defaults use `raw_measurement`.

- `gobbo.core.stamp_models` — `StampSpatial`, `StampFact`,
  `StampInteractionRow`, `FACT_KIND_*` literals
- `gobbo.core.stamp_sentence` — frozen canonical sentence builder
  (`At {voxel}@{depth} at {timeIso}, {assignment}'s {metric} of {value}.`)
- `gobbo.core.stamp_canonical` — frozen `stampv:2` serialization +
  `compute_stamp_id_v2`
- `gobbo.core.stamp_interactions` — `compute_delta_t_seconds`,
  `compute_delta_v`, `compute_interaction_metrics`, `build_interaction_row`

CLI access for non-developers:

```bash
gobbo stamp-sentence --path-int 123 --depth 10 --temporal "2026-04-12T10:11:12Z" --assignment "sensor.alpha" --metric "temperature_c" --point 23.5
```

## Tests and conformance

Golden-vector conformance (identity epoch v2 + `stampv:2`) and the full test
suite:

```bash
python3 -m unittest discover -s tests
```

TypeScript parity checks require the geospatial extra
(`pip install "gobbo[geospatial]"`).

## Documentation in this bundle

| Path | Contents |
|------|----------|
| `gobbo/docs/training/` | Lessons 0–8 — full beginner-to-formal course |
| `gobbo/docs/formal/PRIMER.md` | Formal primer → frozen specs bridge |
| `gobbo/examples/` | Runnable training example scripts |
| `docs/PAIRWISE_LINES_AND_ENRICHMENTS.md` | Pairwise lines, §7 encoding, E-STAMP linear model, parent/child means |
| `gobbo/PRD.md` | Product requirements (historical MVP scope) |
| `gobbo/core/gobbo.py` | Octree path generation, converters, spatial ops |
| `gobbo/core/gobbo_exact.py` | Exact fixed-point identity core (epoch v2) |
| `gobbo/core/requirements.txt` | Optional geospatial stack |

## License and attribution

- License: **Apache-2.0** (`LICENSE`)
- Required attribution notices: `NOTICE`
- Branding/trademark usage guidance: `TRADEMARKS.md`
- Suggested software citation metadata: `CITATION.cff`

The Apache-2.0 license keeps the SDK open source and broadly adoptable, while
`NOTICE` and `TRADEMARKS.md` preserve clear attribution to Gobbo Datum and
Gobbo Datum Labs and protect against misleading branding.

## Pro download

Subscribers can also download this SDK from the Secure Envelope dashboard
(authenticated **Download ZIP**). The archive matches the tracked
`content/sdk/gobbo-datum-sdk` tree in the product repository.
