Metadata-Version: 2.4
Name: microscopy-llm-profiler
Version: 0.2.0
Summary: Deterministic microscopy image analysis for AI agents, over MCP. Point your Claude/Cursor/Codex agent at an image and it segments, counts, and measures cells — Fiji/ImageJ-equivalent, every number traceable to a tool, never guessed.
Author: microscopy-llm-profiler maintainers
License: # PolyForm Noncommercial License 1.0.0
        
        <https://polyformproject.org/licenses/noncommercial/1.0.0>
        
        Required Notice: Copyright (c) 2026 microscopy-llm-profiler maintainers
        
        ## Acceptance
        
        In order to get any license under these terms, you must agree
        to them as both strict obligations and conditions to all
        your licenses.
        
        ## Copyright License
        
        The licensor grants you a copyright license for the
        software to do everything you might do with the software
        that would otherwise infringe the licensor's copyright
        in it for any permitted purpose. However, you may
        only distribute the software according to [Distribution
        License](#distribution-license) and make changes or new
        works based on the software according to [Changes and New
        Works License](#changes-and-new-works-license).
        
        ## Distribution License
        
        The licensor grants you an additional copyright license
        to distribute copies of the software. Your license
        to distribute covers distributing the software with
        changes and new works permitted by [Changes and New Works
        License](#changes-and-new-works-license).
        
        ## Notices
        
        You must ensure that anyone who gets a copy of any part of
        the software from you also gets a copy of these terms or the
        URL for them above, as well as copies of any plain-text lines
        beginning with `Required Notice:` that the licensor provided
        with the software. For example:
        
        > Required Notice: Copyright (c) 2026 microscopy-llm-profiler maintainers
        
        ## Changes and New Works License
        
        The licensor grants you an additional copyright license to
        make changes and new works based on the software for any
        permitted purpose.
        
        ## Patent License
        
        The licensor grants you a patent license for the software that
        covers patent claims the licensor can license, or becomes able
        to license, that you would infringe by using the software.
        
        ## Noncommercial Purposes
        
        Any noncommercial purpose is a permitted purpose.
        
        ## Personal Uses
        
        Personal use for research, experiment, and testing for
        the benefit of public knowledge, personal study, private
        entertainment, hobby projects, amateur pursuits, or religious
        observance, without any anticipated commercial application,
        is use for a permitted purpose.
        
        ## Noncommercial Organizations
        
        Use by any charitable organization, educational institution,
        public research organization, public safety or health
        organization, environmental protection organization,
        or government institution is use for a permitted purpose
        regardless of the source of funding or obligations resulting
        from the funding.
        
        ## Fair Use
        
        You may have "fair use" rights for the software under the
        law. These terms do not limit them.
        
        ## No Other Rights
        
        These terms do not allow you to sublicense or transfer any of
        your licenses to anyone else, or prevent the licensor from
        granting licenses to anyone else. These terms do not imply
        any other licenses.
        
        ## Patent Defense
        
        If you make any written claim that the software infringes or
        contributes to infringement of any patent, your patent license
        for the software granted under these terms ends immediately. If
        your company makes such a claim, your patent license ends
        immediately for work on behalf of your company.
        
        ## Violations
        
        The first time you are notified in writing that you have
        violated any of these terms, or done anything with the software
        not covered by your licenses, your licenses can nonetheless
        continue if you come into full compliance with these terms,
        and take practical steps to correct past violations, within
        32 days of receiving notice. Otherwise, all your licenses
        end immediately.
        
        ## No Liability
        
        ***As far as the law allows, the software comes as is, without
        any warranty or condition, and the licensor will not be liable
        to you for any damages arising out of these terms or the use
        or nature of the software, under any kind of legal claim.***
        
        ## Definitions
        
        The **licensor** is the individual or entity offering these
        terms, and the **software** is the software the licensor makes
        available under these terms.
        
        **You** refers to the individual or entity agreeing to these
        terms.
        
        **Your company** is any legal entity, sole proprietorship,
        or other kind of organization that you work for, plus all
        organizations that have control over, are under the control of,
        or are under common control with that organization. **Control**
        means ownership of substantially all the assets of an entity,
        or the power to direct its management and policies by vote,
        contract, or otherwise. Control can be direct or indirect.
        
        **Your licenses** are all the licenses granted to you for the
        software under these terms.
        
        **Use** means anything you do with the software requiring one
        of your licenses.
License-File: LICENSE
Keywords: cell-counting,claude,fiji,image-analysis,mcp,microscopy,nd2,segmentation
Classifier: Intended Audience :: Science/Research
Classifier: License :: Free for non-commercial use
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.11
Requires-Dist: jinja2<4,>=3.1
Requires-Dist: mcp[cli]>=1.0
Requires-Dist: nd2>=0.9
Requires-Dist: numpy<3,>=1.26
Requires-Dist: opencv-python-headless<5,>=4.9
Requires-Dist: pillow<12,>=10.0
Requires-Dist: pydantic<3,>=2.0
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: scikit-image<1,>=0.22
Requires-Dist: scipy<2,>=1.12
Provides-Extra: api
Requires-Dist: fastapi>=0.115; extra == 'api'
Requires-Dist: httpx>=0.27; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.30; extra == 'api'
Provides-Extra: cellpose
Requires-Dist: cellpose>=3.0; extra == 'cellpose'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: fiji
Requires-Dist: pyimagej>=1.4; extra == 'fiji'
Provides-Extra: stardist
Requires-Dist: stardist>=0.9; extra == 'stardist'
Requires-Dist: tensorflow>=2.15; extra == 'stardist'
Provides-Extra: vision
Requires-Dist: anthropic>=0.40; extra == 'vision'
Description-Content-Type: text/markdown

# microscopy-llm-profiler

**Deterministic microscopy image analysis for AI agents, over MCP.**

Point your Claude / Cursor / Codex agent at a microscopy image and it does the
analysis for you — segment, count, measure, localize, colocalize — by calling
**51 deterministic [MCP](https://modelcontextprotocol.io) tools**. Every number
comes from a named tool (segmenter + metric), traceable and reproducible — **never
an LLM guess**. No browser, no separate analysis API key: your agent is the
orchestrator; Python does the math.

Think of it as **Fiji/ImageJ, driven in plain language** — "profile this ND2",
"count the rods on the DIC channel", "give me per-cell bipolar vs septal
localization" — with the rigor of a scripted pipeline.

## Why

- **Trustworthy by construction.** The engine is deterministic; the agent chooses
  *which* tool and interprets overlays, but it cannot invent a count. Every result
  is a segmenter + metric you can re-run.
- **QC-first workflow.** Metadata, saturation, SNR, and focus checks run before any
  measurement, so you catch bad data instead of counting noise.
- **Formats scientists actually use.** Native `.nd2` (multi-channel, by channel
  name), `.tif`/`.tiff`, `.png`.

## What's inside

- **Segment & count** — nuclei, puncta/vesicles, condensates, and rod bacteria
  (DIC-guided), with an evaluate-and-retune quality loop for counts you can trust.
- **Segmenters** — `opencv_watershed` (blobs, deterministic, no GPU), `dic_rod`
  (rods on DIC/brightfield), plus optional deep-learning `cellpose` / `stardist_2d`.
- **Measure** — per-object tables (area, intensity, shape), colocalization
  (Pearson/Manders), spatial cross-correlation, subcellular localization
  (membrane / polar / bipolar / septal / diffuse).
- **Agent-in-the-loop** — `threshold_step` / `segment_step` / `outline_step` for
  one-iteration-at-a-time visual review on hard images.
- **A `/micro` harness prompt** that boots the analysis workflow, shipped inside the
  package (no files to copy).

## Install (no repo clone)

```bash
# A) run on demand with uv — nothing installed globally
claude mcp add microscopy-profiler --scope user -- uvx microscopy-llm-profiler

# B) or pip install, then register + install the /micro skill
pip install microscopy-llm-profiler
microscopy-profiler-setup            # writes the /micro + /welcome skills, prints the mcp-add line
claude mcp add microscopy-profiler --scope user -- microscopy-profiler
```

Restart Claude Code, run `/mcp` to confirm `microscopy-profiler` is connected, then
type **`/micro`** to boot the harness (or use the built-in MCP prompt
`/mcp__microscopy-profiler__micro` — it ships in the package, no local files needed).

**Other clients:** the server speaks stdio MCP, so it works in Cursor, Claude
Desktop, and Codex too — point their MCP config at the `microscopy-profiler`
command. `microscopy-profiler-setup --print-config` prints the JSON snippet.

**Optional extras** (deep-learning segmenters / Fiji macros / VLM judge):

```bash
pip install "microscopy-llm-profiler[cellpose]"   # or [stardist], [fiji], [vision]
```

## Use

Just describe the task with an **absolute image path**:

> Profile `/abs/path/to/sample.nd2` — channels, pixel size, and any quality issues
> (saturation, low SNR, out of focus) before we measure anything.

> In `/abs/path/to/sample.nd2`, use the DIC channel for cell boundaries and the GFP
> channel for signal. Count rods and give per-cell bipolar / septal / diffuse
> localization with a histogram.

Requirements: Python ≥ 3.11. Deep-learning segmenters benefit from a GPU but aren't
required — the core watershed/rod path is CPU-only and deterministic.

## Data handling & security

Designed to be safe on unpublished / sensitive research data. Defaults are private:

- **Nothing leaves your machine by default.** The engine is fully local. The only
  off-box path is the *optional* VLM quality-check, which is **doubly gated** — it
  sends image pixels to the Anthropic API only if you set **both** `ANTHROPIC_API_KEY`
  **and** `MICROSCOPY_PROFILER_ALLOW_VLM=1`. Data sent there is subject to Anthropic's
  terms. Leave it unset to stay 100% local.
- **Telemetry is OFF by default.** Product/usage telemetry is written only if you opt
  in with `MICROSCOPY_PROFILER_TELEMETRY=1`; then it goes to local JSONL under
  `~/microscopy_profiler_runs/telemetry/` with file paths/emails redacted best-effort.
  It stays local unless you *also* set a collector URL (opt-in "phone home",
  `MICROSCOPY_PROFILER_TELEMETRY_UPLOAD_URL`) — a deliberate second switch. Even then,
  only redacted events are sent, and free-text queries are stripped unless you set
  `MICROSCOPY_PROFILER_TELEMETRY_UPLOAD_TEXT=1`. See SECURITY.md for all flags.
- **Run provenance** (manifests, overlays) is written under `~/microscopy_profiler_runs/`
  and includes the input file path. It has no auto-expiry — relocate it with
  `MICROSCOPY_PROFILER_RUNS=/path` (and telemetry with `MICROSCOPY_PROFILER_TELEMETRY_DIR`)
  to a scratch/encrypted location and purge periodically for sensitive data.
- **`run_fiji_macro` is arbitrary code execution** (ImageJ macros can spawn shells) and
  is **disabled** unless you set `MICROSCOPY_PROFILER_ALLOW_FIJI_MACROS=1` in a trusted
  environment. Every other tool is deterministic and non-privileged.

**Locked-down profile for clinical/sensitive data:** don't set `ANTHROPIC_API_KEY` /
`MICROSCOPY_PROFILER_ALLOW_VLM`, leave telemetry off, and point the runs dir at a scratch
location you control.

## License

**PolyForm Noncommercial 1.0.0** — free to use, modify, and share for any
**noncommercial** purpose (research, education, nonprofits, personal/hobby use).
**Commercial use is not permitted** — you may not use this software to build a
commercial product or business. See [`LICENSE`](LICENSE). For a commercial license,
contact the maintainers.

