# MO API SDK
**`mo-api-sdk`** is the official SDK for building backend/API plugins for the [**Multimodal Observer (MOo)**](https://github.com/MultimodalObserver-2/mo) application.
It provides core interfaces, utilities, and tools to ensure your plugins are fully compatible with the MO backend runtime.
## 🚀 Features
- Exposes base interfaces and utilities for building valid MO-compatible plugins.
- Includes CLI tools to assist in plugin development and packaging.
- Current available commands:
- `create-mop`: interactive template generator for starting new MO plugin projects.
- `build-mop`: packages a plugin directory into a `.zip` file ready for use in MO.
- `test-capture-mop`: simulate and test your MO CapturePlugin with real or simulated input events, including coverage reporting.
## 🛠️ Usage
### Importing Base APIs
Import all base classes and utilities **directly from** `mo` to ensure compatibility with the MO backend:
```python
from mo.core.plugin import Plugin
from mo.core import Properties, PropertySelectOption
# Or import other base classes, helpers, or constants as needed
```
### Building Your Plugin
- Implement your plugin as a subclass of the provided base interfaces (`Plugin`, `CapturePlugin`, etc).
- Use the provided tools to define properties, validate configuration, and interact with the MO runtime.
- Add your `metadata.json` and all required files in your plugin directory.
### 📦 Example: Minimal Capture Plugin
```python
from mo.modules.capture import CapturePlugin, CaptureData
class MyCapture(CapturePlugin):
def load(self):
# Initialize plugin
pass
def unload(self):
# Cleanup resources
pass
# ...implement all required methods...
```
## 🔧 CLI Tools
The SDK provides a command-line tool for packaging your plugin:
### `create-mop`
Start a new MO plugin project using the interactive template generator:
```bash
create-mop
```
- Prompts you for the essential details and generates a full plugin project structure.
- Includes ready-to-edit `metadata.json`, code skeletons, property templates, icon, and locale folders.
You can also use command-line flags:
create-mop --plugin-id my-plugin --publisher-id my-lab --venv
---
### `build-mop`
Package your plugin for MO by running:
```bash
build-mop
```
This will:
- Validate your `metadata.json` and all entry points.
- Package all necessary files into a versioned `.zip` in the `dist/` directory.
- Ensure all dependencies are included in the package.
> **Note:**
> If you encounter issues with automatic dependency detection, you can provide your own `requirements.txt` file and specify it using the `-r` or `--requirements` flag when running `build-mop`.
---
### `test-capture-mop`
Test your MO CapturePlugin implementation in isolation, with real or simulated input, and (optionally) get a code coverage report of your plugin.
```bash
test-capture-mop
```
**Key features:**
- Runs your capture plugin just as MO would, and writes output to a timestamped file.
- Lets you simulate external events (like mouse or keyboard) during the test using the --simulate option.
- Supports pause/resume testing, custom flush interval, settings injection, and coverage analysis of your plugin's code.
- You can also import the `CapturePluginTester` class in your own Python test files and run programmatic tests, not just from the CLI.
**Common options:**
| Option / Short | Description |
| ----------------------------- | --------------------------------------------------------------- |
| `--plugin-dir PATH` | Path to the plugin root or metadata.json (default: `./`) |
| `--pause`, `-p` | Simulate pause and resume during test |
| `--duration SECONDS`, `-d` | Duration of the test (default: `3.0`) |
| `--flush SECONDS`, `-f` | Data flush interval (default: `1.0`) |
| `--settings FILE` | Path to settings file (JSON) |
| `--out DIR`, `-o` | Output folder for results |
| `--prefix STRING` | Prefix for output file name |
| `--quiet`, `-q` | Only show warnings and errors |
| `--verbose`, `-v` | Show detailed log output |
| `--simulate ENTRYPOINT`, `-s` | Python entrypoint for a simulation function (e.g. `my.mod:run`) |
| `--coverage`, `-c` | Measure coverage for just the plugin's entrypoint code |
**Examples:**
```bash
# Basic usage
test-capture-mop --plugin-dir ./my_plugin
```
```bash
# With keyboard simulation (run function in ./tests/sim_keyboard.py)
test-capture-mop -s tests.sim_keyboard:run
```
```bash
# Run for 10 seconds, with pause/resume, and coverage
test-capture-mop -d 10 -p -c
```
```bash
# Custom settings and output folder
test-capture-mop --settings settings.json -o ./test-results
```
To see a coverage report after running with --coverage, just run:
```bash
coverage report
```
Or for a HTML report:
```bash
coverage html
```
Raw data
{
"_id": null,
"home_page": "https://github.com/MultimodalObserver-2/mo-api-sdk",
"name": "mo-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.12",
"maintainer_email": null,
"keywords": "sdk, mop, cli, tools, MOo, MO, plugin, multimodal, observer",
"author": "Mat\u00edas Figueroa Contreras",
"author_email": "matias.figueroa.c@usach.cl",
"download_url": "https://files.pythonhosted.org/packages/0c/51/649771b2fe01ddf19e96f5a43d750dacfd0e39cb5abce707f6ddf4351671/mo_sdk-1.0.0.tar.gz",
"platform": null,
"description": "# MO API SDK\n\n**`mo-api-sdk`** is the official SDK for building backend/API plugins for the [**Multimodal Observer (MOo)**](https://github.com/MultimodalObserver-2/mo) application. \nIt provides core interfaces, utilities, and tools to ensure your plugins are fully compatible with the MO backend runtime.\n\n\n## \ud83d\ude80 Features\n\n- Exposes base interfaces and utilities for building valid MO-compatible plugins.\n- Includes CLI tools to assist in plugin development and packaging.\n- Current available commands:\n - `create-mop`: interactive template generator for starting new MO plugin projects.\n - `build-mop`: packages a plugin directory into a `.zip` file ready for use in MO.\n - `test-capture-mop`: simulate and test your MO CapturePlugin with real or simulated input events, including coverage reporting.\n\n## \ud83d\udee0\ufe0f Usage\n\n### Importing Base APIs\n\nImport all base classes and utilities **directly from** `mo` to ensure compatibility with the MO backend:\n```python\n from mo.core.plugin import Plugin\n from mo.core import Properties, PropertySelectOption\n # Or import other base classes, helpers, or constants as needed\n```\n\n### Building Your Plugin\n\n- Implement your plugin as a subclass of the provided base interfaces (`Plugin`, `CapturePlugin`, etc).\n- Use the provided tools to define properties, validate configuration, and interact with the MO runtime.\n- Add your `metadata.json` and all required files in your plugin directory.\n\n\n### \ud83d\udce6 Example: Minimal Capture Plugin\n\n```python\n from mo.modules.capture import CapturePlugin, CaptureData\n\n class MyCapture(CapturePlugin):\n def load(self):\n # Initialize plugin\n pass\n\n def unload(self):\n # Cleanup resources\n pass\n\n # ...implement all required methods...\n```\n\n\n## \ud83d\udd27 CLI Tools\n\nThe SDK provides a command-line tool for packaging your plugin:\n\n\n### `create-mop`\n\nStart a new MO plugin project using the interactive template generator:\n```bash\n create-mop\n```\n\n- Prompts you for the essential details and generates a full plugin project structure.\n- Includes ready-to-edit `metadata.json`, code skeletons, property templates, icon, and locale folders.\n\nYou can also use command-line flags:\n\n create-mop --plugin-id my-plugin --publisher-id my-lab --venv\n\n---\n\n### `build-mop`\n\nPackage your plugin for MO by running:\n\n```bash\n build-mop\n```\n\nThis will:\n\n- Validate your `metadata.json` and all entry points.\n- Package all necessary files into a versioned `.zip` in the `dist/` directory.\n- Ensure all dependencies are included in the package.\n\n> **Note:** \n> If you encounter issues with automatic dependency detection, you can provide your own `requirements.txt` file and specify it using the `-r` or `--requirements` flag when running `build-mop`.\n\n---\n\n### `test-capture-mop`\n\nTest your MO CapturePlugin implementation in isolation, with real or simulated input, and (optionally) get a code coverage report of your plugin.\n\n```bash\ntest-capture-mop\n```\n\n**Key features:**\n- Runs your capture plugin just as MO would, and writes output to a timestamped file.\n- Lets you simulate external events (like mouse or keyboard) during the test using the --simulate option.\n- Supports pause/resume testing, custom flush interval, settings injection, and coverage analysis of your plugin's code.\n- You can also import the `CapturePluginTester` class in your own Python test files and run programmatic tests, not just from the CLI.\n\n**Common options:**\n\n| Option / Short | Description |\n| ----------------------------- | --------------------------------------------------------------- |\n| `--plugin-dir PATH` | Path to the plugin root or metadata.json (default: `./`) |\n| `--pause`, `-p` | Simulate pause and resume during test |\n| `--duration SECONDS`, `-d` | Duration of the test (default: `3.0`) |\n| `--flush SECONDS`, `-f` | Data flush interval (default: `1.0`) |\n| `--settings FILE` | Path to settings file (JSON) |\n| `--out DIR`, `-o` | Output folder for results |\n| `--prefix STRING` | Prefix for output file name |\n| `--quiet`, `-q` | Only show warnings and errors |\n| `--verbose`, `-v` | Show detailed log output |\n| `--simulate ENTRYPOINT`, `-s` | Python entrypoint for a simulation function (e.g. `my.mod:run`) |\n| `--coverage`, `-c` | Measure coverage for just the plugin's entrypoint code |\n\n\n**Examples:**\n\n```bash\n # Basic usage\n test-capture-mop --plugin-dir ./my_plugin\n```\n\n```bash\n # With keyboard simulation (run function in ./tests/sim_keyboard.py)\n test-capture-mop -s tests.sim_keyboard:run\n```\n\n```bash\n # Run for 10 seconds, with pause/resume, and coverage\n test-capture-mop -d 10 -p -c\n```\n\n```bash\n # Custom settings and output folder\n test-capture-mop --settings settings.json -o ./test-results\n```\n\nTo see a coverage report after running with --coverage, just run:\n```bash\n coverage report\n```\n\nOr for a HTML report:\n```bash\n coverage html\n```\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "Official SDK for building Multimodal Observer (MOo) plugins.",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/MultimodalObserver-2/mo-api-sdk",
"Repository": "https://github.com/MultimodalObserver-2/mo-api-sdk"
},
"split_keywords": [
"sdk",
" mop",
" cli",
" tools",
" moo",
" mo",
" plugin",
" multimodal",
" observer"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eadb633e1d127aede195f6f5225d101a86d3022ad0b61358e1cc1572d9fd2dfa",
"md5": "50d0b8e8115f92057450e3afe0eb4f8d",
"sha256": "8c7432e6c2915f7d0b303fc8549facda1dad3c0f4b94ec001c59c44fa2c95852"
},
"downloads": -1,
"filename": "mo_sdk-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "50d0b8e8115f92057450e3afe0eb4f8d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.12",
"size": 36464,
"upload_time": "2025-09-07T00:47:19",
"upload_time_iso_8601": "2025-09-07T00:47:19.031148Z",
"url": "https://files.pythonhosted.org/packages/ea/db/633e1d127aede195f6f5225d101a86d3022ad0b61358e1cc1572d9fd2dfa/mo_sdk-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0c51649771b2fe01ddf19e96f5a43d750dacfd0e39cb5abce707f6ddf4351671",
"md5": "a63f66d810fba63f19add76551f101fc",
"sha256": "f217b9074c5d7243f19ed249463efb06370c7698d97e37c663bf6926b013491b"
},
"downloads": -1,
"filename": "mo_sdk-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "a63f66d810fba63f19add76551f101fc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.12",
"size": 29181,
"upload_time": "2025-09-07T00:47:20",
"upload_time_iso_8601": "2025-09-07T00:47:20.656468Z",
"url": "https://files.pythonhosted.org/packages/0c/51/649771b2fe01ddf19e96f5a43d750dacfd0e39cb5abce707f6ddf4351671/mo_sdk-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-07 00:47:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MultimodalObserver-2",
"github_project": "mo-api-sdk",
"github_not_found": true,
"lcname": "mo-sdk"
}
JSON
