Metadata-Version: 2.4
Name: vaas-x
Version: 0.1.0
Summary: VAAS-X BraaS SDK -- Bootstrap sensor onboarding + ArtificialCognition client for the hosted VAAS-X cognitive substrate.
Author-email: VAAS-X Ltd <hello@vaasx.com>
License: Proprietary -- see LICENSE
Project-URL: Homepage, https://vaasx.com
Project-URL: Documentation, https://vaasx.com/docs
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Provides-Extra: websocket
Requires-Dist: websockets>=12.0; extra == "websocket"
Provides-Extra: mqtt
Requires-Dist: paho-mqtt>=2.0; extra == "mqtt"
Provides-Extra: dataframe
Requires-Dist: pandas>=2.0; extra == "dataframe"
Provides-Extra: ac
Requires-Dist: torch>=2.0; extra == "ac"
Requires-Dist: torchvision>=0.18; extra == "ac"
Requires-Dist: torchaudio>=2.0; extra == "ac"
Requires-Dist: sentence-transformers>=3.0; extra == "ac"
Requires-Dist: pillow>=10.0; extra == "ac"

# vaas-x -- BraaS SDK (PyPI package source)

This folder is the source for the `vaas-x` package published to PyPI --
distinct from both `deployment_package/` (the self-hostable public demo,
which ships full substrate source) and `core/`/`bootstrap/` (the private
EC2 codebase). This is the thin client: Bootstrap's local sensor pipeline
plus a plain HTTP wrapper around the public resolver API. It never
contains HCI retrieval, SAO encoding internals, OKE encryption, or the
salience loop -- those stay on EC2 permanently.

## Layout

```
vaasx/
  __init__.py         Bootstrap, HiveMind, ArtificialCognition
  client.py            Bootstrap -- thin HTTP client for api.vaasx.com
  hive.py               HiveMind -- multi-device fan-out queries (Developer+)
  config.py             Client-side config only, no server paths/secrets
  bootstrap/            Local edge pipeline (Bootstrap P8)
    profiler.py          Online per-channel statistics (portable, no deps)
    classifier.py         Schema classification from profiler snapshots
    accumulator.py         SAO episode construction + batched ingest
    detector.py            Confidence-scaled anomaly detection
    provisioner.py          device_id helper -- NOT the server process-spawner
    pipeline.py             Wires the above together for Bootstrap.connect()
    connectors/              http, websocket, mqtt, file, generator, dataframe, pipe
  ac/                    ArtificialCognition (P9) -- see status below, real but not
                          production-ready yet (untrained IMU weights, unverified
                          third-party encoder wrappers -- see ac/__init__.py's
                          docstring for the exact gaps)
    composite.py           Fused operational-state vector (Cython target)
    retrieval.py            Cross-modal retrieval against resolver /ac/query (Cython target)
    encoders/
      imu.py                 OIE architecture wrapper (Cython target, needs torch)
      text.py                 sentence-transformers wrapper
      vision.py                torchvision ViT wrapper
      depth.py, thermal.py      single-channel variants, reuse vision.py's ViT
      audio.py                  torchaudio WAV2VEC2 wrapper
      base.py                   encoder interface
```

## Status vs. the original build spec

Adapted from the private `bootstrap/{profiler,classifier,accumulator,detector}/`
modules, with two real deviations from a straight copy:

- **provisioner.py** is NOT a port of the private service's provisioner,
  which spawns actual OS shard processes on the EC2 host. That has no
  meaning on a customer's machine. Provisioning is already transparent --
  the resolver auto-provisions on first request (`_ensure_shard()` in
  `bootstrap/api/resolver.py`). This file is just a `device_id` helper.
- **accumulator.py / detector.py** talk to the resolver via
  `vaasx.client.Bootstrap` (authenticated, tier-gated) instead of the
  private service's direct shard-URL / multi-shard-fanout calls, which
  were private-network-only and never meant for customer access.

**Cython build status (matches `VAASX_BraaS_SDK_Build_Prompt_v5_1.md`
Section 7a exactly -- `setup_cython.py`'s compiler directives, target list,
and build commands are copied from that spec):**

- `bootstrap/{profiler,classifier,accumulator,detector,provisioner}.py` (5 of
  the spec's 8 target files -- the only 5 that exist today, the 3 AC files
  below don't exist yet) compile cleanly to native `.so`/`.pyd` extension
  modules via `python3 setup_cython.py build_ext --inplace`.
- Verified three ways: (1) round-tripped through a copy of the package tree
  with the `.py` sources for those 5 files deleted entirely -- import and a
  functional smoke test (device_id sanitization, profiler channel stats,
  confidence scoring) passed against the `.so`-only tree; (2) spec Step 2's
  own check, automated in `build_scripts/verify_ip_protection.py --inplace`
  -- each module imports from its `.so` and has zero recoverable `def
  name(...)` signatures (the naive `strings *.so | grep 'def '` from the
  spec false-positives on Cython's own boilerplate, which contains "def " as
  a substring of "cdef "; the checker uses a word-boundary regex instead);
  (3) a full wheel build + the spec's IP protection checklist, automated in
  the same script's `--wheel` mode.
- **Real defect found and fixed while verifying the wheel build:**
  `python -m build --wheel` alone silently drops the compiled `.so` files --
  they're pre-built binaries sitting in the tree, not `ext_modules` that
  invocation compiles itself, so without an explicit `package-data` entry
  `pyproject.toml`'s default packaging produces a `py3-none-any` wheel with
  **zero compiled code in it**. Fixed by adding
  `[tool.setuptools.package-data]` entries for `vaasx.bootstrap`, `vaasx.ac`,
  `vaasx.ac.encoders`.
- **Second defect found and fixed:** even with the `.so` files included, the
  wheel still tagged itself `py3-none-any` ("pure Python, any platform") --
  pip would install it anywhere, including platforms where the x86_64 Linux
  binary can't load. `verify_ip_protection.py --wheel` now hard-fails on
  this combination (compiled binaries + universal tag). The real manylinux
  release path (`build_manylinux.sh`, `auditwheel repair`) tags correctly by
  construction; a local/dev-only retag command is documented in
  `package_release.py`'s docstring.
- **All 8 of the spec's targets now compile**, including the 3 AC (P9)
  files: `ac/encoders/imu.py`, `ac/composite.py`, `ac/retrieval.py`.
  `composite.py`/`retrieval.py` are pure numpy and fully functionally
  verified (round-tripped `.so`-only, zero `.py` source, real cosine
  projection/fusion math checked). `imu.py` compiles cleanly under Cython
  without torch installed (Cython transpiles source without executing it),
  but importing the *compiled* module still requires torch at runtime, same
  as the plain-Python version would -- not tested end-to-end in this
  sandbox (no torch here). `verify_ip_protection.py --inplace` treats that
  specific "requires the 'ac' extra" failure as a WARN (proves the .so ran
  real compiled code and hit its own documented dependency check) rather
  than a FAIL.
- **AC's server-side gap is closed**: `bootstrap/api/resolver.py` now has
  `POST /ac/ingest` and `POST /ac/query`, backed by a new
  `bootstrap/api/ac_store.py` (SQLite-persisted flat cosine index, scoped
  per customer+device). Full end-to-end test (ingest 3 embeddings, query,
  confirm correct similarity ranking, confirm free-tier gets 403, confirm
  device isolation, confirm persistence across a fresh store instance) --
  all passing. This was v1 scope: no HCI integration, no cross-device
  search -- see `ac_store.py`'s docstring.
- **Still genuinely open:** no trained `imu_weights.pt` exists (needs real
  IMU training data -- a data-acquisition question, not an engineering
  one); the 5 non-IMU encoder wrappers are structurally correct but
  unverified against real torch/torchvision/torchaudio/sentence-transformers
  installs.
- **Not yet done:** an actual multi-platform release build (linux
  x86_64/arm64, macOS x86_64/arm64, Windows) -- everything above was run on
  this one Linux x86_64 sandbox. `build_manylinux.sh` exists but is
  untested here (no Docker in this sandbox); treat it as a first draft to
  validate before the first real release.
- `accumulator.py`'s periodic `/finalize` call has no resolver passthrough
  yet -- noted inline, finalization currently happens server-side on its
  own schedule.

**Build pipeline files (`build_scripts/`):**

- `verify_ip_protection.py` -- automates spec Step 2 (`--inplace`) and the
  full IP protection checklist table (`--wheel <path>`). Wire into CI as a
  hard gate; exits non-zero on any failure.
- `package_release.py` -- spec Steps 3: copies the tree to `--dest`, strips
  `.py` sources for compiled targets and all `.c`/`.pyx` intermediates.
  Never touches the working tree.
- `build_manylinux.sh` -- spec's manylinux Docker build (Step 4-5 + platform
  tagging via `auditwheel repair`). Not run in this sandbox -- no Docker
  available here.

## Quick start (once published)

```python
from vaasx import Bootstrap

brain = Bootstrap(api_key="...", device_id="my_device")
brain.connect("https://your-data-stream.com/events")
hits = brain.query("your query here", k=5)
```

## Building a release wheel

```bash
pip install --break-system-packages Cython setuptools wheel numpy build
# Add the 'ac' extra's deps too (torch, torchvision, torchaudio,
# sentence-transformers) if you want ac/encoders/imu.py's runtime import
# check to actually pass rather than WARN -- not required for compilation.

# 1. Compile all 8 targets to .so
python3 setup_cython.py build_ext --inplace

# 2. Verify no source is recoverable from the compiled binaries
python3 build_scripts/verify_ip_protection.py --inplace

# 3. Strip .py sources for compiled targets into a release tree
python3 build_scripts/package_release.py --dest dist_release

# 4. Build the wheel from the stripped tree
cd dist_release && python3 -m build --wheel --no-isolation && cd ..

# 5. Retag (local/dev only -- see build_manylinux.sh for the real release path)
python3 -m wheel tags --python-tag cp310 --abi-tag cp310 \
    --platform-tag linux_x86_64 dist_release/dist/vaas_x-*-py3-none-any.whl

# 6. Final IP protection checklist against the actual wheel contents
python3 build_scripts/verify_ip_protection.py --wheel "dist_release/dist/vaas_x-*.whl"
```

For a real PyPI release, build inside the manylinux Docker image
(`build_manylinux.sh`) once per target platform, which handles platform
tagging correctly via `auditwheel repair` -- the hand-retag in step 5 above
is only for quick local sanity builds on this machine.
