Models
Lakehousecat uses two distinct model types that work together:
- Provider Models — Connections to AI provider APIs (Anthropic, OpenAI, Google, Azure, AWS, xAI). They store API credentials and route requests to the underlying LLM. Created and managed by Administrators only.
- Custom Models — Domain-specific AI assistants built on top of a Provider Model. They combine a provider, a system prompt, linked datasources, and suggestion prompts to create a purpose-built assistant for a specific workflow. Created by Administrators and Builders.
The setup order is always: create a Provider Model → build a Custom Model on top of it → share the Custom Model with users.
Role Overview
| Task | Administrator | Builder | User |
|---|---|---|---|
| Create / delete Provider Models | ✅ | ❌ | ❌ |
| Set default Provider Model | ✅ | ❌ | ❌ |
| Create / delete Custom Models | ✅ | ✅ | ❌ |
| Share Custom Models | ✅ | ✅ | ❌ |
| Use Custom Models in sessions | ✅ | ✅ | ✅ (if shared) |
Provider Models
Provider Models define how Lakehousecat authenticates and connects to an AI provider. Each configuration stores the API credentials, the specific model ID, and the model type (Chat or STT).
Provider Models consume your AI provider's API quota on every request — for natural language queries, semantic extraction, and all backend processing. API costs scale directly with usage. The Administrator is responsible for monitoring and controlling API key usage. Revoke or rotate API keys immediately if unexpected usage is detected.
Supported Providers
For the current list of supported providers and their model types, see AI Providers.
Model Types
| Type | Description |
|---|---|
| Chat | Language model for text generation and natural language queries |
| STT | Speech-to-Text model for voice input (transcription only) |
Creating a Provider Model
Only Administrators can create Provider Models.
- Navigate to Workspace → Models.
- Click the Provider Models tab.
- Click the + button to open the creation form.
Step 1 — Select Provider Type
Choose the provider from the dropdown. The form updates to show the fields required for that provider.
Step 2 — Select Model Type
Choose Chat or STT (Speech-to-Text).
Step 3 — Enter a Configuration Name
Enter a descriptive name, for example anthropic-claude-sonnet or openai-gpt4o-chat. This name appears in dropdowns when Builders create Custom Models.
Step 4 — Fill in Provider-Specific Settings
The required fields depend on the selected provider. For the exact configuration fields, see the dedicated page for your provider under AI Providers.
Step 5 — Set Defaults (Administrators only)
An Administrator: Default Settings section appears at the bottom of the form once a Model ID is selected. These settings apply platform-wide and should be set deliberately.
| Setting | Description |
|---|---|
| Set as default for UI | This model becomes the default shown to users in the UI for the selected model type |
| Set as default for Backend | This model is used for all backend processing — including semantic extraction (analyzing datasource schemas and generating descriptions). Chat type only. |
The backend default determines which LLM processes your semantic layer. This has a direct impact on the quality of natural language queries and the cost of semantic extraction. Choose a capable, cost-effective model and review this setting when changing providers.
Step 6 — Save
Click Save. The Provider Model is stored and immediately becomes available for Builders to use when creating Custom Models.
Provider Model Visibility
Provider Models are not shared directly with Builders or Users via the share dialog. Instead, the Administrator controls which Provider Models exist — and all existing Provider Models are available to Builders in the Custom Model creation form. If you do not want a Provider Model to be used, delete it.
Actions
| Action | Description |
|---|---|
| Clone | Creates a copy of the configuration |
| Delete | Permanently removes the Provider Model and all dependent configurations |
Custom Models
Custom Models are the AI assistants that users interact with. They are built on top of a Provider Model and can be shared with specific groups or users.
Creating a Custom Model
Administrators and Builders can create Custom Models.
- Navigate to Workspace → Models.
- Click the Custom Models tab.
- Click the + button.
Step 1 — Enter Name and Model ID
| Field | Required | Description |
|---|---|---|
| Name | Yes | A human-readable name for the custom model, e.g., Sales Assistant |
| Model ID | Yes | A unique identifier, automatically generated from the name (e.g., sales_assistant). You can edit it manually. Only lowercase letters, digits, and underscores are allowed — no hyphens or spaces, since the ID becomes an internal database name. |
Step 2 — Select a Provider Model
In the Provider Model dropdown, select the Provider Model this custom model should use. The dropdown shows all available Chat-type Provider Models with their provider name and base model ID.
This selection determines which LLM processes all queries made through this custom model.
Step 3 — Add a Description (Optional)
A description helps users understand the model's purpose and scope. You can type it manually or click the microphone icon to use voice input.
Step 4 — Upload a Profile Image (Optional)
Click the image upload area to upload a profile picture. It appears in model lists and the chat interface for visual identification. Supported formats: JPEG, PNG, WebP, GIF.
Hover over an existing image and click the remove button to clear it.
Step 5 — Create
Click Create. You are automatically redirected to the Custom Model Editor, where you can configure:
- System Prompt — Define the AI's base instructions and persona
- Datasources — Link one or more data sources to enable natural language queries
- Filters — Restrict which semantic views of a linked datasource this model exposes (see below)
- Suggestion Prompts — Define quick-start prompts shown to users
Filtering a Custom Model's Datasource Views
The Filters tab in the Custom Model Editor lets you restrict, per linked datasource, which semantic views this model exposes — independent of any filters already applied on the datasource itself. This is useful when several Custom Models share one datasource but should each see a different slice of it (for example, one assistant scoped to sales data, another to HR data from the same source).
For CLI or automation access to the same filters, see the CLI reference:
lhc models filters get <model-id> --datasource-id <datasource-id> --output json
lhc models filters set <model-id> --datasource-id <datasource-id> --include-tables entity_customer,entity_order
lhc models filters clear <model-id> --datasource-id <datasource-id> --confirm
After changing filters on a model that has already been built, trigger a semantic update from the
Operations tab (or lhc semantic update model <model-id> via CLI) so the change takes effect.
Sharing Custom Models
Custom Models are not visible to users by default. The Administrator or Builder who created the model must explicitly share it before users can access it in sessions.
How to Share
- In the Custom Models list, hover over a model entry.
- Click the ··· (more) menu.
- Select Share.
The Share dialog lets you share the model with Groups or Users individually.
Permissions
| Permission | What the recipient can do |
|---|---|
| Read | Use the model in sessions |
| Write | Edit the model configuration |
| Owner | Full control, including re-sharing and deletion |
Start with Read for end users. Grant Write to Builders who collaborate on model configuration.
Unsharing
To revoke access, navigate to Workspace → Models, switch to the Shared by me tab, find the model, and select Unshare.
Model Actions
Hover over any model entry to reveal the available actions via the ··· menu.
Custom Models
| Action | Roles | Description |
|---|---|---|
| Edit | Admin, Builder | Opens the model editor |
| Clone | Admin, Builder | Creates a shallow copy of the model |
| Deep Clone | Admin, Builder | Creates a full copy including datasource bindings |
| Share | Admin, Builder | Opens the sharing dialog |
| Delete | Admin, Builder | Permanently removes the model |
A Custom Model is the data foundation for every chart and dashboard built on it. Deleting the model removes that foundation, so any chart or dashboard still referencing it stops working.
Before deleting a Custom Model that has charts or dashboards attached, Lakehousecat blocks the deletion and shows you how many charts and dashboards would be affected. You must explicitly confirm again to proceed with the deletion anyway. A model with no charts or dashboards attached (for example, a model still in development) deletes immediately without this check.
This protection applies in addition to, and independently of, the Locked setting — a locked model cannot be deleted at all, regardless of dependents; an unlocked but shared model with live charts is still flagged before deletion.
Provider Models
| Action | Roles | Description |
|---|---|---|
| Clone | Admin | Creates a copy of the configuration |
| Delete | Admin | Permanently removes the Provider Model |
Setup Workflow
The typical end-to-end workflow for making a model available to users:
- Administrator creates a Provider Model with the appropriate API credentials and sets the backend default.
- Administrator or Builder creates a Custom Model, selects the Provider Model, and configures the system prompt and datasource bindings.
- Administrator or Builder shares the Custom Model with the relevant groups or users.
- Users open a session, select the shared Custom Model, and begin querying their data.
Next Steps
Once your Custom Model is created and a datasource is linked:
- Go to the Operations tab of the linked datasource and trigger Semantic Extraction to build the semantic layer.
- Share the Custom Model with the relevant user groups.
- Open a new Session and select the custom model to start querying your data.