Metadata-Version: 2.5
Name: biocognia-intelligence
Version: 0.3.3
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: plexora<0.1,>=0.0.35; python_version < '3.15'
Requires-Dist: scimappro[ai,bridge,search]<0.2,>=0.1.28; python_version < '3.15'
Requires-Dist: spatialagents<0.3,>=0.2.5
Requires-Dist: spatialbridge[mcp]<0.3,>=0.2.3
Description-Content-Type: text/markdown

# Biocognia Intelligence

One AI workspace over the BioCognia products, opened with one command.
Installing it installs the products, and installing a product installs it, so
any one of these gives you the app, SCIMAP Pro and Plexora in one environment:

```bash
pip install biocognia-intelligence     # or scimappro, or plexora
biocognia
```

Each product is used where its licence is on this device. (`pip install
biocognia` is the licensing library alone, not the app.)

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

The assistant can also work on the computer itself, as you would at a
terminal: make a conda environment or a Python venv, install a package, run a
command or a script (in the background for a long one, which keeps running if
the app closes), and read, search and write files. Its shell keeps its folder
from one command to the next.

Each workspace has a folder of its own, made when the workspace is, under
`~/Biocognia` (Preferences › Workspace folders changes where; the composer's
menu › Workspace Folder… moves one). `results/` holds what the work produced
-- figures, tables, AnnData objects, scripts; SCIMAP Pro's figures and tables
go there too -- and `system/` what can be made again: downloads, command logs.
Environments are made where their tools keep them (conda's own `envs` folder,
`~/.virtualenvs` for a venv), so `conda activate` and your editor find them,
and the workspace records each one its work made. Deleting a workspace asks
whether to delete either part; its system files take those environments with
them.

Routine work runs without asking. You are asked before anything that reaches
beyond the work: deleting outside the workspace's folder, uninstalling from an
environment it did not make, installing into the app's own Python, `sudo`,
killing a process, running a downloaded script, reading a credential -- and,
unless autonomy is automatic, changing a file of yours outside the workspace's
folder. Manual autonomy asks before every change. `BIOCOGNIA_COMPUTER=0` turns
this off.

| 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.
- **This computer is a tool too.** `computer.<tool>` runs shell commands
  (in the foreground, or in the background to follow later, even after a
  restart), reads, lists, searches, writes and edits files, and finds the
  Python environments here: this app's own, conda, mamba or micromamba and
  their environments, venvs, and uv. It runs in this process, so a call can
  wait for the person's approval as a provider's own do, and its class is read
  off what the call would do: routine work is a `reversible_write`, a file of
  the person's outside the workspace's folder a `source_file_write`, and what
  reaches beyond the work `destructive`. A command runs non-interactively in
  its conversation's shell folder, without this app's credentials, and with
  conda on its PATH even when the app was started from the desktop. The
  contract is in `src/biocognia_intelligence/computer.py`.
- **A workspace has a folder.** Chosen when it is made, recorded in the
  workspace with the environments its commands made, shown and moved from the
  page, and offered part by part when it is deleted
  (`src/biocognia_intelligence/folders.py`). An in-process provider whose host
  has `use_folder(path)` is told where its results go.
- **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. A
   family product is also added to the app's own dependencies, so it comes
   with the app and with every other product.
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.
