Skip to content

Commit 10f440a

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
authored
docs+proofs: reintroduce architecture/build/install/usage + proofs scaffolding (follow-up to #102) (#120)
## Summary Restores the 8 docs+proofs files that PR #81 added but #102 had to drop while reverting #81's wrong-direction license change. Per #102's PR body: > "Reverting #81 also dropped 4 new docs + proofs/ scaffolding... These can be reintroduced cleanly in a separate, license-free PR after this lands." This is that PR. ## Files (all NEW, no edits to existing content) | File | Purpose | |---|---| | `docs/architecture.adoc` | LSM/ESN/bridge architecture (149 lines) | | `docs/build.adoc` | Build instructions (72 lines) | | `docs/installation.adoc` | Installation guide pointed-to by README (113 lines) | | `docs/usage.adoc` | Usage docs (41 lines) | | `proofs/README.adoc` | Proof corpus index | | `proofs/dafny/README.adoc` | Dafny/F* proofs subdirectory | | `proofs/lean/README.adoc` | Lean/Coq proofs subdirectory | | `proofs/tla/Lifecycle.tla` | TLA+ lifecycle obligation 2.1 (issue #84) | ## Licensing All 8 files carry \`SPDX-License-Identifier: MPL-2.0\` per the canonical estate license policy (neurophone = sole-owner repo). #81 had originally added these with PMPL stamps; this PR adds them with the correct MPL-2.0 SPDX from the start. ## Verification \`\`\`sh grep -r 'SPDX-License-Identifier' docs/architecture.adoc docs/build.adoc \\ docs/installation.adoc docs/usage.adoc proofs/ \`\`\` All 8 files report \`MPL-2.0\`. ## Test plan - [ ] CI green (no new SPDX violations) - [ ] Files render correctly (asciidoctor + TLA+ syntax) - [ ] \`docs/installation.adoc\` link from README.adoc resolves ## Why draft License sweep aftermath; owner sight on docs reintroduction before flipping to ready. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 5245a66 commit 10f440a

8 files changed

Lines changed: 516 additions & 0 deletions

File tree

‎docs/architecture.adoc‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
// SPDX-License-Identifier: MPL-2.0
2+
= NeuroPhone Architecture
3+
:toc:
4+
5+
== Architecture
6+
7+
=== Rust Crates (8 modules)
8+
9+
|===
10+
| Crate | Purpose | Key Features
11+
12+
| `lsm`
13+
| Liquid State Machine
14+
| 512 spiking neurons, 3D grid, 1kHz processing
15+
16+
| `esn`
17+
| Echo State Network
18+
| 300-neuron reservoir, ridge regression
19+
20+
| `bridge`
21+
| Neural ↔ Symbolic
22+
| State encoding, context generation
23+
24+
| `sensors`
25+
| Phone Sensors
26+
| Accel, gyro, magnetometer, light, proximity
27+
28+
| `llm`
29+
| Local Inference
30+
| Llama 3.2 via llama.cpp, streaming
31+
32+
| `claude-client`
33+
| Cloud Fallback
34+
| Claude API, retry logic, context injection
35+
36+
| `neurophone-core`
37+
| Orchestration
38+
| Main coordinator, query routing
39+
40+
| `neurophone-android`
41+
| Android JNI
42+
| Kotlin ↔ Rust bridge
43+
|===
44+
45+
=== Android App (Kotlin)
46+
47+
```
48+
android/
49+
├── app/src/main/
50+
│ ├── java/ai/neurophone/
51+
│ │ ├── MainActivity.kt
52+
│ │ ├── NativeLib.kt # JNI interface
53+
│ │ ├── SensorManager.kt # Sensor collection
54+
│ │ └── ui/ # Compose UI
55+
│ └── res/
56+
└── build.gradle.kts
57+
```
58+
59+
== Components
60+
61+
=== LSM (Liquid State Machine)
62+
63+
Spiking neural network for temporal sensor processing:
64+
65+
* 3D grid: 8×8×8 = 512 Leaky Integrate-and-Fire neurons
66+
* Distance-dependent connectivity
67+
* Excitatory/inhibitory balance
68+
* Real-time spike processing at 1kHz
69+
70+
=== ESN (Echo State Network)
71+
72+
Reservoir for state prediction:
73+
74+
* 300-neuron reservoir
75+
* Spectral radius: 0.95
76+
* Leaky integrator dynamics
77+
* Ridge regression output
78+
79+
=== Sensors
80+
81+
Phone sensor integration:
82+
83+
* Accelerometer, gyroscope, magnetometer
84+
* Light and proximity sensors
85+
* IIR filtering (low-pass, high-pass)
86+
* Feature extraction at 50Hz
87+
88+
=== Bridge
89+
90+
Neural ↔ Symbolic translation:
91+
92+
* Integrates LSM + ESN states
93+
* Generates natural language context for LLMs
94+
* Temporal pattern detection
95+
* Salience and urgency computation
96+
97+
=== Local LLM
98+
99+
On-device language model:
100+
101+
* Llama 3.2 1B/3B via llama.cpp
102+
* Optimized for Dimensity 8350
103+
* Q4_K_M quantization (~700MB)
104+
* Neural context injection
105+
106+
=== Claude Client
107+
108+
Cloud fallback for complex queries:
109+
110+
* Messages API integration
111+
* Automatic retry with exponential backoff
112+
* Hybrid inference (local/cloud decision)
113+
* Neural state context injection
114+
115+
== Performance
116+
117+
Optimized for Oppo Reno 13 (Dimensity 8350):
118+
119+
|===
120+
| Component | Latency | Notes
121+
122+
| Sensor processing
123+
| <1ms
124+
| 50Hz loop
125+
126+
| LSM step
127+
| <2ms
128+
| 512 neurons
129+
130+
| ESN step
131+
| <1ms
132+
| 300 neurons
133+
134+
| Bridge integration
135+
| <1ms
136+
| Per step
137+
138+
| Local LLM (1B)
139+
| 50-100ms/token
140+
| Q4 quantized
141+
142+
| Claude API
143+
| 500-2000ms
144+
| Network dependent
145+
|===
146+
147+
== Topology
148+
149+
See link:../TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard.

‎docs/build.adoc‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
// SPDX-License-Identifier: MPL-2.0
2+
= Building NeuroPhone
3+
:toc:
4+
5+
== Getting Started
6+
7+
=== Prerequisites
8+
9+
* Rust 1.75+
10+
* Android NDK 26+
11+
* Android Studio (for app development)
12+
* Oppo Reno 13 or Android 8.0+ device
13+
14+
=== Build
15+
16+
```bash
17+
# Clone
18+
git clone https://github.com/hyperpolymath/neurophone
19+
cd neurophone
20+
21+
# Setup
22+
./scripts/setup.sh
23+
24+
# Build native libraries for Android
25+
./scripts/build-android.sh
26+
27+
# Open android/ in Android Studio
28+
```
29+
30+
=== Download LLM Model
31+
32+
```bash
33+
# Download Llama 3.2 1B Instruct (Q4_K_M, ~700MB)
34+
# From: https://huggingface.co/bartowski/Llama-3.2-1B-Instruct-GGUF
35+
36+
# Push to device
37+
adb push llama-3.2-1b-instruct-q4_k_m.gguf /data/local/tmp/
38+
```
39+
40+
=== Configure
41+
42+
Set Claude API key (for cloud fallback):
43+
44+
```bash
45+
export ANTHROPIC_API_KEY="your-api-key"
46+
```
47+
48+
Or in `config/default.toml`:
49+
50+
```toml
51+
[claude]
52+
api_key = "your-api-key"
53+
model = "claude-sonnet-4-20250514"
54+
55+
[llm]
56+
model_path = "/data/local/tmp/llama-3.2-1b-q4_k_m.gguf"
57+
n_threads = 4
58+
context_size = 2048
59+
```
60+
61+
== Development
62+
63+
```bash
64+
# Run tests
65+
cargo test
66+
67+
# Build for Android
68+
./scripts/build-android.sh
69+
70+
# Generate docs
71+
cargo doc --open
72+
```

‎docs/installation.adoc‎

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

‎docs/usage.adoc‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
// SPDX-License-Identifier: MPL-2.0
2+
= NeuroPhone Usage
3+
:toc:
4+
5+
== Usage
6+
7+
=== Kotlin API
8+
9+
```kotlin
10+
// Initialize
11+
NativeLib.init()
12+
NativeLib.start()
13+
14+
// Query with neural context
15+
val response = NativeLib.query("What's my current activity?", preferLocal = true)
16+
17+
// Get raw neural state
18+
val context = NativeLib.getNeuralContext()
19+
// Returns: [NEURAL_STATE] Description: ... [/NEURAL_STATE]
20+
21+
// Cleanup
22+
NativeLib.stop()
23+
```
24+
25+
=== Rust API
26+
27+
```rust
28+
use neurophone_core::{NeuroSymbolicSystem, SystemConfig};
29+
30+
let mut system = NeuroSymbolicSystem::with_config(config)?;
31+
let _rx = system.start().await?;
32+
33+
// Send sensor data
34+
system.send_sensor(reading).await?;
35+
36+
// Query
37+
let response = system.query("What's happening?", true).await?;
38+
39+
// Get neural context
40+
let context = system.get_neural_context().await;
41+
```

0 commit comments

Comments
 (0)