Upload SEARCH_GUIDE.md with huggingface_hub

SEARCH_GUIDE.md

@@ -0,0 +1,135 @@
+# Hub search: URLs and Python
+
+This guide shows how to search models, datasets, and Spaces using **URL parameters** and the **Python library** (`huggingface_hub`). Use it to find repos by tag, author (user or org), and more.
+
+---
+
+## 1. Search by URL
+
+You can build URLs that pre-fill the Hub search. There is no UI to build these yet, so you construct the URL manually.
+
+### Main parameters
+
+| Parameter   | Meaning                                      | Example                          |
+|------------|-----------------------------------------------|----------------------------------|
+| `other`    | Tags (comma-separated for multiple)          | `other=hunyuan` or `other=hunyuan,conversational` |
+| `author`   | User or org that owns the repo               | `author=netflix` or `author=tencent-community`   |
+| `search`   | Full-text search in repo name/description    | `search=bert`                   |
+
+### Models
+
+- Base URL: `https://huggingface.co/models`
+- Examples:
+  - All models with tag **hunyuan**:  
+    `https://huggingface.co/models?other=hunyuan`
+  - Models with **two tags**:  
+    `https://huggingface.co/models?other=hunyuan,conversational`
+  - Models from an **org** (e.g. tencent-community):  
+    `https://huggingface.co/models?author=tencent-community`
+  - **Tag + author**:  
+    `https://huggingface.co/models?other=hunyuan,conversational&author=tencent-community`
+
+### Datasets
+
+- Base URL: `https://huggingface.co/datasets`
+- Same idea: `other=...` for tags, `author=...` for user/org.  
+  Example:  
+  `https://huggingface.co/datasets?author=netflix`
+
+### Spaces
+
+- Base URL: `https://huggingface.co/spaces`
+- Use `filter=...` for tags (e.g. region), `author=...` for owner.  
+  Example:  
+  `https://huggingface.co/spaces?author=netflix`
+
+---
+
+## 2. Search with Python
+
+The same filters are available in `huggingface_hub`: `list_models`, `list_datasets`, `list_spaces`.  
+For **private** or **gated** repos, use a token (e.g. `token=True` or `token="hf_..."`).
+
+### List models
+
+```python
+from huggingface_hub import list_models
+
+# All models from an org (e.g. netflix – use token if private)
+for repo in list_models(author="netflix", token=True):
+    print(repo.id)  # e.g. netflix/mdeberta_512_v3_base, netflix/my-bert-model
+
+# By tag
+list_models(other="conversational")
+
+# By tag + author
+list_models(other="hunyuan,conversational", author="tencent-community")
+```
+
+### List datasets
+
+```python
+from huggingface_hub import list_datasets
+
+# All datasets from an org (use token if private)
+for repo in list_datasets(author="netflix", token=True):
+    print(repo.id)  # e.g. netflix/acrostic_poem, netflix/ifeval
+```
+
+### List Spaces
+
+```python
+from huggingface_hub import list_spaces
+
+list_spaces(author="netflix", token=True)
+```
+
+---
+
+## 3. Example: private org "netflix"
+
+If your org has these repos:
+
+- **Models:** `netflix/mdeberta_512_v3_base`, `netflix/my-bert-model`
+- **Datasets:** `netflix/acrostic_poem`, `netflix/ifeval`
+
+### URLs (logged in)
+
+- All models from netflix:  
+  `https://huggingface.co/models?author=netflix`
+- All datasets from netflix:  
+  `https://huggingface.co/datasets?author=netflix`
+
+### Python (with token for private)
+
+```python
+from huggingface_hub import list_models, list_datasets
+
+# Models
+for m in list_models(author="netflix", token=True):
+    print(m.id)
+# netflix/mdeberta_512_v3_base
+# netflix/my-bert-model
+
+# Datasets
+for d in list_datasets(author="netflix", token=True):
+    print(d.id)
+# netflix/acrostic_poem
+# netflix/ifeval
+```
+
+---
+
+## 4. Discovering tags
+
+- On a **model repo page**, the tags are listed; **clicking a tag** takes you to the models search with that tag in `other`.
+- For datasets and Spaces, you can use the same tag names you see on repo cards in the `other` or `filter` param.
+
+---
+
+## 5. Full reference
+
+- **URLs:** Build `https://huggingface.co/{models|datasets|spaces}?other=tag1,tag2&author=<namespace>`.  
+  **`author`** is the **namespace**: the org name or username (e.g. `netflix`, `tencent-community`, or a Hub username). Use the same value in URLs and in Python.
+- **Python:** [Search guide](https://huggingface.co/docs/huggingface_hub/guides/search) in the docs.
+- **Token:** For private/gated repos, use `token=True` (from env or cache) or `token="hf_..."` in Python; for URLs, be logged in on the site.