MarketFish – Simulate a market with 128 AI consumers before you launch

Notifications You must be signed in to change notification settings

Fork 0

Star 0

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

80 Commits

80 Commits

.streamlit

.streamlit

config

config

data

data

engine

engine

locales

locales

screenshots

screenshots

tests

tests

.env.example

.env.example

.gitignore

.gitignore

Dockerfile

Dockerfile

LICENSE

LICENSE

README-ZH.md

README-ZH.md

README.md

README.md

docker-compose.yml

docker-compose.yml

main.py

main.py

requirements.txt

requirements.txt

run.py

run.py

streamlit_app.py

streamlit_app.py

Repository files navigation

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

About

Dont guess. Simulate. Multi-agent market prediction engine.

Topics

simulation

multi-agent

agent-based-modeling

product-validation

ai-agents

streamlit

market-simulation

market-prediction

llm

generative-agents

Resources

Readme

License

MIT license

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks

Report repository

Releases

No releases published

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Python 99.8%

Dockerfile 0.2%