Skip to main content

Provider architecture

AI providers are how SmartHopper reaches external AI services — OpenAI, Anthropic, Gemini, and local servers like Ollama. The important architectural fact: providers are plugins, not part of the host. Each one is a separate SmartHopper.Providers.<Name>.dll assembly discovered at runtime, which is why SmartHopper can support providers nobody has written yet.

The ProviderSdk boundary​

Everything a provider needs to implement or call lives in SmartHopper.ProviderSdk — a standalone, MIT-licensed package so community authors can build providers (even closed-source ones) without the SmartHopper repo or its LGPLv3 license.

In the SDK (what providers get):

  • Contracts: IAIProvider, IAIProviderFactory, IAIProviderSettings, IAIProviderModels
  • Base classes: AIProvider, AIProvider<T> (singleton base), OpenAICompatibleProvider<T>, AIProviderSettings, AIProviderModels, AIProviderStreamingAdapter
  • All the AICall types: interactions, AIBody, AIRequestCall, AIReturn, AIMetrics
  • Capability/model types: AICapability, AIModelCapabilities, AIModelPricing
  • Settings descriptors: SettingDescriptor, AIExtraDescriptor
  • Compatibility attributes: SmartHopperProviderId, BuiltAgainstSdk, MinHostSdk
  • Host-injected services the provider receives: IProviderSettingsStore, IProviderHttpClientFactory, IProviderRegistryHost, IContextProviderHost, IPolicyPipelineHost, IToolRegistryHost, logging

Deliberately NOT in the SDK (what stays in the host): ProviderManager, trust/integrity verification, settings dialogs and persistence, ConversationSession, the policy pipeline, the tool registry, and all UI. Providers call into the host through the Hosting/ interfaces — never the other way around.

Discovery and loading​

ProviderManager (src/SmartHopper.Infrastructure/AIProviders/) finds provider assemblies matching SmartHopper.Providers.*.dll in one location: the app-local directory containing SmartHopper.Infrastructure.dll. Providers load into the default load context via Assembly.LoadFrom (a dedicated ProviderLoadContext for isolation exists in the codebase but isn't wired in yet).

README vs. code

The SmartHopper.ProviderSdk README also describes a user-local drop-in (%AppData%\SmartHopper\Providers\ / ~/.config/SmartHopper/Providers\). That path isn't implemented — app-local only today. It also describes SDK-version attributes and AssemblyLoadContext isolation as if live; both exist as code (SdkCompatibility, ProviderLoadContext, ProviderClassifier) but are not invoked by ProviderManager.

Integrity and trust​

Before a provider is usable, the load path applies:

1. Signature match (Windows only). The provider's Authenticode certificate and strong-name public key token must match the host's byte-for-byte — effectively restricting loadable providers to officially built ones on Windows. Skipped on macOS (warning logged). Community providers therefore can't load on Windows today; macOS and DEBUG builds are where a self-built provider can get through.

2. SHA-256 hash verification against the official published-hash repository → Match / Mismatch / Unavailable / NotFound. ProviderIntegrityCheckMode decides: Strict/Hard block on anything but Match; Soft warns and allows (DEBUG forces Soft).

3. Trust prompt. An assembly with no TrustedProviders entry triggers "A new AI provider was detected — enable it?"; the answer persists in settings. isOfficial (hash match or host key-token match) and isUnsigned flags feed warning surfaces.

The stronger machinery — BuiltAgainstSdk/MinHostSdk SDK-version gating, AssemblyLoadContext isolation, and a formal Official/Community/Invalid classification — is implemented but not invoked, so treat it as the intended model rather than current enforcement. See the security reference for the user-facing trust model.

Lifecycle​

Once loaded and trusted, a provider is a singleton (AIProvider<T> exposes Instance). Per-request, the host drives the call lifecycle:

IsValid → PreCallAsync → Encode → CallApi/Call (HTTP) → Decode → PostCall → AIReturn

The provider only owns the middle of that — wire encoding, the API dialect, and decoding. Validation, model selection, context injection, tool loops, streaming orchestration, policies, and metrics plumbing are all host-side. That's why a provider implementation is mostly an Encode/Decode pair.

Settings​

Providers declare their configuration surface as SettingDescriptors (API key, model, temperature…). The host renders the settings dialog from those descriptors, validates via ValidateSettings, and stores values through IProviderSettingsStore — IsSecret = true values go to OS secure storage, never plain files. Providers read values back with GetSetting<T>("Name"). Details: Provider settings.

The four files of a provider​

A provider project is small — four classes do all the work:

FileImplementsPurpose
XyzProvider.csAIProvider (or OpenAICompatibleProvider<T>)Name, Icon, DefaultServerUrl, IsEnabled, IsConfigured, Encode, Decode
XyzProviderModels.csAIProviderModelsRetrieveModels() — models + capabilities
XyzProviderSettings.csAIProviderSettingsGetSettingDescriptors(), ValidateSettings()
XyzProviderFactory.csIAIProviderFactoryCreateProvider(), CreateProviderSettings() — the entry point discovery reflects over

Continue to Writing a provider for the step-by-step implementation.