Python session

The Python session is a small REPL (read–eval–print loop): you type Python in the editor, run a cell, and mesh-api executes it on the same VTK session as the 3D view. Nothing runs in your browser tab — the simulation stays on the server; you get stdout, errors, and a result value back.

The point of the REPL is your analysis: mesh-api gives you pre-loaded globals (vtk, numpy, and a read-only session handle on the loaded mesh). You write custom cells — often a VTK pipeline on session.mesh() — without import. When a snippet is stable, upload it as a Script and wire a Skill in amAIra workflows. Shared slash commands are examples of that path; the Python tab is where you invent your own.

Where it is

Sign in on the home page, then open Python session on the right side of the viewer. amAIra is the other tab in that panel. Those tabs stay hidden if you open the viewer without that sign-in.

Python session in the Antinode slide-in panel
Python session in the Antinode slide-in panel

The starter text in the editor shows a minimal session.describe() example. Run it first on on-prem (or billed cloud) to confirm the connection.

How the REPL works

You (Python tab)  →  viewer  →  mesh-api POST …/repl/eval  →  sandboxed Python
                                                      ↓
                                            active VTK session (your loaded mesh)
                                                      ↓
                                            stdout + result JSON back to the tab
Step What happens
1 You load an example or open a file. mesh-api holds that simulation in memory for your account.
2 The viewer keeps mesh-api aligned with what you see: asset, source, and frame (time step) via the live session binding.
3 You run a cell. The viewer sends your code plus the current frame_index (and asset_id when needed).
4 mesh-api builds a SessionReplContext (session in your code) for that frame and asset, runs the cell in a sandbox (no import, timeout, size cap).
5 print output appears as stdout. The last expression on the last line, or a variable named result, is serialized and shown as the cell result.

Cells run one at a time and block until the server finishes. A new upload or a fresh viewer session starts a new server context.

Before a cell will run

You need Why
A file or example loaded The session uses that simulation
Infrastructure on Connected The cell runs on the server
A connection that can run Python On-prem today, or hosted cloud when your account includes the full tool set. The preview is Examples only

Pre-loaded globals (no import)

Every cell runs in the same sandbox as uploadable skill scripts. mesh-api injects globals; you do not import packages yourself.

Name Role
vtk VTK Python — filters, arrays, geometry on the server copy of the mesh
np, numpy NumPy for arrays and numeric work
session Read-only bridge to what the viewer has loaded (frame, asset, metadata, mesh())
scipy Only if installed on your mesh-api image
print, len, range, … Safe builtins only
args Empty in the Python tab. In skills, parameters from amAIra (e.g. field, bins)

You cannot use import or access __dunder__ names. That keeps cells safe on shared infrastructure.

Most custom work starts with dataset = session.mesh() and VTK/NumPy from there. Use session when you need names, counts, or quick field summaries without hand-rolling VTK array access.

What session gives you (overview)

session is not a list of slash commands — it is a small, generic API on the active simulation:

Capability Typical calls
What is loaded describe(), field_names(), list_assets() when several parts are in memory
VTK handle mesh() → dataset for the bound frame (and asset when multi-part)
Field data field_stats, histogram, percentile, and related helpers on point arrays
Transient Move the viewer time slider, then re-run; or compare two frames in one cell

Start with session.describe() so you use real field names. Multi-asset: pick the row in Scene so the binding matches the part you mean.

Optional extras exist on session (same sandbox shared skills may call). You do not need them to use the REPL — compose vtk + numpy for bespoke logic, or use a helper when it saves typing.

Example cells (copy and adapt)

See what is loaded (always a good first cell):

info = session.describe()
print(info["source_name"], info["point_count"], "points")
print("Fields:", info["fields"])
info

VTK on the loaded frame (main REPL pattern):

dataset = session.mesh()
print(dataset.GetClassName(), dataset.GetNumberOfPoints(), "points")
# e.g. inspect point data: dataset.GetPointData().GetArrayName(0)

One convenience helper vs rolling your own:

session.field_stats("stress")  # replace with a name from describe()

Use print(...) for logs. End with an expression or set result = { ... } when you want JSON back — the same habit you use when you promote the cell to an uploadable script.

What to use it for

  • Explore the loaded model with VTK and NumPy on the server
  • Prototype checks and summaries before you upload a Script and Skill
  • Learn field names and mesh structure via session, then go deeper with custom code

Everyday clip and warp in the UI are authored from Scene → Selected prim on a mesh row (compile). The REPL does not replace that — it is read-only for scene edits. See Agentic workflows for packaging cells into chat-driven flows.

From REPL to your own skill

  1. Get the snippet working in the Python session (correct field names, frame, output shape).
  2. In amAIra Workflows, upload a Script (.py) with the same logic; set result = { "type": "…", "data": { … } } if you want structured chat output (see tenant Knowledge on response format).
  3. Add a Skill that invokes run-script and points at that script — copy how shared Scenaven examples are wired.

Shared Scenaven skills are examples; your REPL experiments are the fastest path to your workflows.

Limits

Limit Typical value
Cell size About 8 KB per REPL cell (uploadable skill scripts allow more)
Run time About 10 seconds per cell
Imports Not allowed
Files on your PC Not visible — only the server session
Rate Shared accounts may be rate-limited on mesh-api

Troubleshooting

What you see What to check
The tab is missing Sign in on the home page. Infrastructure should be connected
“No active session” Load a file or an example first
Unknown field / empty stats Run session.describe() or session.field_names()
Wrong frame or part Move time or select the Scene row, then re-run
A cell times out Smaller loops; sample fewer points
An authorization error Sign in again; confirm this connection allows Python (on-prem / billed cloud)
Cloud preview message VTK REPL is off on hosted preview — use on-prem

Next steps