hfsearch

A Python library and CLI tool to search for models and datasets on the Hugging Face Hub.

Installation

Install from PyPI:

pip install hfsearch

Or install from source:

git clone https://github.com/yourusername/hfsearch.git
cd hfsearch
pip install -e .

Usage

As a Library

from hfsearch import search_models, search_datasets, export_to_csv

# Search for models
results = search_models(query="bert", limit=10)
print(f"Found {len(results)} models")
for model in results:
    print(f"{model['id']} - {model['author']}")

# Search for datasets
datasets = search_datasets(query="sentiment", limit=5)
for dataset in datasets:
    print(f"{dataset['id']} - Downloads: {dataset['downloads']}")

# Export results
export_to_csv(results, "Model", "results.csv")

As a CLI Tool

After installation, use the hfsearch command:

# Search for models
hfsearch models --query "bert"

# Search with filters
hfsearch models --query "translation" --limit 20 --author "google"

# Search datasets
hfsearch datasets --query "sentiment" --limit 15

# Export results
hfsearch models --query "bert" --export
hfsearch models --query "bert" --export --export-format txt

Features

• Search Models: Find models by keywords, author, tags, or task
• Search Datasets: Find datasets by keywords, author, or tags
• Export Results: Export search results to CSV or TXT files
• Beautiful Output: Formatted terminal output with Rich
• Python API: Use as a library in your Python projects

CLI Examples

Search Models

# Search by keyword
hfsearch models --query "bert"

# Search with limit
hfsearch models --query "translation" --limit 20

# Filter by author
hfsearch models --author "google" --limit 5

# Filter by tags
hfsearch models --tags "text-classification" "pytorch"

# Filter by task
hfsearch models --task "text-classification"

# Combine filters
hfsearch models --query "bert" --author "google" --limit 10

Search Datasets

# Search by keyword
hfsearch datasets --query "sentiment"

# Filter by tags
hfsearch datasets --tags "text-classification" --limit 15

# Filter by author
hfsearch datasets --author "huggingface"

Export Results

# Export to CSV (default)
hfsearch models --query "bert" --export

# Export to TXT
hfsearch models --query "bert" --export --export-format txt

API Reference

search_models(query=None, limit=10, author=None, tags=None, task=None)

Search for models on Hugging Face Hub.

Parameters:

• query (str, optional): Search query/keywords
• limit (int): Maximum number of results (default: 10)
• author (str, optional): Filter by author/organization
• tags (list, optional): Filter by tags
• task (str, optional): Filter by task (e.g., "text-classification")

Returns:

• List of dictionaries with keys: id, author, downloads, likes, tags

search_datasets(query=None, limit=10, author=None, tags=None)

Search for datasets on Hugging Face Hub.

Parameters:

• query (str, optional): Search query/keywords
• limit (int): Maximum number of results (default: 10)
• author (str, optional): Filter by author/organization
• tags (list, optional): Filter by tags

Returns:

• List of dictionaries with keys: id, author, downloads, likes, tags

export_to_csv(results, result_type, filename)

Export results to a CSV file.

Parameters:

• results (list): List of result dictionaries
• result_type (str): "Model" or "Dataset"
• filename (str): Output filename

export_to_txt(results, result_type, filename)

Export results to a text file.

Parameters:

• results (list): List of result dictionaries
• result_type (str): "Model" or "Dataset"
• filename (str): Output filename

Requirements

• Python 3.7+
• huggingface_hub>=0.20.0 - For accessing Hugging Face Hub API
• rich>=13.0.0 - For beautiful terminal output

Notes

• The tool uses the Hugging Face Hub API, so you need an internet connection
• For downloading models, use the official huggingface-cli download command
• Authentication is optional but recommended for private models/datasets

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Links

• GitHub: https://github.com/HenokB/hfsearch
• PyPI: https://pypi.org/project/hfsearch/