MiroFish Simulation Platform Limitations: Current Constraints and Architectural Boundaries

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, 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 and 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 declares TWITTER_ACTIONS and 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 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 (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, activities batch in groups of 5 before persistence (lines 216-227), introducing latency for high-frequency event streams. Additionally, 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 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 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:

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:

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:

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:

# 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 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 (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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}