Faro — AI-native commercial insurance intake & analysis on iOS / iPadOS

• Inspiration
• What it does
• Hackathon context & sponsor tracks
• How we built it
  • Libraries & dependencies
• Repository layout
• API surface
• Prerequisites
• Installation
• Configuration (environment variables)
• Local development
• Testing
• iOS: Widget & App Groups
• Challenges we ran into
• Accomplishments we're proud of
• What we learned
• What's next
• License

Commercial insurance for small businesses is broken. Getting coverage takes days of back-and-forth with human brokers, pages of confusing jargon, and mountains of paperwork. A daycare owner, a restaurant operator, a contractor—they want to know what they need, how much it costs, and where to get it. For people building a business, that friction is an easy problem to overlook until it blocks them cold.

We built Faro to compress that workflow into under two minutes, powered by an autonomous AI agent that reasons like a broker.

We chose to build natively on iOS and iPadOS because we believe the future of AI applications is increasingly on-device. Today, Faro runs model inference through cloud APIs, but a native Swift architecture positions the product for a world where models run directly on the phone or tablet with minimal data leaving the device. For a product handling sensitive business financials, headcount, and revenue, that privacy story matters.

A business owner opens Faro on an iPhone or iPad, describes their company in plain English, and within about two minutes receives a structured insurance analysis. There are two primary intake paths:

• Guided questionnaire — A one-question-at-a-time flow for business name, description, employee count, US state, and approximate annual revenue.
• Conversational voice intake — The user talks naturally with Faro. An ElevenLabs Conversational AI agent runs a voice interview over a WebSocket; when the conversation finishes, the transcript is turned into structured intake fields using Google Gemini.

After intake, Faro runs a four-step agent pipeline (orchestrated with LangGraph, reasoning with Gemini):

1. Risk profiler — Risk exposure and regulatory-style considerations.
2. Coverage mapper — Required, recommended, and projected coverages with premium estimates (hybrid rules + LLM).
3. Submission builder — Carrier-oriented submission packet content.
4. Explainer — Plain-English narrative; optional ElevenLabs text-to-speech produces audio served at GET /audio/{session_id}.

The Agent tracker screen streams step progress over WebSocket so users see the pipeline work in real time.

Outputs include a coverage dashboard (including Swift Charts), spoken summary playback, PDF export via the system share sheet (UIKit-based PDF generation), a WidgetKit home screen widget fed from App Group data, and MongoDB-backed session persistence (with an in-memory fallback when no database is configured). Auth0 secures HTTP and WebSocket access when configured. A simple marketing landing page lives under web/.

Faro was built for YHack 2026 (team context and prize strategy are captured in CONTEXT.md). Official eligibility always depends on the published Devpost / organizer rules; the list below is how the project maps to the tracks the team targeted.

The client is a SwiftUI app with adaptive layouts for phone and tablet, WidgetKit extension, URLSession REST clients, WebSocket for pipeline progress, AVFoundation for microphone capture and audio playback (including ElevenLabs live conversation), and UIKit-based PDF rendering for exports. Swift Charts powers dashboard visualizations.

Gemini drives structured JSON generation across pipeline steps and post-processes ElevenLabs transcripts into validated IntakeRequest payloads. Defaults (overridable via env): gemini-3-flash-preview primary, gemini-2.5-flash fallback, with timeouts and validation wrappers in code.

• Conversational AI — Backend provisions or reuses a ConvAI agent, returns a signed WebSocket URL from POST /conv/start; the iOS client connects directly to ElevenLabs for bidirectional audio.
• Text-to-speech — Explainer step calls the REST TTS API; audio is persisted and exposed through GET /audio/{session_id}.

Motor (async driver) talks to Atlas when configured. Documents accumulate heterogeneous JSON from each agent step—natural fit for a document store.

Auth0.swift (with JWTDecode and SimpleKeychain transitive dependencies) handles login; the API uses PyJWT with cryptography for RS256 verification against Auth0’s JWKS.

Four sequential graph nodes mirror the business workflow. Each transition can broadcast running / complete / error updates to the client WebSocket.

Deterministic pricing rules are blended with model-generated components so premium ranges are grounded in policy-type logic rather than pure free-form generation.

Static landing page: web/index.html.

Resolved in ios/Faro.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved:

Protected routes use Bearer tokens when Auth0 env vars are set; WebSockets enforce the same policy via connection-time checks.

• macOS with Xcode (for iOS 17+ targets; project deployment target is 17.0).
• Python 3.12+ recommended (matches team venv; 3.11 may work if dependencies resolve).
• MongoDB Atlas cluster or run without MONGODB_URI for in-memory mode.
• API keys: Gemini (GEMINI_API_KEY or GOOGLE_API_KEY), ElevenLabs (voice + TTS), optional Auth0 tenant.

cd backend
python3 -m venv .venv
.venv/bin/pip install -U pip
.venv/bin/pip install -r requirements.txt
cp .env.example .env
# Edit .env — never commit real secrets

The helper script backend/run.sh auto-creates .venv on first launch if missing (or uses .uenv if you already have that directory).

1. Open ios/Faro.xcodeproj in Xcode.
2. Let Swift Package Manager resolve Auth0 packages.
3. Select the Faro scheme; set your Signing & Capabilities team.
4. For the widget, align signing and App Groups with the main app (see below).

Open web/index.html in a browser, or serve the folder with any static file server.

Backend loads backend/.env then backend/.env.local (see main.py).

iOS backend URL: default http://localhost:8000 via ios/Faro/Info.plist (adjust for device testing using your machine’s LAN IP).

From the repository root:

./run-backend.sh

Or directly:

./backend/run.sh

Server listens on http://127.0.0.1:8000. Interactive docs: http://127.0.0.1:8000/docs.

1. Start the backend (above).
2. Run the Faro scheme in Xcode against a simulator.

Use your Mac’s LAN IP in Info.plist (or your config pattern) instead of localhost, and ensure the device can reach port 8000.

cd backend
.venv/bin/python -m unittest discover -s tests -v

(Use .uenv instead of .venv if that is what you created.)

1. Use the same development team for Faro and FaroWidgetExtension.
2. Enable App Groups on both targets.
3. Shared group identifier: group.com.faro.shared.

Apple’s free/personal teams can limit certain capabilities; widgets may sign while App Group persistence is constrained—test on a paid team when possible.

• ElevenLabs Conversational AI on iOS — Bidirectional WebSocket audio required careful protocol alignment (initiation messages, format negotiation, echo handling, transcript assembly). Native AVAudioSession and converter plumbing added complexity.
• Auth0 — Redirect URLs, bundle identifiers, API audience strings, and JWKS verification must match exactly across dashboard, Swift SDK, and FastAPI.
• Gemini JSON reliability — Structured outputs need timeouts, fallback models, and Pydantic validation to survive edge cases under demo pressure.
• Parallel development — Swift models and FastAPI contracts evolved together; WebSocket payloads and results schemas had to stay in lockstep.

• Native SwiftUI client plus FastAPI backend with a real multi-step agent, built on a hackathon clock.
• Live WebSocket agent tracker so users watch the pipeline progress instead of a static spinner.
• Two intake modes—guided form and ElevenLabs voice—converging on one analysis path.
• Hybrid pricing logic plus LLM reasoning for many commercial line types.
• PDF export, TTS summary, MongoDB persistence with graceful degradation, Auth0 security, and a widget surface.

• Defensive LLM engineering (timeouts, fallback models, strict parsing) is non-negotiable for demos that must not flake.
• Voice-first UX is compelling, but native real-time audio is a specialty integration—budget time accordingly.
• Document databases fit agent pipelines that accumulate nested, evolving JSON per session.
• Auth0 accelerates security, but cross-platform JWT alignment has a learning curve.
• Streaming UX (WebSocket progress) dramatically improves perceived quality versus batch-only APIs.

• On-device inference where feasible for privacy-sensitive fields.
• Carrier integrations for bindable quotes vs. illustrative estimates.
• Proactive risk monitoring via widgets and notifications.
• Document upload / OCR for existing policies.
• Multi-state / multi-location rules expansion.
• Broker marketplace handoff once needs are understood.

No license file is present in this repository as of the last update. Add a LICENSE file before open-sourcing or redistributing.