🦉 Noctua

On-device AI wellness intelligence for Oura Ring — privacy-first Android SDK.

Noctua (the owl genus — nocturnal wisdom) is an open-source Kotlin toolkit that combines a complete, typed client for the Oura API v2 with an on-device AI layer that turns raw biometrics into explainable insights and a next-day readiness forecast — without your health data ever leaving the phone.

---

Screenshots

Captured from the example app running in demo mode on a Pixel 7 Pro emulator.

Why Noctua?

Most wearable companion apps ship your biometric history to a cloud LLM to generate "insights". Noctua takes the opposite stance:

Architecture

graph TD
    A[Oura Cloud API v2] -->|OAuth2 / PAT| B[noctua-core<br/>typed Kotlin client]
    B --> C[WellnessSnapshot<br/>readiness · sleep · activity · HRV]
    C --> D[noctua-ai<br/>FeatureExtractor]
    D --> E1[HeuristicInsightEngine<br/>explainable rules]
    D --> E2[ExecuTorchForecaster<br/>.pte neural model, on-device]
    E1 --> F[NoctuaReport]
    E2 --> F
    E2 -.missing runtime.-> E3[LinearHeuristicForecaster<br/>zero-dependency fallback]
    E3 --> F
    F --> G[example-app<br/>Jetpack Compose]

Quickstart

1. Get Oura credentials

• Personal use: create a Personal Access Token at cloud.ouraring.com/personal-access-tokens (note: Oura has been moving new integrations to OAuth2).
• Multi-user apps: register an OAuth2 application at cloud.ouraring.com/oauth/applications with redirect URI noctua://callback.

2. Add the libraries

The modules are plain Gradle project dependencies (publish to Maven or use via includeBuild / JitPack):

dependencies {
    implementation("com.noctua:noctua-core:0.1.0")
    implementation("com.noctua:noctua-ai:0.1.0")
    // Optional: enable the neural forecaster
    implementation("org.pytorch:executorch-android:1.0.0")
}

3. Fetch your data

val oura = OuraClient.Builder()
    .token("YOUR_TOKEN")
    .build()

// Coroutine-first; pagination is handled for you.
val readiness = oura.dailyReadiness(startDate = "2026-08-01", endDate = "2026-08-21")
val sleep     = oura.dailySleep(startDate = "2026-08-01", endDate = "2026-08-21")
val periods   = oura.sleep(startDate = "2026-08-01", endDate = "2026-08-21")

OAuth2 (client-side flow) in two lines:

val url = OuraOAuth.authorizationUrl(clientId, redirectUri = "myapp://callback")
// open `url` in a Custom Tab, then in your deep-link handler:
val token = OuraOAuth.parseClientSideRedirect(intent.dataString!!).accessToken

For long-lived apps, OAuthTokenProvider refreshes expiring tokens automatically via Oura's refresh_token grant.

4. Generate on-device insights

val ai = NoctuaAI()
val report = ai.analyze(WellnessSnapshot(
    readiness = readiness,
    sleep = sleep,
    activity = oura.dailyActivity("2026-08-01", "2026-08-21"),
    sleepPeriods = periods,
))

println(report.forecastedReadiness)   // e.g. 74 — tomorrow's predicted score
report.insights.forEach { println("• ${it.title} (${it.confidence}%)") }
// • Sleep debt accumulating (88%)
// • HRV below your baseline (80%)

5. Go neural with ExecuTorch

cd model
pip install torch executorch
python export_readiness_forecaster.py   # → readiness_forecaster.pte

Ship the .pte with your app and swap the forecaster:

val ai = NoctuaAI(forecaster = ExecuTorchForecaster(pteFile.absolutePath))

If the ExecuTorch runtime or model file is absent, Noctua silently falls back to the bundled linear model — the app never breaks.

API coverage

Errors map to typed OuraException subtypes: Unauthorized, RateLimited (Oura allows ~5000 req / 5 min), Http, Network, Serialization.

Run the example app

git clone https://github.com/RanjithRagavan/Noctua.git
cd Noctua
./gradlew :example-app:installDebug

The app boots into demo mode with a deterministic 21-day dataset, so you can evaluate the full UX — score rings, trend chart, forecast card, AI coach — before connecting a real ring. The screenshots above show exactly what demo mode renders.

Roadmap

• On-device LLM sleep coach (ExecuTorch Llama runner, fully local chat)
• Personal fine-tuning loop: retrain the forecaster nightly on-device
• Health Connect write-back (share derived insights with Android Health)
• Webhook subscription helpers (/v2/webhook/subscription)
• Compose Multiplatform + iOS (KMP) port of noctua-ai

Contributing

Issues and PRs welcome. The heuristics in HeuristicInsightEngine are deliberately readable — improving them with better evidence is a great first contribution. Run ./gradlew test before submitting.

License

Apache 2.0 — use it in personal or commercial apps.

Noctua is an independent open-source project and is not affiliated with, endorsed by, or sponsored by Ōura Health Oy.