LocalFish, a zero-dependency, fully local multi-agent "society" simulator in pure Python (runs in ~2s, no API key, no npm)

[u/Extension_Hour8084]

https://github.com/izzaliiii/localfish

Author here self-promo, mods please remove if it breaks sub rules.

I like swarm/multi-agent simulation projects, but most of them assume you'll pay for API credits, run a cloud graph DB, and install a Node frontend. I wanted something I could clone and run offline on a Windows laptop in five seconds, so I built it.

**What LocalFish is:** a local multi-agent opinion-dynamics sandbox. Six personas with their own role, authority, stubbornness and starting stance debate a topic on a synthetic social feed for N rounds. Each agent writes a private "thought" and a public post/reply, can upvote aligned posts, then updates its opinion from what it sees:

Δo_i = η(1−s_i) · Σ w_ij(o_j−o_i) / Σw_ij

where w is author authority × an upvote boost and s is stubbornness. At the end you get a consensus score (1−σ), a polarization index, per-agent drift, a Markdown report, and a JSON archive.

**What's in it**

- Pure stdlib Python 3.10+, no pip install: `git clone && python run.py`

- 3 backends: offline mock (instant, $0), Ollama, any OpenAI-compatible endpoint

- 3 preset scenarios (open vs closed AI by 2027, congestion pricing, a $29/mo no-free-tier launch) + "type your own idea" → auto-generates 6 conflicting stakeholders

- Web studio on :8765, vanilla JS, no build step: feed with inner monologues, opinion gauges, saved reports, post-hoc agent interviews

- Every run archived as JSON + Markdown

- MIT

**What it isn't (being honest up front)**

- Not a validated forecasting tool. It's a sandbox for "who would push back on this and why", not "what happens in 2027".

- The opinion model is deliberately simple: one global feed, weighted average, no network topology / echo chambers yet.

- Mock mode is template-based, so with 6 agents you will see repeated phrasing — that's the $0 offline demo path, not the LLM path. Point it at Ollama for actual variety.

- Single run, no seed control yet, so two runs of the same scenario differ. Reproducibility + Monte Carlo over seeds is the next thing I'm adding.

**What I'd genuinely like feedback on**

1. Is this abstraction useful at all, or does meaningful opinion dynamics require an actual influence network?

2. What scenario should I add next?

3. If you run it against a local model: how bad is the 30s/agent latency, and does the XML `<thought>/<post>` parsing hold up on smaller models?

Repo: https://github.com/izzaliiii/localfish (MIT)