Metadata-Version: 2.5
Name: spatialbridge
Version: 0.2.0
Summary: The protocol SCIMAP Pro, Plexora and other spatial tools speak to share one dataset
Author-email: Ajit Johnson Nirmal <ajitjohnson.n@gmail.com>
License-Expression: LicenseRef-Proprietary
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.12
Requires-Dist: anndata>=0.10
Requires-Dist: platformdirs>=4
Requires-Dist: pydantic>=2.13
Provides-Extra: geometry
Requires-Dist: shapely>=2.1; extra == 'geometry'
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2.2; extra == 'mcp'
Description-Content-Type: text/markdown

# spatialbridge

The protocol SCIMAP Pro (analysis) and Plexora (viewer, image processing) speak
to share one dataset. Either application can hand work to the other, with or
without an AI agent in between, and a third tool can join later without
either package changing.

Neither application imports the other. Both depend on this package, which defines:

| Module | What it is |
|---|---|
| `schema` | Exchange objects: `Ref`, `Dataset`, `Regions`, `Gates`, `Selection`, `QCResult`, `CapabilityDescriptor`, `Provenance`, `Handoff`. JSON Schema copies are in `schema/`. |
| `workspace` | The on-disk record both sides read: identity, revision, per-section stamps, external-change detection, leases. |
| `peers` | Who is running: `peers.json`, plus Plexora's `servers.json` and `sidecars.json`. |
| `client` | Reaches a peer by the highest rung available: in-process, HTTP, a spawned MCP stdio server, MCP over HTTP. |
| `tools` | The `bridge_*` tools each application mounts on its own MCP server. |
| `handoff` | Hands work to the peer in five steps: ensure_visible, ensure_bound, invoke, collect, record. |
| `registry` | The merged catalogue, the role vocabulary, and the routing rule. |
| `anndata` | Readers and writers for the shared keys (`uns["gates"]`, selections, regions). |
| `conformance` | A pytest plugin a third tool runs to prove it speaks protocol 1.0. |
| `grouping` | Which images, masks and tables under a folder belong together: one project per image, each pairing scored with its reasons and confidence, corrections as overrides. Stdlib only. |

The MCP SDK is the `[mcp]` extra (`pip install 'spatialbridge[mcp]'`). Without
it, `grouping`, `schema`, `workspace` and the in-process and HTTP rungs work;
reaching a peer over MCP raises `peer_unavailable` with that install as the hint.

There is no daemon. The shared state is a directory:
`$SPATIAL_WORKSPACE_DIR` if set, otherwise the platform user-data directory
(`.../nirmallab/spatialbridge/workspaces`).

## Development

The repository lives in a Dropbox-synced folder, and a virtual environment
inside it gets corrupted. Keep the environment outside the folder:

```bash
export UV_PROJECT_ENVIRONMENT=$HOME/.venvs/spatialbridge
uv sync --all-groups --all-extras
$UV_PROJECT_ENVIRONMENT/bin/python -m pytest
```

After changing a model in `schema/`, regenerate the committed JSON Schemas:

```bash
$UV_PROJECT_ENVIRONMENT/bin/python -m spatialbridge.schema export schema
```

## A third tool joins by

1. depending on `spatialbridge`;
2. subclassing `spatialbridge.adapter.Adapter` (the capabilities with roles,
   plus `invoke`, `bind`, `collect`, `on_event`);
3. calling `spatialbridge.tools.mount(server, adapter)` on its MCP server;
4. passing `pytest --peer "<its mcp command>" -o python_files=__init__.py --pyargs spatialbridge.conformance` (the check lives in the package's `__init__.py`, which pytest collects only when told to).
