Plugin Ecosystem

Docket adapters are just npm packages. Anyone can create one, publish it, and let users install it with npm install and a config line.

The 30-second version

As a developer:

npm install docket-llm-groq

As a user:

adapters:
  llm:
    providers:
      groq:
        adapter: "docket-llm-groq"
        config:
          apiKey: "${GROQ_API_KEY}"

Naming convention

Community plugins should follow this pattern so users can find them and the registry can infer their category:

docket-{category}-{name}

Category	Example
LLM	docket-llm-groq
Embedder	docket-embedder-cohere
Store	docket-store-qdrant
Blob	docket-blob-s3
Queue	docket-queue-redis

Scoped packages work too:

@myorg/docket-llm-groq

Creating a plugin

1. Scaffold

mkdir docket-llm-groq
cd docket-llm-groq
npm init -y

2. Implement the interface

const { LlmAdapter } = require('docket-core/interfaces/llm-adapter');
 
class GroqLlmAdapter extends LlmAdapter {
  constructor(config) {
    super(config);
    this.client = new Groq({ apiKey: config.apiKey });
  }
 
  async chat(messages, options = {}) {
    const response = await this.client.chat.completions.create({
      model: options.model || this.config.model,
      messages,
      temperature: options.temperature ?? 0.7,
      max_tokens: options.maxTokens
    });
 
    return {
      content: response.choices[0].message.content,
      usage: {
        prompt: response.usage.prompt_tokens,
        completion: response.usage.completion_tokens,
        total: response.usage.total_tokens
      },
      finishReason: response.choices[0].finish_reason,
      model: response.model
    };
  }
 
  async health() {
    // Return { ok, latency, error? }
    return { ok: true, latency: 0 };
  }
 
  static get metadata() {
    return {
      name: 'groq-llm',
      version: '0.1.0',
      description: 'Groq LLM adapter for Docket',
      category: 'llm',
      capabilities: ['chat'],
      docketCompatibility: '>=0.1.0 <0.3.0',
      author: '[email protected]',
      repository: 'https://github.com/you/docket-llm-groq',
      license: 'MIT'
    };
  }
}
 
module.exports = { GroqLlmAdapter };

3. Required metadata fields

Field	Type	Required	Description
name	string	yes	Unique plugin identifier (kebab-case)
version	string	yes	Semver version
category	enum	yes	llm, embedder, store, blob, or queue
capabilities	string[]	yes	What the adapter can do (e.g., ['chat'])
docketCompatibility	string	yes	Semver range of supported Docket versions
description	string	no	Short human-readable description
author	string	no	Author name or email
repository	string	no	URL to source code
license	string	no	SPDX license identifier

4. Publish to npm

npm publish --access public

No special registry needed. Standard npm works.

User onboarding flow

Install the package

npm install docket-llm-groq

Add to config

# config/docket.yaml
adapters:
  llm:
    default: "groq"
    providers:
      groq:
        adapter: "docket-llm-groq"
        config:
          apiKey: "${GROQ_API_KEY}"
          model: "llama3-70b-8192"

Validate without restarting

curl -X POST http://localhost:3001/admin/plugins/validate \
  -H "Content-Type: application/json" \
  -d '{"packageName": "docket-llm-groq"}'

Register at runtime

curl -X POST http://localhost:3001/admin/plugins \
  -H "Content-Type: application/json" \
  -d '{
    "packageName": "docket-llm-groq",
    "config": { "apiKey": "gsk_...", "model": "llama3-70b-8192" }
  }'

Runtime plugin management

The control plane exposes endpoints to manage plugins without editing code:

Method	Route	Purpose
GET	/admin/plugins	List registered plugins
POST	/admin/plugins/validate	Validate a package without registering
POST	/admin/plugins	Register and initialize a plugin
DELETE	/admin/plugins/:category/:name	Deregister a plugin

For package authors: best practices

1. Export a single class — The registry loads the first class-like export it finds.
2. Implement health() — Return { ok, latency, error? } so the control plane can aggregate status.
3. Handle missing config gracefully — Throw clear errors in initialize() if required config is missing.
4. Document config options — Users should know what to put in the config: block.
5. Pin docketCompatibility — Be honest about which Docket versions you support.
6. Use semantic versioning — Breaking changes = major version bump.

Coming soon

• Plugin marketplace — Curated list of community adapters
• CLI onboarding — docket plugin install groq instead of npm install
• Verified badge — Adapters that pass extended contract tests
• Auto-discovery — Scan node_modules for docket-* packages and suggest them