MiroShark boundary

Type: agentic-system-analyses/types/agentic-system-boundary.md

Boundary and evidence

This run covers MiroShark as a shipped application for building document-derived agent populations, running social-media and prediction-market simulations, and consuming their retained results through reports, interviews and retrieval. Its intended analytical use is to explain the source-native runtime and state loop, not to establish that simulated outcomes predict real populations. The declared pipeline includes graph build, agent setup, simulation, reporting and interaction (SRC-1, docs/ARCHITECTURE.md).

The target class is enclosing runtime. MiroShark is not merely the graph-storage API or a client of a separately shipped simulation service: its server selects and launches shipped simulation drivers; those drivers create agents, supply context, advance environments and collect actions. The bundled Wonderwall package and graph-memory stack are internal mechanisms of this target. The shell launcher, browser client, HTTP CLI and stdio MCP server are also shipped paths, not excluded enclosing applications (SRC-1, miroshark, backend/run.py, backend/app/__init__.py, backend/cli.py, backend/mcp_server.py, backend/app/services/simulation_runner.py, backend/scripts/run_parallel_simulation.py).

The server's driver selection makes the ownership boundary explicit:

if platform == "twitter": script_name = "run_twitter_simulation.py" --- backend/app/services/simulation_runner.py

elif platform == "polymarket": script_name = "run_parallel_simulation.py" --- backend/app/services/simulation_runner.py

The parallel driver supplies the model-dependent action loop rather than returning a one-shot computation:

async def step_twitter(active_agents=active): actions = {agent: LLMAction() for , agent in active_agents} await twitter_result.env.step(actions) return active_agents --- backend/scripts/run_parallel_simulation.py

The agent obtains an environment observation and passes the resulting user message into its model-driven step (SRC-1, backend/wonderwall/social_agent/agent.py):

response = await self.astep(user_msg) tool_calls_data = [] for tool_call in response.info['tool_calls']: --- backend/wonderwall/social_agent/agent.py

Functional scope and initial loop trace

The boundary kind is whole-system: it includes state producers, maintenance paths, admission/configuration, execution and later consumers, rather than isolating the embedded runtime. The following paths establish that functional scope; they are initial inspection anchors, not a file allowlist.

• Input admission and graph production: browser requests reach graph API routes; project management retains uploaded/extracted text and metadata; graph construction calls storage ingestion. Storage ingestion obtains the graph ontology, extracts entities and relations and embeds their text (SRC-1, frontend/src/api/graph.js, backend/app/api/graph.py, backend/app/models/project.py, backend/app/services/graph_builder.py, backend/app/storage/neo4j_storage.py).
• Graph-to-agent consumption: simulation preparation reads defined graph entities with edges, instantiates the profile generator with storage and graph ID, and supports real-time profile files. Configuration and profile reload paths remain included; they are not external fixtures (SRC-1, backend/app/services/simulation_manager.py, backend/app/services/wonderwall_profile_generator.py).
• Prompts and maintenance: the locale registry and shipped prompt packages, round-memory compaction, belief updates, cross-platform context and optional graph-memory updates all belong to the target. The parallel driver's post-round path records fetched actions, updates beliefs and compacts memory for subsequent rounds (SRC-1, backend/app/prompts/registry.py, backend/app/prompts/locales/en/profile_generator.py, backend/scripts/run_parallel_simulation.py, backend/scripts/round_memory.py, backend/app/services/graph_memory_updater.py).
• Retained state and later use: action logs feed report tools; report metadata and Markdown are saved and reloaded; optional reasoning traces are initialized through graph storage. Browser interaction reloads reports, profile data and action history. The stdio MCP server directly exposes graph search, community construction/browsing and retained report reasoning (SRC-1, backend/app/services/report_agent.py, frontend/src/components/Step5Interaction.vue, backend/mcp_server.py).
• Other shipped control paths: single-platform drivers, environment-only interview reload, branch/counterfactual preparation, simulation API control, MCP tool integration, publishing and export services remain inside the boundary. Initial inspection traced driver selection and parallel execution, reload/branch preparation, API call sites and MCP storage dispatch; it did not exhaustively assess each auxiliary route (SRC-1, backend/app/services/simulation_runner.py, backend/app/services/simulation_manager.py, backend/app/api/simulation.py, backend/scripts/run_parallel_simulation.py, backend/mcp_server.py).
• Evaluators: backend tests, script-based pipeline probes, CI and root deployment smoke tooling are included as source evidence about checks, not as successful executions. Initial inspection includes the stub-backed Camel compatibility test, CI job definitions and deployment smoke-test source (SRC-1, backend/tests/test_smoke_camel_agent.py, .github/workflows/tests.yml, scripts/smoke_test.py).

Two retained-state connections illustrate why this is not a storage-only boundary. The graph updater writes simulated activity back through ingestion:

self.storage.add_text( self.graph_id, combined_text, valid_at=valid_at, kind=edge_kind, source_type="agent", source_id=source_id, ) --- backend/app/services/graph_memory_updater.py

The report consumer reads the simulation's persisted per-platform actions:

actions_path = os.path.join(sim_dir, platform, "actions.jsonl") --- backend/app/services/report_agent.py

Top-level coverage

All tracked top-level entries are classified below from the pinned Git tree (SRC-1). Included means eligible for this whole-system analysis, not that every line has been inspected. Directory rows name material subpaths. Excluded means a deliberate functional exclusion, not inaccessible evidence. No material shipped loop path was unavailable. Files explicitly marked not yet inspected are available; no behavioral conclusion is drawn from their contents here.

Frozen evidence and external limits

The only frozen source is SRC-1 at full commit e95d3d8c2a2206b8b6695648e8504cf23436d3de; checkout HEAD was verified against the supplied acquisition pin. The applicability cutoff is 2026-10-15, the supplied run date. It is not a claim that upstream activity after this commit was searched or that the checkout represents the latest upstream release. The overall evidence tier is code-grounded, with target-authored architecture and prompt text supplying declared design alongside implementation.

External dependencies are not additional frozen sources: Neo4j, model/embedding providers (including the illustrated Ollama deployment), Camel, numerical/retrieval libraries and external MCP hosts/services are outside this repository's implementation boundary. Their shipped adapters and configuration remain included. The backend manifest explicitly bundles Wonderwall while depending on Camel (SRC-1, backend/pyproject.toml):

Wonderwall (wonderwall package) is bundled directly in backend/wonderwall/

"camel-oasis==0.2.5", # replaced by bundled Wonderwall

"camel-ai==0.2.90", --- backend/pyproject.toml

No dependency repositories, provider outputs, deployed databases, live web enrichment, remote demographic datasets or external publication services were captured. These access limits prevent conclusions about dependency internals, actual model decisions, factual grounding supplied remotely, live integration reliability and deployed retention. No target code, tests, examples or service calls were executed. Test and architecture descriptions therefore support only attributed design/check intent; they do not establish observed runs, predictive validity, cost, latency or causal effects. The deliberate exclusions in the coverage table do not remove any identified simulation or graph-memory state-loop responsibility.

Source register