Skip to content

Commit 5e8e356

Browse files
rwilliamspbg-opsrwilliamspbg-ops
committed
docs: add onboarding and license guides
1 parent fb28221 commit 5e8e356

4 files changed

Lines changed: 348 additions & 2 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Contributing to Mohawk Inference Engine
2+
3+
Thanks for helping improve Mohawk Inference Engine. This repository is intentionally small, but it has a few conventions that keep the prototype and release docs easy to follow.
4+
5+
## Before You Start
6+
7+
- Read [README.md](README.md), [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), and [docs/PQC_INTEGRATION.md](docs/PQC_INTEGRATION.md).
8+
- If you are touching secure transport or session logic, run the focused prototype tests before opening a PR.
9+
- Keep changes small and scoped. This repo favors incremental updates over broad rewrites.
10+
11+
## Development Setup
12+
13+
```bash
14+
python -m pip install -r prototype/requirements.txt
15+
```
16+
17+
Optional secure-local setup:
18+
19+
```bash
20+
export OQS_INSTALL_PATH=/usr/local
21+
```
22+
23+
## Code Style
24+
25+
- Prefer readable, explicit Python over clever abstractions.
26+
- Preserve the current module structure under `prototype/`.
27+
- Keep doc updates in sync with code changes.
28+
- Avoid adding extra dependencies unless they clearly reduce complexity or improve correctness.
29+
30+
## Testing Expectations
31+
32+
Run the relevant tests for the slice you changed:
33+
34+
```bash
35+
python -m pytest -q prototype/test_oqs_hybrid.py prototype/test_secure_hybrid_integration.py prototype/test_concurrency_smoke.py prototype/test_secure_run.py -q -rA
36+
```
37+
38+
If you modify the load harness or telemetry path, also run the broader prototype smoke flow with the secure worker.
39+
40+
## Pull Requests
41+
42+
- Use a short imperative commit message.
43+
- Include a note about any environment variables or native libraries required to reproduce the change.
44+
- Mention any tests you ran in the PR description.
45+
46+
## Release Hygiene
47+
48+
- Do not commit generated artifacts, virtual environments, or local caches.
49+
- If you update the secure flow or binding assumptions, document the runtime requirement in [docs/PQC_INTEGRATION.md](docs/PQC_INTEGRATION.md).

‎LICENSE‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
Apache License
2+
Version 2.0, January 2004
3+
4+
http://www.apache.org/licenses/
5+
6+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7+
8+
1. Definitions.
9+
10+
"License" shall mean the terms and conditions for use, reproduction,
11+
and distribution as defined by Sections 1 through 9 of this document.
12+
13+
"Licensor" shall mean the copyright owner or entity authorized by
14+
the copyright owner that is granting the License.
15+
16+
"Legal Entity" shall mean the union of the acting entity and all
17+
other entities that control, are controlled by, or are under common
18+
control with that entity. For the purposes of this definition,
19+
"control" means (i) the power, direct or indirect, to cause the
20+
direction or management of such entity, whether by contract or
21+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
22+
outstanding shares, or (iii) beneficial ownership of such entity.
23+
24+
"You" (or "Your") shall mean an individual or Legal Entity
25+
exercising permissions granted by this License.
26+
27+
"Source" form shall mean the preferred form for making modifications,
28+
including but not limited to software source code, documentation
29+
source, and configuration files.
30+
31+
"Object" form shall mean any form resulting from mechanical
32+
transformation or translation of a Source form, including but
33+
not limited to compiled object code, generated documentation,
34+
and conversions to other media types.
35+
36+
"Work" shall mean the work of authorship, whether in Source or
37+
Object form, made available under the License, as indicated by a
38+
copyright notice that is included in or attached to the work
39+
(an example is provided in the Appendix below).
40+
41+
"Derivative Works" shall mean any work, whether in Source or Object
42+
form, that is based on (or derived from) the Work and for which the
43+
editorial revisions, annotations, elaborations, or other modifications
44+
represent, as a whole, an original work of authorship. For the purposes
45+
of this License, Derivative Works shall not include works that remain
46+
separable from, or merely link (or bind by name) to the interfaces of,
47+
the Work and Derivative Works thereof.
48+
49+
"Contribution" shall mean any work of authorship, including the
50+
original version of the Work and any modifications or additions to
51+
that Work or Derivative Works thereof, that is intentionally submitted
52+
to Licensor for inclusion in the Work by the copyright owner or by an
53+
individual or Legal Entity authorized to submit on behalf of the
54+
copyright owner. For the purposes of this definition, "submitted"
55+
means any form of electronic, verbal, or written communication sent
56+
to the Licensor or its representatives, including but not limited to
57+
communication on electronic mailing lists, source code control systems,
58+
and issue tracking systems that are managed by, or on behalf of, the
59+
Licensor for the purpose of discussing and improving the Work, but
60+
excluding communication that is conspicuously marked or otherwise
61+
designated in writing by the copyright owner as "Not a Contribution."
62+
63+
"Contributor" shall mean Licensor and any individual or Legal Entity
64+
on behalf of whom a Contribution has been received by Licensor and
65+
subsequently incorporated within the Work.
66+
67+
2. Grant of Copyright License. Subject to the terms and conditions of
68+
this License, each Contributor hereby grants to You a perpetual,
69+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70+
copyright license to reproduce, prepare Derivative Works of,
71+
publicly display, publicly perform, sublicense, and distribute the
72+
Work and such Derivative Works in Source or Object form.
73+
74+
3. Grant of Patent License. Subject to the terms and conditions of
75+
this License, each Contributor hereby grants to You a perpetual,
76+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77+
(except as stated in this section) patent license to make, have made,
78+
use, offer to sell, sell, import, and otherwise transfer the Work,
79+
where such license applies only to those patent claims licensable by
80+
such Contributor that are necessarily infringed by their Contribution(s)
81+
alone or by combination of their Contribution(s) with the Work to which
82+
such Contribution(s) was submitted. If You institute patent litigation
83+
against any entity (including a cross-claim or counterclaim in a
84+
lawsuit) alleging that the Work or a Contribution incorporated within
85+
the Work constitutes direct or contributory patent infringement, then
86+
any patent licenses granted to You under this License for that Work
87+
shall terminate as of the date such litigation is filed.
88+
89+
4. Redistribution. You may reproduce and distribute copies of the
90+
Work or Derivative Works thereof in any medium, with or without
91+
modifications, and in Source or Object form, provided that You meet
92+
the following conditions:
93+
94+
(a) You must give any other recipients of the Work or Derivative Works
95+
a copy of this License; and
96+
97+
(b) You must cause any modified files to carry prominent notices
98+
stating that You changed the files; and
99+
100+
(c) You must retain, in the Source form of any Derivative Works that
101+
You distribute, all copyright, patent, trademark, and attribution
102+
notices from the Source form of the Work, excluding those notices
103+
that do not pertain to any part of the Derivative Works; and
104+
105+
(d) If the Work includes a "NOTICE" text file as part of its
106+
distribution, then any Derivative Works that You distribute must
107+
include a readable copy of the attribution notices contained
108+
within such NOTICE file, excluding those notices that do not
109+
pertain to any part of the Derivative Works, in at least one of
110+
the following places: within a NOTICE text file distributed as
111+
part of the Derivative Works; within the Source form or
112+
documentation, if provided along with the Derivative Works; or,
113+
within a display generated by the Derivative Works, if and
114+
wherever such third-party notices normally appear. The contents of
115+
the NOTICE file are for informational purposes only and do not
116+
modify the License. You may add Your own attribution notices within
117+
Derivative Works that You distribute, alongside or as an addendum
118+
to the NOTICE text from the Work, provided that such additional
119+
attribution notices cannot be construed as modifying the License.
120+
121+
You may add Your own copyright statement to Your modifications and
122+
may provide additional or different license terms and conditions for
123+
use, reproduction, or distribution of Your modifications, or for any
124+
such Derivative Works as a whole, provided Your use, reproduction, and
125+
distribution of the Work otherwise complies with the conditions stated
126+
in this License.
127+
128+
5. Submission of Contributions. Unless You explicitly state otherwise,
129+
any Contribution intentionally submitted for inclusion in the Work by
130+
You to the Licensor shall be under the terms and conditions of this
131+
License, without any additional terms or conditions. Notwithstanding
132+
the above, nothing herein shall supersede or modify the terms of any
133+
separate license agreement you may have executed with Licensor
134+
regarding such Contributions.
135+
136+
6. Trademarks. This License does not grant permission to use the trade
137+
names, trademarks, service marks, or product names of the Licensor,
138+
except as required for reasonable and customary use in describing the
139+
origin of the Work and reproducing the content of the NOTICE file.
140+
141+
7. Disclaimer of Warranty. Unless required by applicable law or
142+
agreed to in writing, Licensor provides the Work (and each
143+
Contributor provides its Contributions) on an "AS IS" BASIS,
144+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
145+
implied, including, without limitation, any warranties or conditions
146+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
147+
PARTICULAR PURPOSE. You are solely responsible for determining the
148+
appropriateness of using or redistributing the Work and assume any
149+
risks associated with Your exercise of permissions under this License.
150+
151+
8. Limitation of Liability. In no event and under no legal theory,
152+
whether in tort (including negligence), contract, or otherwise,
153+
unless required by applicable law (such as deliberate and grossly
154+
negligent acts) or agreed to in writing, shall any Contributor be
155+
liable to You for damages, including any direct, indirect, special,
156+
incidental, or consequential damages of any character arising as a
157+
result of this License or out of the use or inability to use the
158+
Work (including but not limited to damages for loss of goodwill,
159+
work stoppage, computer failure or malfunction, or any and all other
160+
commercial damages or losses), even if such Contributor has been
161+
advised of the possibility of such damages.
162+
163+
9. Accepting Warranty or Additional Liability. While redistributing
164+
the Work or Derivative Works thereof, You may choose to offer, and
165+
charge a fee for, acceptance of support, warranty, indemnity, or
166+
other liability obligations and/or rights consistent with this
167+
License. However, in accepting such obligations, You may act only on
168+
Your own behalf and on Your sole responsibility, not on behalf of any
169+
other Contributor, and only if You agree to indemnify, defend, and
170+
hold each Contributor harmless for any liability incurred by, or
171+
claims asserted against, such Contributor by reason of your accepting
172+
any such warranty or additional liability.
173+
174+
END OF TERMS AND CONDITIONS
175+
176+
APPENDIX: How to apply the Apache License to your work.
177+
178+
To apply the Apache License to your work, attach the following
179+
boilerplate notice, with the fields enclosed by brackets "[]"
180+
replaced with your own identifying information. (Don't include the
181+
brackets!) The text should be enclosed in the appropriate comment
182+
syntax for the file format. We also recommend that a file or class
183+
name and description of purpose be included on the same "printed
184+
page" as the copyright notice for easier identification within
185+
third-party archives.
186+
187+
Copyright 2026 Mohawk Inference Engine contributors
188+
189+
Licensed under the Apache License, Version 2.0 (the "License");
190+
you may not use this file except in compliance with the License.
191+
You may obtain a copy of the License at
192+
193+
http://www.apache.org/licenses/LICENSE-2.0
194+
195+
Unless required by applicable law or agreed to in writing, software
196+
distributed under the License is distributed on an "AS IS" BASIS,
197+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
198+
See the License for the specific language governing permissions and
199+
limitations under the License.

‎README.md‎

Lines changed: 50 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,50 @@
1-
# Mohawk-Inference-Engine
2-
build a much faster, leaner, and more secure local inference and management engine than a standard LM Studio setup
1+
# Mohawk Inference Engine
2+
3+
Mohawk Inference Engine is a local inference and management stack for splitting model execution across multiple devices while keeping transport and session handling secure. The project focuses on three capabilities that are hard to get in one place in lightweight desktop tools: multi-device layer splitting, PQC-secured edge offload, and high-concurrency session management.
4+
5+
## What This Repo Contains
6+
7+
- A toy layer-splitting runtime that partitions a model into slices and runs them across workers.
8+
- A secure controller/worker path with X25519 plus optional liboqs-backed hybrid KEM support.
9+
- A session manager and load harness for concurrent encrypted inference runs.
10+
- Telemetry and timing hooks for preload and execute paths.
11+
12+
## Quick Start
13+
14+
```bash
15+
python -m pip install -r prototype/requirements.txt
16+
python prototype/run_demo.py
17+
```
18+
19+
For the secure prototype, start the secure worker in a separate terminal:
20+
21+
```bash
22+
python prototype/worker_secure.py --port 8003
23+
```
24+
25+
If you have a local liboqs install, set:
26+
27+
```bash
28+
export OQS_INSTALL_PATH=/usr/local
29+
```
30+
31+
## Recommended Reading
32+
33+
- [Project scope](docs/SCOPE.md)
34+
- [Architecture spec](docs/ARCHITECTURE.md)
35+
- [PQC integration notes](docs/PQC_INTEGRATION.md)
36+
- [Getting started guide](docs/GETTING_STARTED.md)
37+
- [Contributor guide](CONTRIBUTING.md)
38+
39+
## Testing
40+
41+
Run the focused prototype checks with:
42+
43+
```bash
44+
python -m pytest -q prototype/test_oqs_hybrid.py prototype/test_secure_hybrid_integration.py prototype/test_concurrency_smoke.py prototype/test_secure_run.py -q -rA
45+
```
46+
47+
## Release Notes
48+
49+
- Release `v0.1.0` includes the liboqs devcontainer, secure prototype path, telemetry, and the scaling harness.
50+
- The repository is licensed under Apache-2.0. See [LICENSE](LICENSE).

‎docs/GETTING_STARTED.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Getting Started
2+
3+
This guide covers the shortest path from a fresh clone to running the prototype locally.
4+
5+
## Prerequisites
6+
7+
- Python 3.12 or newer
8+
- `pip`
9+
- Optional: a native liboqs install if you want the hybrid PQC path to activate
10+
11+
## Install Dependencies
12+
13+
```bash
14+
python -m pip install -r prototype/requirements.txt
15+
```
16+
17+
If you have a local liboqs install, export:
18+
19+
```bash
20+
export OQS_INSTALL_PATH=/usr/local
21+
```
22+
23+
## Run the Demo
24+
25+
```bash
26+
python prototype/run_demo.py
27+
```
28+
29+
That script compares a single-node baseline against the distributed toy model path.
30+
31+
## Run the Secure Worker
32+
33+
```bash
34+
python prototype/worker_secure.py --port 8003
35+
```
36+
37+
The secure path uses the hybrid X25519 + OQS adapter when the binding is present.
38+
39+
## Run Tests
40+
41+
```bash
42+
python -m pytest -q prototype/test_oqs_hybrid.py prototype/test_secure_hybrid_integration.py prototype/test_concurrency_smoke.py prototype/test_secure_run.py -q -rA
43+
```
44+
45+
## Useful Docs
46+
47+
- [README](../README.md)
48+
- [Architecture](ARCHITECTURE.md)
49+
- [PQC integration](PQC_INTEGRATION.md)
50+
- [Contributing](../CONTRIBUTING.md)

0 commit comments

Comments
 (0)