Metadata-Version: 2.5
Name: spatialbridge
Version: 0.1.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: mcp<3,>=2.2
Requires-Dist: platformdirs>=4
Requires-Dist: pydantic>=2.13
Provides-Extra: geometry
Requires-Dist: shapely>=2.1; extra == 'geometry'
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. |

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
$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>" --pyargs spatialbridge.conformance`.
