Raptor Studio

Add a drawing annotation (text box, rect, ellipse or arrow). Place it **next to an element or another annotation** with `adjacent_to` (a block/node/event/hierarchy name or `Kind:id`, or `Annotation:<id>` / an annotation's label) plus `location` (`right`/`left`/`above`/`below`/`center`, default `above`) and `gap`: it is anchored, so it moves with the target when the target is dragged or `auto_layout` runs. `center` puts the annotation over the target and ignores `gap`. Or place it **by coordinates** with `x`/`y` (+ `w`/`h`): in scene pixels (the default, what the GUI stores) or, with `units="model"`, in the model's own coordinates (the numbers element `x`/`y` use). `w`/`h` are scene pixels (a block is 108 x 46). It inherits the target's hierarchy; set `parent` to draw it inside another level. An `arrow` connects two things by name: give `from_` and `to` (an element or an `Annotation:<id>`), or the four coordinates `x1`/`y1`/`x2`/`y2`. Each end is independent: name just one (say `from_`) and give the other end as coordinates (`x2`/`y2`) to leave it free. An attached end follows its target and stops at the target's edge, not its centre. `style` carries the cosmetic fields: `border_colour`, `border_width` (0 = none), `line_style` (`solid`/`dash`/`dot`/`dash-dot`/ `dash-dot-dot`), `fill_colour` (null = transparent), `text_colour`, `font_family`, `font_size`, `font_bold`, `font_italic`, `z`. Returns {annotation_id, annotation, summary}. For an arrow the parameter is spelled `from_` (a Python keyword conflict); the stored `anchor` object reads back as `from`. In a `build_model` spec the same `from_` spelling applies. Annotations exist only in `.rbds`; exporting with `save_model_as(format="rbd")` drops them.

Add a block to the model. `fail_dist`/`repair_dist` take a distribution name ("Weibull") or a code from `list_distributions`. Numeric parameters accept expression strings with a `#` comment for traceability, e.g. "0.00015 * 20000 / 8760 # failure rate". `after` wires the new block after an existing element name/id, which must not already have its one link out. A block takes at most one incoming and one outgoing link (RAPTOR Studio) -- to feed it from/to more than one other element, route through a Node (`add_node` + `connect`; see `connect`). Returns {block_id, name, warnings}.

Add many blocks, nodes or events with one save. Each item is `kind` plus the same fields the single add tool takes: - block: `name`, optional `fail_dist`, `fail_params`, `repair_dist`, `repair_params`, `parent`, `after` - node: `name`, `type` (start/regular/end/in/out), `parent`, `k` - event: `name`, `prob`, `parent` Items are created in list order, so a later item may use `after` to wire itself to an earlier one. Atomic: a refused item restores the model. Returns {added, elements: [{kind, id, name}]}.

Add an event to the model. `prob` is its probability (0-1).

Create an empty hierarchy -- a sub-model boundary -- with its In and Out markers already wired up correctly. This is the fiddly part to do by hand: each marker's own `parent` must be the new hierarchy's id (not the enclosing level) and both markers' `n` must match their real link counts, or the engine crashes on load with an unhelpful KeyError. Building one through `build_model` means declaring `in_id`/`out_id`, the two marker nodes with their `parent` set to the hierarchy's own id, and their link counts -- three non-obvious constraints. The hierarchy starts empty and unwired. Add contents with `add_block(parent=<hier_id>)` (read the id from `describe_model(detail='full')`, or from the return value here), then `connect` the In marker to the first element and the last element to the Out marker. To build a hierarchy *around* elements you already have, use `collapse_selection` instead -- it does all the rewiring. Returns {hier_id, name, in_id, out_id}.

Add a node to the model. type: 'start', 'regular', 'end', 'in' or 'out'. k: K-out-of-N threshold. A node's n comes from its *incoming* links, so set k only after the voting blocks are wired INTO the node. `-1` (the default) is RAPTOR's "K-of-N never set" sentinel and is treated as 1-of-N -- it does **not** mean "all incoming paths required"; use `k = n` for an all-required node. It is stored verbatim as `-1`, so `get_element` reports `k=-1`; the coercion to 1 happens when the model runs.

Solve the static subset of a model exactly. **Reliability mode** is non-repairable: `R(t)`, density, hazard, MTTF, BX life, conditional reliability and exact importance. **Availability mode** is steady state for independent components with perfect repair: `A_i = MTTF_i / (MTTF_i + MTTR_i)` and exact availability importance. The solver supports series, parallel, mixed, k-of-n, bridge networks and hierarchies. It refuses PM, spares, resources, dependencies, standby, phases and non-Bernoulli events; use `simulate` for those. `at` defaults to the model's time-terminated run length. `tau` adds the conditional reliability of a further mission of that length after `at`. `ignore_repairs` (same as `ignore=["repairs"]`) gives the first-failure reliability of a repairable model. The default solver limits are 5,000 blocks/events and 1,000,000 BDD nodes. `max_variables` and `max_bdd_nodes` override them for a large but tractable model. Raising a limit does not guarantee a solution: the BDD can still exceed it, and the solver refuses rather than approximate. A long solve sends MCP progress notifications about once a second while the BDD and importance measures are built.

Re-arrange a model's diagram onto the shared layered grid. Runs the same engine the GUI's Auto Layout button and .rbd save normalization use: longest-path columns from the Start node(s) (left = upstream), rows spread within each column, so no connector runs through a block. Positions are written back to the model file, so a subsequent `render_diagram` reflects them. Scope the pass with one of: - `hierarchy`: a hierarchy name or id — only that level's elements are repositioned; every other level keeps its coordinates. - `selectors`: names / `Kind:id` of the elements to move. The layout is still computed for the whole level (a subset laid out in isolation does not line up with its neighbours), but only the named elements adopt the new positions. With neither, every level is laid out. `build_model` already lays out by default (`auto_layout=True`). The collision-refining step has a time budget (30 s in all): a dense model can otherwise take minutes. If it runs out, the layered layout is kept with whatever refinement was done, and `refine_cut_short` says how many levels were left less than fully refined (0 when none). Annotations placed next to an element (`adjacent_to`, or an arrow's `from_`/`to`) move with it; ones placed by coordinates stay where they are in the model. For a whole-model layout the gaps between stacked elements are first stretched so notes anchored `above`/`below` fit (the elements either side move apart equally; nothing moves closer), and a note that would still land on an element or another note is nudged to the nearest clear spot; one a user dragged away keeps its offset. Nothing else ever re-lays out a model: saving and exporting keep the positions as they are. Returns {moved, model_id, scope, elements_moved, annotations_moved, refine_cut_short}.

Build a complete model from a friendly .rbds spec document. Give the spec inline as `spec`, or, for a large one, as `spec_path`: a JSON file **relative to the workspace** (or an `--allow-read` directory). Exactly one of the two. To open a finished `.rbds` or `.rbd` file instead, use `open_model`, which takes the same kind of path. `build_model` always creates a NEW model. `model_id` is accepted only to reject it with a clear message: it used to be ignored silently, so a caller that passed one believed it was appending to that model. Use `add_elements`/`add_block` to edit an existing model. `spec` is a JSON object with `blocks`, `nodes`, `events`, `hierarchies`, `links`, `system`, `experiment`, `rates`, `spare_pools`, `resources`, `triggers`, `phases` and `annotations`, using the friendly snake_case fields from docs/RBDS_FORMAT.md (e.g. a block's `fail_dist`/`fail_params`; distributions may be given by name or code). Ids are assigned where omitted, links are wired, counts synced. This is the main tool for creating a whole model in one call. A complete `.rbds` document goes in as `spec={"rbds_text": "<the file's text>"}`. `experiment` takes the .rbds run block itself (`trials`, `termination_type`, `term_condition`, `analyses`, `recording`, ...), so the run settings no longer need a second `configure_system` call. RAPTOR Studio's input rules apply as they do to every edit: a spec with a link RAPTOR Studio will not let you draw (Start linked to two blocks, say -- use Start -> a Node -> the blocks) or a value its dialogs refuse is rejected with RAPTOR Studio's own message. `spare_pools`/`resources`/`triggers`/`phases` are lists of dicts built with the same row constructors the `configure_*` tools use. Friendly fields per entry: - spare_pools: name, stock, new_spares, arrive_every, eso, emer_time, slo, level, quantity, slo_time, rso - resources: name, num_in, spare_cost, fixed_per_use, per_time_unit, phases - triggers: name, init_used, dist, params, repeats…

Ask a background job to stop (checked between replications, and while a large model is still being set up). The replications already completed are kept and become a run, exactly as when `simulate` is cut short: the result is marked truncated. Returns the job snapshot; poll `run_status` until `state` is `cancelled`.

Close one or more models. Set delete=true to also remove their files. `model_id` accepts a single id or a list, for cleaning up several scratch/sweep models in one call. Each id is closed independently and only the ids you pass are affected -- other open models are never touched, whatever their names. One bad id doesn't abort the rest; the failures are reported alongside the successes. `delete=true` removes that model's own workspace directory (its `model.rbds`, backups and meta) and is **irreversible** -- the undo history goes with it. It does not delete exported files (use `delete_file`) or runs.

Move existing blocks/nodes/events into a new hierarchy, rewiring the boundary. The API counterpart of the GUI's *Collapse Selection*. `selectors` names the elements (by name, or `Block:N` / `Node:N` / `Event:N`) that should become the new hierarchy's contents. Links wholly inside travel down a level untouched; links that crossed the boundary are rewritten to address the hierarchy, and each is split so the sub-model's own graph stays complete (the outside half keeps its id, an inside half is added off the In/Out marker). Start/End/In/Out nodes and existing hierarchies are refused -- a hierarchy cannot contain the model's own terminators, and nesting one hierarchy inside another needs the boundary wired by hand. This is the one-call way to wrap a branch you have already built, and the way to reproduce the book's "three ovals" figures. Read `describe_model(detail='full')` afterwards to see the new level. Returns {hier_id, name, in_id, out_id, moved}.

Compare 2–5 models or runs side by side. Returns per-metric values (`metrics`, in `models`/`labels` order), deltas against the first entry, and which entry is best per metric, plus a Markdown comparison table. `labels` gives each entry's model name (a run's cached `model_name`), parallel to `models` -- `deltas` keys and `best` values use the label, not the raw id, unless two entries share a name, in which case that label gets its id appended to stay unique.

Set the distributions `add_block` uses when you don't name any. This is the MCP equivalent of the GUI's *Block Defaults* button: set your house values once and every block you place picks them up, instead of restating four numbers on every `add_block` call. - `action='list'` — show the current defaults (`{}` means "use each model's own template-row defaults"). - `action='set'` — store the fields you supply; omitted fields are left as they are. `fail_dist`/`repair_dist` are distribution codes from `list_distributions`. - `action='clear'` — forget them and fall back to model defaults. Precedence at placement time: the arguments you pass to `add_block`, then these defaults, then the model's own block template row, then the `rbdlib` canonical values. Defaults are per-workspace and persist across server restarts.

Configure preventive maintenance for a block. pm_freq: maintenance interval (hours). pm_duration_dist/pm_params: the PM duration distribution. trigger_name: a trigger element (for triggered PM). defer_flags: bool-valued PM Options, matching the block Properties dialog exactly (unknown keys raise an error): - `spare`: needs a spare on hand to conduct PM. - `refresh`: after PM completes, refresh the block like new. - `mis_defer`: defer PM until a non-mission phase occurs (only meaningful when the model has phases). - `req_defer`: defer PM until a spare or resources are available. - `fail_reset`: a failure resets the time to next PM activity.

Configure mission phases. phases: [{name, duration_dist, params, mission}]. `mode='replace'` (default) makes `phases` the whole list; `mode='add'` appends them to the phases already there (cells for the new phase are filled with Raptor's default); `mode='remove'` deletes the phases named in `remove` and shifts the rest down. `unassign` names blocks/events/nodes whose phasing is cleared (flag off, per-phase cells dropped) -- previously there was no MCP route for this. assignments: {element: [per-phase state]}, one list entry per phase (a short list is an error, not padded). A block/event state is `"<code>: <value>"` -- code `A` (Active), `C` (Cut) or `L` (Linked), value the stress multiplier, e.g. `"A: 1.000"`, `"C: 0.500"`; the colon and value are required even for Cut (a bare word like "Cut" crashes the engine's phase parser instead of erroring here). A node state is a bare token: `"C"`, `"L"`, or an integer k-of-n threshold for that phase. Phase rows are always built through rbdlib.make_phase_row.

Configure sparing for a block. mode: 'infinite' (default), 'custom', or 'pool'. `spare_pool` is required for mode='pool' and must name an existing pool (create one with `manage_spare_pools`). stock: initial spare count; restock_every: restock interval (hours); emergency: emergency shipping time (hours); slo: stock level order. With mode='pool' the POOL's stock and restock interval govern; the block's own `stock` only applies to mode='custom'. Returns {applied, warnings}.

Configure system-level simulation settings. run_length: simulation duration (hours unless `units` says otherwise). termination: 'TimeSim' or 'CycleSim'. display_unit overrides the display unit without changing stored values. capacity=true enables capacity analysis; `flow_generated` sets its demand (the flow the system is asked to deliver). Returns {applied, previous}.

Connect two elements with a link. `from_element`/`to_element` are either ["Block", id] / ["Node", id] or a bare element name like "PumpA". `replace=True` removes any link already leaving the source and any link already entering the target first, so a wrong connection is corrected in one call. Without it, RAPTOR Studio's own limit (one link in/out per element) refuses the second connection. RAPTOR Studio's link rules apply, and a link it will not let you draw is refused with its own message, leaving the model unchanged: a block, event or hierarchy takes at most one link in and one out; a Start or In marker one link out and none in; an End or Out marker one link in and none out. Fan-in/fan-out (two blocks feeding one element, or Start feeding two) goes through a Node: `add_node` first, then connect each element to it.

Create many links with one save. Endpoints are the same as `connect` (a name, or ["Block", id] / ["Node", id] / ["Hier", id]). Applied as one atomic batch; the model is written once. Returns {connected, links: [{link_id, from, to}]}.

Create a new model. template: 'blank' (default), 'series' (n blocks in series), 'parallel' (n in parallel), or 'k_of_n' (k-of-n voting of n blocks). Non-blank templates are auto-laid-out on the shared layered grid, so the diagram renders cleanly without a separate `auto_layout` call. Returns {model_id, summary}.

Delete one annotation by id. Returns {deleted, kind}.

Delete an element from the model. reconnect=true removes its links and rewires adjacent connections. Returns {removed, links_removed}.

Delete many elements with one save. `reconnect` behaves as for `delete_element`. Applied as one atomic batch; a refused selector restores the model. Returns {deleted: [{selector, kind}], links_removed}.

Delete a file previously exported with `save_model_as` (or any other file inside the workspace or an --allow-write directory). Does not touch an open model's own files -- use `close_model(..., delete=true)` for those. Refuses a path outside the workspace/ allow-write directories, same containment `save_model_as` enforces.

Delete one link by id, leaving both elements in place. This is the safe alternative to deleting an element just to break one connection (which removed every other link on that element too). Find link ids in `describe_model(detail='full')` or `get_table('inputs.links')`.

List the result metrics, and optionally show one run's values. Without `run_id`, returns the name and units of every metric RAPTOR reports: availability, reliability, conditional reliability, dependability, MTBDE/MDT, MTBM/MTBMs/MTBMu, MMT/MMTs/MMTu, system and component failures, and green/yellow/red percentages, plus, for a run with capacity analysis, units produced, mean flow and capacity, capacity-weighted availability (mean flow / flow generated) and lost flow. **Definitions and equations are not repeated here** -- call `read_doc('formulas')` for them; that page is the single source. With `run_id`, also returns that run's sample count, min/mean/max, standard deviation and standard error. `model_id` is optional and only checks that the run belongs to that model. These are the engine's existing outputs; no analytical or alternative solution method is applied. Use `get_report` or `get_table` for the underlying data. Censored MTBDE/MTBM values are lower bounds and are marked with `>` in the Markdown view.

Describe the model structure. detail='summary' gives counts plus a topology sentence; detail='full' lists every element in one response (use get_table for paged input tables). `level` filters to a hierarchy level (0 = whole model).

Say what is different between two models (their inputs, not their results). This compares *the models themselves*: elements added, removed, renamed or changed (distributions, sparing, maintenance, costs...), connections added or removed, hierarchy moves, k-of-n changes, system settings, rates, spare pools, resources, triggers and phases. It runs nothing. `compare_models` is the other one: it runs models and compares their *results*. `model_a` / `model_b` are workspace model ids (the reference and the one changed); open files with `open_model` first, this tool does not load paths. Elements are paired by name, then by id (`match`: "auto"; "name" or "id" to use only one; "id" is right for a model against an earlier copy of itself). `ignore` lists categories to leave out. The default (omit it) is ["layout", "derived"]: screen positions and columns the file reader computes. Pass [] to show everything. Categories: layout, derived, identity, failure, repair, streams, sparing, maintenance, logistics, dependency, cost, phasing, capacity, structure, system, project, other. detail="summary" returns the counts, the added/removed/renamed lists and at most 50 field changes (`truncated` says whether more exist; `total_changes` counts them); detail="full" returns every change. Each change has `field`, `label`, `category` and the values `a` and `b` (distributions are described in words, with raw columns in `a_raw` / `b_raw`).

Estimate wall-clock time for a simulation before running it. Times a real pilot and extrapolates. `workers` is taken into account with a contention-aware speed-up: parallel replications on a large model scale at roughly ``w / (1 + 0.25 (w - 1))``, not ``w`` (8 workers measured 2.8x on an 8-core box). Models of 1,500+ elements are piloted at an 8,760 h horizon and the fit scaled, so the call always returns. `importance` overrides the model experiment's importance setting for the estimate. When importance is on, `seconds_estimate` is the TOTAL time until the whole operation finishes: the baseline batch plus one batch per block per variant kind. `baseline_seconds` and `importance_seconds` show the split. Returns {seconds_estimate, baseline_seconds, importance_seconds, total_batches, importance_batches, importance_blocks, range, per_run_ms, pilot_runs, estimate_seconds, cached, advice}.

Write tables to files: CSV, text, or one spreadsheet. `tables`: keys from `list_tables`; omit for the default set (all input tables except the all-columns block table, plus every result table except the long ones). Result tables need `run_id`. `formats` (default ['xlsx']): 'csv' one .csv per table; 'txt' one fixed-width .txt per table; 'txt_report' ONE combined text report; 'xlsx' ONE workbook with a Run Info tab and a tab per table, real numeric cells (the End-of-Run and interim cost reports go beside it as .txt files). Any combination. `folder` is inside the workspace (relative paths resolve against its root); default `Tables/<model>` (or `Tables/<model>_<run_id>`). Existing files of the same names are replaced. Returns {folder, tables, files: [path], resource_links}.

Build a standalone model from one hierarchy (a port extension), or just list what crosses its boundary. The hierarchy's In node becomes Start and its Out node End, so its input is always available. Hazards at the boundary -- elements following something outside, spare and resource pools shared with outside blocks, random streams shared with outside elements -- each get a documented treatment; see `simulate`'s `treatments`. With `report_only` nothing is created and the hazards (with the treatment each would get) are returned. Otherwise the extract is registered as a new model: returns {model_id, name, isolation}. The source model is not changed.

Run failure-effects analysis (Raptor workbook Chapter 10). Fails and/or repairs the listed blocks or events and reports the resulting system status and the Failure Effects text (failed, induced, idle and PM components, down and degraded nodes). A phased model starts in phase 1; `phase` moves it to another phase first. Returns {system_status, affected, log, effects, criticality, phase}, plus, for a model with capacity analysis, `capacity`: {flow_generated, delivered, lost, delivered_fraction, system_capacity, nodes: [{id, name, flow, capacity}]} -- the flow the state delivers, as capacity analysis would record it (Raptor 7's view shows no flow). Each call is an **independent scenario starting from the all-good state**: it does not accumulate failures across calls. To test several simultaneous failures, name them all in one `fail` list; a `repair` can only undo a failure named in the same call.

Run many failure-effects scenarios in one call, on one model set-up. `scenarios` is a list of `{"fail": [...], "repair": [...], "phase": N}` (every key optional), up to 2000. Each scenario is independent and starts from the all-good state, exactly as a separate `failure_effects` call would; the model is only set up once, so hundreds of combinations on a large model take seconds, not one set-up each. Returns {model_id, count, failed, scenarios}. `scenarios[i]` has the scenario's `index`, `fail` and `repair`, then either its result ({system_status, affected, effects, criticality, phase}, `capacity` for a model with capacity analysis, plus the `log` text when `include_log` is true) or `{"error": ...}` when that scenario could not be applied (an unknown or already-failed element, a bad phase). A bad scenario does not stop the others. `failed` counts them.

Read one block, node, event, hierarchy or link back in full. `selector` is an element name or 'Block:N' / 'Node:N' / 'Event:N' / 'Hier:N' / 'Link:N' (links have no name; use their id). This is the read counterpart of `update_element`: every field uses the friendly name `update_element` accepts. A block returns its connections (upstream/downstream), `failure` and `repair` (distribution name, named parameters, mean/stdev), any `logistics_delay` before/after repair, `sparing`, `maintenance`, `dependency` and `phasing`. `dependency` says what the block follows (a block, node, event, hierarchy, its own node, or the whole system), the % split of what happens when that goes down (nothing / idle / pm / failure) and a plain-English `meaning`. detail='full' adds costs, growth/decay and standby stress. A distribution's mean/stdev is null (with a note) when it has no finite value for those parameters, e.g. a Pearson 5 with shape <= 2.

Get a paginated report section from a completed run. section: 'final_results', 'end_of_run', 'events', 'capacity', 'cost', 'weak_link', 'importance' (only when the run asked for it) or 'availability_plot'. `run_number` selects one replication where the section is per-run. format: 'markdown' (default) or 'raw'. Returns {lines, total, next_offset, markdown}; `lines` never exceeds `limit` (≤200).

One completed run as a single assessable bundle. Reads what the run wrote: the metric means and per-replication figures, the capacity summary, and the weakest elements (`weak_link`). Use it to judge a run without paging through `get_report`, and `get_table` / `export_tables` (with the same `run_id`) when you need a whole table or a workbook. `top` caps the weak-link list (1..100).

Read one table: its column headers and a page of rows. `table` is a key from `list_tables` (e.g. 'inputs.blocks', 'results.summary'; result tables need `run_id`). Rows are returned as lists in header order, as the model file holds them (text such as "12.500000") or as numbers for computed tables. `limit` is at most 200; use `offset` and `next_offset` to page. Returns {key, title, group, headers, rows, total_rows, next_offset, notes}.

Get time-series data from a completed run, for the client to plot. series: 'availability', 'capacity' or 'cost'. runs: 'mean' (default), 'all', or a specific run number. points: max samples after decimation (default 100). Returns {t, values, runs_included, decimated_from, envelope?} plus a short Markdown preview. No image is ever returned.

List a model's diagram annotations. `parent` filters to one hierarchy level (the `parent` field, 0 = home). Returns {annotations, count}; each annotation gives annotation_id, kind, parent, text, geometry and, for name-anchored ones, its `anchor` (target/location/gap, or from/to for an arrow).

List every distribution supported by the RAPTOR engine. Returns structuredContent.distributions: each entry has the integer code used in .rbd/.rbds, a human name, the number of parameters expected, the parameter names in order, valid ranges, and an example mean/stdev computed at unit parameters (the engine exposes numeric stats, not symbolic formulas). Use this before setting fail_dist / repair_dist to supply the right number of parameters in the right order.

List open models and (optionally) bundled example models. Returns structuredContent.models — rows of {model_id, name, blocks, nodes, last_modified, source} — and structuredContent.examples (names) when include_examples=true. Use this to find model_id values for the other tools. Long workspaces are paged: `limit` (max 200) and `offset`; `total` and `next_offset` describe the rest.