# Contributing to UMoX

Thank you for considering UMoX. This is a small, early research prototype, and
careful help is more valuable than flashy numbers. You do not need specialized
hardware to review the scheduler math, documentation, evaluation protocol, or
failure handling.

Please be kind, assume good faith, and make room for beginners. Reproduction
failures and slower results are welcome when they are documented honestly.

## Helpful contributions

- Reproduce the current GPU control and adaptive-head result.
- Test a different Snapdragon device, driver, or ONNX Runtime version.
- Add paired GPU/UMoX quality evaluations.
- Review the uncertainty/refinement rule mathematically.
- Reduce persistent QNN session count or cold-start time.
- Measure energy, memory bandwidth, thermals, and long-context behavior.
- Propose coarse CPU/GPU/NPU partitions with a falsifiable cost model.
- Improve recovery, telemetry, packaging, and documentation.

## Before opening a result

Include:

1. exact hardware, OS, driver, runtime, and power/OEM performance modes;
2. model and artifact identifiers plus hashes where licensing allows;
3. prompt or dataset version, context length, sampling, seed, and chat template;
4. warmup, repetition count, test order, and all raw timing samples;
5. numerical/task-quality evidence and declared acceptance thresholds;
6. provider logs demonstrating whether operations spilled or fell back; and
7. a clear label: `accepted`, `rejected`, `inconclusive`, or `exploratory`.

Please compare against a matched same-session baseline. Avoid comparing your
best UMoX run with an old or differently powered control.

## Proposed workflow

1. Start a Hugging Face Discussion describing the hypothesis and acceptance
   gate. This helps prevent duplicated downloads or long compile attempts.
2. Keep the experiment small and reversible.
3. Upload sanitized raw evidence and a human-readable summary.
4. Open a Pull Request that changes one idea at a time.
5. Invite another contributor to audit the result before changing a public claim.

## Claim hygiene

- Advertised accelerator TOPS is not a token/s prediction.
- Component latency is not end-to-end token throughput.
- An upstream model score is not a score measured under UMoX.
- Unified memory does not imply coherent zero-copy operation.
- Faster output is not accepted if the declared quality gate fails.
- A scaffold change can alter an agent benchmark independently of the runtime.

We will gladly celebrate a real improvement. We will also gladly document why
a clever idea did not work—both outcomes move UMoX forward.

## Safety and privacy

Never include secrets, private prompts, customer data, surveillance/access-
control details, proprietary SDK files, or production system identifiers.
Genetec/MCP experiments must use a read-only replay or isolated sandbox. See
[SECURITY.md](SECURITY.md).

## Conduct

Technical disagreement is healthy; personal attacks are not. Critique claims
with evidence, acknowledge uncertainty, and help others reproduce your work.
If someone is new to NPU development, offer a path forward rather than dismissing
their question. UMoX will improve fastest as a welcoming, rigorous project.