ErgoPlanner

Appearance

AI provider setup ​

SuperAdmin walkthrough for connecting an AI provider at /admin/ai-providers.

Last verified: 2026-09-06 Status: Current

ErgoPlanner routes AI agent calls — symbol recognition, chatbot, project agents — through a per-tenant LLM profile. A SuperAdmin configures the profile once; all agents on the tenant then use it.

For the full technical background (architecture, sovereignty model, Stripe metering) see LLM Multi-Provider — feature doc.

Who can configure this ​

The /admin/ai-providers page is gated to SuperAdmin system role. Company Admins and Engineers cannot reach it.

Three modes ​

ModeWhat it meansWho can use it
ManagedUses the ErgoPlanner platform's OpenRouter account. Models available from the catalog. Metered: usage billed against the company's prepaid AI budget.All plans (Pro and above)
BYOK (Bring Your Own Key)Your organisation's own API key with Anthropic, OpenAI, or Gemini. Key is encrypted at rest; unmetered.Enterprise plan
Self-hostedPoints at your own OpenAI-compatible endpoint (Azure OpenAI, Ollama, vLLM, LM Studio). Prompts never leave your network.Enterprise plan

If your plan does not include BYOK or Self-hosted, those options appear greyed out. Contact sales to upgrade.

Setting up a profile ​

  1. Sign in as a SuperAdmin and navigate to /admin/ai-providers.

  2. If no profile exists yet, click Add AI provider.

  3. Choose a mode (Managed / BYOK / Self-hosted).

  4. Fill in the fields for that mode:

    Managed

    • Pick a default model from the dropdown catalog.
    • No key required — the platform account is used.

    BYOK

    • Select provider: Anthropic, OpenAI, or Gemini.
    • Paste your API key. The key is stored encrypted (AES-256 via ASP.NET Data Protection); it is masked in the UI after saving.
    • Pick a default model compatible with the provider.

    Self-hosted

    • Enter the base URL of your OpenAI-compatible endpoint (e.g. http://ai.internal:11434).
    • Pick or type a model name (e.g. llama3.1:8b).
    • No key required for open endpoints; enter one if your server requires it.

  5. Click Test connection to verify the endpoint is reachable and the key is accepted. A green "Connection successful" message confirms it. Fix any error before saving.

  6. Click Save.

Sovereign no-fallback ​

When your organisation is on a plan that requires data sovereignty — and you enable the Sovereign: no managed fallback toggle — ErgoPlanner guarantees that AI requests never fall back to the platform's managed OpenRouter account. If your endpoint is unreachable, calls fail explicitly rather than silently rerouting to a third-party provider. Enable this only after you have verified the Test connection step passes reliably.

Per-agent model overrides ​

After the profile is saved, the Agent overrides panel appears below the profile card. Use it to assign a different model to specific agents — for example, a faster model for the chatbot and a more capable one for symbol recognition. Overrides are optional; agents fall back to the profile's default model when no override is set.

Editing or replacing a profile ​

Click Edit on the profile card to reopen the editor form. You can change the mode, update the key, or switch models. Saving writes the new values immediately.

To replace the profile entirely, click Delete on the profile card and then add a new one. There is only one active profile per tenant at a time.

Checking usage (Managed mode) ​

Every AI call is recorded per company: tokens in and out, the model, the cost and the feature that made it (for example ai-chat or template-code-generator). Only Managed calls are charged, against the plan's monthly managed AI credit (Starter $0, Professional $50, Enterprise $500, resetting on the 1st, UTC). Calls on your own key (BYOK) or a self-hosted model are recorded but never charged.

Settings → Billing → Usage this period shows a Managed AI credit bar: used and allowance in dollars, the share used, and the five features that used the most.

  • From 80% the bar turns amber and a warning says how much is left. Calls still run.
  • At 100% the bar turns red and Managed AI calls are refused with 402 Payment Required (the same plan-limit response as other limits: resource AiCredit, code AI_QUOTA_EXHAUSTED) until the next month. To keep working, upgrade the plan or switch the profile to BYOK or Self-hosted. Those modes are never blocked by the credit.
  • Bursts are still limited per minute with 429.

On Starter there is no managed credit, so the card says "Not included in this plan" and Managed calls are refused. Use BYOK or Self-hosted instead.

When AI is unavailable ​

Every AI surface — the chatbot (/chatbot), the BoQ agent chat, the Draw P&ID agent dock, the Agents page, and the knowledge search page — asks the platform on entry whether AI is configured, and shows a warning bar immediately if it is not, before you type anything: "AI is not configured on this preview — chat and agents will not answer. A SuperAdmin adds a key under Admin → AI Providers." You do not have to send a message or run a dispatch to learn this.

Send and dispatch buttons stay enabled while the bar is shown — the honest banner is the guard, not a disabled control — so if you try anyway you will get a clear "no reply" outcome rather than a silent hang. The chat composer's placeholder also changes to "AI is not configured…" for the same reason.

If you are a SuperAdmin, follow Setting up a profile above to clear the bar for your whole tenant. If you are not, ask your SuperAdmin to add a key at /admin/ai-providers — the bar's own link points there.

The knowledge search page's empty-index card is a related but separate state: it means no documents have been ingested yet, independent of whether an LLM provider is configured. On a tenant without ingest access, the card says the operator runs the corpus ingest for that environment — it is not something a tenant account can trigger.

  • LLM multi-provider — technical feature doc
  • ADR-0016 — LLM multi-provider strategy