Swarm Oracle

Swarm Oracle is an Android-first Flutter app that combines a local AI-swarm oracle gadget UX with private, on-device context intelligence.

Current Product Shape

The app is first a small OK-message gadget:

• shake to generate a short, reassuring oracle message
• use the small local LLM path; no cloud oracle and no fabricated standard oracle text
• copy/send the OK message from the app UI
• keep private oracle inputs on the phone
• run the separate Nomad transition worker in the background as an edge node

The Nomad worker is intentionally secondary in the user experience. It reads public Syndiode contracts, emits public edge-node proof signals, and never receives private oracle text or raw sensor axes.

Download / Install

The repository can produce an Android APK through GitHub Actions:

1. Open the Android APK workflow.
2. Run it manually or use the latest successful main build.
3. Download the uploaded handyoracle-apk artifact.
4. Install the APK on an Android phone.

For local builds:

flutter pub get
flutter build apk --release

Product Goal

Build a premium-feeling consumer app that:

• feels warm, playful, and emotionally uplifting
• gives self-empowering, actionable oracle guidance
• adapts to real-life context from opted-in device sources
• runs the oracle fully on-device while the separate Nomad edge worker talks only through public Syndiode contracts

Target State (Goldstandard)

• Context-aware oracle experience that users want to revisit daily
• Strong ritual loop (Today -> Shake -> Oracle -> History)
• On-device multimodal context pipeline (audio, video, usage, motion, location, device context)
• Transparent consent UX with one-time opt-in and editable source permissions
• Beautiful, mystical interface with polished micro-animations and delightful feedback

Current Architecture Highlights

• lib/features/ai/:
  • domain/context_vector.dart: fused context representation for downstream decision logic
  • domain/context_collector.dart: collector interface
  • domain/context_collection.dart: collection request + sample contracts
  • data/collectors/mock_collectors.dart: collector implementations (Phase A baseline)
  • data/context_sampling_policy.dart: sampling mode decision (idle, standard, intense)
  • data/on_device_context_pipeline.dart: fusion pipeline with source confidence output
• lib/features/oracle/:
  • domain/oracle_engine.dart: oracle interfaces and result models
  • data/local_oracle_engine.dart: local oracle generation logic

Phase A Status

Implemented:

• collector-based context pipeline foundation
• sampling policy
• context vector confidence scores
• oracle integration with context-driven output

Phase B Status

Implemented:

• LlmRunner abstraction for local text generation
• default local provider set to mistral_local (open-source aligned runtime contract)
• strict local oracle generation (invalid model output is surfaced instead of replaced)

Planned next:

• replace mock collectors with real Android data collectors
• connect mistral_local runner to native on-device inference bridge
• add optional llama_local runner behind the same interface
• optimize performance and battery budget for production devices

Phase C-D Runtime Bridge

Implemented runtime scaffold:

• Flutter MethodChannel bridge (handorakel/llm)
• Android runtime registry and provider resolution
• llama.cpp-targeted runtime placeholder (LlamaCppRuntime) mapped to mistral_local
• model asset staging directory: android/app/src/main/assets/models/

Next step for full native inference:

1. Add GGUF model file to assets or app-managed storage.
2. Wire llama.cpp JNI backend (CMake + native bridge is scaffolded).
3. Replace placeholder generation in LlamaCppRuntime.generate(...) and handorakel_llm.cpp with real token generation.
4. Return structured message + action.

App Store Packaging Note

The GitHub repository intentionally stays small and does not include GGUF model binaries. For a local-LLM build on your machine, put the model here:

android/app/src/main/assets/models/smollm2_135m_q4km.gguf

Without that file, the app still builds but shaking will report that no usable local model reading is available. With that file present locally, the native llama.cpp runtime can prepare it through prepareLocalModel.

Production Model Strategy (2-Tier)

• small (optional local asset): compact model for local-LLM builds without committing binaries
• pro (optional pack): larger model delivered separately after entitlement/subscription
• runtime scaffold exists in:
  • lib/features/ai/data/model_release_strategy.dart
  • lib/features/ai/data/local_model_bootstrapper.dart
• current behavior:
  • GitHub checkout contains only placeholders, not model binaries
  • small can be added locally for a model-backed build
  • pro is intentionally non-bundled and can be activated later via optional local pack flow

Pro-Pack Note

Pro remains reserved for local model packs. Optional cloud oracle paths are disabled for the app runtime.