Repository navigation
Architecture and Model Variants
PAIOS (page.puzzak.paios) pairs a Flutter / Dart main application (AIEngine) with a pure-Kotlin native Android Digital Assistant (MeshOverlayActivity) so both full-screen multi-chat sessions and instant system-level assistant overlays share the same on-device Gemini Nano engine and user state.
-
Central State Machine (
lib/engine.dart):AIEngine(ChangeNotifier) orchestrates initialization, model variant selection, tool-calling turns, streaming updates, auto-continuation, andAppLifecycleState.resumedsynchronization with dismissed overlay chats. -
Hive Storage (
'paios_storage'):MigrationService(lib/storage/migration.dart) migrates legacySharedPreferencespayloads into a unified'paios_storage'Hive box backing dedicated repositories:-
ChatRepository(conversations, pinned/archived state, per-turn"author"and epoch-ms"time",thoughtProcess) -
PromptRepository(bundled & custom Markdown personas, refreshed from assets for the default persona) -
ResourceRepository(in-app resources & sanitized links) -
IntroSlideRepository(onboarding SWR slides) -
AppConfig(model channel/preference, token/temperature settings, extension toggles)
-
-
Dart <-> Kotlin Bridge (
SharedPreferences/FlutterSharedPreferences): Bridges lightweight cross-runtime state between Flutter and native Kotlin services (such aspending_assistant_chatsqueued byMeshOverlayActivityandflutter.mesh_extension_<moduleId>_enabledflags read byInternalToolsHelper).
-
MeshOverlayActivity+PaiosVoiceInteractionService: Runs natively in Kotlin inside a dedicatedpage.puzzak.paios.overlaytask (launchMode="singleTask", excluded from recents) without spinning up a Flutter engine, enabling instant overlay launches over any foreground app. -
FlutterLocalAiPlugin.kt&PaiosModelHelper.kt: Shared Kotlin inference helpers powering both the FlutterMethodChannel/EventChannelbridge and the native overlay.
PAIOS enumerates all 4 (releaseStage, preference) combinations natively via PaiosModelHelper.probeAllComboStatuses (ComboStatuses -> "modelVariants"):
| Channel | Internal Model IDs | Availability | Capabilities |
|---|---|---|---|
| Stable |
gemini-nano-v3 (stable/full, stable/fast) |
Production | Everyday chat, System Instructions, Function Calling, Multimodality |
| Preview / Beta |
gemini-nano-v4-full, gemini-nano-v4-fast
|
Preview / Beta | Expanded context (up to 8,192 tokens), native Thinking Mode (thoughtProcess), native <ctrl42>call:... & FunctionCall tool calling |
-
Unified Model Selector & Decoupled Downloader:
showModelSelectorDialog(from the"nano-v3"/"nano-v4"header chip or Settings -> Model) lets users switch channels and download variants in parallel (FlutterLocalAiPlugin.variantDownloadJobsConcurrentHashMap) independently of the active client, displaying realDownloadStarted.bytesToDownloadtotals,B/s–GB/sspeed, and remaining bytes. -
Active-Inference Lock:
FlutterLocalAiPlugin.activeGenerationCount(AtomicInteger) andAIEngine.isLoadingblock concurrent model switches while inference is running and defer closing the previousGenerativeModeluntil the active stream completes.
Upgraded in v1.8.9 (com.google.mlkit:genai-prompt:1.0.0-beta5), PAIOS leverages the latest native Prompt API capabilities:
-
model.warmup(): Pre-loads NPU/TPU weights when idle (triggerWarmupIfIdleand interactive overlay startup) to cut first-token latency. -
PromptPrefixCaching: AttachesPromptPrefix(cacheSystemInstruction = true, cacheTools = true)when caching is supported, reusing KV-cache state across turns. -
Native Multi-Image
Content(ImagePart): Sends multiple attached images as nativeImagePartentries inContentrather than stitching bitmaps vertically onto a single composite canvas. -
Token Telemetry (
countTokens/getTokenLimit): Queries exact token counts and model token limits natively. -
Sampling Controls: Supports
topKandseedalongsidetemperatureandmaxOutputTokens. -
Non-Deprecated Feature Discovery: Uses
model.getAvailableFeatures()instead of deprecated capability probes. -
Streaming
FunctionCallCapture: Captures nativeFunctionCallobjects (onNewFunctionCall/candidate.functionCalls) alongside<ctrl42>fallback parsing. -
ML Kit
beta5zzaxl.zzrgetBaseModelName()Quirk: Insidegenai-prompt:1.0.0-beta5,zzaxl.zzrmapsPREF_FULLfeature IDs{645, 646, 651, 653}insidegetBaseModelName()to"nano-v4-fast"/"gemini-nano-v4-fast". PAIOS separatesinternalModelNamefrom display labels so variant badges and selectors remain accurate even whengetBaseModelName()reportsnano-v4-fastforPREF_FULL.
Because Gemini Nano enforces tight hardware limits (such as a 4,096-token window on v1–v3, 256-token/step output bounds, and a 25-second NPU execution watchdog), PAIOS implements a shared Dart + Kotlin hardening pipeline:
-
Token-Budgeted Sliding Window:
Prompt(defaultMaxHistoryChars = 2800, dynamichistoryBudget&schemaBudget) prunes older history before hittingREQUEST_TOO_LARGE (12), with an automatic compact retry (600history /400system chars) if overflow still occurs. -
Tail-Bounded
[CONTINUATION]Prompts: Multi-round continuations never re-stuff full persona/history intoSystemInstruction; insteadPrompt.generateContinuationandPaiosModelHelper.buildOverlayContinuationPromptemit a compact[CONTINUATION]directive (<= 240-char persona,<= 220-char question,~450-char trailing slice viaboundTailAtBoundary).- Caps:
maxProseContinuations = 3(soft/hard stops at1600/2400chars),maxContinuations = 10for open code blocks, andMAX_OVERLAY_CONTINUATIONS = 6in the overlay.
- Caps:
-
Tool-Call Repair & Fallback:
-
Truncated JSON Repair:
PaiosModelHelper.extractToolCallJson+sanitizeJsonLikeStringperform string/brace-aware closure repair (recovering truncated drafts like109-charinspect_screendrafts missing"}}), normalize"name"/"method"and"parameters"/"args"/"arguments", and cap tool drafts atMAX_TOOL_JSON_CONTINUATIONS = 2. -
Nano v4
<ctrl42>& Thought-Trapped Tool Promotion: Parses<ctrl\d+>call:tool{...}<ctrl\d+>tokens (andapp:toolprefixes), scrubs raw control tags from thought bubbles (stripControlToolTags), and promotes tool calls trapped inthoughtwhentextis empty. -
Tool-Free Fallback: Invalid or unparseable Turn-1 tool JSON triggers an automatic tool-free fallback (
includeTools: false/runToolFreeFallbackAttempt) instead of leaking raw JSON into chat history.
-
Truncated JSON Repair:
-
Deduplication & Cutoff Rescue:
-
Overlap & Stutter Guard:
240-char suffix-prefix overlap stitching (stitchContinuation/stitchOverlayContinuation), ellipsis seam stripping (...,…),28-char mid-word backoff (splitTrailingPartialWord), and>= 24-char earlier-sentence loop stripping (detectAndTrimStutterLoop/hasContinuationStutter). -
Mid-Clause
STOPRescue & Final Trimming: Detects dangling prepositions, determiners, contractions ("I can'"), transitive-ingparticiples ("and ensuring"), and negations ("and do not") for a bounded1-shotSTOPrescue (maxStopCutoffContinuations = 1,maxNullReasonContinuations = 3), and runstrimTrailingIncompleteSentenceat all final commit paths (including unpunctuated multi-sentence cutoff tails).
-
Overlap & Stutter Guard:
-
Lifecycle & Performance Hardening (
v1.8.9):-
AIEngine.cancelGeneration()bumps_streamGenerationId++and clears turn flags/buffers so stale callbacks become no-ops. -
FlutterLocalAiPlugin.dispose()cancelscoroutineScopeandvariantDownloadJobs;FileAccessPluginoffloads SAFDocumentFileI/O toDispatchers.IO; bitmaps are explicitly.recycle()d after inference; andv1.8.9removed the per-token500msstreaming delay, per-turnsyncRemoteDocs()HTTP calls, and backgroundChatsPagefull-history JSON re-parsing.
-
Related Pages: Supported Devices & AICore Error Taxonomy · 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