Skip to content

Component: Smrt.Tools.ProviderDoctor

Canonical source: SmrtApps/src/Smrt.Tools.ProviderDoctor/README.md (mirrored below)

Smrt.Tools.ProviderDoctor

Overview & Responsibilities

Smrt.Tools.ProviderDoctor is a CLI harness used to: - Seed and edit SmrtHub cloud provider config/state (cloud-providers-*) without requiring a full UI. - Store and clear provider secrets in Windows Credential Manager (never in JSON config/state). - Run connection tests for specific vendor/services. - Exercise local-only structured extraction (doc-local) without any cloud calls.

Platform note: - This tool targets net8.0-windows10.0.19041.0 because it references Windows-specific host projects (for example Smrt.ExtractStructuredText.Host).

Non-Responsibilities

  • Does not replace the Settings UI (it is a developer/operator harness).
  • Does not embed vendor SDKs; vendor calls are performed via the shared provider library.

Public Surface / Entry Points

  • Entry point: Smrt.Tools.ProviderDoctor.Program.
  • Key commands (see help output for the authoritative list):
  • paths
  • options-init
  • options-show
  • options-validate
  • options-open
  • requirements
  • profile-upsert
  • profile-rename
  • service-enable
  • service-setting-set / service-setting-clear
  • secret-set / secret-clear
  • test-service
  • discover-models
  • onboard
  • onboard-service
  • test
  • route
  • doc-local

Dependencies / Integrations

  • Smrt.CloudProviders for config/state + routing + connection tests + secret discipline.
  • Smrt.CloudProviders.Contracts for vendor/service/capability IDs.
  • SmrtHub.Config for canonical config/state paths.
  • Smrt.ExtractStructuredText + host executors for doc-local local-only structured extraction.

Configuration, Operational Data, and Paths

Provider config/state (owned by Smrt.CloudProviders): - %AppData%/SmrtHub/Config/cloud-providers/cloud-providers-config.json - %AppData%/SmrtHub/Config/cloud-providers/cloud-providers-state.json

ProviderDoctor connection-test options (non-secret; used to provide endpoint URIs for some tests): - %AppData%/SmrtHub/Config/smrt-provider-doctor/smrt-provider-doctor-config.json

Notes: - Secrets are stored in Windows Credential Manager under canonical targets managed by Smrt.CloudProviders. - The options file contains only non-secret endpoint URIs; ProviderDoctor provides commands to show/validate/open it.

Observability and Diagnostics

  • This tool writes console output for interactive/operator usage.
  • Do not add logging that could emit secrets; secrets should never be printed.

Build

  • Use the repo build scripts/tasks (preferred). This project is intended to be built for win-x64 per the Architecture & Platform Policy.

Testing & Validation

Unit tests (command parsing)

  • dotnet test SmrtApps/tests/Smrt.Tools.ProviderDoctor.Tests/Smrt.Tools.ProviderDoctor.Tests.csproj -c Debug -r win-x64

Non-mutating smoke validation (no writes)

The commands below are designed to be read-only and avoid creating/modifying SmrtHub config/state/secrets.

Note: Many ProviderDoctor commands load Smrt.CloudProviders config/state. If those files are missing, Smrt.CloudProviders may seed defaults (write) on first load. The commands below avoid that code path.

Copy/paste (PowerShell):

  • Print canonical file locations (exit code: 0):
  • dotnet run --project SmrtApps/src/Smrt.Tools.ProviderDoctor/Smrt.Tools.ProviderDoctor.csproj -c Debug -- paths
  • Validate endpoint-options file shape (exit code: 0 if valid; 2 if missing/invalid):
  • dotnet run --project SmrtApps/src/Smrt.Tools.ProviderDoctor/Smrt.Tools.ProviderDoctor.csproj -c Debug -- options-validate
  • Show endpoint-options values with query strings stripped (exit code: 0):
  • dotnet run --project SmrtApps/src/Smrt.Tools.ProviderDoctor/Smrt.Tools.ProviderDoctor.csproj -c Debug -- options-show
  • Print requirement keys for a specific vendor/service (exit code: 0; prints keys only):
  • dotnet run --project SmrtApps/src/Smrt.Tools.ProviderDoctor/Smrt.Tools.ProviderDoctor.csproj -c Debug -- requirements OpenAI OpenAI

Preferred validation path (enterprise-grade, repeatable): - Run options-init once to seed non-secret connection-test endpoints (see paths). - Run options-validate to confirm all endpoints are valid absolute URIs and contain no query strings. - Use options-show to view the configured endpoint values (query strings are never printed). - Use options-open to open the options file in your default editor. - Use requirements <vendor> <serviceId> to print the required secret/setting/option keys for a specific service (keys only). - Use profile-rename <vendor> <oldProfileId> <newProfileId> --dry-run to preview a profile ID migration plan. - Use profile-rename <vendor> <oldProfileId> <newProfileId> to migrate a profile ID across config/state and migrate known secrets. - Use onboard <provider> for guided setup, which stores secrets in Windows Credential Manager and runs a metadata-only connection test. - Use onboard-service <vendor> <profileId> <serviceId> for requirements-based setup (vendor/service driven, prompts for missing required settings and missing required secrets). - Use test-service <vendor> <profileId> <serviceId> to re-run and persist the latest connection test result into provider state.

Notes: - Profile concept: - A “profile” is an isolation boundary for a given vendor (work/personal, dev/prod, billing accounts, etc.). - Profiles are vendor-scoped, so it is normal to have work for multiple vendors. - Prefer keeping profileId stable and using displayName for friendly naming. - Important: profileId is part of the Windows Credential Manager secret target name; renaming it requires migrating secrets. - If a connection test requires non-secret endpoint URIs and those values are missing/invalid, tests return NotConfigured with a details list (e.g., options: OpenAiModelsUri). - During onboarding/tests, ProviderDoctor pre-checks for required endpoint options and can offer to create the options file using bundled defaults (options-init). - When required endpoint values are missing/invalid, ProviderDoctor can also prompt to enter the missing values interactively (non-secrets) and will validate https URLs without query strings/fragments. - Use --local to validate configuration without making any network calls. - Onboarding service selection accepts either numeric menu choices or service names. - Azure OpenAI onboarding requires an endpoint + deployment non-secret setting, plus an api-key secret. - onboard azure can onboard ComputerVision + DocumentIntelligence in a single run (shared endpoint + shared api-key secret for the profile). If you need different keys per Azure service, use separate profiles. - onboard aws can enable Bedrock, Textract, or both in a single run (shared credentials + shared region; tests use STS GetCallerIdentity). - For large secrets (for example Google service account JSON), prefer reading from a file path when prompted (or use secret-set ... --file <path>).

Support Bundle

  • Not applicable directly (this tool is not a long-running service).
  • When diagnosing provider behavior, use Support Bundles from the host app(s) and include provider config/state.
  • vNext plan checklist: README.Files/SmrtHub-vNext-Architecture/Plans/Smrt.Tools.ProviderDoctor.plan.md
  • Providers spine: README.Files/SmrtHub-vNext-Architecture/Plans/Smrt.CloudProviders.plan.md
  • Cloud Providers core: SmrtApps/src/Smrt.CloudProviders/README.md
  • Cloud Providers UI: SmrtApps/src/Smrt.CloudProviders.UI.WinUI3/README.md