Skip to content

Commit dee043c

Browse files
Jonathan D.A. Jewellclaude
Jonathan D.A. Jewell
and
claude
committed
fix: Restore original README content
The previous RSR standardization commit accidentally replaced the full README content with a minimal template. This restores the original project documentation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 69f6d51 commit dee043c

1 file changed

Lines changed: 263 additions & 53 deletions

File tree

‎README.adoc‎

Lines changed: 263 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,286 @@
1-
= heterogenous-mobile-computing
2-
Jonathan D.A. Jewell <jonathan.jewell@gmail.com>
3-
:toc: macro
4-
:icons: font
5-
:source-highlighter: rouge
6-
:experimental:
7-
:url-github: https://github.com/hyperpolymath/heterogenous-mobile-computing
8-
:url-gitlab: https://gitlab.com/hyperpolymath/heterogenous-mobile-computing
9-
:url-bitbucket: https://bitbucket.org/hyperpolymath/heterogenous-mobile-computing
10-
:url-codeberg: https://codeberg.org/hyperpolymath/heterogenous-mobile-computing
1+
= Mobile AI Orchestrator
112

12-
Cross-device mobile computation distribution
3+
[![RSR Compliance](https://img.shields.io/badge/RSR-Bronze-cd7f32)](https://rhodium-standard.org)
4+
[![License](https://img.shields.io/badge/license-MIT%20%2B%20Palimpsest--0.8-blue)](LICENSE.txt)
5+
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](.gitlab-ci.yml)
6+
[![Safety](https://img.shields.io/badge/unsafe-forbidden-success)](src/lib.rs)
137

14-
image:https://img.shields.io/badge/RSR-Certified-gold[RSR Certified]
15-
image:https://img.shields.io/badge/License-AGPL%20v3-blue[License]
8+
A hybrid AI orchestration system for constrained mobile platforms, combining on-device inference with intelligent routing to remote APIs.
169

17-
toc::[]
10+
== Features
1811

19-
== Overview
12+
🔒 *Safety-First*
13+
- Zero `unsafe` blocks
14+
- Type-safe by design (Rust ownership model)
15+
- Memory-safe (compile-time guarantees)
16+
- Formal rule-based safety layer
2017

21-
heterogenous-mobile-computing is part of the link:https://rhodium.sh[Rhodium Standard] (RSR) ecosystem.
18+
📱 *Mobile-Optimized*
19+
- Designed for 2-4GB RAM devices
20+
- Battery-aware processing
21+
- Optimized for ARM (NEON intrinsics)
22+
- Support for NPU/GPU acceleration (future)
2223

23-
Domain: *software-development*
24+
🌐 *Offline-First*
25+
- Core functionality works without internet
26+
- Network features optional (feature flag)
27+
- Graceful degradation
28+
- Local SLM inference (1-3B parameters)
2429

25-
== Installation
30+
🧠 *Intelligent Routing*
31+
- Automatic local vs. remote decisions
32+
- Context-aware processing
33+
- Project-specific state management
34+
- Conversation history tracking
2635

27-
[source,bash]
28-
----
29-
# Clone from GitHub (primary)
30-
git clone {url-github}
36+
🔐 *Privacy-Preserving*
37+
- Automatic detection of sensitive data
38+
- Configurable blocking rules
39+
- On-device processing by default
40+
- Explainable routing decisions
3141

32-
# Or from mirrors
33-
git clone {url-gitlab}
34-
git clone {url-codeberg}
35-
----
42+
== Quick Start
3643

37-
== RSR Stack
44+
=== Installation
3845

39-
This project follows RSR conventions:
46+
```bash
47+
= Clone the repository
48+
git clone https://github.com/Hyperpolymath/heterogenous-mobile-computing
49+
cd heterogenous-mobile-computing
4050

41-
* ✅ ReScript for frontend/logic
42-
* ✅ Deno for JS runtime
43-
* ✅ WASM for performance-critical code
44-
* ✅ Rust/OCaml/Haskell for systems/proofs
45-
* ✅ Guile/Scheme for configuration
46-
* ❌ No TypeScript
47-
* ❌ No Go
48-
* ❌ No npm
51+
= Build (offline-first by default)
52+
cargo build --release
4953

50-
== Mirrors
54+
= Run
55+
./target/release/mobile-ai --help
56+
```
5157

52-
[cols="1,2"]
53-
|===
54-
| Platform | URL
58+
=== Usage
5559

56-
| GitHub (primary) | {url-github}
57-
| GitLab | {url-gitlab}
58-
| Bitbucket | {url-bitbucket}
59-
| Codeberg | {url-codeberg}
60-
|===
60+
*Interactive mode:*
61+
```bash
62+
./target/release/mobile-ai --interactive
63+
```
6164

62-
== License
65+
*Single query:*
66+
```bash
67+
./target/release/mobile-ai "How do I iterate a HashMap in Rust?"
68+
```
69+
70+
*With project context:*
71+
```bash
72+
./target/release/mobile-ai --project oblibeny "Explain the type system"
73+
```
74+
75+
*Enable network features:*
76+
```bash
77+
cargo build --release --features network
78+
```
79+
80+
== Architecture
81+
82+
```
83+
Query → Expert System → Router → Context → Inference → Response
84+
(Safety) (Route) (History) (Local/API)
85+
```
86+
87+
See [claude.md](claude.md) for comprehensive architecture documentation.
88+
89+
=== Components
90+
91+
| Component | Purpose | Implementation |
92+
|-----------|---------|----------------|
93+
| *Expert System* | Rule-based safety | `src/expert.rs` |
94+
| *Router* | Local/remote routing | `src/router.rs` |
95+
| *Context Manager* | Conversation state | `src/context.rs` |
96+
| *Orchestrator* | Main coordinator | `src/orchestrator.rs` |
97+
98+
== Phase 1 MVP (Implemented)
99+
100+
✅ Expert system (rule-based safety)
101+
✅ Heuristic router (keyword-based routing)
102+
✅ Context manager (in-memory history)
103+
✅ Orchestrator (pipeline coordination)
104+
✅ CLI interface
105+
✅ Comprehensive tests (>90% coverage)
106+
107+
== Phase 2+ Features (Implemented)
108+
109+
✅ *Reservoir Computing* - Echo State Networks for temporal context compression
110+
✅ *Neural Routing* - Multi-Layer Perceptron for learned routing decisions
111+
✅ *Spiking Neural Networks* - Event-driven wake detection (ultra-low power)
112+
✅ *Benchmarking Suite* - Performance profiling with Criterion
113+
✅ *Example Applications* - Runnable demonstrations of all features
114+
115+
*Stats*: 69+ tests, 7,500+ lines of code, 10 modules
116+
117+
See [AUTONOMOUS_DEVELOPMENT_SUMMARY.md](AUTONOMOUS_DEVELOPMENT_SUMMARY.md) for details.
118+
119+
== Future Phases
120+
121+
*Phase 3: Integration & Training*
122+
- [ ] Integrate MLP with router (replace heuristics)
123+
- [ ] Replace bag-of-words with sentence-transformers
124+
- [ ] Train reservoir on real conversation data
125+
- [ ] Deploy SNN on DSP/NPU hardware
126+
127+
*Phase 4: Advanced Features*
128+
- [ ] Mixture of Experts (specialized models)
129+
- [ ] Bayesian decision engine
130+
- [ ] SQLite persistence
131+
- [ ] RAG system (document retrieval)
132+
- [ ] Knowledge graph (project relationships)
133+
- [ ] On-device fine-tuning
134+
- [ ] Reinforcement learning from user feedback
135+
136+
== Development
137+
138+
=== Prerequisites
139+
140+
- Rust 1.75+ (`rustup`)
141+
- Just (`cargo install just`)
142+
- Nix (optional, for reproducible builds)
143+
144+
=== Building
145+
146+
```bash
147+
= Standard build
148+
cargo build
149+
150+
= Release build (optimized)
151+
cargo build --release
152+
153+
= With network features
154+
cargo build --features network
155+
156+
= Using Nix (reproducible)
157+
nix build
158+
```
159+
160+
=== Testing
161+
162+
```bash
163+
= Run all tests
164+
cargo test
165+
166+
= Run with coverage
167+
cargo tarpaulin --out Html
168+
169+
= Benchmarks (future)
170+
cargo bench
63171

64-
Licensed under AGPL-3.0-or-later OR LicenseRef-Palimpsest-0.5.
172+
= RSR validation
173+
just validate
174+
```
65175

66-
See link:LICENSE[LICENSE] for details.
176+
=== Documentation
177+
178+
*Core Documentation:*
179+
- [claude.md](claude.md) - Comprehensive architecture (10,000+ words)
180+
- [AUTONOMOUS_DEVELOPMENT_SUMMARY.md](AUTONOMOUS_DEVELOPMENT_SUMMARY.md) - Development progress and features
181+
182+
*Usage Guides:*
183+
- [ADVANCED_FEATURES.md](ADVANCED_FEATURES.md) - Reservoir computing, MLP routing, SNN wake detection
184+
- [DEPLOYMENT.md](DEPLOYMENT.md) - Platform deployment (Android, iOS, Linux mobile)
185+
- [PERFORMANCE.md](PERFORMANCE.md) - Optimization techniques for constrained devices
186+
187+
*Examples:*
188+
```bash
189+
= Run basic usage example
190+
cargo run --example basic_usage
191+
192+
= Reservoir computing demo
193+
cargo run --example reservoir_demo
194+
195+
= MLP router demonstration
196+
cargo run --example mlp_router
197+
```
198+
199+
*API Documentation:*
200+
```bash
201+
= Generate API documentation
202+
cargo doc --open
203+
```
204+
205+
*Benchmarks:*
206+
```bash
207+
= Run performance benchmarks
208+
cargo bench
209+
```
210+
211+
== RSR Compliance
212+
213+
This project follows the *Rhodium Standard Repository* framework and achieves *Bronze-level* compliance:
214+
215+
✅ Type safety (Rust type system)
216+
✅ Memory safety (ownership model, zero `unsafe`)
217+
✅ Offline-first (network is optional)
218+
✅ Comprehensive documentation
219+
✅ Test coverage (>90%)
220+
✅ Build system (`justfile`, `flake.nix`)
221+
✅ CI/CD automation
222+
✅ Security policy (`SECURITY.md`)
223+
✅ Dual licensing (MIT + Palimpsest-0.8)
224+
✅ Community governance (TPCF Perimeter 3)
225+
226+
See [RSR Compliance Checklist](docs/compliance-checklist.md) for details.
67227

68228
== Contributing
69229

70-
See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc].
230+
Contributions are welcome! This project operates under the *Tri-Perimeter Contribution Framework (TPCF)*.
231+
232+
*Current Perimeter*: 3 (Community Sandbox - fully open)
233+
234+
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
235+
236+
== Security
237+
238+
For security issues, see [SECURITY.md](SECURITY.md) or contact:
239+
- Email: hyperpolymath@protonmail.com
240+
- Security contact: `.well-known/security.txt`
241+
242+
== License
243+
244+
Dual-licensed under:
245+
- [MIT License](LICENSE.txt)
246+
- [Palimpsest License v0.8](LICENSE.txt)
247+
248+
You may choose either license for your use.
249+
250+
== Citation
251+
252+
If you use this work in research, please cite:
253+
254+
```bibtex
255+
@software{mobile_ai_orchestrator_2025,
256+
author = {Jewell, Jonathan},
257+
title = {Mobile AI Orchestrator: Hybrid Architecture for Constrained Platforms},
258+
year = {2025},
259+
url = {https://github.com/Hyperpolymath/heterogenous-mobile-computing},
260+
note = {RSR Bronze-compliant, Phase 1 MVP}
261+
}
262+
```
263+
264+
== Related Projects
265+
266+
- *Echomesh*: Conversation context preservation across sessions
267+
- *Oblíbený*: Safety-critical programming language with formal verification
268+
- *UPM*: Universal Project Manager for multi-project workflows
269+
- *CADRE*: Distributed state management via CRDTs
270+
271+
== Contact
272+
273+
*Author*: Jonathan Jewell (Hyperpolymath)
274+
*Email*: jonathan.jewell@open.ac.uk
275+
*Matrix*: (see MAINTAINERS.md)
276+
277+
== Acknowledgments
278+
279+
- *llama.cpp* for ARM-optimized LLM inference
280+
- *Anthropic* for Claude API
281+
- *Rust community* for safety-first tooling
282+
- *RSR framework* for principled repository design
71283

72-
== Metadata
284+
---
73285

74-
* Domain: software-development
75-
* Framework: RSR (Rhodium Standard Repository)
76-
* Dublin Core: link:.well-known/dc.xml[.well-known/dc.xml]
286+
*Built with Rust 🦀 • RSR Bronze Compliant • Offline-First • Type-Safe • Memory-Safe*

0 commit comments

Comments
 (0)