MarketFish is a multi-agent market simulation engine that, instead of asking a single LLM whether a product will succeed, builds a digital market of 128+ AI consumer agents - each with its own identity, budget, emotions, and biases - and lets them shop across 30 rounds. Their purchase decisions, churn patterns, and social influence are meant to reveal what real users would do. It's built on six academic papers and supports 11 LLM providers. A five-stage pipeline runs each simulation: ontology extraction (market structure from seed data), a knowledge graph (entities, relationships, pain points), an agent factory (128 heterogeneous consumers driven by up to 6 LLMs), the simulation itself (30 rounds of decisions, coupling, reinforcement learning, and memory), and a final report naming who bought, why, and what killed the competitors.

Six modules implement specific papers: Memory (Generative Agents, UIST 2023 - agents remember purchases, regrets, and reflections), a Time Engine (OASIS, 2025 - realistic 24-hour activation so not every agent is active every round), a recommendation system (OASIS - personalized product recommendations), BDI v2 (TwinMarket, NeurIPS 2025 - a six-step cognitive loop plus behavioral biases), Stress (EconSimulacra, 2026 - financial/social pressure adjusting willingness to pay), and Grounding (SMIF, ETASR 2026 - RAG plus rule constraints for realistic decisions).

Use Explore mode to let the simulation discover and rank product directions from seed data with no input idea of your own, Validate mode to test your own product idea and get a survival score, buyer profiles, and an optimal price point, or Hybrid mode to pit your idea against AI-generated competitors in the same sandbox.

Don't expect it to be free to run at scale - at least one LLM API key is required (the project notes DeepSeek as the cheapest option), and more agents or more diverse providers mean more API spend; --reuse-agents on the CLI exists specifically to save cost by reusing previously generated agents across runs.

Inputs are seed data (static JSON) plus, for Validate/Hybrid modes, a product name and pricing. Output is a report naming buyer profiles, survival scoring, and competitive outcomes. The project positions itself against MiroFish, a similarly-scoped multi-agent simulation project: MarketFish is scoped specifically to product-market prediction (versus MiroFish's general-purpose social simulation), runs as a single Streamlit app with zero external dependencies for memory (versus Flask+Node.js+Docker with Zep Cloud), and supports 11 LLM providers across China and global markets (versus OpenAI-compatible only).

MarketFish itself is released under the MIT License, a more permissive terms than the comparison project mentioned above.

git clone https://github.com/Key-wxh/market-fish.git
cd market-fish
cp .env.example .env
pip install -r requirements.txt
streamlit run streamlit_app.py

At least one LLM API key must be added to .env before running. The CLI supports python run.py --mode explore, --mode validate --name "My App" --pricing "$10", and --reuse-agents to reuse previously generated agents. Supported providers span China (DeepSeek, Qwen, Doubao, Zhipu, Baidu, Hunyuan) and global (OpenAI, Anthropic, Google, Mistral, Meta).

Founders and product teams who want an evidence-based read on product-market fit - buyer profiles, pricing, and competitive dynamics - before launch, grounded in a multi-agent simulation rather than a single model's guess.