Metadata-Version: 2.4
Name: holoscript
Version: 6.0.8
Summary: Python bridges for HoloScript — scientific domain bridges and cognition surfaces; parsing lands in 6.1.0
Author: Brian X Base Team
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: mypy>=1.11.0; extra == "dev"
Provides-Extra: medical
Requires-Dist: pydicom>=2.4.0; extra == "medical"
Requires-Dist: numpy>=1.24.0; extra == "medical"
Provides-Extra: alphafold
Requires-Dist: requests>=2.31.0; extra == "alphafold"
Provides-Extra: astronomy
Requires-Dist: numpy>=1.24.0; extra == "astronomy"
Provides-Extra: robotics
Requires-Dist: roslibpy>=1.6.0; extra == "robotics"
Provides-Extra: scientific
Requires-Dist: numpy>=1.24.0; extra == "scientific"
Provides-Extra: all
Requires-Dist: holoscript[alphafold,astronomy,medical,robotics,scientific]; extra == "all"

# holoscript

Python bridges that carry scientific tooling into
[HoloScript](https://github.com/brianonbased-dev/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`](https://www.npmjs.com/package/@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](https://pypi.org/project/holoscript/)
comes from this file in the published wheel.

## Install

```bash
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

```python
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.

| Not here | Where it is | When |
| --- | --- | --- |
| `parse`, `validate` | `@holoscript/core` on npm (permissive) | planned for 6.1.0 |
| `generate`, scene rendering, `share` | MCP server tools (`generate_object` / `generate_scene`, `render_preview`, `create_share_link`); not in the Python package | not planned here |
| AlphaFold structure prediction | nowhere yet: the bridge is a stub (`capabilities()` lists it under `not_implemented`) | unscheduled |
| Full trait registry | `@holoscript/core` | with 6.1.0 |

`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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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.

```bash
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

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

## Links

- [GitHub](https://github.com/brianonbased-dev/HoloScript)
- [MCP Server](https://mcp.holoscript.net)
- [Store](https://store.holoscript.net)
- [npm](https://www.npmjs.com/org/holoscript)
- [PyPI](https://pypi.org/project/holoscript/)

## License

MIT
