๐ MarketFish
Don't guess. Simulate.
Before you launch, let hundreds of AI consumers vote with their wallets.
MarketFish is a multi-agent market simulation engine. Instead of asking one LLM "will this product succeed?", it builds a digital market with 128+ AI consumers โ each with their own identity, budget, emotions, and biases โ and lets them shop across 30 rounds. Their purchase decisions, churn patterns, and social influence reveal what real users would do.
Built on 6 academic papers (Generative Agents, OASIS, TwinMarket, Agent Bazaar, EconSimulacra, SMIF) and 11 LLM providers.
Quick Start
git clone https://github.com/Key-wxh/market-fish.git cd market-fish cp .env.example .env # Edit .env โ add at least ONE LLM API key (DeepSeek is cheapest) pip install -r requirements.txt streamlit run streamlit_app.py
Open http://localhost:8501 โ pick a mode โ run.
Screenshots
How It Works
Seed Data (static JSON) โ 5-Stage Pipeline
1. Ontology โ extract market structure
2. Knowledge Graph โ entities, relationships, pain points
3. Agent Factory โ 128 heterogeneous AI consumers (6 LLMs)
4. Simulation โ 30 rounds: decisions, coupling, RL, memory
5. Report โ evidence: who bought, why, what killed competitors
V6 Modules (6 papers implemented)
| Module | Paper | What it does |
|---|---|---|
| Memory | Generative Agents (UIST 2023) | Agents remember purchases, regrets, reflections |
| Time Engine | OASIS (2025) | Realistic 24h activation โ not all active every round |
| RecSys | OASIS (2025) | Personalized product recommendations |
| BDI v2 | TwinMarket (NeurIPS 2025) | 6-step cognitive loop + behavioral biases |
| Stress | EconSimulacra (2026) | Financial/social pressure โ adjusted willingness to pay |
| Grounding | SMIF (ETASR 2026) | RAG + rule constraints for realistic decisions |
Modes
| Mode | Input | Output |
|---|---|---|
| ๐ Explore | Seed data | AI discovers product directions, ranked |
| โ Validate | Your product idea | Survival score, buyer profiles, optimal price |
| โ๏ธ Hybrid | Your product + data | Your idea vs AI competitors, same sandbox |
Supported LLM Providers
11 providers. One is enough. More = more diverse agents.
| ๐จ๐ณ China | DeepSeek, Qwen, Doubao, Zhipu, Baidu, Hunyuan | | ๐ Global | OpenAI, Anthropic, Google, Mistral, Meta |
CLI
python run.py --mode explore # Discover directions python run.py --mode validate --name "My App" --pricing "$10" # Test your idea python run.py --mode explore --reuse-agents # Reuse agents (save cost)
Project Structure
market-fish/
โโโ engine/ # Core engine (20+ modules)
โ โโโ simulator.py, agent_factory.py # Simulation core
โ โโโ agent_store.py, memory.py # V6: persistence + memory
โ โโโ temporal.py, recsys.py # V6: time + recommendations
โ โโโ bdi_v2.py, stress.py, grounding.py # V6: cognition + stress + validation
โโโ config/ # Model registry + parameters
โโโ locales/ # EN/ZH i18n (300+ keys)
โโโ tests/ # 26/26 tests
โโโ streamlit_app.py # Dashboard
โโโ run.py # CLI
โโโ .env.example # API key template
Academic Foundation
| Paper | Venue | ID | Module |
|---|---|---|---|
| Generative Agents | UIST 2023 | 2304.03442 | Memory |
| OASIS | 2025 | 2411.11581 | RecSys + TimeEngine |
| SMIF | ETASR 2026 | 10.48084/etasr.16536 | Grounding |
| Agent Bazaar | Princeton 2026 | 2605.17698 | RL |
| TwinMarket | NeurIPS 2025 | 2502.01506 | BDI v2 |
| EconSimulacra | 2026 | 2606.26883 | Stress |
vs MiroFish
MiroFish (5.5k โญ) is the most well-known multi-agent simulation engine. Both projects simulate social/market behavior with AI agents โ but with different focuses:
| MiroFish | MarketFish | |
|---|---|---|
| Scope | General-purpose social simulation | Product market prediction |
| Architecture | Flask + Node.js + Docker | Streamlit single-app |
| Memory | Zep Cloud (external service) | Built-in (local JSON, zero external deps) |
| LLMs | OpenAI-compatible only | 11 providers (China + Global) |
| Data | User-uploaded documents | 8-source live ingestion pipeline |
| Language | EN/ZH | EN/ZH |
| License | AGPL-3.0 | MIT |
License
MIT โ free for personal and commercial use.
Built by Keystart AI ยท Solo founder ยท AI-Native