Using your own AI provider

SageFin's AI runs on a model we choose and pay for. If you would rather it ran on one you choose — because you already pay a provider, want a particular model, or do not want your data going to the provider we use — an owner can give SageFin an API key of the household's own.

It is optional, and most households will never need it.

What changes when you do

Everything SageFin's AI does for your household runs on your key instead of ours: categorizing new transactions, reading receipts, splitting retail orders by item, drafting rules and reports, and every answer from Sage.

Three things follow, and they are worth knowing before you switch:

• Your data goes to that company, under its terms. The merchant names, amounts, receipt images and questions that would have gone to our provider go to yours. Our privacy policy does not reach what it does with them.
• It bills you. SageFin still records how much your household used, but the charge is between you and your provider.
• Quality depends on the model you pick. A weaker model categorizes worse and answers worse, and SageFin cannot promise how well a model we did not choose will do. What it learns about a merchant is remembered for later charges, so a poor answer can outlast the model that gave it. Correcting a transaction's category replaces what was remembered.

Setting it up

In Settings → Preferences, under Your own AI provider, choose Use your own. Only an owner can.

The iPhone app has it in the same place: in Settings → Preferences, Your own AI provider opens a screen of its own with the same fields, the same test and the same month of usage. There a model field opens a list you can search, and a name that is not in the list can be typed and used as it is.

• Provider is one of the companies SageFin lists, or Your own server if you run a model yourself (see below).
• Model is the model's name exactly as your provider lists it. The arrow at the end of the field opens a list of that provider's models, each with its price, and typing narrows it. You can still type a name that is not in the list.
• Model for receipts is optional, and needs a model that can read images. Leave it blank and receipts are not scanned at all. SageFin's own model is not used in its place.

The suggestions come from models.dev, a public list of what each provider says its models can do. Under each field SageFin tells you what that list says about the name you entered: its price, or that it is not listed as doing something the field needs. A name the list does not have may still work, and a model it describes well may not. The test below is what decides.

Where a model in the list is marked Suggested, it scores at or above the model SageFin includes on the Epoch Capabilities Index, a published general benchmark from Epoch AI. It is a starting point for choosing, not a promise: the benchmark does not measure how well a model categorizes transactions. A model with no mark has simply not been matched to a score, which is different from scoring badly, and that is common for the newest models, which are often released before they are scored.

• API key is stored encrypted. It is never shown again: afterwards you see only its last four characters, so you can tell which key it is.

Test and save asks your provider four things before saving anything: whether the key works, whether the model can return structured answers, whether it can use tools, and whether it can read an image.

• A key the provider rejects, or a model it does not know, is not saved. From the moment it was, every AI feature would be pointed at something that cannot answer.
• A model that connects but cannot do one of the other three is saved, and the page tells you which features that costs you. No structured answers means no categorization; no tool use means Sage cannot look anything up; no image reading means no receipt scanning.

Test asks again at any time. Remove deletes SageFin's copy of your key and returns the household to the provider we include. The key itself still works at your provider until you revoke it there.

Seeing what your key was used for

Once a provider is set, the same card shows This month on your key: each thing SageFin's AI did on it, such as Sage, categorizing transactions or reading receipts, with how many calls it made and how many tokens went in and out. Your provider's own usage page shows what you were charged, but it cannot tell you which part of SageFin the charge came from. This can.

The Estimate column is tokens at your provider's published list prices. It is not a bill: it does not know your discounts or every charge for cached input, so treat your provider's figure as the real one. A model with no listed price, including one you run yourself, shows a dash instead of an amount. Only calls that got an answer are counted.

Running a model yourself

Choose Your own server as the provider and give its server address: the https:// address of an API that speaks the same protocol as OpenAI's, which Ollama, LM Studio, vLLM and most other self-hosting tools do.

The address has to be reachable from the internet, because the request comes from SageFin's servers and not from your browser. That rules out the most common setup: a model listening on localhost, or on a machine on your home network, cannot be reached from here, and SageFin refuses those addresses outright. To use a model like that you would put it behind an https address of your own, with a key, and give SageFin that.

Three things differ from a listed provider:

• No suggestions. The model field is plain text, since nobody publishes a list of what your server runs.
• Errors are terse. When your server refuses a request SageFin tells you the status it answered with and not what it said.
• It has to be up when SageFin needs it. Transactions are categorized as they arrive, not when you are at your computer. If your server is off, that work waits, and the notification described below is sent at most once a day.

If your key stops working

SageFin never falls back to its own provider. Someone who brings a key may be doing it to keep their data away from ours, so a failure of yours stays a failure rather than quietly becoming a call to us.

What happens instead depends on whether you set a failover: a second provider, model and key of your own, in the same form.

• With a failover, SageFin uses it while the first is rejecting your key, out of credit, or not answering, and goes back on its own when the first recovers.
• Without one, AI features wait. New transactions are still categorized by your rules, the merchants SageFin has remembered and your bank's own category, and anything that needed a model is left until the key works again.

Either way every owner gets one notification, AI provider key not working, saying which of those happened. It is sent once when the trouble starts, not once per failed request, and at most once a day. It cannot be switched off in Settings → Notifications, because nothing else on any screen would tell you why AI had stopped. Settings → Preferences shows the same thing for as long as it lasts, and on the phone tapping the notification opens the screen where the key is tested and changed.

Receipts are the exception to the failover: they are read only by the receipts model on your first provider.

What still uses SageFin's provider

One thing, whichever provider you choose: looking up a merchant's website, which is how an unfamiliar merchant gets its logo. The answer is shared by every household, so it is asked once on our key rather than on yours. Only the merchant's name is sent.

Nothing you type goes to our providers. On the provider SageFin includes, what people type to Sage, or into a rule, a report or a split suggestion, is first checked by a moderation service, because one person's message there could get a key every household shares switched off. Your key is not shared, so that check is not run for your household: what you type goes to your provider and nowhere else, and your provider's own rules about acceptable use are the ones that apply to it.

If you have turned AI off for the household, your key is not used either: those switches come first.