meadows-bot 0.1.0__tar.gz

meadows_bot-0.1.0/.env.example

@@ -0,0 +1,10 @@
+# Meadows server URL (the hub this bot connects to)
+MEADOWS_SERVER_URL=http://localhost:8080
+
+# Pre-signed JWT token for this bot.
+# Only the server knows the signing key. Generate this token with:
+#   cd meadows-server && inv bot-jwt --name=<bot_name> --expiry=1y
+MEADOWS_JWT_TOKEN=
+
+# Seconds to wait before disconnecting after an auth error (avoids reconnect loops)
+BOT_AUTH_ERROR_DISCONNECT_DELAY=5

meadows_bot-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+
+# edwh / template
+.env
+.toml
+
+# OS / editors
+*.swp
+*.bak
+.DS_Store
+*.coverage

meadows_bot-0.1.0/Dockerfile

@@ -0,0 +1,11 @@
+FROM python:3.13-slim
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+WORKDIR /app
+COPY pyproject.toml .
+COPY src/ ./src/
+COPY README.md .
+RUN uv pip install --system --no-cache .
+
+CMD ["python", "-c", "import meadows.bot; print('meadows-bot', meadows.bot.__version__)"]

meadows_bot-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: meadows-bot
+Version: 0.1.0
+Summary: MEADOWS bot SDK: BaseBot, LLMBot. Bot-author-facing package with fast quick-start.
+Author: MEADOWS
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: meadows-client
+Requires-Dist: meadows-protocol
+Provides-Extra: dependency-heavy
+Requires-Dist: beautifulsoup4>=4.12.0; extra == 'dependency-heavy'
+Requires-Dist: html2text>=2024.2.26; extra == 'dependency-heavy'
+Requires-Dist: httpx>=0.28.0; extra == 'dependency-heavy'
+Requires-Dist: trafilatura>=2.0.0; extra == 'dependency-heavy'
+Provides-Extra: dev
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff==0.14.9; extra == 'dev'
+Provides-Extra: examples
+Provides-Extra: llm
+Requires-Dist: httpx>=0.28.0; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# meadows-bot
+
+> MEADOWS bot SDK: `BaseBot`, `LLMBot`, and ready-to-use bots. Bot-author-facing package with a fast quick-start.
+> Depends on `meadows-client` (transport) and `meadows-protocol` (shapes). Never imports from `meadows-server`.
+
+## What this package contains
+
+- `base.py` — `BaseBot`: the SDK core. Auth, reconnect, registration, routing are hidden.
+- `llm.py` — `LLMBot`: minimal abstract LLM bot (no provider specifics in the PoC).
+- `examples/echo_bot.py` — the canonical example bot.
+- Ready-to-use bots (lazy-loaded via `from meadows.bot import HelpBot`, etc.):
+  - `help_bot.py` — static help text (`help`, `bots`, `commands`, `groups`, `guide`)
+  - `stats_bot.py` — passive monitoring dashboard (`@stats`, `@stats reset`)
+  - `chat_bot.py` — LLM conversational assistant via Ollama
+  - `fetch_bot.py` — fetches URLs and converts to Markdown
+  - `export_bot.py` — exports a thread to a Markdown file
+  - `rag_bot.py` — video/audio fragment search via RAG API
+  - `slo_bot.py` — Dutch SLO curriculum learning outcome search
+
+## Quick start
+
+A working bot is `BOT_NAME` + `should_handle` + `handle` + `connect()`. That's the whole contract.
+
+Set the `MEADOWS_JWT_TOKEN` env var (generate with `cd meadows-server && inv bot-jwt --name=mybot --expiry=1y`), then:
+
+```python
+from meadows.bot import BaseBot
+
+
+class MyBot(BaseBot):
+    BOT_NAME = "mybot"
+    BOT_DESCRIPTION = "My custom bot"
+    BOT_COMMANDS = [{"name": "greet", "description": "Say hello"}]
+
+    def should_handle(self, command, args):
+        return command == "greet"
+
+    def handle(self, command, args, raw_args, message, thread_context):
+        return f"Hello {args[0] if args else 'user'}!"
+
+
+if __name__ == "__main__":
+    MyBot().connect()
+```
+
+## Install
+
+```bash
+cd meadows-bot
+uv pip install -e .
+
+# With extra bots that need HTTP dependencies
+uv pip install -e ".[examples,dependency-heavy,llm]"
+```
+
+## Test
+
+```bash
+uv run pytest -q
+```
+
+## Included bots
+
+### Production bots (lazy-loaded via `from meadows.bot import HelpBot`)
+
+| Bot | Commands | Deps | Description |
+|-----|----------|------|-------------|
+| `HelpBot` | `help`, `bots`, `commands`, `groups`, `guide` | none | Static help text |
+| `StatsBot` | `@stats`, `@stats reset`, `@stats groups`, `@stats top`, `@stats help` | none | Passive monitoring dashboard; observes all traffic |
+| `ChatBot` | `chat`, `ask`, `vraag`, `praat` | `[llm]` | LLM assistant via Ollama (requires `OLLAMA_URL`) |
+| `FetchBot` | `fetch`, `haal` | `[dependency-heavy]` | Fetches URLs → Markdown |
+| `ExportBot` | `export`, `exporteer` | none | Exports a thread to a Markdown file |
+| `RagBot` | `rag`, `zoek` | none | Video/audio fragment search via RAG API |
+| `SLOBot` | `slo`, `leerdoel` | none | Dutch SLO curriculum learning outcome search |
+
+### Example bots (in `examples/` directory)
+
+| Bot | Description |
+|-----|-------------|
+| `EchoBot` | Canonical example bot — echoes messages back |
+| `SentimentBot` | Label producer: sentiment analysis on all messages |
+| `LabelListenerBot` | Label consumer: alerts on angry sentiment |
+| `EchoServiceBot` | Minimal RPC service (echo) |
+| `MathServiceBot` | RPC service (arithmetic) |
+| `RPCCallerBot` | Demonstrates RPC via labels |
+| `TodoBot` | CRUD demo using interactive forms |
+
+## The protocol boundary
+
+> The system contracts what it itself must understand. What only bots and humans need to understand stays opaque.
+
+This package imports from `meadows.client` (transport) and `meadows.protocol` (shapes), never from `meadows.server`. Server and bot meet only via the protocol declaration. If you find yourself wanting an import from `meadows.server`, something has gone wrong — that belongs in `meadows.protocol` or nowhere.
+
+## Bot-author surface
+
+| What | How |
+|---|---|
+| Identity | `BOT_NAME`, `BOT_DESCRIPTION`, `BOT_COMMANDS`, `BOT_CONTEXT_LIMIT` (class attrs) |
+| Decide | `should_handle(command, args) -> bool` (abstract) |
+| Respond | `handle(command, args, raw_args, message, thread_context) -> str \| None` (abstract) |
+| Start | `connect()` — waits 3s for the server, then connects and blocks |
+| Helpers | `log()`, `get_sender_info()`, `format_help_response()`, `extract_quoted_string()` |
+| Patterns | `register_pattern()`, `unregister_pattern()`, `on_pattern_matched()` (decorator) |
+| Labels | `register_label_subscription()`, `unregister_label_subscription()`, `on_label_assigned()`, `emit_label()` |
+| Forms | `send_form()` — send interactive HTML forms, receive submissions via label subscriptions |
+| RPC | `call_rpc()`, `emit_rpc_request()`, `emit_rpc_response()`, `on_rpc_response()` |
+| History | `fetch_messages()` |
+| Lifecycle hooks | `on_connect()`, `on_disconnect()` (passthrough to client) |
+
+## Defaults and errors are pedagogy
+
+The target user is not a standard Python developer — it's a Dutch teacher (groep 6) working with an AI during a hackathon. Defaults that "just work" and errors in human language matter more than elegance. A bot that fails silently teaches nothing.

meadows_bot-0.1.0/README.md

@@ -0,0 +1,112 @@
+# meadows-bot
+
+> MEADOWS bot SDK: `BaseBot`, `LLMBot`, and ready-to-use bots. Bot-author-facing package with a fast quick-start.
+> Depends on `meadows-client` (transport) and `meadows-protocol` (shapes). Never imports from `meadows-server`.
+
+## What this package contains
+
+- `base.py` — `BaseBot`: the SDK core. Auth, reconnect, registration, routing are hidden.
+- `llm.py` — `LLMBot`: minimal abstract LLM bot (no provider specifics in the PoC).
+- `examples/echo_bot.py` — the canonical example bot.
+- Ready-to-use bots (lazy-loaded via `from meadows.bot import HelpBot`, etc.):
+  - `help_bot.py` — static help text (`help`, `bots`, `commands`, `groups`, `guide`)
+  - `stats_bot.py` — passive monitoring dashboard (`@stats`, `@stats reset`)
+  - `chat_bot.py` — LLM conversational assistant via Ollama
+  - `fetch_bot.py` — fetches URLs and converts to Markdown
+  - `export_bot.py` — exports a thread to a Markdown file
+  - `rag_bot.py` — video/audio fragment search via RAG API
+  - `slo_bot.py` — Dutch SLO curriculum learning outcome search
+
+## Quick start
+
+A working bot is `BOT_NAME` + `should_handle` + `handle` + `connect()`. That's the whole contract.
+
+Set the `MEADOWS_JWT_TOKEN` env var (generate with `cd meadows-server && inv bot-jwt --name=mybot --expiry=1y`), then:
+
+```python
+from meadows.bot import BaseBot
+
+
+class MyBot(BaseBot):
+    BOT_NAME = "mybot"
+    BOT_DESCRIPTION = "My custom bot"
+    BOT_COMMANDS = [{"name": "greet", "description": "Say hello"}]
+
+    def should_handle(self, command, args):
+        return command == "greet"
+
+    def handle(self, command, args, raw_args, message, thread_context):
+        return f"Hello {args[0] if args else 'user'}!"
+
+
+if __name__ == "__main__":
+    MyBot().connect()
+```
+
+## Install
+
+```bash
+cd meadows-bot
+uv pip install -e .
+
+# With extra bots that need HTTP dependencies
+uv pip install -e ".[examples,dependency-heavy,llm]"
+```
+
+## Test
+
+```bash
+uv run pytest -q
+```
+
+## Included bots
+
+### Production bots (lazy-loaded via `from meadows.bot import HelpBot`)
+
+| Bot | Commands | Deps | Description |
+|-----|----------|------|-------------|
+| `HelpBot` | `help`, `bots`, `commands`, `groups`, `guide` | none | Static help text |
+| `StatsBot` | `@stats`, `@stats reset`, `@stats groups`, `@stats top`, `@stats help` | none | Passive monitoring dashboard; observes all traffic |
+| `ChatBot` | `chat`, `ask`, `vraag`, `praat` | `[llm]` | LLM assistant via Ollama (requires `OLLAMA_URL`) |
+| `FetchBot` | `fetch`, `haal` | `[dependency-heavy]` | Fetches URLs → Markdown |
+| `ExportBot` | `export`, `exporteer` | none | Exports a thread to a Markdown file |
+| `RagBot` | `rag`, `zoek` | none | Video/audio fragment search via RAG API |
+| `SLOBot` | `slo`, `leerdoel` | none | Dutch SLO curriculum learning outcome search |
+
+### Example bots (in `examples/` directory)
+
+| Bot | Description |
+|-----|-------------|
+| `EchoBot` | Canonical example bot — echoes messages back |
+| `SentimentBot` | Label producer: sentiment analysis on all messages |
+| `LabelListenerBot` | Label consumer: alerts on angry sentiment |
+| `EchoServiceBot` | Minimal RPC service (echo) |
+| `MathServiceBot` | RPC service (arithmetic) |
+| `RPCCallerBot` | Demonstrates RPC via labels |
+| `TodoBot` | CRUD demo using interactive forms |
+
+## The protocol boundary
+
+> The system contracts what it itself must understand. What only bots and humans need to understand stays opaque.
+
+This package imports from `meadows.client` (transport) and `meadows.protocol` (shapes), never from `meadows.server`. Server and bot meet only via the protocol declaration. If you find yourself wanting an import from `meadows.server`, something has gone wrong — that belongs in `meadows.protocol` or nowhere.
+
+## Bot-author surface
+
+| What | How |
+|---|---|
+| Identity | `BOT_NAME`, `BOT_DESCRIPTION`, `BOT_COMMANDS`, `BOT_CONTEXT_LIMIT` (class attrs) |
+| Decide | `should_handle(command, args) -> bool` (abstract) |
+| Respond | `handle(command, args, raw_args, message, thread_context) -> str \| None` (abstract) |
+| Start | `connect()` — waits 3s for the server, then connects and blocks |
+| Helpers | `log()`, `get_sender_info()`, `format_help_response()`, `extract_quoted_string()` |
+| Patterns | `register_pattern()`, `unregister_pattern()`, `on_pattern_matched()` (decorator) |
+| Labels | `register_label_subscription()`, `unregister_label_subscription()`, `on_label_assigned()`, `emit_label()` |
+| Forms | `send_form()` — send interactive HTML forms, receive submissions via label subscriptions |
+| RPC | `call_rpc()`, `emit_rpc_request()`, `emit_rpc_response()`, `on_rpc_response()` |
+| History | `fetch_messages()` |
+| Lifecycle hooks | `on_connect()`, `on_disconnect()` (passthrough to client) |
+
+## Defaults and errors are pedagogy
+
+The target user is not a standard Python developer — it's a Dutch teacher (groep 6) working with an AI during a hackathon. Defaults that "just work" and errors in human language matter more than elegance. A bot that fails silently teaches nothing.

meadows_bot-0.1.0/captain-hooks/backup_files.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Restic file backup (template convention).
+# $HOST, $URI, $SNAPSHOT are provided by the edwh restic plugin at runtime.
+restic $HOST -r $URI backup ./backups --tag files 2>/dev/null || true

meadows_bot-0.1.0/captain-hooks/restore_files.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Restic file restore (template convention).
+# $HOST, $URI, $SNAPSHOT are provided by the edwh restic plugin at runtime.
+restic $HOST -r $URI restore $SNAPSHOT --target ./ 2>/dev/null || true

meadows_bot-0.1.0/docker-compose.yml

@@ -0,0 +1,23 @@
+networks:
+  meadows:
+    driver: bridge
+  broker:
+    external: true
+    name: broker
+
+services:
+  meadows-bot:
+    build: .
+    image: meadows-bot:latest
+    restart: unless-stopped
+    environment:
+      - MEADOWS_SERVER_URL=${MEADOWS_SERVER_URL:-http://localhost:8080}
+      - MEADOWS_JWT_TOKEN=${MEADOWS_JWT_TOKEN}
+      - BOT_AUTH_ERROR_DISCONNECT_DELAY=${BOT_AUTH_ERROR_DISCONNECT_DELAY:-5}
+    networks:
+      - meadows
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "100m"
+        max-file: "5"

meadows_bot-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "meadows-bot"
+version = "0.1.0"
+description = "MEADOWS bot SDK: BaseBot, LLMBot. Bot-author-facing package with fast quick-start."
+readme = "README.md"
+requires-python = ">=3.12"
+license-expression = "MIT"
+authors = [{ name = "MEADOWS" }]
+dependencies = [
+    "meadows-protocol",
+    "meadows-client",
+    "aiohttp>=3.9.0",
+]
+
+[project.optional-dependencies]
+examples = []
+dependency-heavy = ["httpx>=0.28.0", "trafilatura>=2.0.0", "beautifulsoup4>=4.12.0", "html2text>=2024.2.26"]
+llm = ["httpx>=0.28.0"]
+dev = ["hatch", "pytest>=8.0.0", "pytest-asyncio>=0.23.0", "pytest-cov>=5.0.0", "ruff==0.14.9"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/meadows"]
+
+[tool.uv.sources]
+meadows-protocol = { path = "../meadows-protocol", editable = true }
+meadows-client = { path = "../meadows-client", editable = true }
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["F", "E", "W", "Q", "A", "SIM", "ARG", "PTH", "RUF", "C90", "N", "YTT"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.vommit]
+allow_breaking_bang = true
+allow_breaking_footer = true
+prerelease_token = "rc"
+confirm = true
+
+[tool.vommit.git]
+enabled = true
+origin = "origin"
+branch = "main"
+on_wrong_branch = "error"
+tag_format = "v{version}"
+commit_format = "{version}"
+
+[tool.vommit.changelog]
+enabled = true
+file = "CHANGELOG.md"
+include_prereleases = false
+placeholder = "<!-- next-version-placeholder -->"
+placeholder_regex = "<auto>"
+entry_title_format = "## v{version} ({date:%Y-%m-%d})"
+
+[tool.vommit.changelog.levels]
+break = "Breaking Change{s}"
+feat = "Feature{s}"
+fix = "Fix{es}"
+perf = "Performance"
+docs = "Documentation"
+
+[tool.vommit.pypi]
+enabled = true
+use_keyring = true
+
+[tool.vommit.commands]
+clean = "rm -rf ./dist"
+build = "uv build"
+publish = "../pypi-publish"
+post_publish = ""
+
+[tool.vommit.version_bump_map]
+break = "major"
+feat = "minor"
+fix = "patch"
+perf = "patch"

meadows_bot-0.1.0/src/meadows/bot/__about__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("meadows-bot")

meadows_bot-0.1.0/src/meadows/bot/__init__.py

@@ -0,0 +1,37 @@
+"""MEADOWS bot SDK.
+
+BUSINESS RULE (MEADOWS §5 line 131): Document for AI use, because an AI
+writes alongside humans. The existing bot-development-guide.md is the
+pattern to continue: example-first, copy-pasteable, dense tables.
+"""
+
+from meadows.bot.__about__ import __version__
+from meadows.bot.base import BaseBot
+from meadows.bot.llm import LLMBot
+
+__all__ = ["BaseBot", "LLMBot", "__version__"]
+
+
+def __getattr__(name):
+    if name == "HelpBot":
+        from meadows.bot.help_bot import HelpBot
+        return HelpBot
+    if name == "StatsBot":
+        from meadows.bot.stats_bot import StatsBot
+        return StatsBot
+    if name == "RagBot":
+        from meadows.bot.rag_bot import RagBot
+        return RagBot
+    if name == "SLOBot":
+        from meadows.bot.slo_bot import SLOBot
+        return SLOBot
+    if name == "FetchBot":
+        from meadows.bot.fetch_bot import FetchBot
+        return FetchBot
+    if name == "ExportBot":
+        from meadows.bot.export_bot import ExportBot
+        return ExportBot
+    if name == "ChatBot":
+        from meadows.bot.chat_bot import ChatBot
+        return ChatBot
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")