Metadata-Version: 2.4
Name: mira-engine
Version: 0.2.0rc10
Summary: A lightweight personal AI assistant framework
Author: mira 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"> Mira

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

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

Powered by an underlying micro-agent framework, Mira 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

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

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

## 🛡️ Core Agent Features

Mira 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/MIRA-Intelligence/mira.git
cd Mira
pip install -e .
```

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

Then, configure your model settings and API keys in `~/.mira/config.json`:
```json
{
  "agents": {
    "defaults": {
      "workspace": "~/.mira/",
      "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

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

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

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

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

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

- **`mira 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 `mira-engine`:

```bash
mira-engine install-service
mira-engine start
mira-engine status
mira-engine logs
mira-engine doctor
mira-engine doctor --export
mira-engine upgrade --package mira
mira-engine stop
mira-engine uninstall-service
```

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

```bash
~/Library/LaunchAgents/com.projectmira.engine.plist
```

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

```bash
~/.config/systemd/user/mira-engine.service
```

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

```bash
MiraEngine
```

Local engine logs and diagnostics:

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

## 🔗 Release Compatibility Mapping

Mira 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 `mira` package artifacts (wheel/sdist)
- build standalone `mira-engine` 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: `mira-gateway`, `mira-api`, `mira-cli`
- self-hosted release services (profile `self-hosted`): `mira-engine`, `mira-ui`

Operator guide:

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

## 💬 Multi-Channel Deployment (Coming Soon)
Features to deploy Mira 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 Mira is built heavily upon the [mira](https://github.com/MIRA-Intelligence/mira). We sincerely thank the HKUDS team for their excellent open-source contribution to the community.

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