holoscript

Python bridges that carry scientific tooling into HoloScript — DICOM imaging, radio astronomy, ROS 2, molecular docking and Narupa molecular dynamics — plus the decision surfaces under holoscript.cognition. The AlphaFold bridge ships but is a stub: nothing in it predicts a structure yet.

Parsing is not in this package yet. parse() and validate() raise NotImplementedError in 6.0.8. Through 6.0.7 they returned success for any non-empty string, including text that is not HoloScript at all. Real parsing is planned for 6.1.0, on the same grammar the npm package uses, so Python and JavaScript cannot disagree about what valid HoloScript is. Until then, parse with @holoscript/core and check the result: core is permissive and can return an empty composition for text that is not HoloScript.

Python 3.10 or newer. 6.0.8 drops 3.8 and 3.9, which are past end of life and were never tested here. On those versions pip keeps installing 6.0.7.

The README you see on pypi.org/project/holoscript comes from this file in the published wheel.

Install

pip install holoscript                    # bridges only, no heavy dependencies
pip install 'holoscript[medical]'         # DICOM imaging
pip install 'holoscript[alphafold]'       # AlphaFold bridge (a stub: predicts nothing yet)
pip install 'holoscript[astronomy]'       # radio astronomy
pip install 'holoscript[robotics]'        # ROS 2
pip install 'holoscript[scientific]'      # numpy only; docking also needs: pip install vina
pip install 'holoscript[all]'             # every extra above

No extra installs AutoDock Vina (pip install vina) or Narupa's nanover-server.

What happens when a dependency is missing:

• medical raises ImportError at import, naming the install line.
• alphafold, robotics, scientific and narupa import fine, then report the missing dependency in the result they return, naming what to install: status: failed (narupa says status: error).
• radio_astronomy needs no extra package.

None of them ends your process.

What this version implements

import holoscript

print(holoscript.__version__)
print(holoscript.capabilities())

capabilities() is the machine-readable answer — agents and CI should branch on it rather than on this README.

list_traits() returns a static five-name snapshot, not the registry. Of those five only @grabbable is in the core registry today; the registry's size changes with every deploy, so verify it the way docs/NUMBERS.md prescribes rather than trusting a number written here.

Domain Bridges

Medical — DICOM Bridge

from holoscript.bridges.medical import DICOMBridge

bridge = DICOMBridge()
image = bridge.load_dicom("/path/to/scan.dcm")
volume = bridge.extract_3d_volume("/path/to/dicom/")

Requires: pydicom, numpy (pip install 'holoscript[medical]'). extract_3d_volume returns the volume's dimensions, spacing and value range, not the voxels. dicom_to_mesh is not implemented: it always returns success: False.

AlphaFold — Protein Structure

from holoscript.bridges.alphafold import AlphaFoldBridge

bridge = AlphaFoldBridge(api_key="your_key")
result = bridge.predict_structure({
    "sequence": "MKFLILLFNILCLFPVLAADNHGVS",
    "job_name": "demo",
})

A stub. No path in this bridge returns a structure: the AlphaFold API endpoint it calls is a placeholder that does not resolve, and the local ColabFold path (mode: "local") returns "not yet implemented" even with ColabFold installed. Every call fails closed with status: failed. Without an API key it fails before reaching the network. capabilities() lists it under not_implemented.

Astronomy — Radio Telescope Data

from holoscript.bridges.radio_astronomy import calculate_synchrotron

flux = calculate_synchrotron({
    "magnetic_field_gauss": 1e-4,
    "frequency_hz": 1.4e9
})

The synchrotron calculation is a placeholder formula, as its own docstring says.

Robotics — ROS2

from holoscript.bridges.robotics import ROS2Bridge

bridge = ROS2Bridge("ws://localhost:9090")
bridge.connect()
bridge.publish_joint_command("/joint_states", {"joint1": 0.0, "joint2": 0.5, "joint3": 1.0})

Requires: roslibpy

Scientific — Molecular Docking

from holoscript.bridges.scientific import AutoDockBridge

bridge = AutoDockBridge()
results = bridge.run_docking({
    "protein_pdb": "receptor.pdb",
    "ligand_mol": "compound.mol",
    "box_center": [0.0, 0.0, 0.0],  # search box centre, angstroms
    "box_size": [20.0, 20.0, 20.0],  # search box size, angstroms
})

Needs AutoDock Vina: pip install vina. The [scientific] extra installs only numpy. Without Vina this returns a status: failed dict rather than raising.

Narupa — molecular dynamics servers

from holoscript.bridges.narupa import NarupaBridge

bridge = NarupaBridge()
bridge.start_server({"pdb_path": "protein.pdb"})

Needs nanover-server, which no extra installs. Without it start_server returns status: error naming the install line.

Cognition

from holoscript.cognition import record_decision, read_log, render

Feeds a shared decision stream that renders through the SVG compiler. render shells out to the npm holo-decision program and raises RuntimeError when it is not installed.

MCP Server

HoloScript also runs as an MCP server. The Python package provides bridges — the MCP server provides compilation, rendering, and deployment.

curl -X POST https://mcp.holoscript.net/api/compile \
  -H "Content-Type: application/json" \
  -d '{"code": "object Cube { position: [0,1,0] }", "target": "r3f"}'

npm Ecosystem

npx create-holoscript my-app     # scaffold a project
npm install @holoscript/core     # core library, including the parser

Links

• GitHub
• MCP Server
• Store
• npm
• PyPI

License

MIT