Metadata-Version: 2.5
Name: biocognia-intelligence
Version: 0.3.1
Summary: Biocognia Intelligence: one AI workspace over the BioCognia products installed, opened with `biocognia`
Project-URL: Homepage, https://biocognia.com
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: biocognia<0.2,>=0.1.2
Requires-Dist: spatialagents<0.3,>=0.2.4
Requires-Dist: spatialbridge[mcp]<0.3,>=0.2.3
Description-Content-Type: text/markdown

# Biocognia Intelligence

One AI workspace over the BioCognia products you have installed, opened with one command.
It comes with every product:

```bash
pip install scimappro          # or plexora: either brings the app
biocognia
```

`biocognia` opens the Workspace in your browser. Start with a question, with
your data, or both: drop or choose a file or folder, or connect a data location,
and Send makes a workspace for them. The product that reads that kind of data
opens it, and the assistant helps you explore and interpret it. Your workspaces,
and SCIMAP Pro's own sessions, are listed together. A product with an
application of its own, such as Plexora, opens in its own window from
File › Applications.

There is one kind of workspace, and it is the app's. The products you have
installed are its tools: SCIMAP Pro's analyses run in it, and Plexora's tools
join its conversations. You never choose which product a workspace is for.

The app needs no licence of its own. It works once one product is installed
and this device is connected with that product's licence: **Tools › Connect
this device** in the page, or `biocognia connect`, shows a code you approve in
the portal, and every product you hold a seat for is connected at once. The
Tools menu shows each product's state (not installed, not connected,
connected, with or without AI and MCP access) and the tools it brings.

One conversation can use several products. With Plexora installed, the
assistant can also gate markers against the staining, check the image's
quality, draw regions and look at rendered images in Plexora, and bring the
results back into the table. With a Plexora Pro licence it can also run
Plexora's AI gating and AI QC: the whole run on Plexora's own AI (Plexora's
credits), or step by step, deciding from each packet's images itself.

| You have | The app gives you |
|---|---|
| SCIMAP Pro | SCIMAP Pro's analyses in conversation, paid by SCIMAP Pro's licence |
| SCIMAP Pro and Plexora | both in one conversation, Plexora's Free tools included |
| both, with Plexora Pro | Plexora's AI gating and QC too |
| Plexora only | Plexora's tools in conversation, paid by Plexora's licence, and images you add made Plexora projects; `biocognia install scimappro` adds the analyses |

Coding agents such as Claude Code reach SCIMAP Pro over MCP where its licence
includes MCP access: `scimappro ai init` wires them to `scimappro mcp serve`,
and **Tools › Connect a coding agent** lets one into an open workspace.

| Command | What it does |
|---|---|
| `biocognia` | Opens the app. `--no-browser` prints its address instead, and `--port` serves elsewhere (default 8480). |
| `biocognia tools` | Each product as the Tools menu shows it: installed, connected, AI and MCP access, its tools. `--json` prints it as JSON. |
| `biocognia connect` | Connects this device: a code to approve in the portal, or a licence key (`biocognia connect BIOC-...`). The same as `biocognia license activate`. |
| `biocognia list` | The products installed, and those of the family that are not. `--licence` adds whether each one's AI licence lets a conversation run and how many of a guest's tools it unlocks; `--json` prints it all as JSON. |
| `biocognia open plexora` | Opens a product's own application, for a product that has one. |
| `biocognia install plexora` | Installs a product into the Python the app runs in (pip, else uv). `--upgrade` takes it to its newest release. A desktop application's own Python is updated by its installer instead. |
| `biocognia doctor` | Checks each product: its registration, whether it can pay for the assistant, MCP access, its tools and whether it is running. Exits 1 on a problem, with what to do. |
| `biocognia license status` | This device's licences, for every product. `activate`, `refresh`, `install` and the other verbs work as in each product's own command line. |
| `biocognia serve --desktop` | A desktop shell's sidecar: one ready line, then the app until stdin closes. |

## Desktop app

`desktop/` is the app as a desktop application (Tauri 2), moved here from
SCIMAP Pro, whose own app it was until 0.1.27. It runs `biocognia serve
--desktop` from a Python runtime inside the installer and shows it in a
native window, with a menu bar, one instance at a time, `.h5ad` files and
`biocognia://` links opened in it, and Check for Updates. The runtime carries
the app and SCIMAP Pro (`scimappro[ai,bridge,search]`, a compiled wheel), so
SCIMAP Pro's analyses are there with nothing else to install. The installer
updates that Python, never pip.

```bash
python tools/release.py doctor     # what the toolchain lacks: uv, Node, Rust, and Xcode, MSVC or WebKitGTK
python tools/release.py all        # tests, wheel, runtime, installer, validate -> build/desktop, release/
python tools/release.py --scimappro ../scimappro/build/release/dist/scimappro-<version>-cp313-<platform>.whl all
```

SCIMAP Pro comes from PyPI unless `--scimappro` names a wheel or another
requirement (SCIMAP Pro's `python tools/release.py wheel` builds one). A `v*`
tag builds the Windows, macOS (Apple silicon) and Linux installers in
`.github/workflows/desktop.yml` and publishes them, with the updater's
`latest.json`, as a GitHub release. After changing the version in
`pyproject.toml`, `python tools/release.py propagate` copies it into the
shell's files; the tests fail until it does.

| Variable | What it does |
|---|---|
| `BIOCOGNIA_DESKTOP_RUNTIME` | The runtime folder the shell runs (`<runtime>/bin/python3`, or `<runtime>\python.exe` on Windows) in place of the bundled one. |
| `BIOCOGNIA_DESKTOP_PYTHON`, `BIOCOGNIA_DESKTOP_CWD` | Run the server with this Python, from this folder (a checkout's `src`), to work on the shell against a checkout: `cargo run --manifest-path desktop/src-tauri/Cargo.toml`. |
| `BIOCOGNIA_DESKTOP`, `SCIMAPPRO_DESKTOP` | Set by the shell for the server. `biocognia install` refuses to run pip inside the bundled runtime. |
| `BIOCOGNIA_SCIMAPPRO` | The SCIMAP Pro that `tools/release.py` puts in the runtime, as `--scimappro` does. |
| `TAURI_SIGNING_PRIVATE_KEY`, `BIOCOGNIA_UPDATER_PUBKEY` | The updater's key pair (a secret and a repository variable). Without them, installers are built but update by download, not in place. |

## How it is put together

- **A workspace is the app's.** One made here is a folder under the app's own
  (`workspaces/`), with `biocognia.json` saying which products are attached
  and who pays. The product that runs in this process (SCIMAP Pro) keeps its
  session in that folder, exactly as in its own sessions. SCIMAP Pro's own
  sessions, such as those its MCP server makes, are listed beside them and
  opened in place.
- **One product pays.** Every model call of a workspace goes through the
  payer's own gateway, as that product's task (`scimappro.chat.turn`). The
  payer is the first product, SCIMAP Pro before Plexora, whose AI licence is on
  this device when the workspace is made; the person can switch it in the
  Tools menu, and it never changes by itself. Work the payer's licence does not
  cover (plans, on Plexora's) is refused with a sentence saying who could pay
  for it. There is no Intelligence licence: AI comes with each product's
  licence.
- **Other products join as guests.** A guest's tools are listed in the
  conversation as `<product>.<tool>`, from a manifest shipped with the product,
  so the conversation's catalogue does not change when the guest is not
  running. Each call goes over [spatialbridge](https://pypi.org/project/spatialbridge/)
  to the copy already running, or starts one. The guest checks the call against its own licence.
  A tool that needs a licence is offered only where the guest's licence on this
  device covers it. Images a guest draws reach the model as images.
  Guests offer reads and reversible writes only, because the bridge cannot
  carry an approval. The home's own hand-offs, such as SCIMAP Pro's `view_image`,
  still move data between products, and the guest tools they already drive are
  not offered a second time. A file a guest takes, such as an image for
  Plexora, is handed to it through one of its tools when you add it to a
  workspace: Plexora makes it a project, and the conversation is told which.
  In a workspace with no product in this process (Plexora only), the guests'
  tools are all there is.
- **The runtime is shared.** The conversation, plans, approvals and the page are
  [spatialagents](https://pypi.org/project/spatialagents/). Licences and the
  AI token come from [biocognia](https://pypi.org/project/biocognia/).
- **Products register themselves.** A product joins by registering one object
  under the `biocognia.products` entry point, from a package small enough to
  import in a moment. The contract is in `src/biocognia_intelligence/registry.py`.

```toml
[project.entry-points."biocognia.products"]
myproduct = "myproduct_intelligence:PRODUCT"
```

## Adding a product

A new package joins without a release of this app:

1. Depend on `biocognia-intelligence>=0.3.1,<0.4`, so the app comes with it.
2. Register one object under `biocognia.products` (above), and assert
   `registry.check_registration(PRODUCT) == []` in its suite.
3. Run in this process as a **provider**, whose `provider().attach(ctx)`
   answers a workspace's parts (its host, its conversations' tools and
   prefix, its plans) made with the gateway the app hands it, or join over
   spatialbridge as a **guest**, whose `guest()` offers tools in every
   workspace. Offer `pay()` to pay for a workspace's model calls,
   `classify(path)` to say what a file is to you, and as a guest
   `imports(path)` to take a file through one of your tools. A product
   released for 0.3.0 runs in this process as a **home** instead
   (`home().opener()`); the app still attaches it, and pays through its
   opener's gateway.
4. A guest ships its manifest, written from its capability registry with
   `biocognia_intelligence.manifest.build(...)`: every tool names its
   permission, and a licensed one its entitlement, which `grants()` unlocks.
5. Test a whole conversation with `biocognia_intelligence.testing` (`guest_of`,
   `manifest_of`) and spatialagents' `FakeGateway`, then check an install with
   `biocognia doctor`.

The full contract, with how licences and credits work, is
`docs/intelligence.md` in the BioCognia platform repository.
