SwiftMend

Inspiration

App users routinely see messages such as “Something went wrong” or “The request could not be completed.” Those messages may be technically accurate, but they do not explain what the user can safely do next. Developers can write custom recovery guidance for every failure, but covering authentication, networking, checkout, and every unexpected edge case is easy to postpone or miss.

SwiftMend started with a focused question: can a Swift app turn a caught error into useful recovery guidance without exposing sensitive data or making an AI service a single point of failure?

What it does

SwiftMend is a UI-independent recovery SDK for Swift apps. When a host app catches an error, the developer creates a privacy-reviewed ErrorSnapshot and adds app-owned RecoveryContext. SwiftMend then resolves that error in a deliberate order:

Use an exact developer-authored recovery rule when one matches. Ask Gemini or Gemma to explain the problem while selecting only from developer-approved recovery actions. Revalidate the model output, map selected IDs to canonical developer-owned actions, or return deterministic local advice when the model is unavailable, offline, fails, or returns invalid output.

Every result includes its source, so the app can show whether the advice came from a developer rule, Gemini, Gemma, or local fallback. The macOS and iPhone demos compare the original generic failure with one to three actionable recovery steps.

SwiftMend does not claim to intercept every failure or diagnose crashes automatically. The host app explicitly reports caught errors or integrates future convenience wrappers around selected services.

How we built it

The core is a Swift 6 package supporting iOS 18+ and macOS 15+. ErrorSnapshot, RecoveryContext, RecoveryAdvice, RecoveryRule, and RecoveryEngine form the UI-independent API. Exact rules can match error domains, codes, messages, and required context. RecoveryModelRequest carries the reviewed snapshot, app context, and canonical action catalog to any model provider.

GeminiRecoveryModelProvider calls gemini-3.7-flash through the Gemini API for the first two live demo scenarios. GemmaRecoveryModelProvider separately accesses hosted gemma-4-26b-a4b-it through the same API, while the optional SwiftMendLiteRT product runs a fine-tuned Gemma 3 270M model locally through LiteRT-LM 0.16.0. Every model path requests JSON with a title, message, and one to three case-sensitive action IDs. Unknown, duplicate, empty, excessive, or malformed selections are rejected, and accepted IDs are mapped back to developer-owned action titles.

OSLogDiagnosticSource writes the same privacy-reviewed diagnostic used by the recovery engine to Apple Logging. It does not scrape arbitrary OS or device logs. The UI and logs identify whether recovery came from Gemini, on-device Gemma, a developer rule, or local fallback without logging API keys, prompts, raw model responses, or unsafe diagnostics.

We built seven consistently organized SwiftUI demo scenarios for macOS and iPhone, a versioned 70-scenario dataset across seven error categories, reproducible model benchmark and comparison tools, 84 Swift Testing tests, 7 Python training/export tests, and GitHub Actions checks for package build, tests, and iPhone Simulator compilation.

How we used AI and Codex

Gemini handles the hosted long tail of caught errors for which a developer has not written an exact recovery rule. It uses the sanitized error identity and feature context to generate situation-specific wording while selecting only approved action IDs. A tuned on-device Gemma model supports local recovery scenarios, while developer rules remain first and RecoveryEngine independently revalidates every provider response. Reviewed fallback advice remains available, so the user experience never depends entirely on a model.

Codex helped turn the original “self-debugging” idea into an honest recovery SDK with explicit capture and privacy boundaries. It helped design the package API; implement constrained Gemini plus hosted and local Gemma providers; enforce canonical actions; build the seven-scenario demo, versioned dataset, evaluation runner, comparison gate, and 270M training/export workflow; diagnose strict-concurrency and LiteRT packaging issues; configure GitHub Actions; and verify both hosted recovery and the physical-iPhone local benchmark without exposing secrets.

Challenges we ran into

The hardest product challenge was giving Gemini and Gemma enough context to offer useful advice without sending passwords, tokens, account data, or raw server responses. That led to the explicit privacy-reviewed snapshot boundary.

The hardest reliability challenge was ensuring the model could never break recovery itself. We addressed that with strict response validation and a deterministic fallback path.

The hardest model challenge was determining whether a smaller on-device model could meet the same recovery contract. We built a held-out evaluation pipeline, fine-tuned Gemma 3 270M, fixed its LiteRT conversion path, and compared it with the 1B baseline under zero-regression tolerances.

On iPhone, strict-concurrency and dynamic-framework packaging differed from the package build. We isolated and fixed those issues, then verified local builds, GitHub Actions, and the exact model artifact on physical hardware.

Accomplishments that we are proud of

Built a deterministic recovery engine with rule priority, constrained Gemini and Gemma providers, canonical action mapping, and offline fallback. Fine-tuned Gemma 3 270M and made its CPU configuration the package default only after it beat the 1B baseline across every strict acceptance gate. Ran the exact local artifact on an iPhone 17 Pro: 14/14 recovery accuracy, 14/14 valid JSON, zero fallback, and only developer-approved actions. Ran two live Gemini recovery scenarios through gemini-3.7-flash with only canonical developer-approved actions. Verified privacy-reviewed logging and routing without exposing API keys, prompts, raw model responses, or unsafe diagnostics. Passed 84 Swift Testing tests, 7 Python tests, package/app builds, and all GitHub Actions checks. Kept the package core independent from SwiftUI so host apps control presentation.

What we learned

AI-generated recovery guidance works best behind deterministic policy rather than as a replacement for it. The model is useful for contextualizing the long tail of unexpected errors, while developer rules and local fallbacks provide control and reliability.

We also learned that a smaller fine-tuned model can outperform a larger general baseline on a narrow, schema-constrained task—but only when the decision is based on held-out accuracy, valid JSON, fallback rate, latency, memory, and target-device evidence rather than parameter count alone.

Error handling is a product experience. The useful output is not a technical diagnosis alone; it is a small set of safe actions the user can take immediately.

What is next for SwiftMend

Add opt-in wrappers for common networking and authentication flows. Ship reusable SwiftUI recovery components while keeping the core UI-independent. Move hosted-model access behind a developer-controlled backend for production use. Expand the reviewed dataset and repeat the gated comparison as new recovery categories are added. Package a production-safe model-delivery flow without committing or bundling license-gated artifacts.