Skip to content

docs(providers): keep specialized providers as explicit instances - #53

Merged
offendingcommit merged 1 commit into
mainfrom
feat/declarative-providers
Nov 13, 2026
Merged

offendingcommit merged 1 commit into
mainfrom
feat/declarative-providers

Conversation

@offendingcommit

Copy link
Copy Markdown
Owner

Resolves the open question in #22: specialized providers stay explicit instances passed through memory_providers=, image_gen_providers= and video_gen_providers=. No declaration decorator is added.

Why

  • A provider is one stateful instance the plugin builds, often only when a runtime policy allows it. The plugin already evaluates that policy for its other surfaces; the only consumer, hermes-plugin-mempalace, gates its provider in one line: () if policy.read_only else (MemPalaceMemoryProvider(),).
  • A decorator would move that gate rather than remove it, construct the instance itself (assuming a no-argument constructor), and add a second activation mechanism beside resolve_capability_selection.
  • @tool, @hook and @platform declare things the host calls or constructs; providers are a different shape, so the asymmetry is the contract, not a gap.

Decided with the owner on 2026-11-13 over two alternatives: a class decorator (@memory_provider(enabled=...)) and a typed plugin_provider(...) declaration.

Changes

  • README "Subagents and specialized providers": why there is no decorator, with the gated-tuple pattern.
  • Authoring skill reference: a "Specialized provider" surface-map row; the "does not own" list now separates provider behaviour from the registration the kit does forward.
  • AGENTS.md: a working rule recording the decision.
  • tests/test_testing_harness.py: the public-surface guard treats MemoryProvider, ImageGenProvider and VideoGenProvider as host-owned, as it already does ContextEngine.

No runtime code changes. The survey found nothing to build.

Verification

mise run test: 330 run, 26 skipped, EXIT=0.

Closes: #22

https://claude.ai/code/session_01B6XeAWUPdrx34tr5dTg5dY

Issue 22 asked whether memory, image and video providers should get a
declaration decorator like @tool or @platform. They should not. A provider is
one stateful instance the plugin builds, often behind a runtime policy the
plugin already evaluates for its other surfaces; its only consumer gates it in
one line. A decorator would construct the instance itself, assume a
no-argument constructor, and add a second activation gate.

README and the authoring skill now say so and show the gated tuple. The skill's
surface map gains a specialized-provider row, its "does not own" list no longer
reads as if the kit had no provider path, AGENTS.md records the decision, and
the public-surface guard treats the three provider ABCs as host-owned.

Closes: #22

Claude-Session: https://claude.ai/code/session_01B6XeAWUPdrx34tr5dTg5dY
@offendingcommit
offendingcommit merged commit bcf939f into main Nov 13, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Explore declarative registration for specialized providers

1 participant