AI Provider

GiftWrapt has several optional features that call an LLM. All of them share a single provider configuration. Set it up once at Admin > AI (or via env vars) and every AI feature picks it up.

What AI Is Used For

Feature	What it does	Where to enable
AI scraper	Reads raw HTML when the basic scrape can’t get useful fields. One of the providers in the scraping chain.	Scraping: add an AI provider entry.
Clean imported titles	Post-scrape normalises noisy titles (“Amazon.com: Brand X Foo - 4-Pack, Black, Size M - Free Shipping” -> “Brand X Foo (4-Pack, Black, M)”).	Admin > AI - scrapeAiCleanTitlesEnabled.
Photo to item	Fills in a new item (title, price, notes) from a photo the user uploads, on the web or in the iOS app.	Admin > AI - aiPhotoExtractEnabled.
Gift suggestions	A “Need ideas?” button on other people’s lists. It shows the best of what is still open (no AI) and suggests gifts not on the list (AI). The AI runs only when a user asks. Off removes the button. See Help Choosing a Gift.	Admin > AI - aiGiftSuggestionsEnabled.
Paste text to items	An import option that turns pasted free text into items, with a preview before anything is added. See Items.	Admin > AI - aiPasteToItemsEnabled.
Thank-you note drafts	A “Draft a Thank-You” button on the Received page. See Received Gifts.	Admin > AI - aiThankYouDraftsEnabled.
Suggestions (Intelligence)	Per-user analyzers that surface stale items, duplicates, grouping suggestions.	Admin > AI - intelligenceEnabled. More under Intelligence.

If you don’t configure an AI provider, the toggles for these features disable themselves in the admin UI. The rest of GiftWrapt works fine.

AI Is Opt-In and Admin-Gated

Every AI feature is off until a provider is configured, and new features ship off by default. Photo to item is the one exception: it turns on with the provider, as it did before it had its own switch. Enabling features costs money against whichever provider you’ve configured; Admin > AI shows what each one is costing (see Usage and Cost).

What Each Feature Sends

Each feature on Admin > AI has a “What is sent to the AI provider” section. The table below is generated from the same source as that screen, so the two always agree.

Feature	Sent to the provider	Never sent
AI Scraper	The product page URL being added. The text and markup of that page, with scripts and styles removed (up to 32 KB).	Anything about your users, their lists, or their gifts.
Clean Imported Titles	The scraped title. The product page URL. The store name, when known.	Anything about your users, their lists, or their gifts.
Photo to Item	The uploaded photo.	Anything about your users, their lists, or their gifts.
Paste Text to Items	The text the user pasted (up to 8,000 characters).	Anything about your users, their lists, or their gifts.
Thank-You Note Drafts	The first name of the user writing the note. The first names of the people who gave the gifts. The titles of the gifts, which have already been revealed to that user. The name of the pet or baby, when the gifts were for a dependent.	What anything cost, and gift notes. Gifts that have not been revealed yet. Last names and email addresses.
Gift Suggestions	The first name of the person the gift is for. Titles, prices, priorities, and categories of the items on that person’s lists that the user asking can already see. For each of those items, whether it is already claimed (yes or no only). The asking user’s own private gift ideas for that person, and the titles of gifts they already gave them. The occasion, taken from the type of list being viewed (a Christmas list, a birthday list, a holiday list). The budget, when the user gives one.	Who claimed anything, what anyone paid, and claim notes. Item notes, links, and images. Items the asking user cannot see, including anything hidden from a restricted viewer. Other people’s gift ideas, off-list gifts, and comments. Last names, email addresses, and birth dates.
Suggestions	Titles and notes of the items on the user’s own lists. The names and types of those lists, and when each item was last changed. Whether an item is marked unavailable, and the item groups already on the list.	Claims: who is giving what, costs, and gift notes. Gift-ideas lists (private notes about other people). Items already revealed or deleted. Profile details: names, email addresses, and birthdays (a name typed into a list name or an item is sent as written).

To keep everything on your own hardware, point the provider at a local OpenAI-compatible runtime such as Ollama or LM Studio.

Usage and Cost

Admin > AI has an AI Usage card: every AI call the deployment made in the last 30 days, by feature, with calls, errors, tokens in and out, and an estimated cost. The estimate is computed from token counts and a built-in rate table, so treat it as a guide and your provider’s bill as the truth.

• Monthly ceiling. Set Monthly Ceiling (USD) (aiMonthlyCostCeilingUsd) to stop AI features once the month’s estimated spend reaches it. The month is the UTC calendar month. While paused, photo to item reports that the budget has been reached, titles are left as scraped, the AI scraper is skipped, and Suggestions runs record an error. The connection test still works so you can check the provider. The ceiling is a guard rail: a burst of calls can overshoot it slightly.
• Retention. Usage rows are kept for aiUsageRetentionDays (default 90) and never contain prompt or response text.

Supported Providers

Three provider families via the Vercel AI SDK:

Type	Notes
openai	OpenAI’s hosted API. baseUrl ignored.
anthropic	Anthropic’s hosted API. baseUrl ignored.
openai-compatible	Any OpenAI-shape endpoint. Works with OpenRouter, Groq, Together, Mistral, DeepSeek, Ollama, LM Studio, vLLM, and other gateways. baseUrl is required.

The openai-compatible route is the catch-all: if your provider speaks the OpenAI HTTP shape, point GiftWrapt at it.

Configuring It

You have two equivalent options.

Option 1: Admin UI (Recommended)

Go to Admin > AI:

• Provider type - one of the three above.
• Base URL - required for openai-compatible. Examples: https://openrouter.ai/api/v1, https://api.groq.com/openai/v1, http://localhost:11434/v1 for Ollama.
• API key - encrypted at rest using a key derived from BETTER_AUTH_SECRET.
• Model - the model ID to use. Examples: gpt-4o-mini, claude-haiku-4-5, meta-llama/llama-3.1-8b-instruct.
• Max output tokens - optional cap on generated tokens per call. Applies to the connection test, scraping, title clean-up, and photo to item. Suggestions are bounded by batch size instead.

Changes apply on the next read (no restart needed). A “Send test prompt” button verifies the config end-to-end.

Option 2: Env Vars

If you’d rather pin AI config in your deploy config, set these on boot:

AI_PROVIDER_TYPE=openai           # openai | anthropic | openai-compatible
AI_API_KEY=sk-...
AI_MODEL=gpt-4o-mini
AI_BASE_URL=                      # required for openai-compatible
AI_MAX_OUTPUT_TOKENS=

When set, env vars take precedence over the admin form’s stored values. The admin UI shows a “managed via env” banner in that case.

Picking a Model

GiftWrapt doesn’t care which model you use; it cares about cost and latency.

Use case	Reasonable choices
Title cleaner	Smallest available. Output is one short string.
URL extractor	Small or medium. Reads HTML, emits structured JSON.
Intelligence analyzers	Small to medium. Most prompts are small (per-user item lists).

Costs ballpark for a single-family deployment running everything on: pennies a month with a cheap small model, dollars a month with a frontier model.

Per-Feature Model Override

Intelligence supports a intelligenceModelOverride setting that swaps just the model ID for analyzer calls. The provider, API key, and base URL still come from the global AI config; the override only swaps the model within that provider.

Use this when you want frontier-tier scraping AI but cheap-tier Intelligence, or vice versa.

Security Notes

• API keys saved via the admin UI are encrypted at rest with AES-256-GCM. The master key is derived via scrypt from BETTER_AUTH_SECRET. Rotating BETTER_AUTH_SECRET invalidates every stored AI key.
• API keys set via env vars are passed through as-is and not stored in the database.
• Outbound calls to the AI provider go directly from the GiftWrapt server. There’s no Anthropic / OpenAI proxy in the path.
• Prompts include item data (titles, notes, prices, URLs) but never include claim/gifter data. See Privacy for the spoiler-protection rule that extends to AI.