Plugin Hub Implementation Checklist

Status: closed for the sfmapi-side registry, entry-point discovery, install planning, CLI, operator API, benchmark validation, and provider-routing contract.

Product Contract

  • Keep sfmapi as the main interaction point for users.

  • Keep sfm_hub as the registry, manifest, resolver, and validation package.

  • Support multiple installed plugins in one sfmapi environment.

  • Support enabled/disabled plugin state separate from installation.

  • Support provider priority and named routing profiles in local state.

  • Support default, workspace, and project routing profile scopes.

  • Require request-level provider to override defaults.

  • Return a clear ambiguity error when several providers can satisfy a stage.

  • Keep plugin install, enable, and doctor operations under CLI or admin API scope.

  • Prevent public SfM job APIs from silently installing plugins.

Implemented Surfaces

  • sfm_hub Python package.

  • sfm_hub/schemas/backend-plugin.schema.json.

  • sfm_hub/registry/backends/*/manifest.json.

  • Manifest validation through typed Pydantic models.

  • Registry search and info helpers.

  • Installed Python entry-point discovery for [project.entry-points."sfmapi.backends"].

  • Optional entry-point backend loading through SFMAPI_AUTO_LOAD_BACKEND_PLUGINS=true.

  • GitHub-link parser for plugin sources.

  • uv direct-reference install-plan generation.

  • Docker install-plan generation.

  • External-tool install plans and runtime metadata in manifests.

  • External tool detection through PATH and configured env vars, including version checks.

  • HTTP install execution hardened behind allow_unsafe_execution=true; dry-run remains default.

  • Plugin doctor checks.

  • Conformance metadata fields.

  • Benchmark-side plugin validation with python -m bench.cli plugins.

  • Tests for schema coverage, GitHub parsing, install plans, entry points, API, CLI, and routing.

Manifest Fields

Every bundled manifest includes plugin_id, display_name, description, package_name, github_url, entry_points, providers, runtime_modes, capabilities, backend_actions, config_schemas, artifact_contracts, licenses, upstream_projects, compatibility, conformance, and trust_tier.

GitHub Install Contract

  • Registry entries install from GitHub URLs.

  • Branch, tag, and commit refs are accepted.

  • Mutable refs such as main produce warnings.

  • uv install commands use direct references.

  • Docker install plans emit docker pull or docker build commands when metadata exists.

  • Commit SHA refs are recorded as resolved commits in local state.

Example:

sfmapi plugins install colmap_cli --method uv --dry-run
sfmapi plugins install local_test \
  --github https://github.com/SFMAPI/sfmapi_custom.git@v0.1.0 \
  --package sfmapi-custom --dry-run

sfmapi CLI

  • sfmapi plugins list

  • sfmapi plugins search <query>

  • sfmapi plugins info <plugin_id>

  • sfmapi plugins install <plugin_id> --method uv

  • sfmapi plugins install <plugin_id> --github <url>

  • sfmapi plugins install <plugin_id> --method docker

  • sfmapi plugins enable <plugin_id>

  • sfmapi plugins disable <plugin_id>

  • sfmapi plugins doctor <plugin_id>

  • sfmapi plugins detect-tools

  • sfmapi plugins entry-points

  • sfmapi providers list

  • sfmapi profiles list

  • sfmapi profiles create <name>

  • sfmapi profiles set-default <name>

  • sfmapi profiles assign-project <project_id> <name>

  • sfmapi profiles assign-workspace <name>

  • sfmapi serve --profile <name>

  • sfmapi check-backend --load-entry-points

sfmapi API

  • GET /v1/backend/providers

  • GET /v1/backend/routing

  • GET /v1/backend/config-schemas

  • GET /v1/backend/artifact-contracts

  • GET /v1/admin/plugins

  • GET /v1/admin/plugins/entry-points

  • GET /v1/admin/plugins/{plugin_id}

  • POST /v1/admin/plugins/{plugin_id}:doctor

  • POST /v1/admin/plugins/{plugin_id}:install

  • POST /v1/admin/plugins/{plugin_id}:enable

  • POST /v1/admin/plugins/{plugin_id}:disable

  • POST /v1/admin/routing/profiles

  • POST /v1/admin/routing/default

  • POST /v1/admin/routing/projects/{project_id}

  • POST /v1/admin/routing/workspaces

Provider Resolution

  • Check request-level provider.

  • Check project-specific routing profile.

  • Check workspace-specific routing profile.

  • Check the default routing profile.

  • Check global provider priority.

  • Return an ambiguity error with candidate providers and a suggested fix.

  • Keep clean installs working with no plugin state and the stub backend.

Initial Hub Entries

Plugin id

Providers

GitHub source

Runtime modes

colmap_cli

colmap_cli

https://github.com/SFMAPI/sfmapi_colmap_cli.git

uv, external_tool, docker

pycolmap

colmap_pycolmap

https://github.com/SFMAPI/sfmapi_pycolmap.git

uv, docker

colmap_native

colmap_cli, colmap_pycolmap, colmap_cpp_native, colmap_cpp_inmemory

https://github.com/SFMAPI/sfmapi_colmap.git

uv, external_tool, docker

realityscan_cli

realityscan_cli

https://github.com/SFMAPI/sfmapi_realityscan.git

uv, external_tool

hloc

hloc

https://github.com/SFMAPI/sfmapi_hloc.git

uv, docker

instantsfm

instantsfm

https://github.com/SFMAPI/sfmapi_instantsfm.git

uv, docker

spheresfm

spheresfm

https://github.com/SFMAPI/sfmapi_spheresfm.git

uv, external_tool, docker

Backend App Adoption Contract

Backend app repositories should expose plugin.py, a typed plugin object, [project.entry-points."sfmapi.backends"], provider ids matching the manifest, config schemas, artifact contracts, doctor checks, GitHub install metadata, optional Docker metadata, external-tool detection where applicable, and tests for manifest validation, entry-point discovery, provider registration, and API discovery.

Entry-point plugin objects are executable contracts now, not just documentation. They may expose manifest, get_plugin_manifest(), register(register_backend), register_backend(register_backend), backend_factory, or be a callable backend factory. sfmapi plugins entry-points --load, sfmapi check-backend --load-entry-points, and python -m bench.cli plugins --require-entry-points validate adoption.

Validation Commands

uv run pytest tests/unit/test_plugin_hub.py tests/unit/test_plugin_api.py tests/unit/test_plugin_cli.py -q
uv run ruff check sfm_hub app/cli.py app/api/v1/admin.py app/api/v1/backend.py app/schemas/api/plugins.py app/services/plugin_service.py app/services/provider_routing_service.py bench/cli.py tests/unit/test_plugin_hub.py tests/unit/test_plugin_api.py tests/unit/test_plugin_cli.py
uv run python -m bench.cli plugins
uv run sphinx-build -b html docs docs/_build/html