user-profile

# User Profile Skill

This skill provides 3 unified tools for managing user data:
- `get_user_data` - Read user data
- `update_user_data` - Create or update user data
- `remove_user_data` - Delete user data

You should call these tools directly instead of using ExecuteCode tool.

---

## Tool 1: get_user_data

Retrieve user data by entity type.

### Entities

| Entity | Description | entity_id |
|--------|-------------|-----------|
| `all` | Complete user data (profile, preferences, watchlists with items, portfolio) | Not used |
| `profile` | User info (name, timezone, locale) | Not used |
| `preferences` | All preferences (risk, investment, agent) | Not used |
| `watchlists` | List of all watchlists | Not used |
| `watchlist_items` | Items in a specific watchlist | Optional watchlist_id |
| `portfolio` | All portfolio holdings | Not used |

### Examples

```python
# Get complete user data (recommended for initial context)
get_user_data(entity="all")
# Returns: {
#   "profile": {"name": "John", "timezone": "America/New_York", "locale": "en-US"},
#   "preferences": {"risk_preference": {...}, "investment_preference": {...}, ...},
#   "watchlists": [{"name": "Tech Stocks", "items": [...], ...}],
#   "portfolio": [{"symbol": "AAPL", "quantity": 50, ...}]
# }

# Get user profile
get_user_data(entity="profile")
# Returns: {"name": "John", "timezone": "America/New_York", "locale": "en-US"}

# Get all preferences
get_user_data(entity="preferences")
# Returns: {"risk_preference": {...}, "investment_preference": {...}, "agent_preference": {...}}

# Get all watchlists
get_user_data(entity="watchlists")
# Returns: [{"watchlist_id": "abc", "name": "Tech Stocks", "is_default": true}, ...]

# Get items from default watchlist
get_user_data(entity="watchlist_items")
# Returns: [{"symbol": "AAPL", "notes": "..."}, {"symbol": "NVDA", ...}]

# Get items from specific watchlist
get_user_data(entity="watchlist_items", entity_id="abc-123")

# Get portfolio holdings
get_user_data(entity="portfolio")
# Returns: [{"symbol": "AAPL", "quantity": 50, "average_cost": 175.0}, ...]
```

---

## Tool 2: update_user_data

Create or update user data (upsert semantics).

### Common Options for Preferences

All preference entities (`risk_preference`, `investment_preference`, `agent_preference`) support:

| Parameter | Type | Description |
|-----------|------|-------------|
| `replace` | bool | If `True`, completely replace the preference instead of merging with existing data |

The `data` dict accepts any fields. Extra fields like `notes`, `instruction`, `avoid_sectors` are stored alongside named fields.

```python
# Merge with existing (default behavior)
update_user_data(entity="agent_preference", data={
    "output_style": "Balanced summary with key numbers highlighted",
    "notes": "User prefers brevity"
})

# Replace entire preference (delete all existing fields, set only new ones)
update_user_data(entity="agent_preference", data={
    "output_style": "In-depth deep dive with full analysis"
}, replace=True)
```

### Entity: profile

Update user profile info.

| Field | Type | Description |
|-------|------|-------------|
| `name` | str | Display name |
| `timezone` | str | e.g., "America/New_York" |
| `locale` | str | Preferred language, e.g., "en-US", "zh-CN" |
| `onboarding_completed` | bool | Mark onboarding done (write-only, not returned in get) |

```python
# Update display name
update_user_data(entity="profile", data={"name": "John Doe"})

# Mark onboarding complete
update_user_data(entity="profile", data={"onboarding_completed": True})
```

### Entity: risk_preference

Set risk tolerance settings. All fields accept any descriptive string.

| Field | Type | Description |
|-------|------|-------------|
| `risk_tolerance` | str | Risk tolerance description (any text) |
| *(extra fields)* | any | Additional context (notes, constraints, etc.) |

```python
# Descriptive risk preference
update_user_data(
    entity="risk_preference",
    data={
        "risk_tolerance": "Moderate - comfortable with market swings but avoids concentrated bets",
        "notes": "Prefers diversification after 2022 tech losses"
    }
)
```

### Entity: investment_preference

Set investment style settings. All fields accept any descriptive string. At least one field is required.

| Field | Type | Description |
|-------|------|-------------|
| `company_interest` | str | Type of companies interested in (any text) |
| `holding_period` | str | Preferred holding period (any text) |
| `analysis_focus` | str | Primary analysis focus area (any text) |
| *(extra fields)* | any | Additional context (avoid_sectors, focus_sectors, notes, etc.) |

```python
# Full investment profile with rich descriptions
update_user_data(
    entity="investment_preference",
    data={
        "company_interest": "Dividend-paying blue chips and REITs for income",
        "holding_period": "Long-term (5+ years), rarely sells",
        "analysis_focus": "Dividend sustainability and balance sheet strength",
        "avoid_sectors": "Crypto, speculative biotech"
    }
)
```

### Entity: agent_preference

Set agent behavior settings. All fields accept any descriptive string.

| Field | Type | Description |
|-------|------|-------------|
| `output_style` | str | Preferred output style (any text) |
| `data_visualization` | str | Chart/visualization preferences (any text) |
| `proactive_questions` | str | When to ask clarifying questions (any text) |
| *(extra fields)* | any | Additional context (instruction, notes, etc.) |

```python
# Rich agent preferences
update_user_data(
    entity="agent_preference",
    data={
        "output_style": "Balanced summary with key numbers highlighted",
        "data_visualization": "Include charts when comparing multiple stocks",
        "proactive_questions": "Use your judgment, only ask when critical"
    }
)
```

### Entity: watchlist

Create or update a watchlist.

| Field | Type | Required | Description |
|-------|------|----------|---