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.
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
- Get the snippet working in the Python session (correct field names, frame, output shape).
- In amAIra Workflows, upload a Script (
.py) with the same logic; setresult = { "type": "…", "data": { … } }if you want structured chat output (see tenant Knowledge on response format). - Add a Skill that invokes
run-scriptand 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
- Agentic workflows — slash skills, personal scripts, shared examples
- Antinode — sign-in and Workflows
- Load simulation data — load something before the REPL is useful
- Stage operations — UI path for clip, warp, and compile