Improve model card: Add pipeline tag, library name, and usage example

README.md

@@ -1,28 +1,105 @@
 ---
-license: mit
+base_model:
+- Qwen/Qwen2.5-7B-Instruct
 language:
 - en
 - zh
-base_model:
-- Qwen/Qwen2.5-7B-Instruct
+license: mit
 tags:
 - biology
 - finance
 - text-generation-inference
+pipeline_tag: question-answering
+library_name: transformers
 ---
 
-## Model Information
+# HierSearch: A Hierarchical Enterprise Deep Search Framework Integrating Local and Web Searches
 
-We release agent model used in **HierSearch: A Hierarchical Enterprise Deep Search Framework Integrating Local and Web Searches**.
+HierSearch is a novel hierarchical agentic deep search framework presented in the paper [HierSearch: A Hierarchical Enterprise Deep Search Framework Integrating Local and Web Searches](https://huggingface.co/papers/2508.08088). It is designed for private deep search systems that can leverage search tools over both local and web corpora.
 
-<p align="left">
-Useful links: 📝 <a href="https://arxiv.org/abs/2508.08088" target="_blank">Paper</a> • 🤗 <a href="https://huggingface.co/papers/2508.08088" target="_blank">Hugging Face</a> • 🧩 <a href="https://github.com/plageon/HierSearch" target="_blank">Github</a>
+This framework addresses limitations of existing deep search works that are generally restricted to a single knowledge source. Unlike simply training an agent with multiple search tools using flat reinforcement learning (RL), HierSearch proposes a hierarchical RL approach to mitigate issues like low training data efficiency and poor mastery of complex tools. At the low level, specialized local and web deep search agents retrieve evidence from their respective domains. At the high level, a planner agent (this model) coordinates these low-level agents and provides the final answer. Furthermore, to prevent direct answer copying and error propagation, HierSearch incorporates a knowledge refiner that filters out hallucinations and irrelevant evidence.
+
+Experiments demonstrate that HierSearch achieves superior performance compared to flat RL and outperforms various deep search and multi-source retrieval-augmented generation baselines across six benchmarks in general, finance, and medical domains.
+
+<p align="center">
+  <img src="https://github.com/plageon/HierSearch/raw/main/figures/pipeline0730.png" alt="HierSearch Pipeline" width="80%">
 </p>
 
-1. We explore the deep search framework in multi-knowledge-source scenarios and propose a hierarchical agentic paradigm and train with HRL;
-2. We notice drawbacks of the naive information transmission among deep search agents and developed a knowledge refiner suitable for multi-knowledge-source scenarios;
-3. Our proposed approach for reliable and effective deep search across multiple knowledge sources outperforms existing baselines the flat-RL solution in various domains.
+## Useful Links
+
+*   📝 [Paper on arXiv](https://arxiv.org/abs/2508.08088)
+*   🤗 [Paper on Hugging Face](https://huggingface.co/papers/2508.08088)
+*   🧩 [GitHub Repository](https://github.com/plageon/HierSearch)
 
+## Key Features
+
+*   **Hierarchical Agentic Paradigm**: Employs a high-level planner agent to coordinate low-level local and web search agents, trained with hierarchical reinforcement learning.
+*   **Knowledge Refiner**: Designed to filter out hallucinations and irrelevant evidence, ensuring more reliable outputs.
+*   **Multi-Source Integration**: Capable of leveraging search tools over both local and web corpora.
+*   **Robust Performance**: Outperforms existing deep search and multi-source RAG baselines across diverse domains including general, finance, and medical.
 
 🌹 If you use this model, please ✨star our **[GitHub repository](https://github.com/plageon/HierSearch)** or upvote our **[paper](https://huggingface.co/papers/2508.08088)** to support us. Your star means a lot!
 
+## Usage
+
+This model is a Qwen2-based language model and can be loaded using the Hugging Face `transformers` library. The example below demonstrates how to use the model for a basic question-answering task, leveraging its underlying chat template.
+
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+# Load the model and tokenizer
+model_id = "zstanjj/HierSearch-Planner-Agent"
+tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
+model = AutoModelForCausalLM.from_pretrained(
+    model_id,
+    torch_dtype=torch.bfloat16, # or torch.float16, depending on your hardware/preference
+    device_map="auto",
+    trust_remote_code=True
+)
+
+# Define a conversation for a question-answering task, suitable for the planner agent
+messages = [
+    {"role": "system", "content": "You are a helpful assistant that can answer questions using search tools."},
+    {"role": "user", "content": "Who is the sibling of the author of Kapalkundala?"}
+]
+
+# Apply the chat template and prepare inputs
+input_prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+inputs = tokenizer(input_prompt, return_tensors="pt").to(model.device)
+
+# Generate response
+outputs = model.generate(
+    **inputs,
+    max_new_tokens=256, # Adjust as needed
+    do_sample=True,
+    temperature=0.7,
+    top_p=0.9,
+    eos_token_id=tokenizer.eos_token_id,
+    pad_token_id=tokenizer.pad_token_id,
+)
+
+# Decode and print the generated text, excluding the input prompt
+response = tokenizer.decode(outputs[0, inputs.input_ids.shape[1]:], skip_special_tokens=True)
+print(f"Assistant: {response}")
+
+# For more advanced usage, including setting up local and web search servers and agents,
+# please refer to the comprehensive instructions in the project's
+# [GitHub repository](https://github.com/plageon/HierSearch).
+```
+
+## Citation
+
+If you find this work helpful, please cite the original paper:
+
+```bibtex
+@misc{tan2025hiersearchhierarchicalenterprisedeep,
+      title={HierSearch: A Hierarchical Enterprise Deep Search Framework Integrating Local and Web Searches}, 
+      author={Jiejun Tan and Zhicheng Dou and Yan Yu and Jiehan Cheng and Qiang Ju and Jian Xie and Ji-Rong Wen},
+      year={2025},
+      eprint={2508.08088},
+      archivePrefix={arXiv},
+      primaryClass={cs.IR},
+      url={https://arxiv.org/abs/2508.08088}, 
+}
+```