Metadata-Version: 2.4
Name: mira-engine
Version: 0.3.0rc6
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-analysis`**: 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 against the **general-purpose agent loop** (no auto-mode, no agent profiles, no task-plan contracts — closest to the upstream nanobot baseline). You can optionally pass a prompt instantly via the `-m` flag:
  ```bash
  mira agent -m "Summarise the README and list the top 3 todos."
  ```

- **`mira research`**
  Start an interactive session against the **research-flavoured agent loop** powering the desktop UI. Adds auto-mode while-loops, agent profiles (which `AGENTS_*.md` to bootstrap), automation stop policies (token / experiment budgets), and task-plan guardrails. Use this for the kind of multi-experiment workflows the desktop app drives:
  ```bash
  mira research \
    --message "I have 77 MRI Dixon cases. Please set up a 3D classification pipeline." \
    --mode auto \
    --profile research \
    --max-tokens 200000 \
    --max-experiments 8 \
    --project-dir ~/projects/dixon-mri
  ```
  Available flags:
  - `--mode / -m` — `manual` or `auto`. `auto` only triggers the auto-continue
    while-loop when running through the **web channel** (i.e. via `mira gateway`
    + the desktop UI); CLI sessions still honour the flag for cached state but
    won't drive multi-round orchestration.
  - `--profile / -p` — `default | engineer | research` (chooses
    `AGENTS.md` / `AGENTS_EG.md` / `AGENTS_RS.md`).
  - `--max-tokens` / `--max-experiments` — automation stop thresholds.
  - `--project-dir` — forwarded as `metadata.project_dir` so guardrails and
    `task_plan.json` lookups resolve correctly.

  Both `mira agent` and `mira research` are thin wrappers around the same chat
  REPL; the only difference is which loop class (`BaseAgentLoop` vs
  `ResearchAgentLoop`) drives `_process_message`. `mira gateway` keeps using
  `ResearchAgentLoop` to match the desktop UI.

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

UI ↔ Agent release compatibility is tracked in the **`mira-ui` repo** (`compatibility.json` there),
since the UI is the consumer of the agent's API and is the side that needs to declare what it works with.

The agent's own contribution to that handshake is the `api_contract` field on `GET /version`,
sourced from `_API_CONTRACT_VERSION` in `mira_engine/channels/ui.py`. Bump that constant
(and only that constant) whenever the wire format changes in a backward-incompatible way.

## 📦 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.*
