From 1e451347550b879565c0dde9293d5220f174001f Mon Sep 17 00:00:00 2001 From: baketnk Date: Fri, 25 Sep 2026 00:02:53 -0400 Subject: [PATCH] docs: source-only v0.1, move licensing pointers to third-party.md Co-Authored-By: Claude Sonnet 5 --- README.md | 4 +- TODO.md | 22 ++++---- docs/build.md | 6 +- docs/design.md | 12 ++-- docs/install-design.md | 8 +-- docs/overlay.md | 3 +- docs/packaging.md | 6 +- docs/third-party.md | 124 +++++++++++------------------------------ 8 files changed, 61 insertions(+), 124 deletions(-) diff --git a/README.md b/README.md index f1abc9a..f98e519 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,11 @@ Voice typing on Steam Frame, with recognition on the headset rather than a desktop or cloud server. Hold a controller button to record, review the transcript, then deliberately type it into the focused app. -Standalone MIT-licensed OpenVR overlay; no Steam store AppID or sudo. First v0.1 release is in progress. +Standalone OpenVR overlay; no Steam store AppID or sudo. First v0.1 release is in progress. ## Requirements -- Steam Frame with usable SteamVR/OpenVR and Gamescope for the **native** overlay and text delivery; Linux ARM64/glibc for the current installer payload format. Binary compatibility must be checked against each actual release artifact, not inferred from a developer build. +- Steam Frame with usable SteamVR/OpenVR and Gamescope for the **native** overlay and text delivery; Linux ARM64/glibc for the current installer payload format. - For voice recognition, separately provision a compatible **CPU Python runtime** (moondream 2.4.0 / Kestrel 0.8.0 and dependencies) and the pinned local Parakeet Redux model. Neither is bundled or installed with pip by the current native-only installer. There is no fallback ASR service. - A local source build needs CMake 3.20+, C++20 and explicit native libraries/SDK; the default hardware-free build needs only CMake and C++20. See [build requirements](docs/build.md). diff --git a/TODO.md b/TODO.md index 162a085..0f45db6 100644 --- a/TODO.md +++ b/TODO.md @@ -20,8 +20,7 @@ These checkboxes close the *source tasks*, not their empirical acceptance gates. C1's second backend is a fake executable fixture, **not** a second shipped ASR engine. C2's two-click model consent, SHA-bound installer handoff, and D1/D2's source/attended installer paths still need an audited native archive and an -installed clean-account/Frame exercise. A4 (exact artifact ABI/license closure), -D3 (publication and clean-account acceptance), P1 (real-target delivery), G1 +installed clean-account/Frame exercise. D3 (deferred binary archive), D4 (pip runtime), P1 (real-target delivery), G1 (browser), and H (live headset acceptance) remain open. The 0.1.202609250333 build is installed on Frame but not launched or accepted; local code/tests cannot establish a fixed delivery regression. @@ -57,11 +56,8 @@ accepted; local code/tests cannot establish a fixed delivery regression. case-insensitive grep for the former app name must remain empty. - [x] **A3. Commit the pending `AGENTS.md` rename** ("Frame Dictation" → "FrameYap"). (S) Done in baseline checkpoint `07c03ea`. -- [ ] **A4. Inventory the remaining runtime dependencies' licenses.** (M) - Upstream inventory and the FreeType FTL choice are documented, but the exact - staged ARM64 native/runtime binaries, transitive wheel/library notices, symbol - versions, loader and libc floor still require artifact-specific review before - publishing any prebuilt archive. +- [~] **A4. Runtime dependency pointers.** Repos and licenses are listed in + `docs/third-party.md`. No release audit is needed while v0.1 is source-only. - [x] **A5. Drop "POC" from the shipped surface.** (S) Public help, README, CMake and installer use the release name. `scripts/stage-native-poc.py` remains a deprecated compatibility wrapper for `scripts/stage-native.py`, not the @@ -121,10 +117,12 @@ accepted; local code/tests cannot establish a fixed delivery regression. `--print-plan` and `--json` support offline plans and structured outcomes; explicit model installs use installed pinned manifests. Tested with local fixtures only, not a released archive or an installed Frame UI handoff. -- [ ] **D3. Publish a first prebuilt ARM64 archive.** (M) Depends on A4. Follow the - release checklist in `docs/packaging.md`; do not advertise the one-command route - until the archive and its checksum are actually published and tested from a clean - account. +- [ ] **D3. Publish a prebuilt ARM64 archive.** (M) **Deferred.** v0.1 is + source-only. Revisit after source-build acceptance. +- [ ] **D4. Source install fetches the Python runtime with pip.** (M) Proposed, not + implemented: the installer creates a user-local venv and installs pinned + moondream/Kestrel with the CPU Torch wheel, on an explicit flag/confirmation. + The installer does not run pip today. ## E. Naming and versioning @@ -197,5 +195,5 @@ this app is future design and out of scope for v0.1. ## Open questions -Release artifact compatibility/license audit, publication, P1 real-target behavior +Source-install runtime provisioning (D4), P1 real-target behavior and live headset validation are unresolved gates, not implied by checked source tasks. diff --git a/docs/build.md b/docs/build.md index 64f230d..3a035da 100644 --- a/docs/build.md +++ b/docs/build.md @@ -63,7 +63,7 @@ initialize OpenVR, open a microphone, run ASR, download files or inject input. source-build mode, safe extraction, atomic current-version selection, retained rollback, runtime/install lock, foreign-file refusal and explicit unregister-before-uninstall acknowledgement. Source mode needs a local - compiler, SDK, libraries and license inputs; no runtime is pip-installed. + compiler, SDK and libraries; the installer does not yet pip-install a runtime. ## Deliberately not claimed @@ -98,7 +98,7 @@ file sizes/hashes and attribution live in `assets/backends/redux.json`; offline `scripts/model-status.py`) verify without inference or downloads. Manifest schema/verification are in `python/frameyap/model_files.py`. The local generic dispatcher resolves a manifest's in-release Python/executable launcher and -checks request/reply correlation; a new manifest still needs its own licensed, +checks request/reply correlation; a new manifest still needs its own compatible offline runtime and independent tests. Native `--run` flags `--backend ID`, `--model-store /absolute/store` and `--manifest-dir /absolute/manifests` are wired through the installed launcher as an explicit override, not a provisioning command. @@ -155,7 +155,7 @@ are edited and no runtime/session restart is performed. ## Deliberate launch -Explicit setup downloads only the pinned, openly licensed model: +Explicit setup downloads only the pinned model: ```sh python3 scripts/fetch-model.py --destination "$HOME/.local/share/frameyap-model" diff --git a/docs/design.md b/docs/design.md index 2f89893..6d41ab9 100644 --- a/docs/design.md +++ b/docs/design.md @@ -22,9 +22,7 @@ as explicit fallbacks. No desktop ASR server, network hop, LLM cleanup, scene renderer, avatar, desktop capture or root service is needed in the primary path. A first-class product goal is a **one-command GitHub install without a Steam store -AppID**. Package a prebuilt native executable; the current native-only archive requires a -separately supplied, compatible CPU runtime (no automatic pip install). A future -isolated runtime bundle requires its own license and compatibility audit. Use a normal +AppID**. v0.1 is source-only; a prebuilt archive is deferred. Use a normal OpenVR application key for registration, not Steamworks. Installation must remain user-local with opt-in autolaunch. See [installation design](install-design.md). @@ -114,9 +112,8 @@ not an application-rendered hand-pose animation loop. Do not promise a particula GPU cost until measured. A scene renderer's canvas/MSDF resources are not an OpenVR overlay backend and -are not imported here. The bundled Inconsolata TTF is under its retained OFL; the panel renderer is -original FrameYap code. Further source/asset reuse requires an explicit -license-reviewed extraction, never a runtime path into another project's checkout. +are not imported here. The panel renderer is original FrameYap code. Further source/asset reuse requires an +explicit extraction, never a runtime path into another project's checkout. ### Controller bindings @@ -283,7 +280,6 @@ processing timeout. No shell commands in IPC and no input authority in the worke no CUDA device/runtime assumption. Do not copy the desktop's x86 venv. - Weights are ~178 MB; Torch, kernels, temporary conversion and activations mean install size/RSS will be larger. Measure cold load, peak RSS and package size. - Keep runtime notices separate from model attribution. Microphone access does not mute VRChat or any other social-voice app. Shared PipeWire capture may let both hear the same utterance; the overlay must not claim @@ -329,7 +325,7 @@ runs additional offline tests). `FRAMEYAP_NATIVE=ON` explicitly selects OpenVR, SDL3, FreeType and Wayland client/generated protocol bindings. A separately authorized Python Redux environment is explicitly supplied at launch; the native-only installer neither bundles it nor pip-installs one. Pin revisions -and review licenses for each introduced dependency. No automatic fetch/install in configure or normal tests; no external checkout discovery. +for each introduced dependency. No automatic fetch/install in configure or normal tests; no external checkout discovery. Hardware-free tests should cover state transitions, bounded PCM/transcripts, worker framing/timeout/cancellation, duplicate/stale replies and focus generations diff --git a/docs/install-design.md b/docs/install-design.md index 0a31a41..741f7e8 100644 --- a/docs/install-design.md +++ b/docs/install-design.md @@ -7,7 +7,7 @@ The local installer has binary-archive and explicitly provisioned source-build modes, machine-readable plans/results and an attended TTY path. The current native-only artifact does not include or pip-install an ASR runtime; it is not a one-command voice-typing experience. See [packaging](packaging.md) for exact -flags and [third-party inventory](third-party.md) for open license/ABI audits. +flags and [third-party notes](third-party.md). `scripts/install-preflight.sh` is a read-only Linux ARM64/glibc/bootstrap check; `--source` adds toolchain/library checks. It does not download, install, register, @@ -40,7 +40,7 @@ already be available for registration; never start/restart it for installation. - **Source mode**: requires explicit local source, SDK, SDL/OpenVR libraries and their notices, CMake/C++20, native build dependencies and a version. It builds, stages, packages and continues through local installation; it does **not** - provision ASR packages or bypass producer license obligations. See + provision ASR packages. See [packaging](packaging.md) for all flags. - **Model**: only an explicit `--install-model --backend redux --yes` fetches pinned public files for the *already installed* backend. Inspect the read-only @@ -72,8 +72,8 @@ uninstalled backend does not authorize a download or supply its inference engine ## Gate before publishing the goal as fulfilled -Vet the **exact** release closure/licenses, ARM64 symbol versions/loader, -model attribution and compatible CPU Python environment; establish a tested +Vet the exact release closure, ARM64 symbol versions/loader +and a compatible CPU Python environment; establish a tested libc/runtime floor, then publish and authenticate a checksummed archive from a clean tag. On a clean supported Frame, install without a compiler/sudo/store ID, load Redux, type into a disposable owned target and validate rollback/uninstall, diff --git a/docs/overlay.md b/docs/overlay.md index 6d0a6c9..83d29d0 100644 --- a/docs/overlay.md +++ b/docs/overlay.md @@ -14,8 +14,7 @@ delivery. Launching the runtime is explicit, never part of a normal build or tes Explicit development dependencies: Valve OpenVR SDK v2.15.6, Vulkan headers/loader and FreeType 2. The native runtime needs a compatible system Vulkan driver. Configure/build must not fetch them. The default font is the bundled Inconsolata -Regular; its OFL and notices are included in -[third-party notes](third-party.md). `--font FILE` overrides the JSON selection. +Regular; see [third-party notes](third-party.md). `--font FILE` overrides the JSON selection. A missing selected font falls back to bundled Inconsolata, then a system DejaVu Sans face if present. Glyph coverage depends on the selected face; full CJK coverage is not claimed. diff --git a/docs/packaging.md b/docs/packaging.md index e11c355..fdf5221 100644 --- a/docs/packaging.md +++ b/docs/packaging.md @@ -33,11 +33,11 @@ For the current **external-runtime** package, `scripts/stage-native.py --help` documents explicit inputs. The old `scripts/stage-native-poc.py` is retained as a deprecated migration wrapper for that command, not the documented or shipped staging interface. The stage invokes `cmake --install` on an existing native -build, copies SDL/OpenVR and an explicitly licensed font, and retains notices. It does +build, copies SDL/OpenVR and a font. It does not build, download, run the app, or copy an ASR runtime. The native app relies on Frame's system Vulkan loader/driver, Wayland, libxcb, FreeType, -libstdc++ and glibc. Audit the actual staged ARM64 binaries' `NEEDED`, -`GLIBC_*`/`GLIBCXX_*` symbol versions, ELF interpreter and notices; then test +libstdc++ and glibc. Check the actual staged ARM64 binaries' `NEEDED`, +`GLIBC_*`/`GLIBCXX_*` symbol versions and ELF interpreter; then test on a clean target. No compatible libc floor is yet established. SDL/OpenVR resolve inside its own `lib/`, not a producer prefix. ARM64/glibc packaging is not a claim of compatibility with arbitrary Linux. diff --git a/docs/third-party.md b/docs/third-party.md index cc0c1f3..83c13a5 100644 --- a/docs/third-party.md +++ b/docs/third-party.md @@ -1,99 +1,43 @@ -# Dependency provenance and release boundary +# Third-party components -FrameYap's original code is [MIT licensed](../LICENSE). This does not relicense -models, fonts, protocols, native libraries or Python wheels. There is no dependency -on another application's checkout, assets or environment. **This is an upstream -license inventory, not an audit of a particular release binary. No public release -has been published.** Before shipping any archive, inspect the actual staged -files, their transitive dependencies and notices, and test on a clean supported -host. An external dependency does not make the current archive self-contained. +FrameYap's own code is under [LICENSE](../LICENSE). Everything below is fetched +from, or built against, its upstream project; each keeps its own license. This is +a pointer list, not a legal audit. No prebuilt archive is published: v0.1 is +source-only, and Python packages are fetched from PyPI on the user's machine. -## Included source/assets +## Included in this repository -- `protocol/gamescope-input-method.xml`: unmodified public Gamescope **3.16.28** - protocol, . - SHA-256 `da35711f5d1d750bc47931132a89bf34e6b96a72bafc054d34092d3f42358ec4`; - embedded permissive copyright/license notice preserved. Generated bindings are - build outputs; this private Gamescope extension needs rechecking after updates. -- `assets/fonts/Inconsolata-Regular.ttf`: unchanged Inconsolata Regular from - , copyright 2006 The Inconsolata - Project Authors, **SIL OFL 1.1**. SHA-256 - `e0267abf9d734e2b9f766f8cb7a496b552c57cdfeacfa0efdc5bfd21940ae145`. - `assets/fonts/OFL-Inconsolata.txt` retains the license. The font remains OFL, - not MIT, and is not sold by itself. An override font requires its own license. -- Frame controller bindings and the mint-to-blue CPU-rasterized panel were - authored here, using public profile names; no SteamVR driver artwork, MSDF - atlas, other app renderer or protected kernels were copied. - -Native staging uses `scripts/stage-native.py`: it includes the chosen font/license -and copied SDL3 and OpenVR notices in `licenses/THIRD_PARTY_NOTICES.txt`. -It does **not** bundle ASR. A4 is not closed for release: inspect the final -notice file, especially FreeType attribution, plus the selected native binary -and any bundled wheel/licenses before publishing. - -## Native build/runtime inventory - -| Component | Upstream license / evidence | Current packaging boundary / action | +| Item | Upstream | License | | --- | --- | --- | -| Valve OpenVR SDK 2.15.6 | BSD-3-Clause-style license, SDK LICENSE. | Staging copies its loader and explicitly supplied license; verify chosen binary and transitive closure. | -| SDL3 (device trial 3.2.16) | zlib, local `/usr/share/licenses/sdl3/LICENSE`. | Staging copies explicit library and license. Confirm exact build options/version and its transitive libraries. | -| Wayland client + scanner | MIT/Expat-style, local `/usr/share/licenses/wayland/COPYING`. | Client is linked from system; scanner is build-time. If shipped, include copyright/license and audit closure. | -| libxcb | MIT-style with name-use restriction, local `/usr/share/licenses/libxcb/COPYING`. | Xwayland focus guard uses client library at runtime; not bundled by current native stage. Audit exact binary. | -| FreeType 2 | **FreeType Project License (FTL) selected** for this project, local `/usr/share/licenses/freetype2/FTL.TXT`; upstream also offers a GPL option. | Current stage uses system library, not bundled. Credit FreeType Team for use; if distributing its binary, meet FTL binary disclaimer/notice obligations and review the precise build. Do not silently substitute GPL terms. | -| Vulkan loader, driver, system graphics dependencies | Loader/driver licenses vary by build and vendor. | Current stage depends on system Vulkan loader/driver; no GPU runtime is bundled. Audit the chosen loader if ever bundled. | -| Compiler runtime (`libstdc++`, `libgcc_s` when used) | GCC libraries: GPL with **GCC Runtime Library Exception** in upstream distribution; local `/usr/share/licenses/libstdc++/RUNTIME.LIBRARY.EXCEPTION` and `libgcc/...` are exception texts, not a full installed release audit. | Current stage relies on system runtime. Audit dynamic linkage, C++ ABI/`GLIBCXX_*` and exception coverage for *any* bundled compiler libraries; include corresponding complete notices/source obligations as applicable. | -| glibc/loader | GNU LGPL-2.1-or-later for core GNU C Library, with component-specific exceptions and other licenses to inspect. | Current stage relies on system libc/loader. Audit exact target binary symbol versions (`GLIBC_*`), ELF interpreter and its transitive closure; no minimum glibc/`GLIBCXX`/kernel floor is certified here. | +| `protocol/gamescope-input-method.xml` (Gamescope 3.16.28, unmodified, SHA-256 `da35711f5d1d750bc47931132a89bf34e6b96a72bafc054d34092d3f42358ec4`) | | Permissive notice embedded in the file | +| `assets/fonts/Inconsolata-Regular.ttf` (unchanged, SHA-256 `e0267abf9d734e2b9f766f8cb7a496b552c57cdfeacfa0efdc5bfd21940ae145`) | | SIL OFL 1.1, text in `assets/fonts/OFL-Inconsolata.txt` | -The historical Frame CPU trial used Torch **2.8.0+cpu** on a host with **glibc -2.39**. Those are *observed trial versions*, **not** minimum compatible versions -for FrameYap, Python wheels or a future released artifact. `ldd` on a developer -machine alone is not sufficient: inspect the staged ARM64 binaries with `readelf` -(`NEEDED`, ELF interpreter, symbol-version requirements), `ldd` on a trusted -clean target, actual bundled libraries and notices, and test the final archive on -a clean supported Frame. Check the chosen compiler, CPU instruction/kernel, -FreeType/Wayland/XCB/SDL/OpenVR/Vulkan ABI, Python/native wheels and licenses. -Do not invent a libc floor from a build host's version. +## Native build dependencies (system or user-supplied) -## Redux weights and inference runtime - -Model: , exact revision -`fad622f25f303105c20d70e201bcc477c88b620c`, model card **CC-BY-4.0**. -Attribution: Moondream/M87 Labs, Parakeet Redux, derived from NVIDIA Parakeet TDT -0.6B v3. No modifications to the supplied weights are made. Pinned model/config/ -tokenizer/card sizes and SHA-256 hashes, source and attribution are recorded in -`assets/backends/redux.json` (schema validated by `python/frameyap/model_files.py`), -not hardcoded in `model_files.py`. `fetch-model.py` fetches and retains the model -card alongside the weights on **explicit** request; neither build/tests nor a -normal app launch downloads them. `scripts/model-status.py` and the native -`--list-models` / `--check-model` interface inspect/hashes local files offline. -No weights are committed to Git. - -The current Redux worker uses separately provisioned `moondream` Python and its -`kestrel` / `kestrel-kernels` dependencies, not a bundled runtime. Kestrel's -upstream README says “Local inference is free and requires no API key” -(); finetuned-model inference needs an API -key and is **not** this path. The native-only installer **does not run pip**, -provision an interpreter, or make a native-only artifact able to transcribe on -its own. A person supplying a Python environment must review/authorize its -exact dependency closure. No bundled-ASR artifact is licensed/approved by this -inventory. - -| Python/native package | Upstream license inventory (not a wheel audit) | Release action | +| Component | Upstream | License | | --- | --- | --- | -| PyTorch / Torch CPU | PyTorch project: BSD-3-Clause; third-party components/wheels carry additional notices and dependencies. | No Torch wheels bundled. Pin CPU-only ARM64 wheel if building a distribution; audit its `LICENSE`, `NOTICE`, `third_party`/wheel contents and `NEEDED`/symbol versions. | -| NumPy | NumPy core: BSD-3-Clause; dependencies/embedded algorithms carry additional BSD, MIT, 0BSD, zlib, CC0 and other notices depending on wheel. Local `python-numpy` 2.5.3 package metadata (`/usr/lib/python3.14/site-packages/numpy-2.5.3.dist-info/METADATA`) declares `BSD-3-Clause AND 0BSD AND MIT AND Zlib AND CC0-1.0` with many `License-File` entries (different from the historical trial environment). | Not bundled. Keep *all* license files and inspect the exact target wheel, BLAS/OpenBLAS and runtime closure before redistribution. | -| Hugging Face `tokenizers` | Upstream `huggingface/tokenizers` is Apache-2.0; native/Rust crate dependencies need separate inventory. | Not bundled. Confirm actual installed wheel version, package LICENSE/NOTICE and transitive Rust/native code if ever distributed. | -| `moondream`, Kestrel/kernels/native, Python interpreter | Distinct packages with distinct license files and native transitive code; Kestrel local-use statement is not a blanket redistribution license. | None bundled. Exact versions, permissions, wheel notices, CPython build and native linkage require review before any runtime bundle. | +| OpenVR SDK 2.15.6 | | BSD-3-Clause-style | +| SDL3 | | zlib | +| Wayland (client, scanner) | | MIT | +| libxcb | | MIT-style | +| FreeType 2 | | FreeType Project License (FTL) or GPL-2.0; FrameYap uses FTL | +| Vulkan loader and drivers | System | Vary by vendor | -Development CPU trial *interfaces*, not package-floor promises: moondream -**2.4.0**, kestrel **0.8.0**, kernels **0.7.0**, native **0.1.8**, Python -**3.12.3**, Torch **2.8.0+cpu** on ARM64. An unqualified moondream install -initially resolved CUDA-enabled Torch and NVIDIA wheels; the owned trial venv -was corrected before measurement (`torch.version.cuda is None`). Do **not** -repeat unconstrained `pip install moondream` as a CPU setup recipe. +## Voice recognition runtime (fetched by the user's install) -A standalone CPython 3.12.14 ARM64 distribution was downloaded for packaging -research but **not bundled**: , -`cpython-3.12.14+20260901-aarch64-unknown-linux-gnu-install_only_stripped.tar.gz`, -SHA-256 `577b4bec0793ad1ff0cbff9adbd0df078eddde38a4c41bf5d83ad381a85ee39d`. -Its own licenses and native compatibility need review before any release. +| Component | Where | License | +| --- | --- | --- | +| Parakeet Redux weights, revision `fad622f25f303105c20d70e201bcc477c88b620c`, derived from NVIDIA Parakeet TDT 0.6B v3 by Moondream/M87 Labs; pinned sizes and hashes in `assets/backends/redux.json` | | CC-BY-4.0 | +| Kestrel, `kestrel-kernels` | | Local inference is free and needs no API key, per the Kestrel README. Finetuned-model inference needs an API key and is not used here. | +| `moondream` | PyPI | See the package | +| PyTorch (CPU build) | | BSD-3-Clause | +| NumPy | | BSD-3-Clause and bundled notices | +| Hugging Face `tokenizers` | | Apache-2.0 | + +Versions seen working on Frame (ARM64, Python 3.12.3): moondream 2.4.0, kestrel +0.8.0, kestrel-kernels 0.7.0, native 0.1.8, Torch 2.8.0+cpu. These are observed +versions, not tested minimums. An unconstrained `pip install moondream` resolved +CUDA-enabled Torch and NVIDIA wheels, so the CPU Torch wheel must be selected +explicitly. + +Model weights are downloaded only on an explicit request and are never committed.