biocognia-intelligence 0.1.0__tar.gz

biocognia_intelligence-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+/build/
+/dist/
+/wheels/
+*.egg-info
+
+# Virtual environments
+.venv

biocognia_intelligence-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.5
+Name: biocognia-intelligence
+Version: 0.1.0
+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.2
+Provides-Extra: scimappro
+Requires-Dist: scimappro[ai,bridge,chat]; extra == 'scimappro'
+Description-Content-Type: text/markdown
+
+# Biocognia Intelligence
+
+One AI workspace over the BioCognia products you have installed, opened with one command:
+
+```bash
+pip install "biocognia-intelligence[scimappro]"
+biocognia
+```
+
+`biocognia` opens the Workspace in your browser. Start with your data: a file, a
+folder, or a data location. The product that fits it opens it (or the one you
+choose), and the assistant helps you explore and interpret it. Your workspaces
+from each product are listed together. The products you have installed, such
+as Plexora, can be opened from the home screen in their own windows.
+
+| Command | What it does |
+|---|---|
+| `biocognia` | Opens the app. `--no-browser` prints its address instead, `--port` serves elsewhere (default 8480), and `--home ID` sets the product a new workspace belongs to. |
+| `biocognia list` | The products installed. `--licence` adds whether each one's AI licence lets a conversation run, and `--json` prints it all as JSON. |
+| `biocognia open plexora` | Opens a product's own application. |
+| `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. |
+
+## How it is put together
+
+- **A workspace belongs to one product**, its home. It is stored where that
+  product keeps its sessions, so the product's own app (`scimappro`) lists and
+  opens the same workspaces.
+- **The home product pays.** Its AI licence pays for the conversation, through
+  that product's own gateway. There is no separate Intelligence licence: AI
+  comes with each product's licence.
+- **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"
+```

biocognia_intelligence-0.1.0/README.md

@@ -0,0 +1,42 @@
+# Biocognia Intelligence
+
+One AI workspace over the BioCognia products you have installed, opened with one command:
+
+```bash
+pip install "biocognia-intelligence[scimappro]"
+biocognia
+```
+
+`biocognia` opens the Workspace in your browser. Start with your data: a file, a
+folder, or a data location. The product that fits it opens it (or the one you
+choose), and the assistant helps you explore and interpret it. Your workspaces
+from each product are listed together. The products you have installed, such
+as Plexora, can be opened from the home screen in their own windows.
+
+| Command | What it does |
+|---|---|
+| `biocognia` | Opens the app. `--no-browser` prints its address instead, `--port` serves elsewhere (default 8480), and `--home ID` sets the product a new workspace belongs to. |
+| `biocognia list` | The products installed. `--licence` adds whether each one's AI licence lets a conversation run, and `--json` prints it all as JSON. |
+| `biocognia open plexora` | Opens a product's own application. |
+| `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. |
+
+## How it is put together
+
+- **A workspace belongs to one product**, its home. It is stored where that
+  product keeps its sessions, so the product's own app (`scimappro`) lists and
+  opens the same workspaces.
+- **The home product pays.** Its AI licence pays for the conversation, through
+  that product's own gateway. There is no separate Intelligence licence: AI
+  comes with each product's licence.
+- **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"
+```

biocognia_intelligence-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "biocognia-intelligence"
+version = "0.1.0"
+description = "Biocognia Intelligence: one AI workspace over the BioCognia products installed, opened with `biocognia`"
+readme = "README.md"
+authors = [
+    { name = "Ajit Johnson Nirmal", email = "ajitjohnson.n@gmail.com" }
+]
+requires-python = ">=3.12"
+license = "LicenseRef-Proprietary"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+# The application, not a library: the licensing client and the runtime are the
+# shared layer, and each product joins by registering under the
+# `biocognia.products` entry point (registry.py). `biocognia --help` and
+# `biocognia list` load neither: every subcommand imports what it needs.
+dependencies = [
+    "biocognia>=0.1.2,<0.2",
+    "spatialagents>=0.2.2,<0.3",
+]
+
+[project.optional-dependencies]
+scimappro = ["scimappro[ai,chat,bridge]"]
+
+[project.scripts]
+biocognia = "biocognia_intelligence.cli:main"
+
+[project.urls]
+Homepage = "https://biocognia.com"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/biocognia_intelligence"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-timeout>=2.3",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+timeout = 120

biocognia_intelligence-0.1.0/src/biocognia_intelligence/__init__.py

@@ -0,0 +1,10 @@
+"""Biocognia Intelligence: one AI workspace over the BioCognia products installed.
+
+`biocognia` opens it (cli.py): spatialagents' Workspace page, where a
+workspace belongs to one product -- its home, whose AI licence pays for the
+conversation -- and the home screen lists the person's applications.
+Products join by registering under the `biocognia.products` entry point
+(registry.py). Importing this package loads nothing.
+"""
+
+__version__ = "0.1.0"

biocognia_intelligence-0.1.0/src/biocognia_intelligence/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m biocognia_intelligence`: what a desktop shell spawns."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

biocognia_intelligence-0.1.0/src/biocognia_intelligence/api.py

@@ -0,0 +1,98 @@
+"""The app's HTTP contract: spatialagents' Workspace (`WorkspaceApi`), and the
+person's applications beside it.
+
+    GET   /apps              each installed product: {id, name, brand, version, ai, can_open, home, note?}
+    POST  /apps/:id/open     start its own application, in its own window
+
+Everything else is the Workspace's.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+
+_APPS = re.compile(r"^/apps(?:/([^/]+)/(open))?$")
+
+
+class IntelligenceApi:
+    """`inner` is the `WorkspaceApi`; `products` the registered products and
+    `stale` the family's installed too old to register (registry.py);
+    `start(argv, product_id) -> pid` starts an application (tests pass their own)."""
+
+    def __init__(self, inner, products, *, stale=(), start=None):
+        self.inner = inner
+        self.products = {product.id: product for product in products}
+        self.stale = {row["id"]: row for row in stale}
+        self.start = start or _start
+
+    def __getattr__(self, name):
+        # What the server asks of the Workspace's API (whether it runs plans) is the Workspace's.
+        return getattr(self.inner, name)
+
+    def handle(self, method: str, path: str, *, query=None, body=None, headers=None):
+        found = _APPS.match("/" + str(path).strip("/"))
+        if not found:
+            return self.inner.handle(method, path, query=query, body=body, headers=headers)
+        from spatialagents.chat.http import missing, ok, refused
+
+        method = method.upper()
+        if found.group(1) is None and method == "GET":
+            return ok({"apps": self.apps()})
+        if found.group(1) is not None and method == "POST":
+            product_id = found.group(1)
+            argv = self._argv(product_id)
+            if argv is None:
+                return refused({"code": "not_found" if product_id not in self.products else "capability_unavailable",
+                                "message": f"{product_id!r} has no application of its own here",
+                                "detail": None, "retryable": False})
+            name = self._name(product_id)
+            try:
+                pid = self.start(argv, product_id)
+            except OSError as problem:
+                return refused({"code": "resource_unavailable", "message": f"{name} would not start: {problem}",
+                                "detail": None, "retryable": True})
+            return ok({"started": True, "pid": pid, "message": f"{name} is opening in its own window"})
+        return missing(f"no route {method} {path}")
+
+    def apps(self) -> list:
+        from .registry import version_of
+        from .routing import _ai
+
+        rows = []
+        for product in self.products.values():
+            rows.append({"id": product.id, "name": product.name, "brand": product.brand,
+                         "version": version_of(product.distribution), "ai": _ai(product),
+                         "can_open": self._argv(product.id) is not None,
+                         "home": callable(getattr(product, "home", None))})
+        for row in self.stale.values():
+            rows.append({"id": row["id"], "name": row["name"], "brand": row["brand"], "version": row["version"],
+                         "ai": None, "can_open": True, "home": False,
+                         "note": f"opens in its own window; from {row['registers_from']} its workspaces open here too"})
+        return rows
+
+    def _name(self, product_id: str) -> str:
+        product = self.products.get(product_id)
+        return product.name if product is not None else self.stale[product_id]["name"]
+
+    def _argv(self, product_id: str):
+        product = self.products.get(product_id)
+        if product is not None:
+            argv = product.app()
+            return list(argv) if argv else None
+        if product_id in self.stale:
+            return [sys.executable, *self.stale[product_id]["app"]]
+        return None
+
+
+def _start(argv, product_id) -> int:
+    """Start an application on its own, its output in the app's logs."""
+    from .paths import app_dir
+
+    logs = app_dir() / "logs"
+    logs.mkdir(parents=True, exist_ok=True)
+    with open(logs / f"{product_id}.log", "ab") as log:
+        started = subprocess.Popen(list(argv), stdin=subprocess.DEVNULL, stdout=log, stderr=subprocess.STDOUT,
+                                   start_new_session=True)
+    return started.pid

biocognia_intelligence-0.1.0/src/biocognia_intelligence/app.py

@@ -0,0 +1,242 @@
+"""The app: spatialagents' Workspace page over every product that can hold a
+workspace, and the person's applications on its home screen.
+
+`server()` builds it (not started); `launch` is a bare `biocognia`, which
+opens it in a browser where this looks like a desktop; `serve` is the same
+without the browser, or with `--desktop` the desktop shell's sidecar (one
+ready line, then until stdin closes). Like each product's own app it opens
+without an AI licence: the page says so, and model calls in a workspace whose
+product has none are refused by that product's gateway.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from . import __version__, registry
+from .paths import DESKTOP_PORT, LAUNCH_PORT, app_dir
+
+log = logging.getLogger("biocognia_intelligence.app")
+
+TITLE = "Biocognia Intelligence"
+TAGLINE = ("Choose a file, folder, or data location. The product that fits it opens it, "
+           "and AI helps you explore and interpret your data.")
+
+#: Set where nobody is sitting at this machine's screen: a cluster job, CI, an
+#: SSH login (the products' list).
+HEADLESS = ("CI", "SLURM_JOB_ID", "PBS_JOBID", "LSB_JOBID", "SSH_CONNECTION", "SSH_CLIENT")
+
+
+class NoHome(RuntimeError):
+    """No installed product can hold a workspace."""
+
+
+def homes_of(products) -> tuple[list, list]:
+    """`([(product, home, opener)], [problem sentences])`: each product that
+    can hold a workspace, its Home and the opener it built."""
+    homes, problems = [], []
+    for product in products:
+        try:
+            home = product.home()
+            if home is None:
+                continue
+            homes.append((product, home, home.opener()))
+        except Exception as problem:  # noqa: BLE001 -- the others still open
+            log.warning("%s cannot hold workspaces here", product.name, exc_info=True)
+            problems.append(f"{product.name} cannot hold workspaces here: {problem}")
+    return homes, problems
+
+
+def server(*, port=0, host="127.0.0.1", token=None, default=None, require_token=False, frame_ancestors=None,
+           products=None, stale=None, start=None, on_open=None):
+    """A `ChatServer` for the app (not started). `products` and `stale` are
+    the registry's unless given; its `workspaces` attribute is the
+    `WorkspaceService` (close it on the way out), `problems` what could not
+    be opened."""
+    from spatialagents.chat.server import ChatServer
+    from spatialagents.workspace import static_dir
+    from spatialagents.workspace.http import WorkspaceApi
+    from spatialagents.workspace.service import WorkspaceService
+
+    from .api import IntelligenceApi
+    from .routing import RoutingOpener
+
+    if products is None:
+        products = registry.products()
+        stale = registry.too_old() if stale is None else stale
+    homes, problems = homes_of(products)
+    if not homes:
+        raise NoHome("no BioCognia product that holds workspaces is installed" +
+                     (f" ({'; '.join(problems)})" if problems else ""))
+    routing = RoutingOpener(homes, default=default, on_open=on_open)
+    service = WorkspaceService(routing)
+    api = IntelligenceApi(WorkspaceApi(service), products, stale=stale or (), start=start)
+    page = {"assistant": TITLE, "product": TITLE, "brand": "biocognia", "version": __version__,
+            "tagline": TAGLINE, "products": routing.homes(), "apps": True}
+    found = ChatServer(api, host=host, port=int(port or 0), token=token, title=TITLE, page=page,
+                       page_dir=static_dir(), frame_ancestors=tuple(frame_ancestors or ("'self'",)),
+                       require_token=require_token)
+    found.workspaces = service
+    found.problems = problems
+    found.homes = [product.id for product, _, _ in homes]
+    return found
+
+
+def wants_browser(preference="auto", env=None, system=None) -> bool:
+    """Whether a bare `biocognia` opens a browser: always for `yes`, never for
+    `no`, and for `auto` on a desktop -- macOS, Windows, or Linux with a
+    display -- but not on a cluster node, in CI or over SSH."""
+    import os
+    import platform
+
+    if preference in ("yes", "no"):
+        return preference == "yes"
+    env = os.environ if env is None else env
+    system = platform.system() if system is None else system
+    if any(env.get(name) for name in HEADLESS):
+        return False
+    if system in ("Darwin", "Windows"):
+        return True
+    return bool(env.get("DISPLAY") or env.get("WAYLAND_DISPLAY"))
+
+
+def _bound(build, asked, fallback_port, error, **options):
+    """`build(port=...)` on the port asked for, else the usual one, else any."""
+    try:
+        return build(port=asked or fallback_port, **options)
+    except OSError:
+        if asked:
+            error(f"biocognia: port {asked} is in use; choose another with --port, or leave it out")
+            return None
+        return build(port=0, **options)
+
+
+def _say_licences(found, error) -> None:
+    for problem in found.problems:
+        error(f"biocognia: {problem}")
+    for home in found.workspaces.opener.homes():
+        if not home["ai"]["ok"]:
+            error(f"biocognia: {home['name']}: {home['ai']['reason']}")
+            error(f"  {home['name']} workspaces open; the assistant stays off in them until this device has "
+                  f"its licence.")
+
+
+def launch(args, *, write, error, open_url=None) -> int:
+    """`biocognia` alone: the app on its home screen, in a browser where this
+    looks like a desktop, until Ctrl-C."""
+    try:
+        found = _bound(server, getattr(args, "port", 0) or 0, LAUNCH_PORT, error,
+                       default=getattr(args, "home", None))
+    except (NoHome, ValueError) as problem:
+        return _no_home(problem, error)
+    if found is None:
+        return 1
+    _say_licences(found, error)
+    write(TITLE)
+    write(f"Open {found.launch_url}")
+    write("The link works once; press Ctrl-C to stop.")
+    if wants_browser(getattr(args, "browser", "auto")):
+        if open_url is None:
+            import webbrowser
+
+            open_url = webbrowser.open
+        open_url(found.launch_url)
+    return _serve_until_stopped(found)
+
+
+def serve(args, *, write, error, read=None) -> int:
+    """`biocognia serve`: the app without a browser; with `--desktop`, the
+    desktop shell's sidecar."""
+    if getattr(args, "desktop", False):
+        return desktop(args, write=write, error=error, read=read)
+    try:
+        found = _bound(server, getattr(args, "port", 0) or 0, LAUNCH_PORT, error,
+                       host=getattr(args, "host", None) or "127.0.0.1", default=getattr(args, "home", None))
+    except (NoHome, ValueError) as problem:
+        return _no_home(problem, error)
+    if found is None:
+        return 1
+    _say_licences(found, error)
+    write(f"{TITLE} at {found.launch_url}")
+    return _serve_until_stopped(found)
+
+
+def ready_line(found, *, token: str) -> str:
+    """The one line a desktop shell reads (spatialagents' `ready_line`)."""
+    from spatialagents.desktop import ready_line as line
+
+    host, port = found.address
+    return line(host=host, port=port, token=token, version=__version__, origin=found.url,
+                data_root=str(app_dir()), settings_path=str(app_dir() / "desktop.json"),
+                app="biocognia-intelligence", homes=list(found.homes))
+
+
+def desktop(args, *, write, error, read=None) -> int:
+    """The desktop shell's sidecar: one ready line, then serve until stdin closes."""
+    import os
+    import secrets
+    import signal
+    import sys
+    import threading
+
+    token = os.environ.get("SPATIALAGENTS_CHAT_TOKEN") or secrets.token_urlsafe(16)
+    try:
+        found = _bound(server, getattr(args, "port", 0) or 0, DESKTOP_PORT, error, token=token,
+                       default=getattr(args, "home", None))
+    except (NoHome, ValueError) as problem:
+        return _no_home(problem, error)
+    if found is None:
+        return 1
+    write(ready_line(found, token=token))
+    stopped = threading.Event()
+
+    def stop(*_):
+        if not stopped.is_set():
+            stopped.set()
+            threading.Thread(target=found.stop, daemon=True).start()
+
+    def watch():
+        # The shell keeps our stdin open; when it goes away, so do we.
+        reader = read or (lambda: sys.stdin.read(1))
+        try:
+            while reader():
+                pass
+        except Exception:  # noqa: BLE001 -- a closed stdin is a goodbye
+            pass
+        stop()
+
+    threading.Thread(target=watch, name="biocognia-desktop-stdin", daemon=True).start()
+    try:
+        signal.signal(signal.SIGTERM, stop)
+    except ValueError:
+        pass                                    # not the main thread (a test)
+    try:
+        found.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        stop()
+        found.workspaces.close()
+    return 0
+
+
+def _serve_until_stopped(found) -> int:
+    try:
+        found.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        found.stop()
+        found.workspaces.close()
+    return 0
+
+
+def _no_home(problem, error) -> int:
+    error(f"biocognia: {problem}")
+    stale = registry.too_old()
+    for row in stale:
+        error(f"  {row['name']} {row['version']} is installed but too old to open here; it registers from "
+              f"{row['registers_from']}.")
+    if not stale:
+        error('  Install one: pip install "biocognia-intelligence[scimappro]"')
+    return 2

biocognia_intelligence-0.1.0/src/biocognia_intelligence/cli.py

@@ -0,0 +1,140 @@
+"""The `biocognia` command.
+
+    biocognia [--port N] [--browser | --no-browser] [--home ID]   open the app
+    biocognia list [--json] [--licence]       the products installed
+    biocognia open PRODUCT [ARGS ...]         a product's own application
+    biocognia serve [--host H] [--port N] [--home ID] [--desktop]
+    biocognia license [--product ID] VERB     the shared licence verbs
+
+Each subcommand imports what it needs: `--help` and `list` load neither the
+runtime nor a product.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="biocognia", description="Biocognia Intelligence: one AI workspace over the BioCognia products "
+                                      "installed. Alone, it opens in a browser; Ctrl-C stops it.")
+    parser.add_argument("--version", action="store_true", help="print the version and stop")
+    _serving(parser)
+    browser = parser.add_mutually_exclusive_group()
+    browser.add_argument("--browser", dest="browser", action="store_const", const="yes", default="auto",
+                         help="open a browser even where this looks like a cluster, CI or SSH")
+    browser.add_argument("--no-browser", dest="browser", action="store_const", const="no",
+                         help="print the app's address instead of opening it")
+    commands = parser.add_subparsers(dest="command")
+    listed = commands.add_parser("list", help="the BioCognia products installed")
+    listed.add_argument("--json", action="store_true", dest="as_json")
+    listed.add_argument("--licence", "--license", action="store_true", dest="licence",
+                        help="and whether each one's AI licence lets a conversation run (imports each product)")
+    opened = commands.add_parser("open", help="a product's own application, in its own window")
+    opened.add_argument("product")
+    opened.add_argument("args", nargs=argparse.REMAINDER, help="passed to the application")
+    served = commands.add_parser("serve", help="the app without a browser (--desktop: a desktop shell's sidecar)")
+    _serving(served)
+    served.add_argument("--host", help="the address to serve on (default 127.0.0.1)")
+    served.add_argument("--desktop", action="store_true", help="print one ready line and stop when stdin closes")
+    licence = commands.add_parser("license", help="this device's licences, for every product installed")
+    from . import licence as licence_verbs
+
+    licence_verbs.add_arguments(licence)
+    return parser
+
+
+def _serving(parser) -> None:
+    parser.add_argument("--port", type=int, default=0, help="the port to serve on (default 8480, or a free one)")
+    parser.add_argument("--home", help="the product a new workspace belongs to unless the page says "
+                                       "(`biocognia list` names them)")
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    write = lambda line: print(line, flush=True)  # noqa: E731
+    error = lambda line: print(line, file=sys.stderr, flush=True)  # noqa: E731
+    if args.version:
+        from . import __version__
+
+        write(__version__)
+        return 0
+    if args.command == "list":
+        return list_products(args, write=write)
+    if args.command == "open":
+        return open_product(args, error=error)
+    if args.command == "license":
+        from . import licence
+
+        return licence.run(args, out=write, err=error)
+    from . import app
+
+    if args.command == "serve":
+        return app.serve(args, write=write, error=error)
+    return app.launch(args, write=write, error=error)
+
+
+def rows(*, licence: bool = False) -> list:
+    """The products installed, as `biocognia list` says them."""
+    from . import registry
+
+    found = []
+    for product in registry.products():
+        row = {"id": product.id, "name": product.name, "version": registry.version_of(product.distribution),
+               "home": callable(getattr(product, "home", None)), "app": True}
+        if licence:
+            from .routing import _ai
+
+            row["ai"] = _ai(product)
+        found.append(row)
+    for stale in registry.too_old():
+        found.append({"id": stale["id"], "name": stale["name"], "version": stale["version"], "home": False,
+                      "app": True, "too_old": True, "registers_from": stale["registers_from"]})
+    return found
+
+
+def list_products(args, *, write) -> int:
+    found = rows(licence=args.licence)
+    if args.as_json:
+        write(json.dumps(found, indent=1))
+        return 0
+    if not found:
+        write('No BioCognia product is installed. pip install "biocognia-intelligence[scimappro]"')
+        return 0
+    width = max(len(f"{row['name']} {row['version'] or ''}") for row in found)
+    for row in found:
+        name = f"{row['name']} {row['version'] or ''}".ljust(width)
+        if row.get("too_old"):
+            says = f"too old to open here (registers from {row['registers_from']}); `biocognia open {row['id']}`"
+        else:
+            says = "workspaces open here" if row["home"] else "its own application"
+            if "ai" in row:
+                says += " · " + ("AI included" if row["ai"]["ok"] else f"no AI: {row['ai']['reason']}")
+        write(f"{name}  {says}")
+    return 0
+
+
+def open_product(args, *, error) -> int:
+    """A product's own application, in the foreground: this command waits for it."""
+    import subprocess
+
+    from . import registry
+
+    product = registry.find(args.product)
+    if product is not None:
+        argv = product.app()
+    else:
+        stale = next((row for row in registry.too_old() if row["id"] == args.product), None)
+        argv = [sys.executable, *stale["app"]] if stale else None
+    if not argv:
+        known = [row["id"] for row in rows()]
+        error(f"biocognia: no application {args.product!r} is installed"
+              + (f"; installed: {', '.join(known)}" if known else ""))
+        return 2
+    try:
+        return subprocess.call([*argv, *args.args])
+    except KeyboardInterrupt:
+        return 130