# Vendor Management Agents **Referenced Files in This Document** - [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs) - [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs) - [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs) - [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs) - [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs) - [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs) - [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs) - [VendorBuyTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml.cs) - [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs) - [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs) ## 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) ## Introduction This document explains the Vendor Management agents (Buy and Sell) that automate purchasing from and selling to NPC vendors. It covers how buy/sell lists are created, price tracking, stock monitoring, UI management, purchase limits, transaction history, integration with gold/inventory constraints, and error handling for common failure scenarios such as insufficient funds, inventory overflow, and vendor interaction failures. ## Project Structure The vendor system is implemented across shared data models, UI view models, and Avalonia UI controls: - Data models define entries for buy and sell lists and shop items. - View models manage list state, filtering, and actions. - Avalonia tabs host the user interfaces for configuring and operating the agents. - Network packets provide the low-level vendor buy operation. ```mermaid graph TB subgraph "Shared Data" VBA["VendorBuyAgentEntry.cs"] VSA["VendorSellAgentEntry.cs"] SLE["ShopListEntry.cs"] SLSE["SellListEntry.cs"] XYC["XYComparer.cs"] end subgraph "UI ViewModels" VBVM["VendorBuyTabViewModel.cs"] VSVM["VendorSellTabViewModel.cs"] end subgraph "Avalonia UI" VBTAB["VendorBuyTabControl.xaml.cs"] VSTAB["VendorSellTabControl.xaml.cs"] end subgraph "Network" VBP["VendorBuy.cs"] end VBA --> VBVM VSA --> VSVM SLE --> VBVM SLSE --> VSVM XYC --> VBVM XYC --> VSVM VBVM --> VBTAB VSVM --> VSTAB VBVM --> VBP ``` **Diagram sources** - [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs) - [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs) - [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs) - [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs) - [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs) - [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs) - [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs) - [VendorBuyTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml.cs) - [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs) - [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs) **Section sources** - [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs) - [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs) - [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs) - [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs) - [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs) - [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs) - [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs) - [VendorBuyTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml.cs) - [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs) - [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs) ## Core Components - Buy agent entry: Represents a single item to purchase from a vendor, including quantity limits and optional price thresholds. - Sell agent entry: Represents an item to sell to a vendor, including minimum sell price or profit conditions. - Shop list entry: Represents an item available in a vendor’s shop, including price and stock information used for price tracking and stock monitoring. - Sell list entry: Represents an item in your inventory eligible for selling, including current count and sell price. - Comparer utilities: Provide sorting and comparison logic for vendor lists. - View models: Manage collections, filtering, selection, and operations for buy/sell tabs. - UI tabs: Host the interactive interface for managing vendor entries and running automation. - Network packet: Encapsulates the vendor buy request at the protocol level. Key responsibilities: - Maintain persistent lists of items to buy/sell. - Track vendor prices and stock levels over time. - Enforce purchase limits and budget constraints. - Coordinate with inventory space checks before buying. - Present transaction history and status feedback. **Section sources** - [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs) - [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs) - [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs) - [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs) - [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs) - [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs) - [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs) - [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs) ## Architecture Overview The vendor agents operate through a layered architecture: - Data layer: Entry models store configuration and observed state (prices, stock). - ViewModel layer: Manages collections, filters, and orchestration of buy/sell workflows. - UI layer: Avalonia tabs render lists, allow editing, and trigger actions. - Network layer: Sends vendor buy requests via packets; other vendor interactions rely on existing network handlers. ```mermaid sequenceDiagram participant User as "User" participant UIBuy as "VendorBuyTabControl" participant VM as "VendorBuyTabViewModel" participant Model as "VendorBuyAgentEntry" participant Net as "VendorBuy Packet" User->>UIBuy : Open Buy Tab UIBuy->>VM : Initialize bindings User->>VM : Add/Edit entries
Set purchase limits VM->>Model : Persist config User->>VM : Start automated buying VM->>VM : Check gold and inventory space VM->>Net : Send vendor buy request(s) Net-->>VM : Acknowledge result VM-->>UIBuy : Update status/history ``` **Diagram sources** - [VendorBuyTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml.cs) - [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs) - [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs) - [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs) ## Detailed Component Analysis ### Buy Agent The buy agent automates purchasing items from NPCs based on configured lists and constraints. - List creation: Users add items to the buy list with desired quantities and optional maximum price thresholds. - Price tracking: The system records vendor prices per item to compare against thresholds and detect price changes. - Stock monitoring: The system observes vendor stock availability and avoids attempting purchases when out of stock. - Purchase limits: Per-item limits prevent overbuying beyond configured caps. - Gold management: Before buying, the agent verifies sufficient gold and reserves funds accordingly. - Inventory constraints: The agent checks available backpack/container space before executing purchases. - Transaction history: Successful and failed transactions are logged with reasons for failures. ```mermaid flowchart TD Start(["Start Buy Cycle"]) --> LoadEntries["Load Buy Entries"] LoadEntries --> ForEachEntry{"For each entry"} ForEachEntry --> |Yes| CheckPrice["Compare current price vs threshold"] CheckPrice --> PriceOK{"Within limit?"} PriceOK --> |No| SkipBuy["Skip due to price"] PriceOK --> |Yes| CheckStock["Check vendor stock"] CheckStock --> StockOK{"In stock?"} StockOK --> |No| SkipStock["Skip due to stock"] StockOK --> |Yes| CheckGold["Check gold balance"] CheckGold --> GoldOK{"Sufficient funds?"} GoldOK --> |No| FailGold["Fail: Insufficient funds"] GoldOK --> |Yes| CheckSpace["Check inventory space"] CheckSpace --> SpaceOK{"Space available?"} SpaceOK --> |No| FailSpace["Fail: Inventory overflow"] SpaceOK --> |Yes| ExecuteBuy["Send vendor buy request"] ExecuteBuy --> Record["Record transaction history"] Record --> NextEntry["Next entry"] SkipBuy --> NextEntry SkipStock --> NextEntry FailGold --> NextEntry FailSpace --> NextEntry NextEntry --> ForEachEntry ForEachEntry --> |No| End(["End Buy Cycle"]) ``` **Diagram sources** - [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs) - [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs) - [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs) - [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs) **Section sources** - [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs) - [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs) - [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs) - [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs) ### Sell Agent The sell agent automates selling unwanted items to NPCs based on configured lists and conditions. - List creation: Users add items to the sell list with minimum acceptable sell prices or profit targets. - Price tracking: The system tracks vendor buyback prices to ensure profitability. - Stock monitoring: Not applicable for selling; however, it ensures items exist in inventory. - Sell limits: Per-item limits control how many units to sell. - Gold management: Selling increases gold; the agent can optionally enforce minimum gold thresholds before selling. - Inventory constraints: Selling frees space; the agent may prioritize high-value items first. - Transaction history: Logs sold items, prices, and outcomes. ```mermaid flowchart TD StartSell(["Start Sell Cycle"]) --> LoadSellEntries["Load Sell Entries"] LoadSellEntries --> ForEachSell{"For each sell entry"} ForEachSell --> |Yes| HasItem{"Item in inventory?"} HasItem --> |No| SkipNoItem["Skip: No item"] HasItem --> |Yes| CheckMinPrice["Compare sell price vs min price"] CheckMinPrice --> PriceOK{"Meets target?"} PriceOK --> |No| SkipPrice["Skip: Below target"] PriceOK --> |Yes| CheckLimit["Respect sell limit"] CheckLimit --> ExecuteSell["Send vendor sell request"] ExecuteSell --> RecordSell["Record transaction history"] RecordSell --> NextSell["Next sell entry"] SkipNoItem --> NextSell SkipPrice --> NextSell NextSell --> ForEachSell ForEachSell --> |No| EndSell(["End Sell Cycle"]) ``` **Diagram sources** - [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) **Section sources** - [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) ### UI for Managing Vendor Entries - Buy tab: Displays buy list entries, allows adding/removing/editing items, setting purchase limits, and toggling automation. - Sell tab: Displays sell list entries, allows configuring minimum sell prices and sell limits, and starting sell automation. - Filtering and sorting: Use comparer utilities to sort by name, price, or stock. - History panel: Shows recent transactions with success/failure indicators and reasons. ```mermaid classDiagram class VendorBuyTabViewModel { +entries +filters +startBuying() +stopBuying() +addEntry(item, qty, maxPrice) +removeEntry(entry) +updateHistory(reason, item, qty) } class VendorSellTabViewModel { +sellEntries +filters +startSelling() +stopSelling() +addSellEntry(item, qty, minPrice) +removeSellEntry(entry) +updateHistory(reason, item, qty) } class VendorBuyAgentEntry { +item +quantity +maxPrice +enabled } class VendorSellAgentEntry { +item +quantity +minPrice +enabled } class ShopListEntry { +item +price +stock } class SellListEntry { +item +count +sellPrice } VendorBuyTabViewModel --> VendorBuyAgentEntry : "manages" VendorSellTabViewModel --> VendorSellAgentEntry : "manages" VendorBuyTabViewModel --> ShopListEntry : "reads prices/stock" VendorSellTabViewModel --> SellListEntry : "reads inventory/prices" ``` **Diagram sources** - [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs) - [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs) - [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs) - [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs) - [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs) - [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs) **Section sources** - [VendorBuyTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml.cs) - [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs) - [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs) - [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs) - [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs) ### Concrete Usage Examples - Automated purchasing for crafting materials: - Add materials to the buy list with desired quantities and maximum prices. - Enable automation; the agent will periodically check prices and stock, then purchase within budget and space constraints. - Selling unwanted items: - Add items to the sell list with minimum acceptable sell prices. - Enable automation; the agent will sell items meeting criteria and log results. - Managing shop inventories: - Use price tracking and stock monitoring to identify profitable restocking opportunities. - Adjust purchase limits dynamically based on observed vendor stock levels. [No sources needed since this section provides general guidance] ## Dependency Analysis The vendor components depend on shared data models and UI view models, with the buy flow integrating with the network layer for sending vendor buy requests. ```mermaid graph LR VBA["VendorBuyAgentEntry.cs"] --> VBVM["VendorBuyTabViewModel.cs"] VSA["VendorSellAgentEntry.cs"] --> VSVM["VendorSellTabViewModel.cs"] SLE["ShopListEntry.cs"] --> VBVM SLSE["SellListEntry.cs"] --> VSVM XYC["XYComparer.cs"] --> VBVM XYC --> VSVM VBVM --> VBTAB["VendorBuyTabControl.xaml.cs"] VSVM --> VSTAB["VendorSellTabControl.xaml.cs"] VBVM --> VBP["VendorBuy.cs"] ``` **Diagram sources** - [VendorBuyAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorBuyAgentEntry.cs) - [VendorSellAgentEntry.cs](file://ClassicAssist.Shared/Data/Vendors/VendorSellAgentEntry.cs) - [ShopListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/ShopListEntry.cs) - [SellListEntry.cs](file://ClassicAssist.Shared/Data/Vendors/SellListEntry.cs) - [XYComparer.cs](file://ClassicAssist.Shared/Data/Vendors/XYComparer.cs) - [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs) - [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs) - [VendorBuyTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorBuyTabControl.xaml.cs) - [VendorSellTabControl.xaml.cs](file://ClassicAssist.Avalonia/Views/Agents/VendorSellTabControl.xaml.cs) - [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs) **Section sources** - [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs) - [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs) - [VendorBuy.cs](file://ClassicAssist.Shared/UO/Network/Packets/VendorBuy.cs) ## Performance Considerations - Batch operations: Group multiple buy/sell requests to reduce network overhead. - Debouncing: Avoid excessive polling by throttling price/stock checks. - Efficient comparisons: Use comparers for sorting large lists to minimize UI lag. - Memory usage: Keep only necessary history entries and prune old logs. [No sources needed since this section provides general guidance] ## Troubleshooting Guide Common issues and resolutions: - Insufficient funds: - Ensure gold balance meets total purchase cost. - Reduce purchase quantities or adjust maximum price thresholds. - Inventory overflow: - Verify available container space before buying. - Prioritize essential items or free up space by selling. - Vendor interaction failures: - Confirm vendor is targeted and accessible. - Retry after brief delay; check for server-side restrictions. - Price above threshold: - Adjust maximum price or wait for price drops. - Out of stock: - Monitor stock levels and schedule retries later. **Section sources** - [VendorBuyTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorBuyTabViewModel.cs) - [VendorSellTabViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/Agents/VendorSellTabViewModel.cs) ## Conclusion The Vendor Management agents provide robust automation for buying and selling with NPCs. By leveraging configurable lists, price tracking, stock monitoring, and strict constraints around gold and inventory, users can efficiently manage crafting supplies and shop inventories while maintaining clear visibility into transaction history and errors. [No sources needed since this section summarizes without analyzing specific files]