plexora 0.0.33__tar.gz → 0.0.35__tar.gz

{plexora-0.0.33/plexora.egg-info → plexora-0.0.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexora
-Version: 0.0.33
+Version: 0.0.35
 Summary: OpenSeadragon-based cellular image viewing and analysis tool.
 Author-email: BioCognia <support@biocognia.com>
 License-Expression: LicenseRef-Plexora-EULA-1.0
@@ -15,7 +15,7 @@ License-File: LICENSE
 Requires-Dist: aiohttp>=3.14.4
 Requires-Dist: anndata>=0.10
 Requires-Dist: biocognia<0.2,>=0.1.2
-Requires-Dist: biocognia-intelligence<0.3,>=0.2.1
+Requires-Dist: biocognia-intelligence<0.4,>=0.2.1
 Requires-Dist: Flask>=3.1
 Requires-Dist: fsspec>=2024.12
 Requires-Dist: h5py>=3.16.0

{plexora-0.0.33 → plexora-0.0.35}/plexora/agent/core/project.py

@@ -679,6 +679,67 @@ def _record_depth_roles(name, roles):
     record.patch(dataset=spec).with_confirmed(tuple(f"role:{key}" for key in named)).save()
 
 
+# -- which project shows this image (another application's import) ---------------
+
+
+class ImportInput(AgentModel):
+    image: str = Field(description="Path to the image on this machine (OME-TIFF, TIFF, "
+                                   "OME-Zarr, a whole-slide file).")
+    mask: str | None = Field(None, description="Its segmentation mask (a label image), for "
+                             "a new project.")
+    table: str | None = Field(None, description="Its cell table (CSV, Parquet, .h5ad, a "
+                              "SpatialData store), for a new project.")
+    name: str | None = Field(None, description="The new project's name; default from the "
+                             "image's filename.")
+    dataset: str | None = Field(None, description="Put the new project in this dataset.")
+
+
+def import_image(call, inp):
+    """The project that shows this image, made from it when there is none.
+
+    What another application calls when a person adds an image to its
+    workspace (Biocognia Intelligence, through `plexora_intelligence`). A
+    project already showing this file -- matched on the file, however its path
+    is spelled, as quick view matches it -- is answered as it is, its mask and
+    table left alone. Otherwise one is made from the image, with the mask and
+    table when they are given (`datasets.create_project`). The image is read
+    where it lies, never copied; what is written is Plexora's project
+    registry, and for a large TIFF with no reduced-resolution levels the
+    one-time pyramidized copy every import makes of it.
+    """
+    import os
+    from pathlib import Path
+
+    from plexora import datasets, get_config
+    from plexora.agent.receipts import make_receipt
+    from plexora.datasource import _find_existing_datasource_for_image
+
+    # Absolute, so the project never depends on this process's working folder.
+    image = Path(os.path.abspath(Path(inp.image).expanduser()))
+    if not image.exists():
+        raise AgentError("invalid_input", f"no image at {inp.image}",
+                         detail={"image": str(image)})
+    if not os.access(image, os.R_OK):
+        raise AgentError("invalid_input", f"{inp.image} cannot be read by Plexora",
+                         detail={"image": str(image)})
+    found = _find_existing_datasource_for_image(image, get_config())
+    if found:
+        call.project_name = found
+        return {"project": found, "created": False, "image": str(image)}
+    try:
+        name = datasets.create_project(str(image), name=inp.name, segmentation=inp.mask,
+                                       data=inp.table, exist_ok=False, dataset=inp.dataset)
+    except ValueError as exc:
+        raise AgentError("invalid_input", str(exc), detail={"image": str(image)}) from None
+    call.project_name = name
+    receipt = make_receipt(
+        call, changed=True, before=None,
+        after={"project": name, "image": str(image), "mask": inp.mask, "table": inp.table},
+        persistent_state="config", reversible=False)
+    return {"project": name, "created": True, "image": str(image),
+            "receipt": receipt.model_dump(mode="json")}
+
+
 def capabilities():
     return [
         Capability(
@@ -759,6 +820,14 @@ def capabilities():
             permission="reversible_write", input_model=BindInput, handler=bind_project,
             writes=("project",), persistent=True, reversible=False,
             tags=("project", "bind", "bridge", "handoff")),
+        Capability(
+            name="project.import", tool_name="import_image", owner="core",
+            purpose="The project that shows an image file on this machine, made from it (with "
+                    "its mask and cell table, when given) when there is none yet: the image is "
+                    "read where it lies, and a project already showing it is answered as it is.",
+            permission="reversible_write", input_model=ImportInput, handler=import_image,
+            writes=("project",), persistent=True, reversible=False,
+            tags=("project", "import", "image", "bridge", "handoff")),
         Capability(
             name="resource.status", tool_name="get_resource_status", owner="core",
             purpose="Where a project's image, mask and table are (this machine or a data "

{plexora-0.0.33 → plexora-0.0.35/plexora.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexora
-Version: 0.0.33
+Version: 0.0.35
 Summary: OpenSeadragon-based cellular image viewing and analysis tool.
 Author-email: BioCognia <support@biocognia.com>
 License-Expression: LicenseRef-Plexora-EULA-1.0
@@ -15,7 +15,7 @@ License-File: LICENSE
 Requires-Dist: aiohttp>=3.14.4
 Requires-Dist: anndata>=0.10
 Requires-Dist: biocognia<0.2,>=0.1.2
-Requires-Dist: biocognia-intelligence<0.3,>=0.2.1
+Requires-Dist: biocognia-intelligence<0.4,>=0.2.1
 Requires-Dist: Flask>=3.1
 Requires-Dist: fsspec>=2024.12
 Requires-Dist: h5py>=3.16.0

{plexora-0.0.33 → plexora-0.0.35}/plexora.egg-info/requires.txt

@@ -1,7 +1,7 @@
 aiohttp>=3.14.4
 anndata>=0.10
 biocognia<0.2,>=0.1.2
-biocognia-intelligence<0.3,>=0.2.1
+biocognia-intelligence<0.4,>=0.2.1
 Flask>=3.1
 fsspec>=2024.12
 h5py>=3.16.0

{plexora-0.0.33 → plexora-0.0.35}/plexora_intelligence/__init__.py

@@ -3,24 +3,43 @@
 `biocognia_intelligence/registry.py`).
 
 Standard library only, so `biocognia list` names Plexora without importing
-it; each method imports what it needs. Plexora joins as a guest: no workspace
-belongs to it yet, and in a workspace another product holds (SCIMAP Pro's),
-the conversation may call the tools listed in `GUEST_TOOLS` as
-`plexora.<tool>`. Each call reaches Plexora over spatialbridge -- the copy
-already running, else one started for it (`plexora mcp serve --origin
-bridge`) -- and Plexora checks it as it checks any bridge call: its licence,
-its policy, and never a source-file write or a delete.
+it; each method imports what it needs. Plexora holds no workspace of its own
+(`home()` is None and its one role is guest), and takes part in the app's
+workspaces three ways.
+
+- Its tools. In a workspace's conversation the app may call the tools listed
+  in `GUEST_TOOLS` as `plexora.<tool>`. Each call reaches Plexora over
+  spatialbridge -- the copy already running, else one started for it
+  (`plexora mcp serve --origin bridge`) -- and Plexora checks it as it checks
+  any bridge call: its licence, its policy, and never a source-file write or
+  a delete.
+- Its licence pays (`pay()`). A workspace's conversation may be paid for by
+  Plexora: each model call goes through Plexora's own gateway client, on this
+  device's Plexora licence, as Plexora's task (`plexora.chat.turn`). Plexora
+  pays for the conversation only -- its `chat` module -- so the app refuses a
+  plan's call before sending it rather than letting the gateway answer 403.
+  Without Plexora's AI on this device every call is refused with the
+  sentence `ai()` gives, and the licence is asked again at the next call.
+- Its images. An app that can hand a file to a product (0.3.1 on) asks
+  `imports(path)`: for an image Plexora opens, by name alone, it names the
+  guest tool that takes it -- `import_image`, which answers with the project
+  that shows that file, made from it where there is none, the image read
+  where it lies -- and its arguments. `classify(path)` still labels the image
+  as Plexora's, with no action, for an app that cannot.
 
 What a conversation is offered is `guest.json`, written from the capability
 registry by `tools/intelligence_manifest.py`, so the catalogue never depends
 on whether Plexora is running. Its Pro tools (AI gating and QC) carry their
 entitlement, and the app offers them only where `grants()` -- this device's
-Plexora licence, read without a network call -- covers it. Plexora's own AI
--- its chat panel, `plexora ai`, its MCP server -- is untouched by any of this.
+Plexora licence, read without a network call -- covers it. Plexora's own chat
+panel, `plexora ai` and its MCP server work as they did; paying for the app's
+conversation is a second use of the same licence and gateway.
 """
 
 from __future__ import annotations
 
+import os
+import re
 import sys
 
 #: The Plexora tools a conversation in another product's workspace may call:
@@ -31,9 +50,9 @@ import sys
 #: the home's own hand-offs drive (the viewer, gates and regions coming back)
 #: is the home's. `tools/intelligence_manifest.py` checks all of it.
 GUEST_TOOLS = (
-    # What a project is.
+    # What a project is, and the one an image file the person names becomes.
     "list_projects", "inspect_project", "list_channels", "list_markers", "get_marker_distribution",
-    "detect_nuclear_channels", "count_cells_in_roi",
+    "detect_nuclear_channels", "count_cells_in_roi", "import_image",
     # Gates, judged against the marker's distribution.
     "get_gate", "suggest_auto_gate", "get_gate_distribution", "get_gated_summary", "get_gate_provenance",
     "set_gate", "adjust_gate", "reset_gates",
@@ -58,7 +77,9 @@ GUEST_TOOLS = (
 #: What the conversation is told about Plexora (the prefix, beside the catalogue).
 RULES = ("Plexora is the image viewer and its analyses of the pixels. Its tools take a `project` (an image "
          "with its mask and cell table): plexora.list_projects names those it knows, and a dataset it does "
-         "not know yet is handed to it by this workspace's own hand-off first. Gating: "
+         "not know yet is handed to it by this workspace's own hand-off first. An image file the person "
+         "names becomes one through plexora.import_image, which answers with the project that already "
+         "shows that file when there is one. Gating: "
          "plexora.suggest_auto_gate proposes a gate from the marker's distribution, plexora.set_gate stores "
          "it, plexora.get_gated_summary counts what a gate calls positive. Quality control: "
          "plexora.run_basic_qc on an image nobody has checked, then plexora.get_qc_results. "
@@ -83,6 +104,29 @@ CODES = {
     "ambiguous_view": "invalid_input",
 }
 
+#: Why Plexora's AI is off on this device: `ai()`'s reason, and what a call
+#: Plexora would pay for is refused with.
+NO_AI = "Plexora's AI needs Plexora Pro; `plexora license status` says what this device has"
+
+#: What Plexora's licence pays for in a workspace: the conversation (its chat
+#: module), never SCIMAP Pro's plans.
+PAID_MODULES = ("chat",)
+
+#: The images Plexora opens, by the end of their name, longest first so
+#: `.ome.tif` is not read as `.tif`: the format each is. Not a plain `.zarr`:
+#: by its name it may as well be an AnnData or SpatialData store (SCIMAP Pro's).
+IMAGES = ((".ome.tiff", "ome-tiff"), (".ome.tif", "ome-tiff"), (".ome.zarr", "ome-zarr"),
+          (".qptiff", "qptiff"), (".tiff", "tiff"), (".tif", "tiff"))
+
+#: What the app shows beside an image Plexora opens.
+IMAGE_LABEL = "Image · open it in Plexora"
+
+#: What the app shows beside an image it may hand to Plexora (`imports`).
+IMPORT_LABEL = "Image · Plexora"
+
+#: The guest tool an image is handed to Plexora through.
+IMPORT_TOOL = "import_image"
+
 
 class _Guest:
     """Plexora's tools, as a guest in another product's workspace."""
@@ -132,8 +176,59 @@ class _Plexora:
 
         if licensing.allows("ai:chat"):
             return {"ok": True, "reason": None}
-        return {"ok": False, "reason": "Plexora's AI needs Plexora Pro; `plexora license status` says what this "
-                                       "device has"}
+        return {"ok": False, "reason": NO_AI}
+
+    def pay(self) -> dict:
+        """What the app needs for Plexora to pay for a workspace's
+        conversation: a factory for the gateway client each model call goes
+        through, and the modules it serves (the chat only)."""
+        return {"gateway_factory": self._gateway, "modules": PAID_MODULES}
+
+    def _gateway(self):
+        """Plexora's gateway client when this device's licence allows its AI,
+        else one that refuses every call with `ai()`'s reason. Decided at each
+        call, so a device activated while the app runs pays from the next one.
+
+        The app hands it requests carrying SCIMAP Pro's task names too
+        (`chat.researcher`); `tasks.wire_id` sends a task Plexora's registry
+        does not name as `plexora.<module>.<task>`, which the gateway serves
+        at Plexora's default."""
+        state = self.ai()
+        if not state["ok"]:
+            from spatialagents.gateway import RefusingGateway
+
+            return RefusingGateway(state["reason"])
+        from plexora.ai.harness.gateway import GatewayClient
+
+        return GatewayClient()
+
+    def classify(self, path) -> dict | None:
+        """An image Plexora opens, by its name alone (no file is read):
+        `{format, label, action, product}`, with no action in this release;
+        None for anything else, a cell table included."""
+        name = re.split(r"[\\/]", os.fspath(path).rstrip("\\/"))[-1].lower()
+        for suffix, kind in IMAGES:
+            if name.endswith(suffix):
+                return {"format": kind, "label": IMAGE_LABEL, "action": None, "product": self.id}
+        return None
+
+    @property
+    def page(self) -> dict:
+        """What the app's home screen lists among what it opens: the images
+        Plexora takes (`imports`), files and the OME-Zarr folder."""
+        return {"formats": {"files": [suffix for suffix, _ in IMAGES if not suffix.endswith(".zarr")],
+                            "folders": [suffix for suffix, _ in IMAGES if suffix.endswith(".zarr")]}}
+
+    def imports(self, path) -> dict | None:
+        """How the app hands an image Plexora opens to Plexora: `{format,
+        label, tool, arguments}`, the guest tool (`import_image`) and what to
+        call it with; None for anything `classify` does not name an image.
+        By name alone, as `classify`: the tool is what reads the file."""
+        found = self.classify(path)
+        if found is None:
+            return None
+        return {"format": found["format"], "label": IMPORT_LABEL, "tool": IMPORT_TOOL,
+                "arguments": {"image": os.fspath(path)}}
 
     def licensing(self):
         from plexora.licensing import LICENSING

{plexora-0.0.33 → plexora-0.0.35}/plexora_intelligence/guest.json

@@ -469,6 +469,97 @@
     "viewer_required": false
    }
   },
+  {
+   "description": "The project that shows an image file on this machine, made from it (with its mask and cell table, when given) when there is none yet: the image is read where it lies, and a project already showing it is answered as it is. Changes Plexora's own state (reversible); returns a receipt.",
+   "descriptor": {
+    "entitlement": null,
+    "execution": "immediate",
+    "id": "plexora:project.import",
+    "input_schema": {
+     "additionalProperties": false,
+     "properties": {
+      "dataset": {
+       "anyOf": [
+        {
+         "type": "string"
+        },
+        {
+         "type": "null"
+        }
+       ],
+       "default": null,
+       "description": "Put the new project in this dataset.",
+       "title": "Dataset"
+      },
+      "image": {
+       "description": "Path to the image on this machine (OME-TIFF, TIFF, OME-Zarr, a whole-slide file).",
+       "title": "Image",
+       "type": "string"
+      },
+      "mask": {
+       "anyOf": [
+        {
+         "type": "string"
+        },
+        {
+         "type": "null"
+        }
+       ],
+       "default": null,
+       "description": "Its segmentation mask (a label image), for a new project.",
+       "title": "Mask"
+      },
+      "name": {
+       "anyOf": [
+        {
+         "type": "string"
+        },
+        {
+         "type": "null"
+        }
+       ],
+       "default": null,
+       "description": "The new project's name; default from the image's filename.",
+       "title": "Name"
+      },
+      "table": {
+       "anyOf": [
+        {
+         "type": "string"
+        },
+        {
+         "type": "null"
+        }
+       ],
+       "default": null,
+       "description": "Its cell table (CSV, Parquet, .h5ad, a SpatialData store), for a new project.",
+       "title": "Table"
+      }
+     },
+     "required": [
+      "image"
+     ],
+     "title": "ImportInput",
+     "type": "object"
+    },
+    "needs": [],
+    "permission": "reversible_write",
+    "produces": [],
+    "provider": "plexora",
+    "purpose": "The project that shows an image file on this machine, made from it (with its mask and cell table, when given) when there is none yet: the image is read where it lies, and a project already showing it is answered as it is.",
+    "roles": [],
+    "tags": [
+     "project",
+     "import",
+     "image",
+     "bridge",
+     "handoff"
+    ],
+    "tool_name": "import_image",
+    "version": "1",
+    "viewer_required": false
+   }
+  },
   {
    "description": "One marker's stored gate (lower/upper bound, whether it was ever narrowed from the full range) and how many cells it calls positive. Read-only.",
    "descriptor": {

{plexora-0.0.33 → plexora-0.0.35}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "plexora"
-version = "0.0.33"
+version = "0.0.35"
 description = "OpenSeadragon-based cellular image viewing and analysis tool."
 readme = "README.md"
 authors = [{ name = "BioCognia", email = "support@biocognia.com" }]
@@ -54,8 +54,12 @@ dependencies = [
     # in a SCIMAP Pro workspace, its tools -- its Pro AI gating and QC on a Pro
     # licence -- join the conversation over the bridge. Stdlib-only at import;
     # it adds the MCP SDK through spatialbridge[mcp], which the ai extra
-    # already brings.
-    "biocognia-intelligence>=0.2.1,<0.3",
+    # already brings. 0.3 may also have Plexora's licence pay for a
+    # workspace's conversation (`pay()`) and label its images (`classify`);
+    # 0.2 ignores both. 0.3.1 hands Plexora an image a person adds to a
+    # workspace (`imports()`, the `import_image` guest tool); 0.3.0 only
+    # labels it.
+    "biocognia-intelligence>=0.2.1,<0.4",
     "Flask>=3.1",
     "fsspec>=2024.12",
     # Declared rather than leaned on transitively: gating reads and writes

{plexora-0.0.33 → plexora-0.0.35}/tests/test_bridge_mcp.py

@@ -88,6 +88,22 @@ def test_errors_come_back_in_the_protocols_shape(peer):
     assert invalid.value.code == "invalid_input"
 
 
+def test_an_image_is_imported_over_mcp_as_biocognia_intelligence_hands_it(peer, tmp_path):
+    from spatialbridge.errors import BridgeError
+
+    from tests.agent_fixtures import blob_scene, write_image_pyramid
+
+    image = str(write_image_pyramid(tmp_path / "tonsil.ome.tif", blob_scene(size=256, grid=4, radius=12)[0]))
+    made = peer.invoke("import_image", {"image": image}, wait=False)
+    assert (made["project"], made["created"], made["image"]) == ("tonsil", True, image)
+    assert made["receipt"]["capability"] == "project.import"
+    again = peer.invoke("import_image", {"image": image}, wait=False)
+    assert (again["project"], again["created"]) == ("tonsil", False)
+    with pytest.raises(BridgeError) as missing:
+        peer.invoke("import_image", {"image": str(tmp_path / "gone.ome.tif")}, wait=False)
+    assert missing.value.code == "invalid_input" and "no image at" in str(missing.value)
+
+
 def test_a_bridge_origin_needs_no_mcp_grant(license_issuer):
     license_issuer.install()                       # Pro default: ["ai"], no mcp
     registry._reset_for_tests()