Content
# 🔮 ArcaneBazaar — Mystic Marketplace
> *"Where mana meets marketplace."*
>
> A mystical marketplace operated by AI guardians, where magic meets commerce.
## 🧙 What's This Magic?
**ArcaneBazaar** is a multi-agent magical marketplace system based on Google's **A2A (Agent-to-Agent) protocol**. Simply express your desires in natural language - inquire about today's phenomena, search for legendary items, or place purchase orders - and three AI guardians will collaborate to fulfill your requests.
Say goodbye to scrolling through shelves of scrolls. Let AI do the legwork for you.
```
You: "Is there a magical storm in the Crimson Wastes today? Also, check if there are any Dragon's Breath potions for sale."
🔮 System:
→ PhenomenaQueryAssistant queries phenomena...
→ BazaarQueryAssistant searches marketplace...
→ Both guardians respond and present the results
```
## 🏗️ The Architecture of ArcaneBazaar
```
🔮 Traveler (You)
│
┌────▼────┐
│ ArcaneBazaar │ Streamlit / CLI
│ Entrance Hall │ Intent recognition → Routing
└─┬──┬──┬─┘
│ │ │
┌──────────┘ │ └──────────┐
│ │ │
┌─────▼─────┐ ┌────▼────┐ ┌─────▼─────┐
│ 🌋 Phenomena │ │ 📜 Marketplace │ │ ⚖️ Treasury │
│ Query Assistant │ │ Query Assistant │ │ Order Assistant │
│ :5005 │ │ :5006 │ │ :5007 │
└─────┬─────┘ └────┬────┘ └─────┬─────┘
│ │ │
┌─────▼─────┐ ┌────▼────┐ ┌─────▼─────┐
│ MCP Phenomena │ │ MCP Marketplace│ │ MCP Order │
│ Tool │ │ Tool │ │ Tool │
│ :8002 │ │ :8001 │ │ :8003 │
└─────┬─────┘ └────┬────┘ └─────┬─────┘
│ │ │
└─────────────┼─────────────┘
│
┌─────▼─────┐
│ 📚 │
│ MySQL │
│ arcane_ │
│ bazaar │
└───────────┘
```
Three-layer architecture: **UI → A2A Guardians → MCP Tools → Database**
LLMs are responsible for: intent understanding, SQL generation, and result refinement. Guardians are responsible for scheduling and execution.
## 🎭 The Three Guardians
| Guardian | Contract Port | Responsibilities | Catchphrase |
|---|---|---|---|
| 🌋 **PhenomenaQueryAssistant** | `:5005` | Queries magical phenomena across domains | *"The crystal ball shows..."* |
| 📜 **BazaarQueryAssistant** | `:5006` | Searches marketplace for magical items | *"Let's take a look!"* |
| ⚖️ **BazaarOrderAssistant** | `:5007` | Handles purchases and transactions | *"One hand for money, one hand for goods!"* |
Each guardian is equipped with its own **MCP tool** (`:8001` / `:8002` / `:8003`), directly querying or operating data through MySQL.
## 🧪 Alchemical Recipes (Tech Stack)
| Ingredient | Purpose |
|---|---|
| **Python 3.12+** | The crucible for everything |
| **Streamlit** | Crystal ball projection (Web UI) |
| **A2A Protocol** (`python-a2a`) | Telepathy between guardians |
| **MCP Protocol** (`mcp`) | Magical runes (tool invocation protocol) |
| **LangChain** | Spell components (LLM orchestration) |
| **Qwen 2.5 72B** | The sage's brain (LLM, via SiliconFlow) |
| **MySQL** | The great library (data storage) |
| **FastAPI / Uvicorn** | Guardians' contract channels |
## 📖 Mystic Compendium (Database)
### `mystical_phenomena` — Phenomena Forecast
Seven domains, daily updated magical observation data:
| Domain | Today's Phenomenon | Danger Level |
|---|---|---|
| 🌳 Eldergrove | Fairy lantern dance | 🟢 1/5 |
| ⛰️ Iron Furnace Mountains | Mineral vein flicker | 🟡 2/5 |
| 🏜️ Crimson Wastes | Sandstorm | 🟠 4/5 |
| 🏝️ Shattered Isles | Tidal surge | 🟡 2/5 |
| 🗼️ Celestial Spires | Star alignment | 🟢 1/5 |
| 💎 Crystal Caverns | Crystal resonance | 🟡 2/5 |
| 🌌 Void Frontier | Boundary stability | 🟢 1/5 |
### `magical_items` — Marketplace Shelves
20 magical items, from 100-crystal mana crystals to 200,000-crystal hourglasses, covering six categories: artifact, potion, scroll, reagent, weapon, and familiar.
## 🚀 Opening Guide
### 0. Prerequisites
- Python 3.12+
- MySQL 8.0+
- SiliconFlow API Key (or any LLM service compatible with OpenAI interface)
### 1. Clone & Install
```bash
cd ArcaneBazaar
pip install -r requirements.txt
```
### 2. Initialize Database
```bash
mysql -u root -p < sql/schema.sql
mysql -u root -p < sql/sample_data.sql
```
### 3. Configure API Key
```bash
$env:SILICONFLOW_API_KEY = "sk-your-key-here"
```
or modify the default value in `config.py`.
### 4. Summon Guardians
Open **four terminal windows** and execute:
```bash
# Terminal 1 — Start MCP tool servers
python mcp_server/mcp_phenomena_server.py # Phenomena tool :8002
python mcp_server/mcp_bazaar_server.py # Marketplace tool :8001
python mcp_server/mcp_order_server.py # Order tool :8003
# Terminal 2 — Start A2A guardians
python a2a_server/phenomena_server.py # Phenomena query assistant :5005
python a2a_server/bazaar_server.py # Marketplace query assistant :5006
python a2a_server/order_server.py # Treasury order assistant :5007
# Terminal 3 — Start Web interface
streamlit run app.py
# Terminal 4 (optional) — CLI mode
python main.py
```
> Hint: MCP and A2A servers require separate processes. You can use `start` (Windows) or `&` (Linux) to run in the background.
### 5. Start Conversation
Access `http://localhost:8501` in your browser and try these spells:
- *"Is there a meteor shower in the Celestial Spires today?"*
- *"Help me find a legendary artifact"*
- *"Are there any weapons under 5000 crystals?"*
- *"I want to buy a Phoenix Quill"*
- *"Tell me a story about the Void Frontier"*
## 🗺️ Conversation Examples
```
💬 Traveler: What are the dangers in the Crimson Wastes for the next 3 days?
📜 Guardian:
According to the magical eye's observations, the next three days' phenomena in the Crimson Wastes are as follows —
7/13: Sandstorm (common. Very sandy. Very much.)
7/14: Magical storm! Danger level 5/5, magical runaway probability 90%
— Last time someone was teleported to a troll's bathtub. Highly recommend staying home.
7/15: Blood moon shadow, danger level 3/5, probability 45%
— The old mercenary said this is a good omen, but the last time he said this, he encountered three dragons.
💬 Traveler: Are there any Dragon's Breath potions? I'll take two.
📜 Guardian:
【Epic】Dragon's Breath Potion (potion) — 8,000 crystals | Inventory: 15 | Crimson Wastes
Grants fire-breathing ability for 10 minutes. Side effects: spontaneous combustion, golden craving, nesting impulse.
Inventory confirmed: 15 bottles in stock.
Order result: Congratulations! 'Dragon's Breath Potion' x2 purchased! Griffin Express is on the way (may request snacks).
```
## 🧭 Project Structure
```
ArcaneBazaar/
├── app.py # Streamlit Web interface
├── main.py # CLI command-line interface
├── main_prompts.py # All LLM prompt templates
├── config.py # Configuration center
├── create_logger.py # Logging tool
├── requirements.txt # Python dependencies
│
├── a2a_server/ # A2A protocol guardians
│ ├── phenomena_server.py # Phenomena query assistant
│ ├── bazaar_server.py # Marketplace query assistant
│ └── order_server.py # Treasury order assistant
│
├── mcp_server/ # MCP protocol tools
│ ├── mcp_phenomena_server.py
│ ├── mcp_bazaar_server.py
│ └── mcp_order_server.py
│
├── query_data/ # Database query services
│ └── query1.py
│
├── sql/ # SQL schema & data
│ ├── schema.sql
│ └── sample_data.sql
│
├── utils/ # Utility functions
│ └── format.py
│
└── test/ # Test scripts
├── test_phenomena_mcp_server.py
└── test_bazaar_agent_server.py
```
## ⚠️ Disclaimer
This system is a technical demonstration project. All magical items are fictional and do not provide real Dragon's Breath Potion, teleportation scrolls, or Phoenix Quill for purchase. If you successfully cast a spell in the real world, please contact the nearest magical academy.
*Built with A2A Protocol + MCP + LangChain + a pinch of pixie dust.*
*"May your mana never run dry."*
