# What Can You Now Ask the Sandbox?

> The closing reframe: once graph memory, simulated traces, and agent interviews exist, the report system can reason with tools, assemble evidence section by section, and keep the UI portable across file, repository, or catalog skill sources rather than a single hosted provider.

- Repository: 666ghj/MiroFish
- GitHub: https://github.com/666ghj/MiroFish
- Human wiki: https://grok-wiki.com/public/wiki/666ghj-mirofish-5af7beba06b9
- Complete Markdown: https://grok-wiki.com/public/wiki/666ghj-mirofish-5af7beba06b9/llms-full.txt

## Source Files

- `backend/app/api/report.py`
- `backend/app/services/report_agent.py`
- `backend/app/services/zep_tools.py`
- `backend/app/api/simulation.py`
- `frontend/src/components/Step4Report.vue`
- `frontend/src/components/Step5Interaction.vue`
- `frontend/src/api/report.js`
- `frontend/src/views/InteractionView.vue`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [backend/app/api/report.py](backend/app/api/report.py)
- [backend/app/services/report_agent.py](backend/app/services/report_agent.py)
- [backend/app/services/zep_tools.py](backend/app/services/zep_tools.py)
- [backend/app/api/simulation.py](backend/app/api/simulation.py)
- [backend/app/config.py](backend/app/config.py)
- [backend/app/utils/llm_client.py](backend/app/utils/llm_client.py)
- [frontend/src/components/Step4Report.vue](frontend/src/components/Step4Report.vue)
- [frontend/src/components/Step5Interaction.vue](frontend/src/components/Step5Interaction.vue)
- [frontend/src/api/report.js](frontend/src/api/report.js)
- [frontend/src/api/simulation.js](frontend/src/api/simulation.js)
- [frontend/src/views/InteractionView.vue](frontend/src/views/InteractionView.vue)
</details>

# What Can You Now Ask the Sandbox?

This page reframes the end state of MiroFish: after a project has graph memory, a completed simulation, generated report sections, and live agent profiles, the sandbox is no longer just a run log. It becomes a question-answering workbench where a report agent can inspect graph facts, reason through simulated outcomes, and ask simulated agents for first-person responses.

The repository code remains the source of truth here. The selected Compound Engineering knowledge profile shaped the page as reusable wiki knowledge, but no `STRATEGY.md` or `docs/solutions/**` files were present in the inspected repository file list, so this page does not claim prior strategy or solved-problem notes as evidence.

## What Problem Exists?

The product problem is simple: a simulation produces too much raw evidence for a user to inspect manually. The backend therefore turns a `simulation_id` into a report task, validates that the simulation, project, graph, and simulation requirement exist, creates a `report_id`, and runs generation in a background thread. The frontend then watches logs and sections rather than waiting for one final blob.

Sources: [backend/app/api/report.py:25-192](), [frontend/src/components/Step4Report.vue:2020-2165]()

The important reframe is that report generation is not only "write a summary." It is an evidence assembly loop:

```text
simulation_id
  -> graph_id + simulation_requirement
  -> ReportAgent
  -> outline
  -> section_01.md, section_02.md, ...
  -> full_report.md
  -> interaction workbench
```

Sources: [backend/app/services/report_agent.py:1532-1550](), [backend/app/services/report_agent.py:1630-1729]()

## What Is The Simplest Version?

The simplest useful sandbox question is: "What happened in this simulation?" MiroFish answers that by using graph context to plan a report outline, then by generating each section independently. The planning prompt receives the simulation requirement, graph statistics, entity types, active entity count, and related facts, then asks the model for a JSON outline. If outline planning fails, the code falls back to a three-section default report shape.

Sources: [backend/app/services/zep_tools.py:890-941](), [backend/app/services/report_agent.py:1160-1219]()

The persisted report model is intentionally file-shaped: metadata, outline, progress, per-section Markdown, logs, and the final assembled report all live under the report folder. That makes partial output inspectable and recoverable.

Sources: [backend/app/services/report_agent.py:1884-1955](), [backend/app/services/report_agent.py:2200-2228](), [backend/app/services/report_agent.py:2447-2497]()

## Where Does Complexity Become Necessary?

Complexity becomes necessary once the system must answer "why?" and "what evidence supports that?" The `ReportAgent` uses a ReACT loop for each section: ask for tool calls, execute only the first tool call in a turn, feed the observation back, require enough tool use before accepting a final answer, and log each step. The loop also handles malformed responses, such as a model returning both a tool call and a final answer in the same message.

Sources: [backend/app/services/report_agent.py:1221-1309](), [backend/app/services/report_agent.py:1324-1402](), [backend/app/services/report_agent.py:1432-1530]()

The available tools map to different evidence questions:

| User question | Tool path | What it contributes |
| --- | --- | --- |
| "What are the strongest findings?" | `insight_forge` | Breaks a complex question into sub-queries, searches graph facts, extracts entities, and builds relationship chains. |
| "What changed over time?" | `panorama_search` | Separates active facts from historical or expired facts. |
| "Can you verify this one claim?" | `quick_search` | Runs a direct graph search and returns the most relevant facts. |
| "What would affected agents say?" | `interview_agents` | Selects simulated agents, generates interview questions, and calls the simulation interview API. |

Sources: [backend/app/services/report_agent.py:919-954](), [backend/app/services/zep_tools.py:945-1090](), [backend/app/services/zep_tools.py:1145-1270](), [backend/app/services/zep_tools.py:1272-1325]()

## What Can You Ask Now?

Once the report exists, the user can ask the sandbox questions that combine four evidence surfaces:

1. The report content already generated for the simulation.
2. The Zep graph and its facts, nodes, edges, entity summaries, and timelines.
3. Simulated agent profiles loaded from the simulation artifacts.
4. Live or batch interviews against the running simulation environment.

Sources: [backend/app/services/report_agent.py:1766-1865](), [backend/app/services/zep_tools.py:1505-1549](), [backend/app/api/simulation.py:990-1075](), [backend/app/api/simulation.py:2142-2325]()

Good sandbox questions are therefore not generic prompts. They are evidence-seeking prompts:

- "Which simulated groups amplified the issue, and what graph facts support that?"
- "Where did the report rely on current facts versus historical facts?"
- "Interview the most relevant agents about this risk and compare their answers."
- "Show me the relationship chain behind this conclusion."
- "Which section has the weakest evidence?"

The `/api/report/chat` endpoint supports this mode by reconstructing the simulation and project context, resolving the graph, creating a `ReportAgent`, and returning the agent's response, tool calls, and source queries. The frontend calls that endpoint through `chatWithReport`.

Sources: [backend/app/api/report.py:472-556](), [frontend/src/api/report.js:45-51](), [frontend/src/components/Step5Interaction.vue:682-710]()

## How Does The UI Keep Evidence Visible?

Step 4 is the report-generation cockpit. It renders the planned outline, generated sections, metrics, timeline events, tool calls, tool results, model responses, and console output. It polls `agent-log` every two seconds and `console-log` every 1.5 seconds, extracting `planning_complete`, `section_start`, `section_complete`, and `report_complete` into visible UI state.

Sources: [frontend/src/components/Step4Report.vue:7-65](), [frontend/src/components/Step4Report.vue:88-140](), [frontend/src/components/Step4Report.vue:2024-2165]()

Step 5 is the interaction workbench. It defaults to report-agent chat, but can switch to a selected simulated agent or a survey tab. It loads the completed report from agent logs, loads realtime Reddit profiles for the simulation, and routes messages either to the report agent or to the batch interview API.

Sources: [frontend/src/components/Step5Interaction.vue:421-456](), [frontend/src/components/Step5Interaction.vue:501-542](), [frontend/src/components/Step5Interaction.vue:645-760](), [frontend/src/components/Step5Interaction.vue:876-961]()

`InteractionView` keeps the graph and interaction panel separate. It resolves `reportId -> simulationId -> project -> graph`, then displays the graph panel next to `Step5Interaction`. That separation is what lets the workbench ask questions without hiding the graph evidence behind the chat surface.

Sources: [frontend/src/views/InteractionView.vue:38-61](), [frontend/src/views/InteractionView.vue:145-218]()

## How Provider-Neutral Is This?

The model client is OpenAI-compatible, but the actual API key, base URL, and model name come from environment configuration. That means the architecture is BYOK-friendly and can point at any provider that speaks the same chat-completions shape. It is not fully vendor-agnostic yet, because graph memory is explicitly backed by `zep_cloud.client.Zep` and `ZEP_API_KEY`.

```python
# backend/app/config.py
LLM_API_KEY = os.environ.get('LLM_API_KEY')
LLM_BASE_URL = os.environ.get('LLM_BASE_URL', 'https://api.openai.com/v1')
LLM_MODEL_NAME = os.environ.get('LLM_MODEL_NAME', 'gpt-4o-mini')
ZEP_API_KEY = os.environ.get('ZEP_API_KEY')
```

Sources: [backend/app/config.py:30-37](), [backend/app/config.py:66-74](), [backend/app/utils/llm_client.py:17-33](), [backend/app/services/zep_tools.py:425-440]()

For a Grok-Wiki or skill-pack integration, the portable boundary should be above the repository code: treat file, repository, and catalog skill sources as interchangeable knowledge inputs that shape planning and QA, not as a hosted-provider dependency. MiroFish already has useful internal boundaries to build on: frontend API wrappers, report IDs, simulation IDs, graph IDs, and injectable `llm_client` / `zep_tools` constructor arguments. The missing abstraction is a formal graph-memory adapter beyond Zep.

Sources: [frontend/src/api/report.js:1-51](), [frontend/src/api/simulation.js:35-50](), [frontend/src/api/simulation.js:171-177](), [backend/app/services/report_agent.py:884-910]()

## What Would Break If The Abstractions Disappeared?

If per-section files disappeared, the UI could no longer show section completion incrementally, and failure recovery would be weaker. If structured `agent_log.jsonl` disappeared, Step 4 and Step 5 would lose their source of outline, section, tool-call, and completion events. If the interview API disappeared, "ask the agents" would collapse into ordinary model speculation instead of querying the simulation environment.

Sources: [backend/app/services/report_agent.py:258-291](), [backend/app/services/report_agent.py:2019-2064](), [frontend/src/components/Step4Report.vue:2033-2065](), [backend/app/api/simulation.py:2142-2248]()

The closing answer is: you can now ask the sandbox for evidence-backed interpretation, not just output. The report agent can plan, search, inspect timelines, interview agents, assemble sections, persist evidence, and reopen that evidence in an interactive UI. Keep future integrations provider-neutral by making skill packs and model endpoints replaceable inputs, while preserving the repository's current report, graph, simulation, and file-backed evidence contracts. Sources: [backend/app/services/report_agent.py:1532-1729](), [frontend/src/views/InteractionView.vue:38-61]()