Source Code and Data for LLM-MCP

This repository contains the source code and benchmark datasets for the paper: "A Dual Fairness-Aware Multi-agent Collaborative Planning Framework for Logistics Zone Partitioning".

Overview

The project implements LLM-MCP (Large Language Model-based Multi-agent Collaborative Planning), a framework designed to address the limitations of existing zone partitioning methods that overlook couriers' subjective workload perceptions.

Unlike traditional methods that solely focus on objective metrics (e.g., time, distance), LLM-MCP facilitates dual fairness optimization:

1. Objective Fairness: Balancing workload metrics to ensure operational efficiency.
2. Subjective Fairness: Respecting couriers' individual preferences and physical states via unique "Courier Digital Personas".

The system simulates a real-world management hierarchy where agents (Couriers, Team Leaders, and Managers) leverage graph-structured geospatial information and operational tools to collaborate within an iterative, negotiation-centric workflow.

1. Project Structure

The project is organized as follows:

project/
│
├── code/                               # Source code root directory
│   ├── agents/                         # Core agent definitions and interfaces
│   │   ├── base_agent.py               # Base class for LLM agents
│   │   ├── local_agent.py              # Interface for locally deployed models (vLLM)
│   │   ├── specific_agent.py           # Configurable agents for specific tasks
│   │   ├── tools_agent.py              # Agents equipped with external tools
│   │   └── vision_agent.py             # Agents with multimodal capabilities
│   │
│   ├── baselines/                      # Baseline algorithms for comparison
│   │   ├── Evaluation/                 # Evaluation scripts (LLM-based metrics)
│   │   ├── HeuristicSearch/            # Heuristic algorithms (Greedy, MinMax)
│   │   ├── Iterative/                  # Iterative improvement algorithms
│   │   ├── MetaHeuristicsSearch/       # Evolutionary algorithms (GA, NSGA-II)
│   │   ├── Practice/                   # Current practical baseline (Initial Plan)
│   │   ├── Random/                     # Random Walk baseline
│   │   └── data_tools.py               # Shared data utilities for baselines
│   │
│   ├── env/                            # Environment configuration (API Keys)
│   ├── prompts/                        # JSON-based Prompt templates for agents
│   │
│   ├── tools/                          # General-purpose utility libraries
│   │   ├── DataProcessing.py           # Data loading and preprocessing
│   │   ├── FileProcessing.py           # File I/O operations
│   │   ├── GeoProcessing.py            # Geospatial analysis and visualization
│   │   ├── GraphProcessing.py          # Graph algorithms (NetworkX based)
│   │   ├── IndicatorProcessing.py      # Metric calculations (Gini, CV, Balance Score)
│   │   ├── LLM_API.py                  # LLM API wrappers and output parsers
│   │   └── tools_for_Agent.py          # Tool definitions callable by Agents
│   │
│   ├── workflows/                      # Experiment workflows and pipelines
│   │   ├── agents/                     # Workflow-specific agent implementations
│   │   │   ├── CourierFeedbackExpert.py    # Fine-tuned courier feedback model wrapper
│   │   │   ├── clusterLeaderAllocation.py  # Logic for leader assignment
│   │   │   ├── couriersDiscuss.py          # Intra-cluster courier negotiation logic
│   │   │   ├── LeadersDiscuss.py           # Inter-cluster leader negotiation logic
│   │   │   ├── ManagerOptimize.py          # Global manager optimization logic
│   │   │   └── LeaderConversationExtractor.py # Summary extraction agent
│   │   │
│   │   ├── launcher.py                 # Batch execution script for multi-day experiments
│   │   ├── main.py                     # Main entry point for single-day experiments
│   │   └── specific_workflows.py       # Orchestrator for the hierarchical optimization process
│   │
│   ├── __init__.py                     # Package initialization
│   └── config_env.py                   # Project path configuration
│
├── data/                               # Data directory
│   ├── benchmark/                      # Real-world datasets (manxianglin, hetaoyuan, huarun)
│   │   ├── AOIs_graph/                 # Graph topology of Areas of Interest (AOI)
│   │   ├── AOIs_info/                  # Metadata and metrics for each AOI
│   │   ├── courier_info/               # Courier profiles (attributes, preferences)
│   │   ├── courier_plans/              # Historical or initial division plans
│   │   ├── organization_struct/        # Team composition and relations
│   │   └── region_map/                 # GIS data for visualization
│   │
│   └── sft_data/                       # Fine-tuning datasets
│       └── qwen3_finetune_data_en.jsonl # LoRA training data for Courier Expert
│
├── tables/                              # Supplementary tables from the paper
│   ├── table6.png                       # Extended results table (not included in paper due to space)
│   ├── table7.png                       # Extended results table (not included in paper due to space)
│   ├── table8.png                       # Extended results table (not included in paper due to space)
│   ├── table9.png                       # Extended results table (not included in paper due to space)
│   └── table10.png                      # Extended results table (not included in paper due to space)
│
└── README.md                           # This documentation file

2. Repository Organization

The repository is categorized into two main components: Code and Data.

• Code (code/): This directory contains the complete source code for the LLM-MCP framework. It encompasses the following sub-modules:

  • Agents: Core logic for different agent roles.
  • Workflows: Implementation of the hierarchical negotiation process.
  • Tools: Utility libraries, including graph processing and geospatial tools used by agents.
  • Prompts: Template definitions for agent interactions.
  • Baselines: Implementations of comparison algorithms.

• Data (data/): This directory provides the essential resources for experiments, divided into two aspects:

  1. Benchmark Datasets: Real-world logistics data from three distinct regions: manxianglin, hetaoyuan, and huarun.
  2. SFT Data: The instruction-tuning dataset (LoRA) used for fine-tuning the Courier Feedback Expert model.

• Tables (tables/): This directory contains supplementary tables from the paper that were not included in the main manuscript due to space limitations. These tables provide additional experimental results and detailed analysis that complement the findings presented in the paper.

3. Module Descriptions

3.1 Agents (code/agents/)

This module defines the fundamental building blocks of the Multi-Agent System.

• base_agent.py: The foundational class that handles LLM interactions, memory management, and chain execution.
• local_agent.py: A specialized class for interacting with locally hosted fine-tuned models (e.g., using vLLM), supporting custom endpoints.
• specific_agent.py: A wrapper class that initializes agents with specific prompts and output parsers for defined tasks (e.g., Profile Generation, Summary Extraction).
• tools_agent.py: Implements agents that can autonomously select and execute defined tools to retrieve necessary information during reasoning.
• vision_agent.py: Enables agents to process visual data (e.g., maps or charts) using multimodal LLM capabilities for enhanced environmental understanding.

3.2 Workflows (code/workflows/)

This module implements the hierarchical negotiation mechanism described in the paper, simulating the decision-making flow from couriers to management.

• specific_workflows.py: The core orchestrator that manages the lifecycle of the optimization process.
• launcher.py: A utility script for running batch experiments across multiple dates in parallel.
• main.py: The entry point for a single experimental run, initializing the WorkflowManager.

Workflow Agents (code/workflows/agents/):

• CourierFeedbackExpert.py: A specialized agent wrapping a fine-tuned model to simulate courier subjective feedback based on their "Digital Persona".
• couriersDiscuss.py: Manages the negotiation logic between two couriers within the same cluster to exchange AOIs.
• clusterLeaderAllocation.py: Handles the logic for a Team Leader to allocate tasks or intervene in courier disputes.
• LeadersDiscuss.py: Manages the negotiation between Team Leaders from different clusters to balance workload at a district level.
• ManagerOptimize.py: The top-level agent representing the District Manager, responsible for monitoring global indicators and initiating inter-team negotiations.
• LeaderConversationExtractor.py: An auxiliary agent used to summarize negotiation histories and extract key decisions for the next hierarchy level.

3.3 Tools (code/tools/)

Provides essential utilities for environmental understanding and data analysis.

• DataProcessing.py: Utilities for loading raw CSV/JSON data, cleaning courier profiles, and managing division plan formats.
• FileProcessing.py: Helper functions for file I/O operations, logging management, and directory structure maintenance.
• GeoProcessing.py: Handles geospatial operations such as calculating AOI centroids, visualizing district maps, and verifying spatial connectivity to ensure feasible routing.
• GraphProcessing.py: Provides graph algorithms (using NetworkX) to analyze AOI topology, check connectivity, and calculate shortest paths.
• IndicatorProcessing.py: Calculates objective fairness metrics, including the Gini Coefficient, Coefficient of Variation (CV), and Balance Score.
• LLM_API.py: Manages API calls to LLM providers and includes robust Pydantic parsers to ensure structured JSON output from agents.
• tools_for_Agent.py: Wraps lower-level utility functions into BaseTool classes (e.g., ZoneTool, AOIsTool) that can be directly invoked by LangChain-based agents.

3.4 Baselines (code/baselines/)

Contains implementations of various algorithms for comparative analysis. The table below maps the source code files to the specific baseline methods described in the paper:

Category	File	Corresponds to (Paper)	Description
Practice	initial_plan.py	Original	Represents the actual, static partitioning plan used in real-world logistics operations. It serves as a benchmark for the existing, non-adaptive strategy.
Heuristic	greedy.py	Greedy-I	A constructive heuristic that greedily selects candidate AOI assignments yielding the maximum reduction in overall workload variance.
Heuristic	minmax.py	E-partition	A heuristic employing a two-stage greedy selection: identifies the zone with minimum workload and greedily adds the largest available neighbor AOI to promote balance.
Random	randwalk.py	Random-Best	Generates partitions via random walks (repeating the procedure 200 times) and selects the solution with the minimum workload variance.
Meta-Heuristic	GA.py	GA	Single-objective Genetic Algorithm minimizing service time variance. Includes custom initialization (random walks) and mutation operators to preserve connectivity.
Meta-Heuristic	NSGA.py	NSGA-II	Multi-objective Genetic Algorithm optimizing both workload variance and compactness.
Iterative	greedy.py	Greedy-Iterative	An iterative improvement heuristic starting from the original plan. It repeatedly reassigns valid boundary nodes to maximize variance reduction until convergence.
Evaluation	LLM_Evaluator.py	N/A	Uses an LLM as a judge to quantify subjective fairness based on courier profiles.

4. Data Description

All benchmark data is stored in data/benchmark/ and includes three real-world datasets: huarun, hetaoyuan, and manxianglin. These datasets collectively provide a comprehensive view of the geographical layout, operational topology, and human-centric attributes.

4.1 AOI Map Data (data/benchmark/AOIs_info/)

Defines the core geospatial information for the districts, establishing physical boundaries and recording daily operational metrics.

Attribute	Details	Example
aoi_id	A unique integer identifier for each AOI.	0
labelName	The functional category or type of the AOI.	Business & Administration
geometry	The geographical boundary represented as a POLYGON with lat/long coordinates.	POLYGON ((116.52...))
estimated_service_time	A list of daily estimated service times (in hours) for the AOI throughout the dataset period.	[0.0, 0.62, 0.15, ...]
daily_order_counts	A list of daily order counts for the AOI throughout the dataset period.	[0, 1, 1, 2, 0, ...]

4.2 Graph Structure Data (data/benchmark/AOIs_graph/)

Abstracts the district into a graph structure to model spatial relationships, enabling efficient analysis of proximity and connectivity.

Attribute	Details	Example
aoiIndex	The integer identifier for the source AOI node.	0
adjAOIs	A list of integer IDs representing the AOIs that are geographically adjacent to the source AOI.	[3, 5, 22, 45]

4.3 Courier Daily Records (data/benchmark/courier_info/)

Provides a rich snapshot of each courier's operational reality and personal state, serving as the foundation for human-centric fairness evaluation.

Attribute	Details	Example
service_AOIs	A list of AOI IDs constituting the courier's assigned delivery zone for that day.	[107, 108, 112, ...]
service_time	The actual total service time (in hours) for the courier on that day.	6.44
avg_team_work_hours	The average service time for all couriers within the same team on that day.	6.52
age	Courier's age (18-50). Younger couriers tend to have more energy, while older ones may recover slower but offer experience.	22
recent_fatigue_level	Measures recent fatigue on a 4-level scale: 1: Fresh; 2: Normal; 3: Tired; 4: Exhausted.	1
work_experience	Measures seniority on a 5-level scale: 1: Trainee; 2: Junior; 3: Skilled; 4: Senior; 5: Master.	2
supervisory_tags	A chronological history of tagged evaluations from a supervisor, used to infer personality traits.	["He is full of youthful energy..."]
personal_work_mantra	A history of self-written mottos reflecting work philosophy.	["Newbie on the road, happy to learn..."]
recent_event_note	A summary of recent delivery/life events impacting dynamic needs.	["Deliberately optimized the pickup..."]

4.4 Team Organization Structure (data/benchmark/organization_struct/)

Defines the hierarchical structure of the courier teams used during coordination phases.

Attribute	Details	Example
team_leader_id	The unique integer identifier for the Team Leader.	1
team_members	A list of courier IDs who are members of this leader's team.	[1, 3, 6]

4.5 Region Maps (data/benchmark/region_map/)

Contains visual representations (images) of the districts to facilitate understanding of the geographical layout.

5. Usage

Prerequisites

Please ensure the following environment and resources are prepared before running the project:

• Python Environment: Python 3.8 or higher.
• Dependencies: Essential libraries include pandas, numpy, networkx, langchain, pydantic, scikit-learn, pymoo, tqdm, etc.
• LLM API Configuration: You need access to an LLM service (e.g., OpenAI or compatible endpoints). Please configure the following parameters in code/env/.env:
  • OPENAI_API_KEY
  • BASE_URL
  • MODEL_NAME

Running the Main Workflow

To run the hierarchical optimization workflow for a specific date and dataset:

python code/workflows/main.py --dataset manxianglin --date 2025-03-02 --run_id test_run_01 --iterations 5

Parameters:

• --dataset: The target benchmark region (e.g., manxianglin, hetaoyuan, huarun).
• --date: The specific date for simulation data (Format: YYYY-MM-DD).
• --run_id: A unique identifier for the experiment output folder.
• --iterations: The maximum number of negotiation rounds allowed.

Running Batch Experiments

To run experiments for a range of dates concurrently (using launcher.py):

python code/workflows/launcher.py

(Note: Configuration for dates and datasets can be modified inside launcher.py)

Running Baselines

Baseline algorithms can be executed independently from the code/baselines/ directory. For example, to run the Genetic Algorithm baseline:

python code/baselines/MetaHeuristicsSearch/GA.py

6. Anonymity Statement

This repository has been anonymized for the double-blind review process. All author names, affiliations, and specific project identifiers have been removed or replaced with generic placeholders.