Skip to content

Configure the AI model

Futuh’s AI layer is built on gomlo_ai_agent and uses LiteLLM as the switch. You define a primary model and one or more fallback models, and the system switches automatically when the primary fails. Canon default: Mistral Large 2512 via OpenRouter.

Decide who bears the AI cost

Section titled “Decide who bears the AI cost”

This comes before the technical configuration because it determines which API key you will use.

  • Federated: your instance consumes the AI model from Hub Central without any keys of its own. The invoice goes to ACPP, which passes it on through the annual federated subscription. Recommended unless you have a specific reason not to.
  • Local: your instance brings its own OpenRouter account. The invoice comes directly to you. Useful if you have a dedicated AI budget or provider restrictions.

The choice lives in the AI Billing Mode field. Changing it later requires coordination with Hub Central. [VERIFY: exact field name in UI v0.1]

Configure the primary provider

Section titled “Configure the primary provider”
  1. Go to Settings → Futuh → AI → Providers and click New.
  2. Fill in Name (for example, OpenRouter primary).
  3. Under Provider, choose openrouter. Other values: openai, anthropic, mistral, ollama.
  4. Under Base URL, leave https://openrouter.ai/api/v1.
  5. Paste your API Key. It is stored encrypted and visible only to administrators.
  6. Check Active and save.

Register the available models

Section titled “Register the available models”
  1. Go to Settings → Futuh → AI → Models and click New.
  2. Set Name to something readable (for example, Mistral Large 2512).
  3. Under Identifier, enter the exact provider slug: mistralai/mistral-large-2512, anthropic/claude-sonnet-4, openai/gpt-4o.
  4. Associate the Provider you created earlier.
  5. If you want to use this model for vision tasks, check Supports vision.
  6. Save. Repeat for each available model.

Set up the automatic fallback

Section titled “Set up the automatic fallback”

If the primary fails (network error, quota exhausted, rate limit), the system tries the next one. This is configured on the agent.

  1. Go to Settings → Futuh → AI → Agents and select the agent (for example, Silvio).
  2. Under Primary model, choose the model to use first (Futuh canon: Mistral Large 2512).
  3. Under Fallback models, add models in order. Canon recommendation: GPT-4o second, Claude Sonnet 4 third. Provider diversity reduces the risk of simultaneous outages.
  4. Adjust Temperature and Max tokens if you have a preference. Defaults are 0.3 and 2048.
  5. Save.

Verify everything works

Section titled “Verify everything works”
  1. Open Discuss and enter the channel for the configured agent.
  2. Type a short question: “What Futuh modules do I have active?”
  3. Verify that the answer arrives in under ten seconds and correctly names the modules.
  4. To test the fallback, temporarily deactivate the primary provider and repeat. The answer should still arrive with a 2–3 second delay.

Troubleshooting common issues

Section titled “Troubleshooting common issues”
  • “No active provider”. No provider is active. Go back to Providers and activate at least one.
  • “I cannot help with that” in English. The model is rejecting the content by its own policy. Check the agent’s system_prompt: it probably lacks Futuh context.
  • Monthly AI cost higher than expected. Go to Settings → Futuh → AI → Invocation log and filter by model. Typical cause: an agent with a very high max_tokens generating long responses.

Next steps

Section titled “Next steps”