Metadata-Version: 2.4
Name: medpilot
Version: 0.0.0
Summary: A lightweight personal AI assistant framework
Author: medpilot contributors
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: agent,ai,chatbot
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: chardet<6.0.0,>=3.0.2
Requires-Dist: croniter<7.0.0,>=6.0.0
Requires-Dist: ddgs<10.0.0,>=9.0.0
Requires-Dist: dingtalk-stream<1.0.0,>=0.24.0
Requires-Dist: httpx<1.0.0,>=0.28.0
Requires-Dist: json-repair<1.0.0,>=0.57.0
Requires-Dist: lark-oapi<2.0.0,>=1.5.0
Requires-Dist: litellm<2.0.0,>=1.81.5
Requires-Dist: loguru<1.0.0,>=0.7.3
Requires-Dist: mcp<2.0.0,>=1.26.0
Requires-Dist: msgpack<2.0.0,>=1.1.0
Requires-Dist: oauth-cli-kit<1.0.0,>=0.1.3
Requires-Dist: openai>=2.8.0
Requires-Dist: prompt-toolkit<4.0.0,>=3.0.50
Requires-Dist: psutil>=6.0.0
Requires-Dist: pydantic-settings<3.0.0,>=2.12.0
Requires-Dist: pydantic<3.0.0,>=2.12.0
Requires-Dist: python-socketio<6.0.0,>=5.16.0
Requires-Dist: python-socks[asyncio]<3.0.0,>=2.8.0
Requires-Dist: python-telegram-bot[socks]<23.0,>=22.6
Requires-Dist: qq-botpy<2.0.0,>=1.2.0
Requires-Dist: readability-lxml<1.0.0,>=0.8.4
Requires-Dist: rich<15.0.0,>=14.0.0
Requires-Dist: slack-sdk<4.0.0,>=3.39.0
Requires-Dist: slackify-markdown<1.0.0,>=0.2.0
Requires-Dist: socksio<2.0.0,>=1.0.0
Requires-Dist: typer<1.0.0,>=0.20.0
Requires-Dist: websocket-client<2.0.0,>=1.9.0
Requires-Dist: websockets<17.0,>=16.0
Provides-Extra: dev
Requires-Dist: aiohttp<4.0.0,>=3.9.0; extra == 'dev'
Requires-Dist: matrix-nio[e2e]>=0.25.2; extra == 'dev'
Requires-Dist: mistune<4.0.0,>=3.0.0; extra == 'dev'
Requires-Dist: nh3<1.0.0,>=0.2.17; extra == 'dev'
Requires-Dist: pytest-asyncio<2.0.0,>=1.3.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest<10.0.0,>=9.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: matrix
Requires-Dist: matrix-nio[e2e]>=0.25.2; extra == 'matrix'
Requires-Dist: mistune<4.0.0,>=3.0.0; extra == 'matrix'
Requires-Dist: nh3<1.0.0,>=0.2.17; extra == 'matrix'
Description-Content-Type: text/markdown

# <img src="icon.ico" width="40" height="40" align="top"> MedPilot

[![Tests](https://github.com/Project-MedPilot/MedPilot/actions/workflows/tests.yml/badge.svg)](https://github.com/Project-MedPilot/MedPilot/actions/workflows/tests.yml)
[![codecov](https://codecov.io/gh/Project-MedPilot/MedPilot/graph/badge.svg)](https://codecov.io/gh/Project-MedPilot/MedPilot)

An open-source, ultra-lightweight AI assistant tailored specifically for **Medical AI Research**.

Powered by an underlying micro-agent framework, MedPilot is designed to execute complex medical imaging pipelines, from raw DICOM data processing to deep learning tasks, traditional radiomics, and survival analysis.

## 🔬 Built-in Medical Skills

MedPilot comes pre-loaded with specialized medical skills:
1. **`medical-image-dl-pipeline`**: End-to-end deep learning pipeline (classification, segmentation, detection) built on MONAI and PyTorch. Features robust 5-Fold Cross-Validation and early stopping.
2. **`radiomics`**: High-dimensional radiomic feature extraction using PyRadiomics, combined with LASSO/mRMR feature selection.
3. **`survival-analysis`**: Time-to-event statistical modeling, Kaplan-Meier curves, and Cox Proportional Hazards models via lifelines.

*MedPilot can also be leveraged for comprehensive literature reviews and academic manuscript writing.*

## 🛡️ Core Agent Features

MedPilot goes beyond standard AI wrappers by implementing a robust, production-ready agent architecture:
- **Intelligent Model Routing**: Dynamically routes sub-tasks, agent reasoning, and tool calls to the most appropriate AI models based on task complexity and context, ensuring optimal performance and cost-efficiency.
- **Strict Workspace Sandboxing (Read/Write Separation)**: The agent operates within a highly secure, confined workspace directory. Built-in filesystem and shell execution guards actively block path traversals (e.g., `cd ..`, `../`) and unauthorized updates to external paths, guaranteeing the safety of the host system. Crucially, it employs a sophisticated Read/Write separation model—allowing the agent securely to read system-level built-in skills without permitting any unauthorized edits to framework source code.

## 🚀 Quick Start

**1. Install**
```bash
git clone https://github.com/Project-MedPilot/MedPilot.git
cd MedPilot
pip install -e .
```

**2. Configure**
Run `medpilot onboard` to initialize the `config.json` and your workspace (defaults to `~/.medpilot`).
```bash
medpilot onboard
```

Then, configure your model settings and API keys in `~/.medpilot/config.json`:
```json
{
  "agents": {
    "defaults": {
      "workspace": "~/.medpilot/",
      "model": "",
      "provider": "custom",
      "maxTokens": 8192,
      "temperature": 0.6,
      "maxToolIterations": 40,
      "memoryWindow": 100,
      "reasoningEffort": null
    }
  },
  "providers": {
    "custom": {
      "apiKey": "",
      "apiBase": null,
      "extraHeaders": null
    },
    "azureOpenai": {
      "apiKey": "",
      "apiBase": null,
      "extraHeaders": null
    },
    "anthropic": {
      "apiKey": "",
      "apiBase": null,
      "extraHeaders": null
    }
  }
}
```

## 💻 CLI Commands Reference

MedPilot provides a comprehensive CLI for managing your sessions and configurations:

- **`medpilot onboard`**
  Initialize your configuration file and local workspace directory (`~/.medpilot` by default). This is the first command you should run after installation.

- **`medpilot agent`**
  Start an interactive AI chat session directly in your terminal. You can optionally pass a prompt instantly via the `-m` flag:
  ```bash
  medpilot agent -m "I have 77 MRI Dixon cases. Please set up a 3D classification pipeline to predict expiration vs. inspiration."
  ```

- **`medpilot status`**
  Check the current status of your MedPilot configuration, agent defaults, and workspace environment.

- OAuth providers (e.g., `openai-codex`, `github-copilot`) are now configured directly inside `medpilot onboard`.

- **`medpilot gateway`**
  Launch the background gateway service. This enables external API endpoints and multi-channel traffic. 

### Local Engine Service CLI

For desktop/local deployment workflows, use `medpilot-agent`:

```bash
medpilot-agent install-service
medpilot-agent start
medpilot-agent status
medpilot-agent logs
medpilot-agent doctor
medpilot-agent doctor --export
medpilot-agent upgrade --package medpilot
medpilot-agent stop
medpilot-agent uninstall-service
```

On macOS, `install-service` registers a user LaunchAgent at:

```bash
~/Library/LaunchAgents/com.projectmedpilot.agent.plist
```

On Linux, `install-service` registers a user systemd unit:

```bash
~/.config/systemd/user/medpilot-agent.service
```

On Windows, `install-service` registers service name:

```bash
MedPilotAgent
```

Local engine logs and diagnostics:

- Logs: `~/.medpilot/logs/agent-service.log` (+ rotated files)
- Diagnostics bundles: `~/.medpilot/runtime/diagnostics/`

## 🔗 Release Compatibility Mapping

MedPilot tracks UI/Agent release compatibility in `compatibility.json`.

- `release_train`: release window in `YYYY.MM` format
- `ui`: supported UI minor range (e.g. `0.1.x`)
- `agent`: supported agent minor range (e.g. `0.1.x`)
- `api_contract`: API contract version (e.g. `v1`)
- `min_agent_for_ui`: minimum compatible agent patch version

Validate updates locally before opening a PR:

```bash
python scripts/validate_compatibility.py --file compatibility.json
```

## 📦 Agent Release Pipeline

Tagging `v*` triggers `.github/workflows/agent-release.yml` to:

- build/test the project on Linux/macOS/Windows
- publish `medpilot` package artifacts (wheel/sdist)
- build standalone `medpilot-agent` executables with checksums

Use `.github/workflows/release-train.yml` (`workflow_dispatch`) to validate an
`agent_tag + ui_tag` pair and run smoke checks before announcing a combined release.

## 🏗️ Optional Self-hosted Path

Docker-related files are in `deploy/`:

- `deploy/docker-compose.yml`
- `deploy/Dockerfile`
- `deploy/entrypoint.sh`
- `deploy/.env.example`

Compose services include:
- local build/run services: `medpilot-gateway`, `medpilot-api`, `medpilot-cli`
- self-hosted release services (profile `self-hosted`): `medpilot-agent`, `medpilot-ui`

Operator guide:

- `docs/self-hosted-docker.md`

## 💬 Multi-Channel Deployment (Coming Soon)
Features to deploy MedPilot seamlessly to platforms like Telegram, Discord, Feishu, or Slack to assist your research team in real-time are in active development.

## 🤝 Contributing / CLA

All external contributions require acceptance of the Contributor License Agreement.
See `CLA.md` for details. By submitting a PR, you confirm acceptance of this CLA.

## 🙏 Acknowledgments

The foundational CLI framework of MedPilot is built heavily upon the [medpilot](https://github.com/HKUDS/medpilot). We sincerely thank the HKUDS team for their excellent open-source contribution to the community.

---
*Developed for researchers, by ECNU SKMR Lab.*
