Skip to content

Models and sign-in

Familiar reaches models through Pi’s Models registry. createModels() starts empty. You register each provider yourself and pass a credential store the providers read and refresh.

import { createModels } from '@familiar-ai/core/models'
import { openaiProvider } from '@familiar-ai/core/models/openai'
import { openrouterProvider } from '@familiar-ai/core/models/openrouter'
const models = createModels({ credentials })
models.setProvider(openaiProvider())
models.setProvider(openrouterProvider())

credentials is a CredentialStore your host owns. It must persist, or every restart signs out. The daemon’s file store is a working Node example.

Keep provider credentials on the server. Never put them in frontend code.

ChatGPT sign-in lets a Familiar use a ChatGPT subscription instead of an API key. It’s the model’s access, not a login to your app. Pass account, and Familiar signs in through the same models:

assistant.ts
import { openWorkspace } from '@familiar-ai/core'
import { createModels } from '@familiar-ai/core/models'
import { openaiProvider } from '@familiar-ai/core/models/openai'
import { credentials, deviceId, storage } from './host.ts'
const models = createModels({ credentials })
models.setProvider(openaiProvider())
export const workspace = await openWorkspace({
storage,
models,
account: { login: { getDeviceId: deviceId, agentName: 'Familiar' } },
chatModel: { provider: 'openai', modelId: 'gpt-6.1-sol' },
modelChoices: [
{
model: { provider: 'openai', modelId: 'gpt-6.1-sol' },
thinkingLevel: 'low',
},
{
model: { provider: 'openai', modelId: 'gpt-6-luna' },
thinkingLevel: 'medium',
},
],
timeZone: 'Europe/London',
})

The ./host.ts imports stand in for your own code. deviceId returns a stable ID for this installation; OpenAI identifies the app’s logins by it.

With account:

  • workspace.account exposes state(), signIn(), answer(text), cancelSignIn(), signOut() and onChange(listener).
  • The state is one of signed-in, signed-out, expired or signing-in. While signing in it carries the provider’s url and paste: true when the provider needs the address the browser ended on.
  • The HTTP API serves these under /account and streams the state, so a UI can run the whole sign-in.
  • The workspace closes the account when it’s dismissed. Every Familiar in it uses the one login.

Without an account, the host keeps credentials working itself and a failed request fails like any other.

modelChoices lists the models the installation offers, each with the reasoning level it starts on. Leave it out and the only choice is chatModel at medium.

The workspace has a default model and reasoning level for each job. Familiars’ chats run on the chat default, and memory’s filing and profiles on the memory default, which can be a cheaper model: background memory work needs less than a chat does. chatModel and memoryModel (default chatModel), at their levels in modelChoices, are the defaults until the owner chooses others with setModelDefaults({ chat?, memory? }), each { provider, modelId, thinkingLevel? }; a model given without a level runs at its own. modelDefaults() returns the ones in use, each with its level. Changing the chat default moves every Familiar that follows it from its next request.

Each Familiar can choose its own model for either job instead: familiars.update(id, { chatModel, memoryModel }), where null returns it to the default and a memoryModel may carry a thinkingLevel. Its setModel(ref) chooses its chat model the same way, and setThinkingLevel(level) changes the current model’s level, remembered for that model; both are on workspace.familiars.get(id) and over HTTP under /familiars/:familiar/model, and throw a ModelError for a choice that isn’t on offer. Every model must be in modelChoices.

A model’s level for a job is the one chosen with it, else the job’s default level if it’s the default model, else its own in modelChoices. A chat’s level remembered with setThinkingLevel wins over all of these, so changing the default level leaves it alone. A Familiar’s own choice that a restart no longer offers falls back to the default.