Skip to content

Commit e157e51

Browse files
Jonathan D.A. Jewellclaude
Jonathan D.A. Jewell
and
claude
committed
feat: add AI-native installation experience
Add a "Just Say It" section to README with a TIP highlight box so users can install NeuroPhone by giving one sentence to any AI assistant. The AI reads docs/AI_INSTALLATION_GUIDE.adoc and handles everything -- prerequisites, build, config, model download, and verification. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent fcfd0c8 commit e157e51

3 files changed

Lines changed: 636 additions & 0 deletions

File tree

‎README.adoc‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,123 @@ image:https://img.shields.io/badge/Platform-Android-green[Platform]
1212
image:https://img.shields.io/badge/Device-Oppo%20Reno%2013-blue[Target Device]
1313
image:https://img.shields.io/badge/RSR-Bronze-cd7f32[RSR Compliance]
1414

15+
[TIP]
16+
====
17+
**AI-Assisted Install:** Just tell any AI: +
18+
`Set up NeuroPhone on my Android from https://github.com/hyperpolymath/neurophone` +
19+
It reads this repo, asks a few questions, and does everything. <<ai-install,Details below>>.
20+
====
21+
22+
[[ai-install]]
23+
== AI-Assisted Installation (Recommended)
24+
25+
=== Just Say It
26+
27+
**You don't need to read this README.** Just say this to any AI assistant:
28+
29+
[source,text]
30+
----
31+
Set up NeuroPhone on my Android from https://github.com/hyperpolymath/neurophone
32+
----
33+
34+
**That's it. You don't type commands, install packages, or configure anything.** The AI fetches this repo, reads the installation guide inside it, figures out your device, and does everything. You just answer a few questions and confirm the privacy notice.
35+
36+
The URL is the key -- it points the AI to this repo where `docs/AI_INSTALLATION_GUIDE.adoc` contains the complete step-by-step recipe. Any AI that can read a URL and run commands (or generate commands for you to paste) can do this.
37+
38+
The AI handles all of this automatically:
39+
40+
* Checking your device and storage
41+
* Installing Termux (if needed), Rust, Git, and dependencies
42+
* Cloning and building NeuroPhone for your specific hardware
43+
* Downloading the right LLM model for your device's RAM/storage
44+
* Creating your configuration with sensible defaults
45+
* Running the setup wizard
46+
* Giving you a working NeuroPhone
47+
48+
=== Other Ways to Say It
49+
50+
If your AI already knows about NeuroPhone (e.g. it can search the web), even shorter versions work:
51+
52+
* "Make my phone a NeuroPhone"
53+
* "Install NeuroPhone on my Android"
54+
* "Turn my Oppo Reno 13 into a NeuroPhone"
55+
56+
If it doesn't know the project, just include the URL:
57+
58+
* "Set up https://github.com/hyperpolymath/neurophone on my phone"
59+
* "I want neurosymbolic AI on my phone -- install from https://github.com/hyperpolymath/neurophone"
60+
61+
=== What You'll Be Asked
62+
63+
Your AI will ask you:
64+
65+
1. **What device?** (so it picks the right thread count and model size)
66+
2. **Privacy confirmation** -- what sensors are used and how data stays on-device
67+
3. **Cloud fallback?** (optional Claude API for complex queries -- default is local-only)
68+
69+
That's it. Everything else is automatic. No package managers, no build flags, no config files.
70+
71+
=== Privacy & Security Notice
72+
73+
[IMPORTANT]
74+
====
75+
**What NeuroPhone does:**
76+
77+
* Reads phone sensors (accelerometer, gyroscope, magnetometer, light, proximity)
78+
* Processes everything on-device using Rust neural networks + local Llama LLM
79+
* Stores neural states locally in `~/.local/share/neurophone/` (never uploaded)
80+
* Optionally uses Claude API for complex queries (you control this)
81+
82+
**What NeuroPhone does NOT do:**
83+
84+
* Upload sensor data to any server (unless you enable cloud fallback)
85+
* Track you or collect analytics
86+
* Access camera, microphone, contacts, or personal data
87+
88+
**You control everything:** cloud fallback toggle, all config in `~/.config/neurophone/`, uninstall anytime.
89+
====
90+
91+
=== After Install
92+
93+
Once your AI finishes setup, just use it:
94+
95+
[source,bash]
96+
----
97+
neurophone # Start NeuroPhone
98+
neurophone query "What am I doing right now?" # Ask a question
99+
neurophone status # Check system status
100+
----
101+
102+
=== Uninstall
103+
104+
Tell your AI: "Uninstall NeuroPhone from my phone"
105+
106+
=== Troubleshooting
107+
108+
Tell your AI what went wrong -- it can read the troubleshooting docs in this repo. Common issues:
109+
110+
[cols="1,3"]
111+
|===
112+
|Problem |Solution
113+
114+
|"Termux not found"
115+
|AI will guide you to install from F-Droid (NOT Google Play)
116+
117+
|Build takes too long
118+
|Normal for first build (5-10 min). AI adjusts thread count for your device.
119+
120+
|"Model download failed"
121+
|AI will try alternate download methods or suggest `adb push` from PC
122+
123+
|"LSM crashes"
124+
|Low RAM. AI will reduce model size or neuron count for your device.
125+
|===
126+
127+
[[manual-installation]]
128+
For manual installation without AI assistance, see the <<getting-started,Getting Started>> section below.
129+
130+
'''
131+
15132
== What This Is
16133

17134
**neurophone** is a complete *Android application* for neurosymbolic AI on mobile devices. It combines spiking neural networks with large language models for on-device intelligence.
@@ -197,6 +314,7 @@ Cloud fallback for complex queries:
197314
* Hybrid inference (local/cloud decision)
198315
* Neural state context injection
199316

317+
[[getting-started]]
200318
== Getting Started
201319

202320
=== Prerequisites
@@ -425,3 +543,8 @@ Palimpsest-MPL-1.0 License - See LICENSE file
425543
---
426544

427545
*Android Application • On-Device Neural Processing • Spiking Networks • Local LLM*
546+
547+
548+
== Architecture
549+
550+
See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard.

‎TOPOLOGY.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
<!-- SPDX-License-Identifier: PMPL-1.0-or-later -->
2+
<!-- TOPOLOGY.md — Project architecture map and completion dashboard -->
3+
<!-- Last updated: 2026-02-19 -->
4+
5+
# NeuroPhone — Project Topology
6+
7+
## System Architecture
8+
9+
```
10+
┌─────────────────────────────────────────┐
11+
│ ANDROID USER │
12+
│ (Compose UI / Oppo Reno 13) │
13+
└───────────────────┬─────────────────────┘
14+
│ JNI / Kotlin Bridge
15+
▼
16+
┌─────────────────────────────────────────┐
17+
│ NEUROPHONE CORE (RUST) │
18+
│ (Orchestration, Bridge, Routing) │
19+
└──────────┬───────────────────┬──────────┘
20+
│ │
21+
▼ ▼
22+
┌───────────────────────┐ ┌────────────────────────────────┐
23+
│ NEURAL ENGINE (ON-DEV)│ │ INFERENCE LAYER │
24+
│ - LSM (Spiking Resvr) │ │ - Local Llama 3.2 (llama.cpp) │
25+
│ - ESN (Echo Resvr) │ │ - Claude API (Fallback) │
26+
│ - Sensor Fusion │ │ - Bridge (State Encoding) │
27+
└──────────┬────────────┘ └──────────┬─────────────────────┘
28+
│ │
29+
└────────────┬─────────────┘
30+
▼
31+
┌─────────────────────────────────────────┐
32+
│ PHONE HARDWARE │
33+
│ ┌───────────┐ ┌───────────┐ ┌───────┐│
34+
│ │ Accel/Gyro│ │ NPU Accel │ │ Light/││
35+
│ │ (50Hz) │ │ (Dim8350) │ │ Prox ││
36+
│ └───────────┘ └───────────┘ └───────┘│
37+
└─────────────────────────────────────────┘
38+
39+
┌─────────────────────────────────────────┐
40+
│ REPO INFRASTRUCTURE │
41+
│ Justfile Automation .machine_readable/ │
42+
│ Rust / JNI / Kotlin RSR Bronze (Cert) │
43+
└─────────────────────────────────────────┘
44+
```
45+
46+
## Completion Dashboard
47+
48+
```
49+
COMPONENT STATUS NOTES
50+
───────────────────────────────── ────────────────── ─────────────────────────────────
51+
NEURAL ENGINE (RUST)
52+
LSM (Liquid State Machine) ██████████ 100% 512 LIF neurons active
53+
ESN (Echo State Network) ██████████ 100% 300-neuron reservoir stable
54+
Sensor Fusion (Accel/Gyro) ██████████ 100% 50Hz loop verified
55+
Bridge (Neural ↔ Symbolic) ██████████ 100% Context generation verified
56+
57+
INFERENCE & UI
58+
Local LLM (Llama 3.2) ████████░░ 80% Q4 quantization optimized
59+
Claude Client (Fallback) ██████████ 100% Retry logic stable
60+
Android App (Kotlin/Compose) ████████░░ 80% UI components stable
61+
JNI / Native Bridge ██████████ 100% Kotlin ↔ Rust verified
62+
63+
REPO INFRASTRUCTURE
64+
Justfile Automation ██████████ 100% Standard build/JNI tasks
65+
.machine_readable/ ██████████ 100% STATE tracking active
66+
Performance Benchmarks ██████████ 100% Neural steps < 3ms
67+
68+
─────────────────────────────────────────────────────────────────────────────
69+
OVERALL: █████████░ ~90% On-device AI stable
70+
```
71+
72+
## Key Dependencies
73+
74+
```
75+
Sensors ────────► LSM Reservoir ──────► Bridge Context ──────► Local LLM
76+
│ │ │ │
77+
▼ ▼ ▼ ▼
78+
Accel/Gyro ─────► ESN Predict ──────► Query Routing ──────► Claude API
79+
```
80+
81+
## Update Protocol
82+
83+
This file is maintained by both humans and AI agents. When updating:
84+
85+
1. **After completing a component**: Change its bar and percentage
86+
2. **After adding a component**: Add a new row in the appropriate section
87+
3. **After architectural changes**: Update the ASCII diagram
88+
4. **Date**: Update the `Last updated` comment at the top of this file
89+
90+
Progress bars use: `█` (filled) and `░` (empty), 10 characters wide.
91+
Percentages: 0%, 10%, 20%, ... 100% (in 10% increments).

0 commit comments

Comments
 (0)