Metadata-Version: 2.4
Name: soteria-sentinel
Version: 0.1.4
Requires-Dist: pydantic>=2.13.4
Summary: Soteria, she who watches over us.
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# Soteria

She who watches over us.

## Usage

### Installing Soteria

Soteria can be installed via `pip`, `uv` or other similar package managers for PyPI:

```sh
# Using pip
pip install soteria-sentinel

# Using uv
uv add soteria-sentinel
```

### Initializing Soteria

Initialize Soteria with a callback to the function to handle incoming messages:

```py
from soteria_sentinel import Soteria

# Define handler function for incoming messages from Soteria
def handle_message_from_soteria(message: dict):
    # Do whatever you want with Soteria's messages

    # For example,
    temperature = message["value"]
    ...

# Create the Soteria sentinel with callback handler
sentinel = Soteria(on_message=handle_message_from_soteria)

# Start Soteria (this will set up the Unix Domain socket)
sentinel.start()
```

### Monitoring the Situation

Soteria uses her "children" (child processes, built with Rust) to monitor the environment of your trades (e.g., weather changes on Aviation Weather Centre).

You can create a configuration object for a child of Soteria to use. For example, to protect weather trades:

```py
from soteria_sentinel.config.hyperweather import create_hyperweather_config

# Define config object to send to Soteria
config = create_hyperweather_config(
    icao="wsss",
    temperature=31,
    attempt=1,
)

# Get Soteria to spawn a child and start monitoring
sentinel.monitor_situation(config=config)
```

Soteria and her child(ren) will silently run in the background.

### Stopping Soteria

End Soteria's watch (after each signal sent by an Aether client, and at the end of the trading day).

```py
# Stop Soteria's watch
sentinel.stop()
```

Soteria will kill her children and close and clean up the socket connection to her children.

---

Built with ❤️ by Caramel Labs.

