Repository navigation
FAQ
Everything you need to know about PAIOS (Personal AI Operating System, page.puzzak.paios) as of v1.8.9+26112001: 100% offline on-device Gemini Nano inference, Android AICore troubleshooting (ErrorCode 601/606/-101), v3 vs v4 model variants, System Assistant Overlay & on-demand inspect_screen, M3x Mesh extensions, localization (zh-Hans), custom .md prompts, and Nightly builds.
- Privacy, Offline Architecture & Storage
- Supported Devices, AICore Errors & Bootloaders
-
Gemini Nano Variants (
v3vsv4) & Response Behavior -
System Assistant Overlay,
inspect_screen& Vision- 9. How does the System Assistant Overlay work?
- 10. How does on-demand
inspect_screenwork, and when is screen context used or ignored? - 11. How do I turn off passive screen capture or text reading?
- 12. How do Camera and Gallery attachments work, and why does attaching a photo replace the screenshot?
- 13. Does the Assistant Overlay remember my attached photo on follow-up questions?
- M3x Mesh Ecosystem & Extensions
-
Localization (
zh-Hans) & Custom Markdown Prompts - Nightly Builds, Legacy Versions & Support
PAIOS runs inference 100% locally on your phone's NPU/TPU via Android AICore (com.google.android.aicore) and Google's ML Kit GenAI Prompt API (com.google.mlkit:genai-prompt:1.0.0-beta5). No prompt text, chat history, camera photo, gallery image, or screen context is ever sent to cloud LLM APIs, and PAIOS requires zero API keys.
The only optional network activity in PAIOS is strictly non-conversational or opt-in:
-
Opt-in online extension modules (Wikipedia
paios.wikipedia, DuckDuckGo Instant Answerpaios.search, and Open-Meteo Weatherpaios.weather) are disabled by default in Settings -> Extensions. -
Translation & Documentation SWR sync: Fetches updated translation JSONs or Google
.md.txtdocumentation pages when refreshed (with bundled offline fallbacks and captive-portal protection). - Optional anonymous analytics/crash reporting, if enabled.
Because PAIOS is designed around a strict on-device sandbox:
- No arbitrary web browsing: Gemini Nano executes locally inside AICore and cannot open URLs or fetch live pages on its own.
- No shell execution: PAIOS cannot spawn terminal commands or access arbitrary OS internals.
-
Explicit M3x Mesh tools only: Actions and live data run strictly through registered M3x Mesh tools (for example, PTK
page.puzzak.ptkexposes TCP ping and Statuspage diagnostics, while opt-in built-in modules handle Wikipedia/DuckDuckGo/Open-Meteo). If a requested tool is missing or disabled, PAIOS refuses honestly rather than fabricating output.
Conversations, personas, preferences, and cached resources are stored locally inside the app sandbox using Hive ('paios_storage') and Android SharedPreferences (page.puzzak.paios).
Sessions started in the native Kotlin System Assistant Overlay (MeshOverlayActivity) are automatically queued into flutter.pending_assistant_chats on dismissal and drained into your main Hive chat history both on cold boot and immediately on foreground resume (AppLifecycleState.resumed in v1.8.9). See the Security Policy for local security guidance.
PAIOS is a client for Android AICore / ML Kit GenAI (Gemini Nano), so Google controls hardware and firmware eligibility. Check the Supported Devices & AICore Error Taxonomy guide for the full matrix, and verify these prerequisites:
-
Supported Hardware: Pixel 8/9/10 (note: Pixel
a-series such as 9a/10a are restricted by Google unless Google enables them), Samsung Galaxy S24/Z6/S25/S26+, or supported Snapdragon 8 Gen 3/Elite / Dimensity 9300+ flagships. -
Android 14+ (
minSdk = 34) with Google Play Services and Android AICore (com.google.android.aicore) installed and updated from Google Play. - 8 GB+ RAM (12 GB+ recommended for multimodal tasks) and 2.5–3.5 GB free internal storage for model weights.
- Pixel 8 / 8a Developer Options: On some devices (especially Pixel 8/8a), open Settings -> System -> Developer options -> AICore Settings and enable Enable on-device Gemini Nano and Enable Aicore Persistent Mode.
Google AICore enforces device attestation and Play Integrity before provisioning or running Gemini Nano:
-
Unlocked bootloader: AICore intentionally disables on-device Gemini Nano model downloads and Prompt API access on devices with an unlocked bootloader (usually surfacing
ErrorCode 606 - FEATURE_NOT_FOUND). - Custom ROMs / Non-GMS builds: ROMs without certified Google Play Services and OEM AICore feature provisioning cannot bind to or download Gemini Nano weights.
PAIOS cannot bypass Google's AICore hardware/bootloader attestation checks.
| Error Code | Constant | Cause | How to Fix |
|---|---|---|---|
601 |
BINDING_FAILURE (4-CONNECTION_ERROR) |
Failed to bind to the Android AICore system service (common right after phone setup or an AICore update). | Update Android AICore on Google Play, reboot your device, or reinstall PAIOS. |
606 |
FEATURE_NOT_FOUND (3-PREPARATION_ERROR) |
AICore stub is present, but Google Play / OEM firmware has not provisioned the Gemini Nano feature catalog yet (also appears on unlocked bootloaders and some Xiaomi/Poco firmwares). | Since v1.8.8, PAIOS shows a dedicated OEM provisioning diagnostic card in Setup and Model Settings. Keep internet connected, update AICore + Play System Update, and reboot. |
-101 |
AICORE_INCOMPATIBLE |
AICore APK is missing or too old for ML Kit GenAI 1.0.0-beta5 (note: runtime hardware busy is ErrorCode.BUSY = 9, which PAIOS auto-retries). |
Install or update Android AICore (com.google.android.aicore) from the Play Store. |
For the full table (9, 12, 4/11, 27, 30, 8/16, 1-DOWNLOAD_ERROR), see Supported Devices & AICore Error Taxonomy.
PAIOS lets you switch channels and download supported variants in parallel via the header "nano-v3"/"nano-v4" chip or Settings -> Model (see Architecture & Model Variants):
| Aspect | Gemini Nano v3 (Stable) |
Gemini Nano v4 (Preview / Beta) |
|---|---|---|
| Internal Variants |
gemini-nano-v3 (stable/full, stable/fast) |
gemini-nano-v4-full, gemini-nano-v4-fast
|
| Context Window |
4,096 tokens |
Up to 8,192 tokens |
| Thinking Mode | Not supported | Native thoughtProcess collapsible reasoning blocks |
| Tool Calling | JSON / Prompt-guided tool calls | Native <ctrl42>call:... & FunctionCall streaming capture |
| Acceleration & Stability | Production NPU/TPU acceleration on supported devices | Preview/Beta in AICore; on some devices v4 may run experimentally (or CPU-bound) depending on AICore beta rollout |
Since v1.8.9, both variants benefit from ML Kit 1.0.0-beta5 model.warmup(), PromptPrefix KV-caching, native multi-image ImagePart lists, and countTokens / getTokenLimit telemetry.
Gemini Nano is a compact local model tuned for mobile NPU memory, latency, and battery—not a massive server-side model:
-
256-token output ceiling & 25s watchdog: Google AI Core caps each single generation call at 1–256 tokens (
Settings -> Model parameters -> Max response tokens). PAIOS automatically bridges cutoffs with tail-bounded[CONTINUATION]turns (maxProseContinuations = 3, up to10for open code blocks), overlap/stutter loop deduplication, andtrimTrailingIncompleteSentencecleanup. -
Safety filters: Profanity or sensitive content can trigger AICore safety errors (
4/11). PAIOS automatically applies[POLICY FALLBACK RETRY]sanitization or surfaces a clean error state instead of stalling. -
Context budget: Long chat histories are pruned dynamically via PAIOS's token-budgeted sliding window (
historyBudget) to avoidREQUEST_TOO_LARGE (12).
When you set PAIOS as Android's Default digital assistant app, PaiosVoiceInteractionService launches MeshOverlayActivity—a native Kotlin Material 3 Expressive bottom sheet running in a separate task (page.puzzak.paios.overlay) without initializing the Flutter engine. This gives near-instant launch speed over any app, full tool-calling & Markdown support, Thinking Mode display, and a Open in Full App handoff button. See System Assistant Overlay & Screen Inspection.
Earlier assistant builds injected screenshots on every turn, causing unrelated questions to misread background apps and burn vision tokens. Since v1.8.5–v1.8.9, PAIOS uses lazy on-demand inspect_screen:
-
Silent 3-turn buffer (
SCREEN_CONTEXT_TTL_TURNS = 3): When summoned over another app (skipped automatically when opened inside PAIOS itself), the overlay trims system bars/cutouts and holds the screenshot + filteredAssistStructureprivately for up to 3 turns. -
Never force-injected: The screenshot is not attached to general prompts. Instead, Gemini Nano only sees the
inspect_screentool definition. -
Used only when asked: If you ask about your screen ("Summarize this page", "Explain this error"), Gemini Nano invokes
inspect_screen. - Auto-discarded: Unrelated prompts, M3x Mesh tool queries, or photo attachments ignore the screen buffer, and after 3 turns (or on image attachment/reset) the screenshot bitmap is recycled and dropped.
To disable screen capture and UI hierarchy access system-wide:
- Open Android Settings -> Apps -> Default apps -> Digital assistant app.
- Tap the gear icon (or Digital assistant app details, depending on your OEM).
- Toggle off Use screenshot and/or Use text from screen (
AssistStructure).
You can still attach images manually anytime via Gallery or Camera inside the overlay.
12. How do Camera and Gallery attachments work, and why does attaching a photo replace the screenshot?
-
Camera (
Take Photo): Uses Android'sACTION_IMAGE_CAPTUREwith a secureFileProvidercache URI, so PAIOS does not need the runtimeCAMERApermission. Captures are EXIF-orientation corrected and temporary cache files are cleaned up. -
Gallery & Multi-Image (
beta5): Inv1.8.9, multiple attached images are passed natively asImagePartentries (instead of vertical bitmap stitching), with optional768pxfast NPU downsampling and explicit.recycle()memory cleanup. - Replacing passive screenshots: Attaching a photo from Camera or Gallery immediately drops any buffered background screenshot and clears prior visual memory so 100% of Gemini Nano's vision resolution budget is dedicated to your photo.
Yes. Within an active Assistant Overlay session, PAIOS summarizes the visual turn in the background after the initial reply so text-only follow-up questions retain context about your photo without re-encoding raw bitmaps on every turn. Resetting/closing the overlay, removing the attachment, or attaching a new image clears that visual memory.
14. What is M3x Mesh, and which built-in and companion extensions exist (PTK, Alerts, Speech Services)?
M3x Mesh (packages/m3x_mesh) is PAIOS's on-device Android IPC protocol (ContentProvider authorities matching *.mesh, 16s execution timeout, up to 6 chained tool turns per prompt) with zero cloud relays. See M3x Mesh Ecosystem & Extensions.
-
Built-in Offline Modules (Enabled by default):
-
paios.docs(query_aicore_documentation/about_paios): Offline/SWR search over all 23 bundled ML Kit GenAI & PAIOS self-knowledge docs. -
paios.device(get_battery_status): Live battery level & charging state. - Overlay
inspect_screen: Lazy 3-turn screen +AssistStructureinspection.
-
-
Built-in Online Modules (Opt-in, Disabled by default):
-
paios.wikipedia(wikipedia_summary,wikipedia_details),paios.search(duckduckgo_search), andpaios.weather(weather_forecastvia Open-Meteo).
-
-
Compatible & Planned Companion Apps:
-
PTK (Puzzak's ToolKit) (
page.puzzak.ptk): Server telemetry, Statuspage incident monitoring, and TCP ping diagnostics. -
Alerts (
page.puzzak.alerts): Ukraine air raid alerts and map status. -
Speech Services (
TinyASR& TTS) (page.puzzak.speech, planned): A dedicated standalone companion APK delivering offline RustTinyASR+Silero VADspeech-to-text and neural TTS overandroid.speech.RecognitionServiceandM3x Mesh—keeping heavy native ASR runtimes out ofpage.puzzak.paios.
-
PTK (Puzzak's ToolKit) (
Open Settings -> Extensions:
-
First-party Puzzak extensions (
page.puzzak.*,com.puzzak.*) are enabled by default. - Third-party extensions are disabled by default until you toggle them individually or enable "Allow all new extensions".
- Tap any extension to open the schema inspector and inspect its package ID, live status, exposed tools, and parameter schemas. Disabled extensions are excluded from both system prompts and tool execution.
PAIOS supports 6 languages across both the Flutter app and native Kotlin Assistant Overlay:
-
en(English),uk(Українська),zh(繁體中文 / Traditional Chinese),zh-Hans(简体中文 / Simplified Chinese),de(Deutsch), andtr(Türkçe).
Since v1.8.8 and completed with 100% key parity (469 keys) in v1.8.9 (forward-ported from PR #36), both Dictionary.resolveSupportedLocaleCode (Dart) and MeshOverlayActivity.resolveOverlayLanguage (Kotlin) perform script- and region-aware locale detection:
- Tags containing
Hans,CN,SG, orMYresolve automatically tozh-Hans. - Tags containing
Hant,TW,HK,MO(or genericzh) resolve tozh.
PAIOS also runs a mojibake self-healing check (Dictionary.hasMojibake / repairMojibake) so corrupted cache or remote entries can never overwrite clean bundled translations. See Localization & Prompts.
Open Settings -> Prompts to browse, clone, edit, import, or export [USER INSTRUCTIONS] personas in Markdown:
-
Slim default prompt:
system_default.mdis intentionally kept to 2 sentences and refreshed from bundled assets on startup, freeing token headroom while delegating PAIOS self-knowledge toquery_aicore_documentation. -
Android SAF UTF-8 Sync: Link any folder via Storage Access Framework (
pickPromptsFolder) to immediately import.mdfiles and export custom personas (FileAccessService.exportMduses explicitutf8.encodeand preserves Unicode letters/digits in filenames vianameToFilename).
- Join the Tester Google Group (required for Play Store Nightly access): PAIOS Nightlies Google Group.
-
Opt in to Google Play Testing: Open Google Play Testing (
page.puzzak.paios) using the same Google account. - Or sideload from GitHub: Signed APKs and nightly prereleases are published on Puzzaks/PAIOS Releases.
Versions earlier than 1.1.2 used the legacy page.puzzak.geminilocal package ID and older AICore bindings. PAIOS now uses page.puzzak.paios (and automatically sanitizes legacy geminilocal links in cached resources). Install the current release from Google Play or GitHub Releases.
- Device Compatibility Thread: Check or share hardware reports in Issue #15 — Compatibility thread and Supported Devices & AICore Error Taxonomy.
- Bug Reports & Feature Requests: Follow the Support Guide or open an issue on Puzzaks/PAIOS Issues with your device model, Android version, PAIOS version, and bootloader / AICore status.
Related Pages: Home · Supported Devices & AICore Error Taxonomy · Architecture & Model Variants · System Assistant Overlay & Screen Inspection · M3x Mesh Ecosystem & Extensions
PAIOS (page.puzzak.paios) — Synced with v1.8.9+26112001 | GitHub Repository · Nightly Google Group · Play Testing Opt-In · Report an Issue