Model Configuration

Set up provider accounts, logical models, entitlements, and health monitoring at the organization level.

Organization admins manage the model catalog that workspace users consume. This involves configuring provider accounts with API keys, creating logical models that abstract away specific providers, controlling access through entitlements, and monitoring provider health.

Provider Accounts

Provider accounts store the API credentials for each model provider your organization uses. MechaMental supports providers including OpenAI, Anthropic, Azure OpenAI, Google, Cohere, and others.

Navigate to Provider Accounts

Go to Admin -> Provider Accounts in the sidebar. This page lists all configured provider accounts with their current status.

Add a Provider Account

Click Add Account and select the provider from the dropdown.

Enter Credentials

Fill in the authentication details for the selected provider.

Account Name -- a label for this account (e.g., "Production OpenAI")
API Key -- your OpenAI API key

Account Name -- a label for this account (e.g., "Anthropic Primary")
API Key -- your Anthropic API key

Account Name -- a label for this account
Endpoint -- your Azure OpenAI resource endpoint URL
API Key -- your Azure API key
API Version -- the Azure API version string

Account Name -- a label for this account
API Key -- your Google AI API key

Set Limits

Optionally configure rate limits and spending caps for this provider account:

Requests per minute -- maximum API calls per minute
Tokens per minute -- maximum token throughput
Monthly spending cap -- hard limit on monthly costs from this account

Test Connection

Click Test Connection to verify that MechaMental can reach the provider with the supplied credentials. A successful test shows the available models on this account.

Multiple accounts per provider

You can add multiple accounts for the same provider. This is useful for separating production and development workloads, or for distributing load across API keys with different rate limits.

Logical Models

Logical models are provider-agnostic abstractions that workspace users reference in their pipelines. Instead of referencing a specific provider and model name, users select a logical model like fast-chat or high-quality-reasoning. This decouples pipeline definitions from provider details, making it easy to swap providers without updating every pipeline.

Navigate to Models

Go to Admin -> Models in the sidebar. This page shows all logical models with their current targets and status.

Create a Logical Model

Click New Logical Model and fill in:

Name -- a descriptive, use-case-oriented name (e.g., fast-chat, code-generation, document-embedding)
Type -- the model type: chat, embedding, image, or audio
Description -- explain the intended use case

Add Targets

Each logical model has one or more targets -- specific provider + model combinations. Targets form the fallback chain.

For each target, configure:

Provider Account -- select from your configured provider accounts
Model -- the specific model name on that provider (e.g., gpt-4o, claude-sonnet-4-20250514, gemini-2.0-flash)
Priority -- the order in which targets are tried (1 = first choice)

Save

Click Save to create the logical model. It immediately becomes available for workspace users to select in pipeline configurations.

Naming convention

Name logical models by their intended use rather than the underlying provider model. This makes it easy to swap providers without updating every pipeline that references the model.

Managing Targets and Fallback Chains

Each logical model can have multiple targets that form a fallback chain. When a request is made, targets are tried in priority order:

Primary target (priority 1) -- the first choice, usually the best balance of quality and cost
Fallback targets (priority 2, 3, ...) -- used when the primary target fails or hits rate limits
Targets are tried in sequence until one succeeds

Model Entitlements

Entitlements control which workspaces can use which logical models. This prevents teams from accidentally using expensive models and lets you allocate resources appropriately.

Navigate to Entitlements

Go to Admin -> Model Entitlements in the sidebar.

Select a Logical Model

Choose the logical model you want to configure access for.

Assign Workspaces

Select the workspaces that should have access to this model. Unselected workspaces will not see the model in their model picker.

Set Per-Workspace Limits (Optional)

For each entitled workspace, you can optionally set:

Requests per minute -- workspace-level rate limit for this model
Tokens per minute -- workspace-level token throughput limit
Monthly token cap -- maximum tokens this workspace can consume per month

No entitlement = no access

Workspaces without an entitlement for a given logical model cannot use it. Newly created logical models have no entitlements by default -- you must explicitly grant access.

Provider Health Monitoring

Monitor the health and availability of your provider accounts from Admin -> Provider Health. The health dashboard shows:

Metric	Description
Status	Current availability: healthy, degraded, or unreachable
Response Latency	Average and p95 response times
Error Rate	Percentage of failed requests over the last hour
Rate Limit Hits	Number of requests rejected due to provider rate limits
Token Usage	Input and output tokens consumed
Cost	Estimated spending per provider account

Health data updates in real time. If a provider's status degrades, the model router automatically shifts traffic to fallback targets (if configured in the logical model's fallback chain).