feat: support loading shims from external sources

[Oaklight]

Context

PR #272 added load_providers_from_dir() and entry-point plugin discovery. These work well for packages that pip install alongside llm-rosetta, but there are use cases where shims live outside any installed package:

• Users who write custom provider shims but don't want to publish a Python package
• Organizations that maintain private shim collections in internal repos
• Community-contributed shim directories on GitHub
• Gateway deployments that want to configure shim sources in config.jsonc without code changes

This issue tracks how to make external shim loading a first-class feature.

Current state

Method	Status	Use case
Built-in providers/ directory	✅ shipped	llm-rosetta's own shims
load_providers_from_dir(path)	✅ shipped (#272)	Programmatic loading from local path
Entry-point llm_rosetta.shim_providers	✅ shipped (#272)	pip-installable plugin packages
Gateway config-driven loading	❌ not yet	Declarative, no code needed
Remote URL / GitHub loading	❌ not yet	Community sharing

Proposed approaches

1. Gateway shim_sources config field

{
  "shim_sources": [
    "/opt/my-custom-shims",
    "github://Oaklight/argo-proxy/src/argoproxy/shims@master",
    "git+https://github.com/user/my-llm-shims.git@v1.0#path=providers/"
  ]
}

The gateway loads these at startup after built-in shims. Admin panel shows the source of each shim.

2. Remote source resolution

For URL-based sources, clone/fetch to a local cache:

~/.cache/llm-rosetta/shims/<source-hash>/

Considerations:

• YAML-only shims (no transforms.py): safe to fetch from any URL, no code execution
• Shims with transforms.py: require trust — transforms.py is arbitrary Python. Options:
  • Only allow from git clone (user explicitly cloned)
  • Require --trust-remote-transforms flag
  • YAML-only mode by default, skip transforms.py from remote sources unless opted in
• Cache invalidation: TTL-based, manual refresh via admin panel, or ref-pinned (@v1.0)
• Offline fallback: use cached version if remote is unreachable

3. Unified loader API

def load_providers_from_source(
    source: str | Path,
    *,
    trust_transforms: bool = False,
) -> list[ProviderShim]:
    """Load shims from local path, GitHub URL, or git URL."""

Dispatches based on source format:

• Path or plain string → load_providers_from_dir()
• github://... → fetch directory listing via GitHub API, download YAMLs
• git+https://... → git clone --depth 1 to cache

4. Admin panel integration

• Show shim source (built-in / plugin / local path / remote URL) in the provider list
• Allow refresh/re-fetch of remote shim sources
• Visual indicator for shims loaded from untrusted remote sources

Security considerations

• transforms.py = arbitrary Python = RCE risk from untrusted sources
• Default to YAML-only for remote sources; require explicit opt-in for transforms
• Log warnings when loading transforms from non-builtin sources
• Never auto-update cached remote shims without user action

Out of scope (for now)

• Shim marketplace / registry
• Versioned shim dependencies
• Automatic conflict resolution between multiple sources

Related

• Add plugin shim loader via entry points #272 — plugin shim loader (foundation)
• docs: Provider reasoning capability probing matrix and documentation #267 — provider reasoning documentation
• argo-proxy feat: structured logging with JSON output option #126 — shim integration (consumer of this feature)