Metadata-Version: 2.4
Name: owa-msgs
Version: 0.5.3
Summary: Core message definitions for Open World Agents
Project-URL: Homepage, https://github.com/open-world-agents/open-world-agents
Project-URL: Repository, https://github.com/open-world-agents/open-world-agents
Project-URL: Documentation, https://open-world-agents.github.io/open-world-agents/
Author: Open World Agents Team
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: annotated-types
Requires-Dist: numpy>=2.3.0
Requires-Dist: opencv-python>=4.11.0
Requires-Dist: owa-core==0.5.3
Requires-Dist: pydantic>=2.10.6
Description-Content-Type: text/markdown

# owa-msgs

Core message definitions for Open World Agents (OWA).

This package provides the standard message types used throughout the OWA ecosystem, organized by domain and registered through Python entry points for automatic discovery.

## Installation

```bash
pip install owa-msgs
```

## Usage

### Using the Message Registry

The recommended way to access messages is through the global registry:

```python
from owa.core import MESSAGES

# Access message classes by type name
KeyboardEvent = MESSAGES['desktop/KeyboardEvent']
MouseEvent = MESSAGES['desktop/MouseEvent']

# Create message instances
event = KeyboardEvent(event_type="press", vk=65)
```

### Direct Imports

You can also import message classes directly:

```python
from owa.msgs.desktop.keyboard import KeyboardEvent
from owa.msgs.desktop.mouse import MouseEvent
```

### Discovering Available Message Types

To see all available message types, use the CLI command:

```bash
owl messages list
```

Or programmatically:

```python
from owa.core import MESSAGES

# List all available message types
for message_type in sorted(MESSAGES.keys()):
    print(f"- {message_type}")

# Get detailed information about a specific message
print(f"Total messages: {len(MESSAGES)}")
```

### Getting Message Details

For detailed information about any message type:

```bash
# Show comprehensive details about a message
owl messages show desktop/KeyboardEvent

# Show with usage examples
owl messages show desktop/KeyboardEvent --example

# Validate all messages
owl messages validate
```

## Message Domains

Messages are organized by domain for better structure:

- **Desktop Domain** (`desktop/*`): Desktop interaction messages including keyboard, mouse, window, and screen capture events

## Extending with Custom Messages

To add custom message types, create a package with entry point registration:

```toml
# pyproject.toml
[project.entry-points."owa.msgs"]
"custom/MyMessage" = "my_package.messages:MyMessage"
```

## Schema and Compatibility

All messages implement the `BaseMessage` interface from `owa.core.message` and are compatible with the OWAMcap format for data recording and playback.
