Ask Gage, the Atlas AI Assistant

Overview#

Gage is the built-in AI assistant in Timebase Atlas. You type a plain-language question or instruction into a chat panel, and Gage reads your domain, runs queries, and (if you have the right permission) makes changes on your behalf. You would use it when you want to explore or edit a model without learning Cypher, JSON-LD, or the internal shape of an instance map.

A few terms this article uses:

• Domain - one model in Atlas: the entity types you have defined plus the instances built from them.
• Entity type - a kind of thing in your model, such as Pump or FermentationTank.
• Instance map - the file that lists the real, concrete things in your plant and the pattern used to create them.
• Pulse - Timebase Pulse, the component that checks who you are and what you are allowed to do.

Gage is a shared Timebase feature, so the same Ask Gage button appears in other Timebase products. This article covers the Atlas version.

What Gage Can Do#

Gage works through a set of named agents. The default one is called gage and it is the front door: it answers questions itself and hands larger jobs to specialists.

Typical requests:

• Explore a model. "What entity types are in this domain?" or "What properties does a FermentationTank have?"
• Query data. "Show me all pumps currently above 1500 RPM." Gage writes and runs the Cypher for you.
• Change a model. "Add a property called targetSpeed to the Pump entity type." This requires the administrator role - see Who Can Change a Model.
• Run a guided workflow. "Model a new domain for our HVAC system." Gage runs a structured, checkpointed modelling pipeline.

For the full list of agents and how work is handed between them, see the Atlas AI Agents article. For the built-in workflows and the modelling pipeline, see the Atlas Skills article.

Before You Start#

Gage is not offered at all until three things are true. Atlas checks them itself and shows you which one is missing (see Troubleshooting).

1. Pulse authentication is switched on in Atlas. Gage needs to know who is asking, so there is no anonymous mode. With Pulse:Auth:Enabled set to false, the assistant is simply not available. Pulse:Auth:Enabled is true by default.
2. Gage is enabled in Atlas. The setting is Pulse:Gage:Enabled, and it is true by default.
3. At least one model is enabled in Pulse. Atlas does not host or configure a model itself. It asks Pulse for the list of available models when it starts up.

To set all three up from scratch, follow Quick Start: Turn On the AI Assistant.

Open the Ask Gage Panel#

1. Open Atlas in your browser at https://<your-atlas-server>:4552 (or http://<your-atlas-server>:4551 if your deployment is not using HTTPS).
2. Sign in with your Pulse account.
3. Look at the top-right of the toolbar for the Ask Gage button and click it.

The panel docks on the right-hand side of the window and pushes the workspace across rather than floating over it. Drag its left edge to make it wider or narrower.

A new panel has no conversation. Start one with the + button in the panel header, or with Start an agent in the empty panel: both open the picker below.

What You See in the Panel#

Your conversation is kept for the length of the session, so you can refer back to earlier messages without repeating yourself. A refresh restores the thread you were in.

How Gage Knows Which Domain You Mean#

Gage works on the domain and branch of the tab you currently have focused, and it re-reads that on every message. Click a different tab mid-conversation and your next message picks up the new domain and branch automatically.

Tabs that are not a domain or library - Home, the Catalog, Logs, Git, Agents, Skills, or an empty new tab - carry no domain and no branch. If one of those is focused, Gage has nothing to work on and will say the domain does not exist or ask you which domain you mean. Reopening the panel does not help; click the domain's tab instead.

Choose the Model Gage Uses#

Atlas has no model settings of its own. Everything about which model answers, who provides it, and what it costs lives in Pulse. Atlas's entire configuration for the assistant is four keys under Pulse:Gage in settings.config:

{
  "Pulse": {
    "Host": "localhost",
    "Port": 4542,
    "UseTls": true,
    "Cert": { "Enabled": true },
    "Gage": {
      "Enabled": true,
      "Agents": {}
    }
  }
}

Atlas signs in to Pulse's model service using the Client ID and Client Secret it already uses for everything else, Pulse:Auth:ClientId and Pulse:Auth:ClientSecret. There is nothing extra to provision.

Restart Atlas after changing any of these.

Who Can Change a Model#

Reading, asking questions, and running queries are available to any signed-in user. Changing anything requires the pulse:administrator role in Pulse.

Without that role, these are hidden from Gage:

• Creating, editing, and deleting entity types, properties, and relationships
• Editing instance maps
• Creating and editing shared libraries
• Creating, compiling, and deleting domains
• The shell, file, and script tools
• Creating or editing agents and skills

The important part is how they are hidden. The tools are removed before Gage ever sees them, so there is no error and no permission message. Gage simply behaves as though those abilities do not exist: it will explain what needs to change and then tell you it cannot do it, or offer to walk you through doing it by hand. If Gage will read but not write for you, check your Pulse role first.

Where Your Conversation Goes#

Gage never contacts a model provider directly. The path is always:

1. Your message, plus whatever domain structure Gage looked up to answer it, goes from your browser to your Atlas server.
2. Atlas sends it to Pulse.
3. Pulse forwards it to whichever model provider your organisation configured in Pulse.

Which provider that is, and whether it is hosted inside or outside your network, is a Pulse decision. There is no setting in Atlas that changes it.

Two things stay on your own infrastructure:

• Dictated audio. Speech-to-text runs on the Atlas server itself, and the audio never leaves it.
• Files Gage reads and writes. Gage's file and shell tools are confined to the current chat session's own scratch folder. Your ontology data directory and the rest of the server are out of bounds unless an administrator widens the allowed folders in Pulse:Gage:Guardrails:AdditionalAllowedRoots. That setting takes effect on Gage's very next action, with no restart.

Share a Link to an Agent or a Skill#

Atlas has an Agents group in the left sidebar containing Agents and Skills pages, and both support direct links you can send to a colleague:

• https://<your-atlas-server>:4552/agents/<agent-name> opens the Agents page with that agent selected.
• https://<your-atlas-server>:4552/skills/<skill-name> opens the Skills page with that skill selected.

Both take exactly one name. /agents on its own, or a link with extra path segments, does not resolve to anything.

Troubleshooting#