Record an action in the trace table.

Stripped string; ``None`` ⇒ empty.

Coerce ``value`` to a stripped string; ``None`` ⇒ empty.

Map a round number into a pixel x-coordinate inside the plot area. ``max_round`` is the largest round in the trajectory (not the count of rou

Set / clear ``WEBHOOK_SECRET`` for the duration of the block.

Single-byte ``…`` truncation that preserves a trailing ellipsis. Strips whitespace and trims with a one-character margin so the final string

Call after env.step() each round to update beliefs and inject context. Args: db_path: Path to the platform's SQLite database.

Build a text digest of an agent's recent activity on OTHER platforms. Args: agent_id: The agent to build the digest for.

Return the canonical JSON encoding of ``payload`` as UTF-8 bytes. Locked encoding: - ``sort_keys=True`` so two identical dicts produce ide

Clear all recorded actions.

Pick the dominant stance label from a split — or ``None``. Returns ``"bullish"`` / ``"neutral"`` / ``"bearish"`` when one stance leads the ru

Check if enrichment is needed, and if so, research via LLM. Returns a formatted context string, or "" if not needed or failed.

Determine which Agents to activate this round based on time and configuration

Get the current simulation time.

Get report

Inject a cross-platform digest into an agent's system message. Appends (or replaces) the cross-platform section at the end of the agent'

Inject a breaking event into an agent's system message. Uses the same marker-replace pattern as inject_cross_platform_context. Args:

Log simulation start

Show only the scheme + host of a webhook URL. The full URL often carries an opaque secret in the path (``hooks.slack.com/services/T0…/B0…/abc

Wait up to timeout seconds, then drain all buffered events.

Return ``{key: count, ..., total: sum}`` for the sim's stats file. Every key in ``SURFACE_KEYS`` is present (zero-defaulted) plus a synthetic

Render an animated GIF from the embed-summary payload. Always returns valid GIF bytes — a missing trajectory renders a single-frame "Belief t

Save project metadata

Graph semantic search (hybrid: vector + BM25 via Neo4j) Args: graph_id: Graph ID query: Search query

Cache-Control value shared by both endpoints. 60 seconds matches the cache TTL on ``compute_platform_stats`` and the per-sim ``/badge.svg`` r

Build an nbformat 4 code cell with no outputs and no execution count. Unexecuted code cells are the standard distribution form — the user's o

Return a dict with every key in ``SURFACE_KEYS`` set to zero. The dict is fresh on every call — callers mutate the result without affecting s

Ensure report folder exists and return path

Get project directory path

Read ``MIROSHARK_ADMIN_TOKEN`` from the environment at *call* time. Resolved per-request rather than module-import time so tests can monkeypa

Lightweight stand-in for SimulationState — only the attributes the gallery helper reads.

Trim trailing slashes for comparison (Flask treats them equivalently).

Best-effort JSON load — returns ``None`` on any failure.

Build the static HTML returned to scrapers + browsers. Keep this small and dependency-free — the page exists purely to expose Open Graph tags

Same proxy-aware base URL resolution the share-landing route uses — ``X-Forwarded-Proto`` + ``X-Forwarded-Host`` first, then ``request.host_ur

Strip XML namespace prefix from a tag name: '{ns}foo' → 'foo'.

Drop a simulation_config.json with the LLM-generated shape.

Write a ``trajectory.json`` whose final round produces ``final_split`` via the standard ±0.2 stance threshold. ``rounds`` controls how many s

Reduce trajectory snapshots to a final bullish/neutral/bearish split. For each snapshot, average every agent's per-topic belief positions, then

Re-close a JSON string that was truncated mid-structure. When an LLM hits its ``max_tokens`` limit the response often ends partway through a

Create LLM model Supports dual LLM configuration for faster parallel simulation: - General config: LLM_API_KEY, LLM_BASE_URL, LLM_MODEL_

Create a new task Args: task_type: Task type metadata: Additional metadata Returns: Tas

Prepare CAMEL memory messages for an OpenAI-compatible chat call. Gemini rejects assistant/user turns whose ``content`` is empty (INVALID_ARG

Get all nodes in the graph

Get report by simulation ID

Return a freshly-copied list of every catalogued surface. Each call returns a new outer list and a new inner dict per entry so a caller mutat

Inject market prices into a social media agent's system message.

Return a prompt-ready prefix for agents this round, or "". The prefix is an ALL-CAPS banner plus the injection text, so LLM agents reliably t

List all simulations

Read the trajectory rows the chart needs. Reuses ``trajectory_export.build_rows`` so a single change to the underlying ``trajectory.json`` sc

Extract up to max_calls ``<mcp_call .../>`` blocks from agent output. Malformed ``args`` JSON is tolerated (empty dict). Returns [] if none.

Render a summary dict into a 1200x630 PNG. Always returns valid PNG bytes — missing fields render as a stripped-down "Setup" card instead of e

Save report metadata and complete report

Persist this platform's trajectory and refresh the merged view. Writes ``trajectory_<platform>.json`` (authoritative per-platform rec

Build a short ETag from the cheap inputs. ``total_sims`` + ``newest_sim_id`` is enough to detect material change without re-reading the corpu

Build a short ETag from the cheap inputs. ``total_sims`` + ``newest_sim_id`` is enough to detect material change without re-reading the corpu

Convert to text format

Write JSON atomically via temp file + rename.

Compose the ``<meta name="description">`` + ``og:description`` string from an embed-summary payload. Goes ``"Round N · Bullish X% · Neutral Y

``Cache-Control`` value for both catalog endpoints. One hour matches the underlying catalog cadence — both catalogues only change when a new

Measure how much opinions converged or diverged per topic.

Draw a rounded-rect pill, return (right_x, bottom_y) for chaining.

Emit an llm_call observability event (best-effort, never raises).

Return the ``found: false`` envelope. The same shape is emitted for an unknown id and for a private id — a caller cannot distinguish the two

Stable Atom entry id — must not change across feed fetches. Anchoring on the share landing URL gives us a globally unique URI per simulation

Pull the token from the ``Authorization: Bearer <token>`` header. Returns the empty string when the header is missing or malformed — the call

Convert ``2026-04-22`` (or full ISO timestamp) to ``Apr 22, 2026``. Returns the input untouched if parsing fails.

Get post information Args: cursor: Database cursor post_id: Post ID agent_names: agent_id -> agent_name mapping

Get project file storage directory

Get complete report Markdown file path

Find the simulation directory (tries multiple locations).

Coerce a datetime-ish value to RFC3339 / ISO8601 ``Z`` form. Atom requires ``updated`` and ``published`` in RFC3339; RSS 2.0 requires RFC822

``user_id → display name`` lookup for the simulation's agents. Reads ``reddit_profiles.json`` first (every run produces it), then ``polymarke

Convert Neo4j node to the standard node dict format.

Stripped string or ``None`` when empty — preserves null vs blank distinction the JSON consumer expects.

Single 404 for every preview-resolution miss. Unknown token / revoked token / expired token / malformed token all return the same response so

Read actions from a single action file Args: file_path: Action log file path default_platform: Default platf

Issue one DKG daemon HTTP call. Returns ``(ok, status_code, payload)``: * ``ok`` — True for 2xx, False otherwise. * ``status_code`` —

Clear the module cache (only for tests that mutate locale files).

Coerce to a stripped string; never raise.