MiroShark
github.com/aaronjmars/miroshark- Category
- AI Agents
- Rank
- No. 1132Tools index
Previous survey · No. 1120 ·
- Pricing
- Open Source
- Type
- APP
- Use case
- Research & Education
- Builder
- @aaronjmars
- GitHub
- 1.5k stars
- Date
About
Multi-agent simulation engine that generates hundreds of AI agents with unique personalities to simulate public reaction on social media platforms like Twitter, Reddit, and Polymarket. Upload any document and watch realistic opinion dynamics unfold hour by hour.
What it does
Feed it a brief or a question and it builds a knowledge graph of the people, organizations, and claims involved. It then spins up a crowd of personas anchored to that graph, using graph facts, relationships, semantic search, and live web lookups for well-known figures. The personas post and argue across a feed, a comment thread, and a single prediction market, all running at once, with prices and posts nudging each other. A separate reasoning step writes the closing report, citing specific posts and trades instead of summarizing in the abstract. Mid-run you can inject a news event to fork the timeline, or question one persona directly.
Why it's ranked here
The internal API guard fails closed on managed deploy platforms even if debug mode is left on by default, uses constant-time key comparison, and every public analytics endpoint returns identical fields for private and nonexistent runs so scanning can't distinguish them. The API, CLI, and MCP interfaces are documented and versioned as a real integration surface, not an afterthought bolted onto a demo. AGPL-3.0 keeps derivatives open. The cost against the accuracy of the underlying opinion-dynamics model, which nothing in the repository lets a reader verify, is the tradeoff.
What's good
The privacy engineering stands out. Preview links use a random token, strip Open Graph and robots tags so a leaked link cannot auto-unfurl in chat apps, and can be revoked instantly. One endpoint batches up to twenty simulation status lookups in a single call and returns the same 'not found' shape for private and nonexistent runs, so a scanner cannot tell them apart. The command-line client needs nothing beyond Python's own standard library, no extra packages to install, and exposes a wait command with real exit codes for scripting. Cost is not a marketing number: the API breaks every run down by phase and model, in tokens and dollars.
Tradeoffs
The stack is heavy for something meant to run locally: a graph database, a torch-based reranker, a bundled fork of another social-simulation project, and a separate Vue frontend, all wired together by one install script. The README advertises Node 18 and up, but the manifest actually requires Node 22, so the printed quick-start can fail on an otherwise-compliant machine. Demographic grounding is optional and silently degrades to graph-only personas when its libraries aren't available, safer than crashing but also easy to miss. Only English and Chinese are localized; any other language tag falls back to English without an error.
How to use it well
This fits a pre-publication gut check: a press release, a headline, a policy draft. Feed it in, watch a simulated crowd argue across a feed and a prediction market, then read the report before the real audience sees it. The command-line tool's status, publish, and cost commands are built for wiring this into a script or a release gate, not just driving it by hand. It needs an API key for a model provider and a running graph database, so budget for that setup. It is not a replacement for real audience testing, only a cheap first pass before you commission one.
Technical notes+
backend/app/__init__.py wires an internal_auth_guard before_request hook that compares the x-miroshark-internal-key header with hmac.compare_digest (constant-time) and returns 503 whenever RAILWAY_ENVIRONMENT, RAILWAY_PROJECT_ID, RAILWAY_SERVICE_ID, or K_SERVICE is set and no internal key is configured, regardless of Config.DEBUG. backend/cli.py is a stdlib-only argparse/urllib HTTP client (no requests dependency) documented in docs/CLI.md, with ask/list/status/wait/stop/frame/publish/report/cost/trending/health subcommands; wait polls /run-status until a terminal state and writes progress to stderr so stdout stays clean for --json piping. backend/pyproject.toml pins a Python 3.11+, Flask/gunicorn backend on camel-ai==0.2.90 (the bundled Wonderwall fork), torch, sentence-transformers, and igraph, with duckdb and huggingface_hub marked optional for demographic grounding. package.json sets engines.node to >=22.0.0, which is stricter than the README's stated node 18+. backend/app/api/__init__.py registers more than a dozen Flask blueprints, including mcp_bp and feed_bp; docs/ARCHITECTURE.md documents a Leiden-community detection layer and a BGE-reranker-v2-m3 cross-encoder sitting on top of the Neo4j store. Dockerfile builds on a python:3.14 base, installs Node 22 via NodeSource, and its CMD runs npm run dev, a development server rather than a production one.
Observed
- License
- AGPL-3.0
- Backend runtime
- Python 3.11+, Flask application
- Frontend build requirement
- package.json requires Node >=22.0.0, though the README badge states Node 18+
- Interfaces
- Web UI (Vue SPA), HTTP API with an OpenAPI/Swagger spec, a command-line client, and an MCP blueprint
- Packaging
- Dockerfile provided; install is a dual npm (root + frontend) and uv (backend) flow
- External dependencies
- Requires a running Neo4j instance and an LLM API key (OpenRouter, with an Ollama option for local embeddings)
- Localization
- English and Chinese (zh-CN) supported; other locale tags fall back to English without an error
Read from package.json, backend/pyproject.toml, backend/cli.py, docs/CLI.md, frontend/index.html, backend/app/__init__.py, frontend/src/App.vue, frontend/src/main.js, backend/app/api/__init__.py, backend/app/models/__init__.py, backend/app/services/__init__.py, docs/ARCHITECTURE.md, docs/API.md, Dockerfile.
What it can do
Extract entities from uploaded documents
Document file → List of extracted entities and key topics
Generate AI agents with unique personalities
Document content and parameters → Hundreds of AI personas with distinct characteristics
Simulate public reaction on Twitter
AI agents and document topics → Simulated Twitter conversations and engagement patterns
Simulate discussions on Reddit
AI agents and document topics → Simulated Reddit threads and comment chains
Simulate betting behavior on Polymarket
AI agents and document topics → Simulated prediction market activity and odds
Track opinion dynamics over time
Simulation data → Hour-by-hour belief changes and sentiment shifts
Generate cross-platform simulation reports
Multi-platform simulation results → Analytical reports with insights and trends
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.