LogalDeveloper/Owlbot
0
Fork 0
Code Issues 13 Actions 1 Packages Releases 3 Wiki Activity

Added a few more final updates for v1.0.0 release. 

- Added package-based installation instructions, replacing git clone workflow.
- Added owlbot init as the config setup method, replacing manual file copy.
- Added Configuration Priority section and CLI-Only Flags table.
- Added note that module settings are config-file-only.
- Added distinction between built-in modules and user modules throughout.
- Added user module override behavior and resolution order to Lifecycle page.
- Added note that the modules directory is exclusively for custom modules.
- Updated modules_dir description to clarify built-in vs user module loading.
- Updated "Included Modules" sidebar heading to "Built-in Modules".
- Updated "Field" to "Attribute" in all reference tables.
- Updated built-in module intro lines to consistent wording.
LogalDeveloper
2026-02-14 15:03:20 -05:00
parent 744faa6532
commit 268e3c839a
11 changed files with 58 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Configuration.md
+22 -8
@@ -2,21 +2,35 @@
All configuration lives in a single YAML file (default `config.yaml`). It has three top-level sections: `owlbot` for core bot settings, `owncast` for the Owncast server connection, and `modules` for per-module settings.
A complete example is provided in `config.example.yaml`. Copy it and adjust for the target environment:
Run `owlbot init` to generate a default `config.yaml` if one does not already exist, then adjust the values for your setup.
```bash
cp config.example.yaml config.yaml
```
## Configuration Priority
## Owlbot Settings
These control the bot's web server, command system, storage, and handler behavior. Owlbot settings can be configured in the config file, environment variables, or CLI flags. When the same setting is specified in multiple places, the highest-priority source wins:
Both `owlbot` and `owncast` settings can be configured in the config file, environment variables, or CLI flags. When the same setting is specified in multiple places, the highest-priority source wins:
1. **CLI flag** (highest)
2. **Environment variable**
3. **Config file**
4. **Default value** (lowest)
Module settings are config-file-only and do not support environment variables or CLI flags.
### CLI-Only Flags
These flags control runtime behavior and exist outside the priority hierarchy. They do not correspond to config file settings.
| Flag | Description |
|------|-------------|
| `-c`, `--config` | Path to config file (default: `config.yaml`). |
| `-v`, `--verbose` | Enable verbose (DEBUG) logging. |
| `--skip-api-check` | Skip Owncast API accessibility checks during startup. |
| `--webhook-path` | Print the full webhook URL from config and exit. |
| `--version` | Print the Owlbot version and exit. |
## Owlbot Settings
These control the bot's web server, command system, storage, and handler behavior.
```yaml
owlbot:
host: "127.0.0.1"
@@ -38,7 +52,7 @@ owlbot:
| `command_prefix` | `"!"` | `OWLBOT_COMMAND_PREFIX` | | Prefix character for chat commands (e.g., `!help`). |
| `handler_timeout` | `30.0` | `OWLBOT_HANDLER_TIMEOUT` | | Maximum seconds a handler can run before it is cancelled and its storage changes rolled back. |
| `storage_dir` | `"data"` | `OWLBOT_STORAGE_DIR` | `-s`, `--storage-dir` | Directory for per-module SQLite database files. Each module gets a `<module_name>.db` file here. Relative paths are resolved from the working directory. |
| `modules_dir` | `"modules"` | `OWLBOT_MODULES_DIR` | `-m`, `--modules` | Directory containing Owlbot modules. Relative paths are resolved from the working directory. |
| `modules_dir` | `"modules"` | `OWLBOT_MODULES_DIR` | `-m`, `--modules` | Directory for user-written modules. Built-in modules are loaded from the package regardless of this setting. Relative paths are resolved from the working directory. |
| `pool_size` | `4` | `OWLBOT_POOL_SIZE` | | Maximum SQLite connections per module in the connection pool. Connections are created lazily as needed. |
| `log_dir` | *(unset)* | `OWLBOT_LOG_DIR` | `-l`, `--log-dir` | Directory for the `owlbot.log` file. When set, logs are written to this directory in addition to stdout. When unset, logs go to stdout only. |
| `webhook_secret` | *(auto-generated)* | `OWLBOT_WEBHOOK_SECRET` | | Secret token for the webhook URL path (`/webhook/<secret>`). A cryptographically secure value is generated on first run and saved back to the config file automatically. |
Custom-Commands.md
+1 -1
@@ -2,7 +2,7 @@
The `custom_commands` module lets moderators create, edit, and delete chat commands at runtime without code changes or restarts. Commands support a placeholder system for dynamic responses.
This module is included with Owlbot and enabled by default.
This is a built-in module that ships with Owlbot and is enabled by default.
## Quick Start
Home.md
+10 -13
@@ -26,15 +26,18 @@ Owlbot's core is a framework for building and running modules. If the included m
### 1. Installation
Clone the repository and install dependencies. This procedure assumes Owlbot is being installed on the same system as Owncast, but this is not a requirement.
Create a directory for Owlbot, initialize a uv project, and install the package. This procedure assumes Owlbot is being installed on the same system as Owncast, but this is not a requirement.
```bash
git clone --branch v1.0.0 https://git.logal.dev/LogalDeveloper/Owlbot.git
cd Owlbot
uv sync
mkdir owlbot && cd owlbot
uv init --no-readme
uv add owlbot \
--default-index https://git.logal.dev/api/packages/LogalDeveloper/pypi/simple/ \
--index https://pypi.org/simple
uv run owlbot init
```
`uv sync` installs the correct Python version, creates a virtual environment, and installs all dependencies. This also installs a set of default modules.
`uv add` installs the correct Python version, creates a virtual environment, and installs all dependencies. `owlbot init` creates a default `config.yaml`. Built-in modules ship with the package and are loaded automatically.
### 2. Access Token
@@ -46,13 +49,7 @@ uv sync
### 3. Configuration
1. Copy the example config:
```bash
cp config.example.yaml config.yaml
```
2. Set the Owncast server URL and the access token from the previous step:
Open `config.yaml` (created by `owlbot init` in step 1) and set the Owncast server URL and the access token from the previous step:
```yaml
owncast:
@@ -102,7 +99,7 @@ stream.logal.dev {
### 6. Running
Start Owlbot from the directory containing your `config.yaml`. `uv run` executes the command inside the project's virtual environment.
Start Owlbot from the directory containing your `config.yaml`.
```bash
uv run owlbot
Modules-Commands.md
+3 -3
@@ -111,10 +111,10 @@ async def setup(ctx: ModuleContext) -> None:
| `ctx.commands.prefix` | Property: the command prefix character (e.g., `"!"`). |
| `ctx.commands.module_commands` | Property: dict of commands registered by this module only (maps name to `CommandInfo`). |
`CommandInfo` has these fields:
`CommandInfo` has these attributes:
| Field | Type | Description |
|-------|------|-------------|
| Attribute | Type | Description |
|-----------|------|-------------|
| `name` | `str` | Canonical command name. |
| `handler` | `CommandHandler` | The handler function. |
| `module_name` | `str` | Module that owns this command. |
Modules-Context.md
+3 -3
@@ -50,10 +50,10 @@ async def on_chat(ctx: EventContext[ChatEvent]) -> None:
await ctx.owncast_client.send_message(f"{user} said: {message}")
```
### Fields
### Attributes
| Field | Type | Description |
|-------|------|-------------|
| Attribute | Type | Description |
|-----------|------|-------------|
| `event` | `E` | The event that triggered this handler (e.g., `ChatEvent`, `UserJoinedEvent`). |
| `module` | `ModuleContext` | The full module context with all services. |
| `propagation_stopped` | `bool` | Whether propagation has been stopped for this event. |
Modules-Events.md
+2 -2
@@ -177,8 +177,8 @@ Each event type maps to a dataclass:
`User` appears in most events and carries identity and permission data:
| Field | Type | Description |
|-------|------|-------------|
| Attribute | Type | Description |
|-----------|------|-------------|
| `id` | `str` | Unique user identifier. |
| `display_name` | `str` | Current display name. |
| `display_color` | `int` | User's chat color. |
Modules-Lifecycle.md
+3 -1
@@ -4,7 +4,9 @@ A module goes through a fixed sequence of stages from startup to shutdown.
## 1. Discovery
On startup, the modules directory is scanned for Python files and packages. Discovered modules with `enabled: false` in the [config](Configuration) are skipped and do not progress beyond this stage.
On startup, built-in modules are discovered from the package, then the user modules directory is scanned for Python files and packages. Discovered modules with `enabled: false` in the [config](Configuration) are skipped and do not progress beyond this stage.
If a user module has the same name as a built-in module, the user module takes precedence and the built-in is skipped. This allows you to replace any built-in module with your own implementation by placing a module with the same name in your modules directory. When an override is detected, Owlbot logs an informational message indicating that the built-in module will be skipped. User modules are resolved in order of package form (`modules/<name>/__init__.py`) first, then single-file form (`modules/<name>.py`).
## 2. Import
Modules.md
+11 -2
@@ -2,11 +2,18 @@
Owlbot is a platform for building features on top of an Owncast server. It ships with a few built-in modules, but the same API they use is available for writing custom ones. The module system handles event parsing, storage, config, and HTTP so the code can focus on the actual logic.
Modules live in the configured modules directory (default `modules/`) and can be single Python files or packages for more complex setups. Owlbot is built on asyncio, so all handlers are `async` functions.
Owlbot has two kinds of modules:
- **Built-in modules** ship inside the installed package and are loaded automatically. Updating Owlbot updates these modules. See the sidebar for the full list.
- **User modules** live in the configured modules directory (default `modules/`).
Both kinds use the same API. Owlbot is built on asyncio, so all handlers are `async` functions.
If a user module has the same name as a built-in module, the user module takes precedence.
## Module Structure
A module can take one of two forms:
A user module can take one of two forms:
**Single file** - one `.py` file in the modules directory. The module name is the filename without `.py`. This is the simplest option and works for most modules.
@@ -27,6 +34,8 @@ modules/
list.html
```
Note that built-in modules do not appear in the user modules directory. The `modules/` directory is exclusively for custom modules.
In both cases the module name determines its config namespace (`modules.<name>` in `config.yaml`), storage file (`data/<name>.db`), logger name (`owlbot.modules.<name>`), and route prefix (`/owlbot/<name>/`).
## Minimal Example
Quotes.md
+1 -1
@@ -2,7 +2,7 @@
The `quotes` module lets moderators save memorable quotes from chat and anyone can recall them at random.
This module is included with Owlbot and enabled by default.
This is a built-in module that ships with Owlbot and is enabled by default.
## Quick Start
Timers.md
+1 -1
@@ -2,7 +2,7 @@
The `timers` module lets moderators create recurring chat messages that fire on a configurable interval with an optional minimum chat activity threshold.
This module is included with Owlbot and enabled by default.
This is a built-in module that ships with Owlbot and is enabled by default.
## Quick Start
_Sidebar.md
+1 -1
@@ -5,7 +5,7 @@
---
**Included Modules**
**Built-in Modules**
* [Custom Commands](Custom-Commands)
* [Quotes](Quotes)
* [Timers](Timers)