# Sell Agents

<cite>
**Referenced Files in This Document**
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
- [VendorSellTests.cs](file://ClassicAssist.Tests/Agents/SellAgentTests.cs)
</cite>

## Table of Contents
1. [Introduction](#introduction)
2. [Project Structure](#project-structure)
3. [Core Components](#core-components)
4. [Architecture Overview](#architecture-overview)
5. [Detailed Component Analysis](#detailed-component-analysis)
6. [Dependency Analysis](#dependency-analysis)
7. [Performance Considerations](#performance-considerations)
8. [Troubleshooting Guide](#troubleshooting-guide)
9. [Conclusion](#conclusion)
10. [Appendices](#appendices)

## Introduction
This document explains the Vendor Sell Agent system that automatically sells unwanted items to NPCs based on configurable sell lists and conditions. It covers the data structures, filtering logic, UI configuration, profit optimization features, price comparison across vendors, inventory cleanup strategies, and practical workflows such as junk disposal, loot processing, and maintenance routines. It also addresses considerations like vendor reputation effects, selling restrictions, and market value fluctuations.

## Project Structure
The Vendor Sell Agent spans shared data models, UI view models, and tests:
- Shared data models define agent entries, sell list entries, and related helpers.
- Avalonia UI provides the tab control for managing sell rules.
- Tests validate behavior and edge cases.

```mermaid
graph TB
subgraph "Shared Data"
VSAE["VendorSellAgentEntry.cs"]
SLE["SellListEntry.cs"]
VBAE["VendorBuyAgentEntry.cs"]
SLEntry["ShopListEntry.cs"]
XYC["XYComparer.cs"]
end
subgraph "UI (Avalonia)"
VSTabVM["VendorSellTabViewModel.cs"]
VSTabCtrl["VendorSellTabControl.xaml.cs"]
end
subgraph "Tests"
SAT["SellAgentTests.cs"]
end
VSTabVM --> VSAE
VSTabVM --> SLE
VSTabCtrl --> VSTabVM
SAT --> VSAE
SAT --> SLE
```

**Diagram sources**
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
- [SellAgentTests.cs](file://ClassicAssist.Tests/Agents/SellAgentTests.cs)

**Section sources**
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
- [SellAgentTests.cs](file://ClassicAssist.Tests/Agents/SellAgentTests.cs)

## Core Components
- VendorSellAgentEntry: Represents a configured sell agent instance with settings controlling which items are sold, thresholds, and behaviors.
- SellListEntry: Defines individual sell rules including item criteria, minimum value, and exclusion flags.
- VendorSellTabViewModel: Binds UI controls to agent configuration, exposes commands to add/remove/edit rules, and orchestrates selling operations.
- VendorSellTabControl: Hosts the UI surface for managing sell rules and triggers actions from the ViewModel.
- Supporting types: ShopListEntry and VendorBuyAgentEntry provide context for vendor interactions; XYComparer supports spatial comparisons when needed.

Key responsibilities:
- Maintain collections of sell rules and agent options.
- Evaluate inventory items against rules and thresholds.
- Execute sell actions through vendor interfaces.
- Persist and load configurations via the UI.

**Section sources**
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)

## Architecture Overview
The sell flow is driven by the ViewModel, which reads agent configuration and applies filtering logic to inventory items. When an item matches a rule and meets thresholds, the agent initiates a sale through the vendor interface.

```mermaid
sequenceDiagram
participant User as "User"
participant UI as "VendorSellTabControl"
participant VM as "VendorSellTabViewModel"
participant Agent as "VendorSellAgentEntry"
participant Rule as "SellListEntry"
participant Inv as "Inventory"
participant Vendor as "Vendor Interface"
User->>UI : Open Sell Rules Tab
UI->>VM : Load Configuration
VM->>Agent : Read Settings and Rules
User->>UI : Trigger Sell Action
UI->>VM : Execute Sell
VM->>Inv : Enumerate Items
loop For each Item
VM->>Rule : Check Match and Thresholds
alt Matches Rule and Meets Min Value
VM->>Vendor : Sell Item
Vendor-->>VM : Result
else Does Not Match or Below Threshold
VM->>VM : Skip Item
end
end
VM-->>UI : Update Status and Summary
```

**Diagram sources**
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)

## Detailed Component Analysis

### VendorSellAgentEntry
Purpose:
- Holds agent-level configuration such as enabled state, default thresholds, and global filters.
- Provides accessors for rule evaluation and action execution.

Key aspects:
- Global enable/disable toggle.
- Default minimum value threshold if not specified per rule.
- Flags to include/exclude categories or specific properties.
- Integration points for vendor selection and transaction handling.

Complexity:
- O(1) accessors for settings.
- Rule iteration cost depends on number of rules.

Optimization opportunities:
- Cache frequently accessed metadata (e.g., item categories).
- Short-circuit evaluation when global disable is set.

Error handling:
- Validate configuration on load.
- Log invalid rules and skip them during evaluation.

**Section sources**
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)

### SellListEntry
Purpose:
- Encapsulates a single sell rule with match criteria and thresholds.

Attributes typically include:
- Item identifier or pattern matching fields.
- Minimum value threshold override.
- Exclusion flags for valuable or special items.
- Optional category or property constraints.

Evaluation logic:
- Compare item attributes against rule fields.
- Apply minimum value check using either rule-specific or agent-wide threshold.
- Respect exclusion flags to protect high-value items.

Complexity:
- Per-item evaluation is O(R) where R is number of active rules.
- Sorting/comparison helpers may be used for ordering candidates.

Optimization opportunities:
- Precompute normalized identifiers for faster matching.
- Group rules by category to reduce comparisons.

Error handling:
- Ignore malformed rules gracefully.
- Provide clear diagnostics for unmatched expectations.

**Section sources**
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)

### VendorSellTabViewModel
Purpose:
- Binds UI to agent configuration and rules.
- Exposes commands to add, edit, remove, and reorder rules.
- Orchestrates selling operations and updates UI state.

Responsibilities:
- Initialize and persist configuration.
- Manage observable collections of rules.
- Handle user interactions and validation feedback.
- Coordinate with VendorSellAgentEntry to execute sells.

Integration points:
- VendorSellTabControl for rendering and input.
- Underlying vendor interfaces for transactions.

Error handling:
- Validate inputs before saving.
- Report failures during selling with actionable messages.

**Section sources**
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)

### VendorSellTabControl
Purpose:
- Hosts the XAML layout and code-behind for the sell rules tab.
- Wires up events and delegates to the ViewModel.

Responsibilities:
- Display rule lists and forms.
- Trigger ViewModel commands.
- Reflect status changes and summaries.

Error handling:
- Ensure UI remains responsive during long-running operations.
- Surface errors to users without crashing.

**Section sources**
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)

### Supporting Types
- ShopListEntry: Represents shop-related data used in vendor contexts.
- VendorBuyAgentEntry: Related buy agent entry providing symmetry for purchase flows.
- XYComparer: Utility for comparing coordinates or positions when relevant to vendor proximity.

Usage:
- These types support vendor interaction and spatial decisions but are not core to sell rule evaluation.

**Section sources**
- [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs)
- [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs)
- [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs)

### Class Diagram
```mermaid
classDiagram
class VendorSellAgentEntry {
+bool Enabled
+decimal DefaultMinValue
+IEnumerable~SellListEntry~ Rules
+Evaluate(item) bool
+ExecuteSell(item) void
}
class SellListEntry {
+string ItemIdOrPattern
+decimal? MinValueOverride
+bool ExcludeValuable
+Match(item) bool
}
class VendorSellTabViewModel {
+ObservableCollection~SellListEntry~ Rules
+void AddRule()
+void RemoveRule(rule)
+void SaveConfiguration()
+void ExecuteSell()
}
class VendorSellTabControl {
+InitializeComponent()
+OnSellClicked()
}
VendorSellTabViewModel --> VendorSellAgentEntry : "uses"
VendorSellTabViewModel --> SellListEntry : "manages"
VendorSellTabControl --> VendorSellTabViewModel : "binds to"
```

**Diagram sources**
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)

## Dependency Analysis
- VendorSellTabViewModel depends on VendorSellAgentEntry and SellListEntry for configuration and evaluation.
- VendorSellTabControl depends on VendorSellTabViewModel for behavior.
- Tests depend on both data models and ViewModel to assert correctness.

```mermaid
graph LR
VSTabCtrl["VendorSellTabControl.xaml.cs"] --> VSTabVM["VendorSellTabViewModel.cs"]
VSTabVM --> VSAE["VendorSellAgentEntry.cs"]
VSTabVM --> SLE["SellListEntry.cs"]
SAT["SellAgentTests.cs"] --> VSAE
SAT --> SLE
```

**Diagram sources**
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
- [SellAgentTests.cs](file://ClassicAssist.Tests/Agents/SellAgentTests.cs)

**Section sources**
- [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs)
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
- [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs)
- [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs)
- [SellAgentTests.cs](file://ClassicAssist.Tests/Agents/SellAgentTests.cs)

## Performance Considerations
- Rule evaluation complexity scales with the number of active rules; prefer concise patterns and categorization to minimize comparisons.
- Use short-circuiting: disable the agent globally when not needed to avoid unnecessary enumeration.
- Cache expensive lookups (e.g., item metadata) to reduce repeated work.
- Batch sell operations where possible to reduce vendor interaction overhead.

[No sources needed since this section provides general guidance]

## Troubleshooting Guide
Common issues and resolutions:
- No items sold:
  - Verify agent is enabled and at least one rule exists.
  - Confirm minimum value thresholds are not too high.
  - Check exclusion flags that might protect items.
- Incorrect items sold:
  - Review rule patterns and exclusions.
  - Ensure item identifiers or categories match expected values.
- UI not updating:
  - Confirm bindings are correct in the ViewModel.
  - Check for exceptions in command handlers.
- Vendor errors:
  - Inspect logs for transaction failures.
  - Validate vendor availability and reputation requirements.

Validation and logging:
- The ViewModel should validate inputs and report errors clearly.
- Tests can help reproduce and isolate issues.

**Section sources**
- [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs)
- [SellAgentTests.cs](file://ClassicAssist.Tests/Agents/SellAgentTests.cs)

## Conclusion
The Vendor Sell Agent system provides a flexible, configurable approach to automating item sales to NPCs. By combining structured sell rules, thresholds, and exclusion logic, it enables efficient inventory cleanup while protecting valuable items. The UI facilitates easy management of rules and thresholds, and tests ensure reliability. With careful tuning of rules and thresholds, players can optimize profits and maintain streamlined inventories.

[No sources needed since this section summarizes without analyzing specific files]

## Appendices

### Practical Examples
- Junk item disposal:
  - Create rules targeting low-value junk categories with minimal thresholds.
  - Exclude any quest or unique items via exclusion flags.
- Loot processing:
  - After combat, run the sell agent to quickly offload unneeded loot.
  - Use category-based rules to handle common drops efficiently.
- Inventory maintenance:
  - Schedule periodic runs to keep backpacks organized.
  - Combine with other agents (e.g., organizer) for comprehensive management.

[No sources needed since this section provides general guidance]

### Profit Optimization and Price Comparison
- Configure minimum value thresholds to avoid selling undervalued items.
- Compare prices across multiple vendors by selecting the best option when available.
- Monitor market fluctuations and adjust thresholds accordingly.

[No sources needed since this section provides general guidance]

### Vendor Reputation and Selling Restrictions
- Some vendors may have reputation requirements or restricted selling capabilities.
- Ensure the selected vendor is accessible and authorized for the intended sales.
- Handle errors gracefully when restrictions prevent a sale.

[No sources needed since this section provides general guidance]