# shaxiu/xianyuautoagent architecture

> Architecture diagram of the GitHub repository shaxiu/xianyuautoagent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shaxiu/xianyuautoagent
- Repository: https://github.com/shaxiu/xianyuautoagent

## Overview

##### Project Type & Purpose
- This is an AI-powered automated customer service and negotiation system tailored for the 闲鱼 (second-hand trading) platform.
- Its primary purpose is to provide 24×7 chatbot support with features like context-aware conversations, intelligent routing (expert agents for price negotiation, technical support, default responses), and logging/monitoring.
- The README indicates integration with OpenAI’s LLM, and the project supports multiple expert modules that can dynamically switch based on conversation context.

##### Analyzing the File Structure
- Main project files include:
- main.py: Likely the entry point where the application is bootstrapped.
- XianyuAgent.py: Presumably encapsulates the core business logic for managing AI-driven responses, possibly coordinating with the expert agents.
- XianyuApis.py: Contains functions or classes that interface with the闲鱼 platform or external services.
- context_manager.py: Manages conversation histories and context for dynamic input to the LLM.
- The prompts directory holds several text files containing prompt templates, such as for classification, price negotiation, technical support, and default responses. This highlights an extensible method where agents are steered by external configurations.
- The utils folder (with xianyu_utils.py) suggests a layer of helper functions for common tasks across the system.
- The static directory includes JavaScript files, indicating that there might be a client-facing component or at least some front-end logic (or scripts for interfacing with a NodeJS process), as NodeJS 18+ is listed in the environment requirements.
- Other items such as .env.example, requirements.txt, and demonstration images support deployment and demonstration.

##### Key System Components
a. Entry Point & Orchestration Layer:
- main.py: Acts as the frontend to start the application.
- XianyuAgent.py: Core engine that receives requests, manages conversation flows, and selects the appropriate expert agent.
b. Expert Agent Modules:
- Separate prompt templates (in the prompts directory) are used to differentiate the roles: classify, price, tech, and default responses.
- The decision routing (expert routing) mechanism based on LLM prompt engineering.
c. API & Platform Integration:
- XianyuApis.py is responsible for communicating with the platform (likely handling API calls, possibly for fetching listings or sending responses).
d. Context Management:
- context_manager.py manages conversation history and context, ensuring that every interaction is enriched with prior dialogue for LLM inputs.
e. Utility Functions:
- utils/xianyu_utils.py supports common, reusable functionality across the system.
f. Frontend / Static Assets:
- The static folder (with various JavaScript versions) is used for any interactive web functionalities (such as dashboards, real-time logs, or even integrating a NodeJS layer).
g. External Dependencies & Environment:
- OpenAI API interaction (as shown by the provided environment variables).
- NodeJS scripts or services indicated by static JS files.
- External configuration via .env for API keys, cookies, etc.

##### Relationships & Interactions
- main.py then interacts with XianyuAgent.py which orchestrates:
– Invocations to context_manager.py for retrieving or updating conversation history.
– Decision-making based on expert routing logic that uses prompt templates (from the prompts folder).
– Calls to XianyuApis.py for any API call to the backend platform.
– Assistance via shared functionalities in utils/.
- There should be a clear depiction that the core AI modules (prompt templates, conversation context, and LLM interactions) are decoupled from platform-specific API calls.

##### Architectural Patterns & Design Principles
- Modularity: Separation of concerns by having distinct modules for conversation management, API integration, and utility functions.
- Extensibility: Use of external prompt templates allows new expert agents or strategies to be introduced without changing the core logic.
- Context-awareness: A dedicated module (context_manager) is used to store and retrieve conversation history, maintaining stateful interactions with the LLM.
- Loose Coupling: The design leverages independent modules for better maintainability (e.g., experts, APIs, utilities).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core System Subgraph
    subgraph "Core System"
        U["User/External Request"]:::external
        MP["Entry Point (main.py)"]:::python
        XA["Core Agent (XianyuAgent.py)"]:::python
        CM["Context Manager (context_manager.py)"]:::python
        API["API Integration (XianyuApis.py)"]:::python
        UT["Utility Functions (xianyu_utils.py)"]:::utility

        U -->|"triggers"| MP
        MP -->|"orchestrates"| XA
        XA -->|"manages_context"| CM
        XA -->|"calls_APIs"| API
        XA -->|"utilizes"| UT

        %% Expert Agents Subgraph
        subgraph "Expert Agents (Prompt Templates)"
            CP["Classify Prompt"]:::config
            DP["Default Prompt"]:::config
            PP["Price Negotiation Prompt"]:::config
            TP["Technical Support Prompt"]:::config
        end

        XA -->|"chooses_expert"| CP
        XA -->|"chooses_expert"| DP
        XA -->|"chooses_expert"| PP
        XA -->|"chooses_expert"| TP
    end

    %% Frontend & External Subgraph
    subgraph "Frontend & External"
        FE["Static Frontend Assets"]:::frontend
        OAI["OpenAI API"]:::external
        ENV["Environment Variables (.env)"]:::config
    end

    %% Connections between Core and Frontend/External
    MP -->|"loads_config"| ENV
    XA -->|"integrates"| OAI
    MP -->|"serves_UI_logs_to"| FE

    %% Frontend JS Files Subgraph
    subgraph "Frontend JS Files"
        JS1["JS Origin Version 2"]:::frontend
        JS2["JS Version 1"]:::frontend
        JS3["JS Version 2"]:::frontend
    end

    FE -->|"includes"| JS1
    FE -->|"includes"| JS2
    FE -->|"includes"| JS3

    %% Styles
    classDef python fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef config fill:#ABEBC6,stroke:#196F3D,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef frontend fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef utility fill:#FAD7A0,stroke:#D35400,stroke-width:2px;

    %% Click Events
    click MP "https://github.com/shaxiu/xianyuautoagent/blob/main/main.py"
    click XA "https://github.com/shaxiu/xianyuautoagent/blob/main/XianyuAgent.py"
    click CM "https://github.com/shaxiu/xianyuautoagent/blob/main/context_manager.py"
    click API "https://github.com/shaxiu/xianyuautoagent/blob/main/XianyuApis.py"
    click UT "https://github.com/shaxiu/xianyuautoagent/blob/main/utils/xianyu_utils.py"
    click CP "https://github.com/shaxiu/xianyuautoagent/blob/main/prompts/classify_prompt_example.txt"
    click DP "https://github.com/shaxiu/xianyuautoagent/blob/main/prompts/default_prompt_example.txt"
    click PP "https://github.com/shaxiu/xianyuautoagent/blob/main/prompts/price_prompt_example.txt"
    click TP "https://github.com/shaxiu/xianyuautoagent/blob/main/prompts/tech_prompt_example.txt"
    click JS1 "https://github.com/shaxiu/xianyuautoagent/blob/main/static/xianyu_js_origin_version_2.js"
    click JS2 "https://github.com/shaxiu/xianyuautoagent/blob/main/static/xianyu_js_version_1.js"
    click JS3 "https://github.com/shaxiu/xianyuautoagent/blob/main/static/xianyu_js_version_2.js"
```
