HuggingFace OpenPets Plugin

A comprehensive OpenPets plugin for HuggingFace, providing full access to the HuggingFace Hub and Inference APIs. This plugin enables AI assistants to search models and datasets, manage repositories, upload files, and run various inference tasks.

Architecture

The plugin is organized into modular components:

huggingface/
├── index.ts              # Main plugin with core tools (always loaded)
├── src/
│   ├── text-inference.ts # Text inference tools (optional)
│   ├── image-inference.ts # Image inference tools (optional)
│   └── audio-inference.ts # Audio inference tools (optional)
├── package.json
└── README.md

Core tools (models, datasets, repos, files) are always available. Inference modules are disabled by default and can be enabled via environment variables when needed.

Features

Core Tools (Always Available)

Model Operations

• huggingface-list-models: Search and list models with filtering by author, task, and more
• huggingface-get-model-info: Get detailed information about specific models

Dataset Operations

• huggingface-list-datasets: Search and list datasets with filtering options
• huggingface-get-dataset-info: Get detailed dataset information

Repository & File Operations

• huggingface-create-repo: Create new model, dataset, or space repositories
• huggingface-list-files: List files in any repository
• huggingface-upload-file: Upload files to repositories
• huggingface-delete-files: Delete files from repositories

User Operations

• huggingface-test-connection: Test API connection and configuration
• huggingface-whoami: Get current user profile information

Text Inference Module (src/text-inference.ts)

• huggingface-text-generation: Generate text with language models
• huggingface-chat-completion: Chat completion with conversational models
• huggingface-translation: Translate text between languages
• huggingface-summarization: Summarize long texts
• huggingface-question-answering: Answer questions based on context
• huggingface-fill-mask: Fill masked tokens in text
• huggingface-text-classification: Classify text into categories
• huggingface-token-classification: NER and POS tagging
• huggingface-zero-shot-classification: Classify without training
• huggingface-sentence-similarity: Compare sentence similarity
• huggingface-feature-extraction: Extract text embeddings

Image Inference Module (src/image-inference.ts)

• huggingface-text-to-image: Generate images from text prompts
• huggingface-image-to-text: Generate captions from images
• huggingface-image-classification: Classify images
• huggingface-object-detection: Detect objects in images

Audio Inference Module (src/audio-inference.ts)

• huggingface-automatic-speech-recognition: Transcribe audio to text

Quick Start

1. Get Your API Key

1. Go to HuggingFace Settings
2. Create a new access token with appropriate permissions:
   • Read: For listing models, datasets, and running inference
   • Write: For creating repos and uploading files

2. Configure Environment

Create a .env file in your project or set the environment variable:

HUGGINGFACE_API_KEY=hf_your_token_here

Optional configuration:

# Default inference provider (auto, sambanova, together, fal-ai, replicate, cohere)
HUGGINGFACE_INFERENCE_PROVIDER=auto

# Enable inference modules (all disabled by default)
# Set to "true" to enable specific inference capabilities
HUGGINGFACE_ENABLE_TEXT_INFERENCE=true
HUGGINGFACE_ENABLE_IMAGE_INFERENCE=true
HUGGINGFACE_ENABLE_AUDIO_INFERENCE=true

3. Test Connection

opencode run "test my huggingface connection"

Usage Examples

Search Models

opencode run "search for text generation models"
opencode run "list models by meta-llama"
opencode run "find image classification models, limit 10"

Model Information

opencode run "get details for meta-llama/Llama-3.1-8B-Instruct"
opencode run "show info about stabilityai/stable-diffusion-2"

Text Generation

opencode run "generate text with gpt2 using prompt 'Once upon a time'"
opencode run "chat completion with meta-llama/Llama-3.1-8B-Instruct: What is machine learning?"

Image Generation

opencode run "generate image with stabilityai/stable-diffusion-2 prompt 'a beautiful sunset over mountains'"

Translation

opencode run "translate 'Hello, how are you?' to French"

Repository Management

opencode run "create a new model repository called my-awesome-model"
opencode run "list files in meta-llama/Llama-3.1-8B-Instruct"
opencode run "upload README.md with content 'My Model' to my-awesome-model"

Tool Reference

huggingface-test-connection

Test the API connection and return user information.

Parameters: None

huggingface-whoami

Get current user profile information.

Parameters: None

huggingface-list-models

Search and list models.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | search | string | No | Search query | | author | string | No | Filter by author | | task | string | No | Filter by task (e.g., text-generation) | | limit | number | No | Max results (default: 20) |

huggingface-get-model-info

Get detailed model information.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | modelId | string | Yes | Model ID (e.g., meta-llama/Llama-3.1-8B-Instruct) |

huggingface-list-datasets

Search and list datasets.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | search | string | No | Search query | | author | string | No | Filter by author | | limit | number | No | Max results (default: 20) |

huggingface-create-repo

Create a new repository.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | repoId | string | Yes | Repository ID (username/repo-name) | | repoType | enum | No | Type: model, dataset, space (default: model) | | private | boolean | No | Private repository (default: false) | | license | string | No | License identifier |

huggingface-upload-file

Upload a file to a repository.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | repoId | string | Yes | Repository ID | | filePath | string | Yes | Path in repository | | content | string | Yes | File content | | repoType | enum | No | Type: model, dataset, space | | commitMessage | string | No | Git commit message |

huggingface-text-generation

Generate text with a language model.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | model | string | Yes | Model ID | | inputs | string | Yes | Input prompt | | maxNewTokens | number | No | Max tokens to generate | | temperature | number | No | Sampling temperature | | topP | number | No | Top-p sampling | | topK | number | No | Top-k sampling |

huggingface-chat-completion

Chat completion with conversational format.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | model | string | Yes | Model ID | | messages | string | Yes | JSON array of {role, content} messages | | maxTokens | number | No | Max tokens | | temperature | number | No | Sampling temperature |

huggingface-text-to-image

Generate images from text.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | model | string | Yes | Model ID | | inputs | string | Yes | Text prompt | | negativePrompt | string | No | What to avoid | | height | number | No | Image height | | width | number | No | Image width | | numInferenceSteps | number | No | Denoising steps | | guidanceScale | number | No | Guidance scale |

Popular Models

Text Generation

• meta-llama/Llama-3.1-8B-Instruct
• mistralai/Mistral-7B-Instruct-v0.2
• gpt2

Image Generation

• stabilityai/stable-diffusion-2
• black-forest-labs/FLUX.1-dev
• runwayml/stable-diffusion-v1-5

Translation

• Helsinki-NLP/opus-mt-en-fr (English to French)
• Helsinki-NLP/opus-mt-fr-en (French to English)

Summarization

• facebook/bart-large-cnn
• sshleifer/distilbart-cnn-12-6

Question Answering

• deepset/roberta-base-squad2
• distilbert-base-cased-distilled-squad

Speech Recognition

• openai/whisper-large-v3
• facebook/wav2vec2-base-960h

Error Handling

The plugin returns structured JSON responses:

Success:

{
  "success": true,
  "data": "...",
  "message": "Operation completed"
}

Error:

{
  "success": false,
  "error": "Error message",
  "details": {
    "operation": "operation name",
    "error": "detailed error"
  }
}

Troubleshooting

"Plugin not configured"

Ensure HUGGINGFACE_API_KEY is set in your environment.

"Model not found"

Check the model ID is correct and publicly accessible, or that your token has access to private models.

"Rate limit exceeded"

HuggingFace has rate limits on the free tier. Consider using a paid plan or reducing request frequency.

"Inference timeout"

Some models take longer to load. Retry after a few seconds, or use a dedicated Inference Endpoint.

License

MIT License

Links

• HuggingFace
• HuggingFace API Docs
• HuggingFace Hub JS
• OpenPets