# MiroFish Simulation Platform Limitations: Current Constraints and Architectural Boundaries

> Explore MiroFish simulation platform limitations including Twitter/Reddit support, 30 concurrent LLM requests, 10 Zep memory entity types, and manual triggers. Understand current constraints and architectural boundaries.

- Repository: [BaiFu/mirofish](https://github.com/666ghj/mirofish)
- Tags: architecture
- Published: 2026-02-23

---

**MiroFish supports only Twitter and Reddit simulations through hard-coded OASIS adapters, limits concurrent LLM requests to 30 per platform, restricts Zep memory ontology to 10 entity types, and excludes automatic interview actions, requiring manual IPC triggers and careful management of API quotas and simulation rounds.**

MiroFish is an open-source multi-agent simulation framework built on the OASIS library that enables parallel social media prediction across dual platforms. While it provides a powerful sandbox for Twitter and Reddit behavior modeling, the current implementation imposes specific constraints on platform extensibility, action diversity, and resource consumption that users must navigate when designing experiments. Understanding these limitations is essential for researchers planning large-scale simulations or considering extending the system to additional social networks.

## Platform Coverage Constraints: Twitter and Reddit Only

The simulation engine is architecturally bound to two social networks. In [`backend/scripts/run_parallel_simulation.py`](https://github.com/666ghj/mirofish/blob/main/backend/scripts/run_parallel_simulation.py), the platform selection logic hard-codes `DefaultPlatformType.TWITTER` and `DefaultPlatformType.REDDIT` as the only valid options (lines 1157-1350). The dedicated runners [`run_twitter_simulation.py`](https://github.com/666ghj/mirofish/blob/main/run_twitter_simulation.py) and [`run_reddit_simulation.py`](https://github.com/666ghj/mirofish/blob/main/run_reddit_simulation.py) contain no abstraction layer for additional platforms, meaning Facebook, Weibo, or LinkedIn integrations require complete adapter rewrites rather than plugin configuration.

## Action Set Limitations and Manual Intervention Requirements

Each platform defines a restricted vocabulary of automated behaviors. [`run_twitter_simulation.py`](https://github.com/666ghj/mirofish/blob/main/run_twitter_simulation.py) declares `TWITTER_ACTIONS` and [`run_reddit_simulation.py`](https://github.com/666ghj/mirofish/blob/main/run_reddit_simulation.py) declares `REDDIT_ACTIONS` (lines 389-395), but notably exclude the `INTERVIEW` action from automatic execution. To trigger agent interviews, users must send manual IPC commands via the REST API endpoint at `localhost:5001/api/simulation/interview` using `ManualAction` payloads, as the action is deliberately omitted from the autonomous agent decision trees.

## Concurrency Throttling and Performance Bottlenecks

The system enforces strict LLM request limits to prevent API rate limiting. When initializing OASIS environments, [`run_parallel_simulation.py`](https://github.com/666ghj/mirofish/blob/main/run_parallel_simulation.py) passes `semaphore=30` to cap concurrent requests per platform (lines 1159-1360). This hard ceiling means large-scale simulations with hundreds of agents will serialize LLM calls, potentially extending runtime significantly when using high-consumption models like `qwen-plus`.

## Resource Management: Token Costs and Round Limits

MiroFish exposes a `--max-rounds` CLI flag in [`run_twitter_simulation.py`](https://github.com/666ghj/mirofish/blob/main/run_twitter_simulation.py) (lines 52-58) to truncate long-running simulations, though the default remains unlimited. The README explicitly warns that the recommended `qwen-plus` model consumes substantial tokens, advising users to keep simulations under 40 rounds to avoid exhausting API quotas or incurring prohibitive costs during extended prediction runs.

## Zep Memory and Ontology Constraints

The Zep graph memory integration imposes structural limits on simulation complexity. In [`backend/app/services/zep_graph_memory_updater.py`](https://github.com/666ghj/mirofish/blob/main/backend/app/services/zep_graph_memory_updater.py), activities batch in groups of 5 before persistence (lines 216-227), introducing latency for high-frequency event streams. Additionally, [`ontology_generator.py`](https://github.com/666ghj/mirofish/blob/main/ontology_generator.py) enforces a maximum of 10 custom entity types and 10 custom edge types (lines 87-90), forcing researchers with complex ontologies to merge or trim categories manually.

## State Detection Reliability Issues

Simulation completion detection relies on log file parsing rather than process monitoring. The [`simulation_runner.py`](https://github.com/666ghj/mirofish/blob/main/simulation_runner.py) checks for `simulation_end` events in per-platform `actions.jsonl` logs (lines 24-31) to determine platform status. If log corruption occurs or the marker is missing, the system incorrectly reports platforms as active, potentially leaving zombie processes or blocking downstream analysis pipelines.

## Windows Compatibility Workarounds

The codebase includes platform-specific patches for Windows environments. [`run_parallel_simulation.py`](https://github.com/666ghj/mirofish/blob/main/run_parallel_simulation.py) monkey-patches Python's built-in `open` function and environment variables to force UTF-8 encoding (lines 28-66), addressing Unicode errors in OASIS dependencies. However, this workaround may not extend to all third-party libraries, presenting stability risks on Windows hosts with non-standard locale configurations.

## Extensibility Barriers for New Platforms

Adding a third platform requires significant architectural duplication. The parallel runner merges two independent OASIS environments but exposes no plugin mechanism or abstract base class for additional adapters. Implementing support for Instagram or TikTok would necessitate replicating the entire environment setup, logging infrastructure, and IPC handling found in the existing Twitter and Reddit implementations.

## Practical Workarounds and Configuration Examples

### Capping Simulation Rounds to Control Costs

Prevent runaway token consumption by explicitly setting round limits:

```bash
python backend/scripts/run_parallel_simulation.py \
    --config simulation_config.json \
    --max-rounds 30

```

This truncates execution after 30 rounds, approximately 15 hours at 30 minutes per round.

### Monitoring Concurrency Limits

The semaphore restriction is embedded in the environment initialization:

```python
env = oasis.make(
    agent_graph=graph,
    platform=oasis.DefaultPlatformType.TWITTER,
    database_path=db_path,
    semaphore=30,  # Hard limit on concurrent LLM calls

)

```

### Triggering Manual Interviews

Since `INTERVIEW` is excluded from `TWITTER_ACTIONS`, use the IPC interface:

```bash
curl -X POST http://localhost:5001/api/simulation/interview \
     -H "Content-Type: application/json" \
     -d '{"agent_id": 42, "prompt": "What do you think about X?"}'

```

### Designing Ontologies Within Zep Limits

Structure entity types to respect the 10-category ceiling:

```python

# ontology_generator.py enforces truncation at 10 types

ontology = {
    "entity_types": [
        {"name": "Person", "description": "..."},
        {"name": "Organization", "description": "..."},
        # Maximum 10 entries; additional types are silently dropped

    ],
    "edge_types": [...]  # Also limited to 10

}

```

## Summary

- **Dual-platform restriction**: Only Twitter and Reddit are supported via hard-coded adapters in [`run_parallel_simulation.py`](https://github.com/666ghj/mirofish/blob/main/run_parallel_simulation.py) and platform-specific runner scripts.
- **Action limitations**: The `INTERVIEW` action is excluded from automated execution and requires manual IPC triggers via the REST API.
- **Concurrency caps**: A `semaphore=30` limit restricts simultaneous LLM requests per platform, serializing large agent populations.
- **Resource boundaries**: Zep memory updates batch in groups of 5, while ontologies are capped at 10 entity types and 10 edge types.
- **State detection fragility**: Completion status relies on `simulation_end` markers in `actions.jsonl` logs, creating failure modes if logs corrupt.
- **No plugin architecture**: Extending to additional platforms requires duplicating the entire OASIS environment setup and logging infrastructure.

## Frequently Asked Questions

### Why does MiroFish only support Twitter and Reddit?

The platform adapters are hard-coded in [`backend/scripts/run_parallel_simulation.py`](https://github.com/666ghj/mirofish/blob/main/backend/scripts/run_parallel_simulation.py) (lines 1157-1350) with explicit `DefaultPlatformType.TWITTER` and `REDDIT` enumerations. The architecture lacks a plugin interface, so adding Facebook or other networks requires building new OASIS adapters from scratch rather than configuration.

### How can I run simulations without exceeding API rate limits?

The system automatically throttles LLM requests using a semaphore value of 30 concurrent calls per platform, implemented in the OASIS environment initialization. For additional control, use the `--max-rounds` flag to truncate long simulations and monitor the `qwen-plus` token consumption, keeping rounds under 40 as recommended in the documentation.

### Why are my agent interviews not executing automatically?

The `INTERVIEW` action is deliberately excluded from `TWITTER_ACTIONS` and `REDDIT_ACTIONS` in the runner scripts (lines 389-395). This action requires manual invocation through the IPC command interface at `localhost:5001/api/simulation/interview`, ensuring interviews only occur under explicit researcher direction rather than autonomous agent decisions.

### What happens if I define more than 10 entity types in my ontology?

[`backend/app/services/ontology_generator.py`](https://github.com/666ghj/mirofish/blob/main/backend/app/services/ontology_generator.py) enforces a hard limit of 10 custom entity types and 10 custom edge types (lines 87-90). Additional types beyond this ceiling are silently truncated or merged, which may require manually consolidating your ontology categories to fit within these Zep API constraints.