wufus-CART-8B/README.md

---
language:
  - en
license: apache-2.0
base_model: Qwen/Qwen3-8B
tags:
  - reinforcement-learning
  - tool-calling
  - e-commerce
  - shopping-assistant
  - GRPO
  - DAPO
  - multi-turn
pipeline_tag: text-generation
library_name: transformers
---

# WUFUS(CART) — E-Commerce Shopping Cart Assistant

**wufus-CART-8B** is a fine-tuned [Qwen3-8B](https://huggingface.co/Qwen/Qwen3-8B) model, created via on-policy DAPO training(RL) using OpenEnv, specialized for multi-turn, tool-augmented e-commerce shopping conversations. The model helps customers discover products, compare variants, analyse user history and build accurate shopping carts through natural dialogue.

## Key Capabilities

- **Product Discovery**: Searches a product catalog using formulated queries
- **Variant Selection**: Identifies correct color, size, and other variant attributes
- **Cart Management**: Adds products with correct quantities and variants
- **Clarification Dialogue**: Asks follow-up questions when customer requests are ambiguous
- **Multi-Item Orders**: Handles requests for multiple different products in one conversation

## Quick Start

```python
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

model = AutoModelForCausalLM.from_pretrained(
    "owlgebra-ai/wufus-CART-8B",
    torch_dtype=torch.bfloat16,
    device_map="auto",
    trust_remote_code=True,
    attn_implementation="flash_attention_2",  # optional, for speed
)
tokenizer = AutoTokenizer.from_pretrained("owlgebra-ai/wufus-CART-8B", trust_remote_code=True)
```

## System Prompt

Use the following system prompt for optimal performance:

```
You are a shopping cart assistant. Help customers add the correct products to their cart.

WORKFLOW:
Step 0 (COUNT): Count how many distinct items the customer wants. Plan one search per item.
Step 1 (GATHER): Call user_get_visit_history. Then call catalog_search ONCE PER ITEM with a focused query.
Step 2 (IDENTIFY): Match each item to a specific product_id from search results.
Step 3 (CLARIFY): If color/size/quantity is missing, call ask_user to get the details.
Step 4 (VARIANTS): Call catalog_get_variants for each product to find the right variant.
Step 5 (ADD): Call cart_add for each item with the correct product_id, variant_id, and quantity.
Step 6 (VERIFY): Call cart_view. Compare cart contents against the original request item-by-item.

MULTI-ITEM EXAMPLE (2 items):
  User: "Add a blue phone case and 3 screen protectors"
  → catalog_search("blue phone case")
  → catalog_search("screen protectors")
  → catalog_get_variants(phone_case_id)
  → cart_add(phone_case_id, blue_variant, qty=1)
  → cart_add(protector_id, variant, qty=3)
  → cart_view()
```

## Tool Definitions

The model is trained to use the following tools via native Qwen3 tool-calling format:

### `catalog_search`
Search the product catalog for products matching a text query.

```json
{
  "name": "catalog_search",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Natural language description of the desired product."
      }
    },
    "required": ["query"]
  }
}
```

**Returns**: List of product dicts with `product_id`, `title`, `price`, `rating`, `stock_qty`, `key_attrs`.

### `catalog_get_variants`
Get available variants (color, size, etc.) for a specific product.

```json
{
  "name": "catalog_get_variants",
  "parameters": {
    "type": "object",
    "properties": {
      "product_id": {
        "type": "string",
        "description": "The product ID to retrieve variants for."
      }
    },
    "required": ["product_id"]
  }
}
```

**Returns**: List of variant dicts with `variant_id`, `attrs` (e.g. color, size), `price_delta`, `stock_qty`.

### `cart_add`
Add a product to the shopping cart.

```json
{
  "name": "cart_add",
  "parameters": {
    "type": "object",
    "properties": {
      "product_id": {
        "type": "string",
        "description": "The product ID to add (from catalog_search results)."
      },
      "variant_id": {
        "type": "string",
        "description": "Optional variant ID for specific color/size selection."
      },
      "quantity": {
        "type": "integer",
        "description": "Number of units to add. Defaults to 1."
      }
    },
    "required": ["product_id"]
  }
}
```

**Returns**: Updated cart summary with `lines` (list of items), `total_items`, `total_price`.

### `cart_view`
View the current contents of the shopping cart.

```json
{
  "name": "cart_view",
  "parameters": {
    "type": "object",
    "properties": {}
  }
}
```

**Returns**: Cart summary with `lines`, `total_items`, `total_price`.

### `user_get_visit_history`
Get the customer's recently viewed products (browsing history).

```json
{
  "name": "user_get_visit_history",
  "parameters": {
    "type": "object",
    "properties": {}
  }
}
```

**Returns**: List of recently viewed product cards with `product_id`, `title`, `price`, `category`, `brand`.

### `ask_user`
Ask the customer a clarification question about their order.

```json
{
  "name": "ask_user",
  "parameters": {
    "type": "object",
    "properties": {
      "question": {
        "type": "string",
        "description": "Your question to the customer, e.g. 'What color would you like?' or 'How many do you need?'"
      }
    },
    "required": ["question"]
  }
}
```

**Returns**: The customer's response with the requested information.

## Usage with Tool Calling

```python
tools = [
    {"type": "function", "function": {"name": "catalog_search", "description": "Search products", "parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}},
    {"type": "function", "function": {"name": "catalog_get_variants", "description": "Get variants for a product", "parameters": {"type": "object", "properties": {"product_id": {"type": "string"}}, "required": ["product_id"]}}},
    {"type": "function", "function": {"name": "cart_add", "description": "Add to cart", "parameters": {"type": "object", "properties": {"product_id": {"type": "string"}, "variant_id": {"type": "string"}, "quantity": {"type": "integer"}}, "required": ["product_id"]}}},
    {"type": "function", "function": {"name": "cart_view", "description": "View cart", "parameters": {"type": "object", "properties": {}}}},
    {"type": "function", "function": {"name": "user_get_visit_history", "description": "Get browsing history", "parameters": {"type": "object", "properties": {}}}},
    {"type": "function", "function": {"name": "ask_user", "description": "Ask customer a question", "parameters": {"type": "object", "properties": {"question": {"type": "string"}}, "required": ["question"]}}},
]

messages = [
    {"role": "system", "content": SYSTEM_PROMPT},
    {"role": "user", "content": "I need a pair of running shoes and 3 water bottles"},
]

text = tokenizer.apply_chat_template(messages, tools=tools, tokenize=False, add_generation_prompt=True)
inputs = tokenizer(text, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model.generate(**inputs, max_new_tokens=2048, temperature=0.7, do_sample=True)
response = tokenizer.decode(outputs[0][inputs["input_ids"].shape[1]:], skip_special_tokens=False)
print(response)
```

The model will produce tool calls in Qwen3's native format:
```
<tool_call>
{"name": "catalog_search", "arguments": {"query": "running shoes"}}
</tool_call>
<tool_call>
{"name": "catalog_search", "arguments": {"query": "water bottles"}}
</tool_call>
```

Feed tool results back as `tool` role messages and continue the loop until the model produces a text-only response (conversation complete).

## Training Details

| Attribute | Value |
|-----------|-------|
| Base Model | [Qwen/Qwen3-8B](https://huggingface.co/Qwen/Qwen3-8B) |
| Parameters | 8.2B |
| Precision | bf16 |
| Context Length | 8192 tokens (tool-calling conversations) |
| Training Method | GRPO/DAPO (Reinforcement Learning) |
| Training Framework | TRL + vLLM + FSDP2 |
| Tool Calling Format | Qwen3 native (`<tool_call>` / `</tool_call>`) |
| Thinking Mode | Supported (Qwen3 `<think>` tokens) |

## Intended Use

This model is designed for integration into e-commerce platforms as a shopping cart assistant. It works best when:

- Connected to a real product catalog via the tool interface
- The catalog supports text search (e.g., FAISS, Elasticsearch)
- Products have variant information (color, size, etc.)
- The conversation is multi-turn with tool execution between turns

## Limitations

- Requires external tool implementations — the model generates tool calls but does not execute them
- Trained on English product data only
- Variant matching depends on catalog quality — ambiguous product names may cause errors

## Citation

If you use this model, please cite:

```bibtex
@software{ecomrlve2026,
  title={EcomRLVE-GYM: Reinforcement Learning with Adaptive Verifiable Environments for E-Commerce},
  year={2026},
  url={https://github.com/owlgebra-ai/EcomRLVE-Gym}
}
```