AI context
In the ecosystem, context is the fourth ingredient — information about the user's environment passed to the providers so the model knows when it is, which file is open, what you selected, and what's on screen. It's the cheapest way to make the assistant situation-aware, and the easiest extension point in SmartHopper.
Structure of a context provider
A context provider is a class implementing the two-member IAIContextProvider contract:
| Member | What it is |
|---|---|
ProviderId | Stable identifier — the namespace prefix for all its keys (time, file, selection…) and the name ContextFilters match against. |
GetContext() | Returns Dictionary<string, string> — the facts to inject. Runs on every request that admits it, so it must be cheap. |
That's the whole contract — no registration call baked in; you register the instance with AIContextManager once (see below).
How it works
IAIContextProvider(SmartHopper.Infrastructure/AIContext/) — the contract above.AIContextManager(same folder) — a static registry:RegisterProvider,UnregisterProvider,GetProviders,GetProvider(id),GetCurrentContext(providerFilter).AIBody.ContextFilterdecides which providers contribute to a given request. When the filter yields data, the body'sInteractionsgetter prepends a synthesizedAIInteractionTextwithAgent = Context— a non-mutating injection: the stored list is unchanged, only the copy the provider sees.
Built-in providers
In SmartHopper.Core/AIContext/, registered at assembly load by AIContextBootstrapper (a [ModuleInitializer], so they're always present; EnsureInitialized() is available and idempotent):
| Provider | ProviderId | Example keys |
|---|---|---|
TimeContextProvider | time | time_local-datetime, time_local-timezone |
EnvironmentContextProvider | environment | OS, runtime, SmartHopper version |
FileContextProvider | file | current document name/path, app versions |
SelectionContextProvider | selection | selected canvas objects |
ViewportContextProvider | viewport | what's visible on the canvas right now |
Filtering
Consumers set AIBody.ContextFilter (via AIBodyBuilder.WithContextFilter(...) or the request's context parameter):
| Filter | Result |
|---|---|
"*" | all registered providers |
"-*" | none (the AIBody.Empty default) |
"time, environment" | only those ids |
"*, -selection, -viewport" | everything except the excluded ones |
The assistant defaults to time, environment, file, selection, viewport. Components like the text transforms pass "-*" because context adds nothing but tokens for a stateless transform.
Key namespacing: keys returned without an underscore are automatically prefixed "{ProviderId}_" — return local-datetime from provider time and it surfaces as time_local-datetime. Later providers overwrite duplicate keys.
Writing a context provider
public class BuildInfoContextProvider : IAIContextProvider
{
public string ProviderId => "buildinfo";
public Dictionary<string, string> GetContext()
{
// Runs on every request that includes this provider — keep it cheap.
return new Dictionary<string, string>
{
["configuration"] = "Debug",
["machine"] = Environment.MachineName,
};
}
}
Register it once (e.g. your assembly's [ModuleInitializer], mirroring AIContextBootstrapper):
AIContextManager.RegisterProvider(new BuildInfoContextProvider());
Now any request whose ContextFilter admits buildinfo gets buildinfo_configuration / buildinfo_machine in the injected context message.
Rules of thumb
- Keep
GetContext()fast and non-blocking — it runs per request, before every provider call. No I/O, no UI thread dependencies, no heavy computation. - Stay small. Context is injected verbatim into every request — every entry costs tokens on every call. Facts, not documents.
- Stable keys beat clever keys. Consumers (and humans debugging raw payloads) rely on predictable
provider_keynames. - Respect privacy. Context goes to whatever provider the user configured — never include secrets, file contents, or anything the user wouldn't expect to leave the machine. Facts like "file name" yes; "file body" no.
- Register/unregister cleanly on lifecycle events to avoid duplicates —
RegisterProvideron init,UnregisterProviderif your provider has a lifetime.
User-facing surfaces
- Context-parameter components in
SmartHopper.Components(AI >subcategory) let users supply or inspect context data on the canvas — useful for debugging what a request will see. - The canvas assistant docs describe the context users experience (
time, environment, file, selection, viewport).