roboherd 0.1.2__tar.gz

roboherd-0.1.2/.gitignore

@@ -0,0 +1,5 @@
+herd.toml
+roboherd.toml
+*.whl
+tmp
+bovine_jsonld_cache.sqlite

roboherd-0.1.2/.woodpecker/create_release.yml

@@ -0,0 +1,15 @@
+when:
+  branch: [main]
+  event: [push]
+
+depends_on: ["test"]
+
+steps:
+  create_release:
+    image: helgekr/release_helper
+    environment:
+      CODEBERG_TOKEN: { from_secret: codeberg_token }
+      CODEBERG_OWNER: bovine
+      CODEBERG_REPO: roboherd
+      caddle_drive_connection_string:
+        { from_secret: caddle_drive_connection_string }

roboherd-0.1.2/.woodpecker/publish_docker.yml

@@ -0,0 +1,29 @@
+when:
+  - event: tag
+    branch: main
+
+matrix:
+  PYTHON_VERSION: [3.13]
+
+depends_on: ["publish_pypi"]
+
+steps:
+  publish_docker_latest:
+    image: woodpeckerci/plugin-docker-buildx
+    settings:
+      platforms: linux/amd64,linux/arm64
+      repo: helgekr/roboherd
+      username:
+        from_secret: docker_username
+      password:
+        from_secret: docker_password
+      dockerfile: resources/docker/Dockerfile
+      tags:
+        - latest
+        - ${CI_COMMIT_TAG}
+        - ${CI_COMMIT_TAG}-python${PYTHON_VERSION}
+      build_args:
+        - tag=${CI_COMMIT_TAG}
+        - python_tag=${PYTHON_VERSION}
+    when:
+      - matrix: { PYTHON_VERSION: 3.13 }

roboherd-0.1.2/.woodpecker/publish_pypi.yml

@@ -0,0 +1,13 @@
+when:
+  - event: tag
+    branch: main
+steps:
+  publish_pypi:
+    image: ghcr.io/astral-sh/uv:python3.11-alpine
+    commands:
+      - uv sync --frozen
+      - uv build
+      - uv publish --token  $PYPI_API_KEY
+    environment:
+      PYPI_API_KEY:
+        from_secret: pypi_api_key

roboherd-0.1.2/.woodpecker/test.yml

@@ -0,0 +1,22 @@
+when:
+  - branch: [main]
+    event: [pull_request, push]
+
+steps:
+  build:
+    image: ghcr.io/astral-sh/uv:python3.11-alpine
+    commands:
+      - uv sync --all-extras
+  test_format:
+    image: ghcr.io/astral-sh/uv:python3.11-alpine
+    commands:
+      - uv run ruff format .
+      - uv run ruff check .
+  test_pytest:
+    image: ghcr.io/astral-sh/uv:python3.11-alpine
+    commands:
+      - uv run pytest
+  build_docs:
+    image: ghcr.io/astral-sh/uv:python3.11-alpine
+    commands:
+      - uv run mkdocs build

roboherd-0.1.2/.woodpecker/website.yml

@@ -0,0 +1,16 @@
+when:
+  branch: main
+  event: push
+
+steps:
+  build:
+    image: ghcr.io/astral-sh/uv:python3.11-alpine
+    commands:
+      - uv sync --all-extras
+      - uv run mkdocs build
+  deploy:
+    image: codeberg.org/xfix/plugin-codeberg-pages-deploy:1
+    settings:
+      folder: site
+      ssh_key:
+        from_secret: deploy_ssh_key

roboherd-0.1.2/CHANGES.md

@@ -0,0 +1,11 @@
+# Changes to roboherd
+
+## 0.1.1 ([Milestone](https://codeberg.org/bovine/roboherd/milestone/10245))
+
+- Document environment variable overrides [roboherd#16](https://codeberg.org/bovine/roboherd/issues/16)
+- Add minimal password length (6 characters) for roboherd register
+- Finish documentation [roboherd#6](https://codeberg.org/bovine/roboherd/issues/6)
+- Add a roboherd register command
+- Repair bovine annotations [roboherd#11](https://codeberg.org/bovine/roboherd/issues/11)
+- Enable setting the type of the actor [roboherd#9](https://codeberg.org/bovine/roboherd/issues/9)
+- Enable setting PropertyValues for the cow actor [roboherd#4](https://codeberg.org/bovine/roboherd/issues/4)

roboherd-0.1.2/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: roboherd
+Version: 0.1.2
+Summary: A Fediverse bot framework
+Requires-Python: >=3.11
+Requires-Dist: almabtrieb[mqtt]>=0.1.0a1
+Requires-Dist: apscheduler>=3.11.0
+Requires-Dist: click>=8.1.8
+Requires-Dist: cron-descriptor>=1.4.5
+Requires-Dist: dynaconf>=3.2.6
+Requires-Dist: fast-depends>=2.4.12
+Requires-Dist: tomli-w>=1.1.0
+Requires-Dist: watchfiles>=1.0.4
+Provides-Extra: bovine
+Requires-Dist: bovine>=0.5.15; extra == 'bovine'
+Description-Content-Type: text/markdown
+
+# Roboherd
+
+Roboherd is a framework for building Fediverse bots
+using the [Cattle Drive Protocol](https://bovine.codeberg.page/cattle_grid/cattle_drive/).
+
+For more information, see the [documentation](https://bovine.codeberg.page/roboherd/) or the [repository](https://codeberg.org/bovine/roboherd/).

roboherd-0.1.2/README.md

@@ -0,0 +1,6 @@
+# Roboherd
+
+Roboherd is a framework for building Fediverse bots
+using the [Cattle Drive Protocol](https://bovine.codeberg.page/cattle_grid/cattle_drive/).
+
+For more information, see the [documentation](https://bovine.codeberg.page/roboherd/) or the [repository](https://codeberg.org/bovine/roboherd/).

roboherd-0.1.2/docs/annotations.md

@@ -0,0 +1 @@
+:::roboherd.annotations

roboherd-0.1.2/docs/cli.md

@@ -0,0 +1,14 @@
+# Command Line Interface
+
+The simplest usage of the command line interface is just
+to run
+
+```bash
+roboherd run
+```
+
+::: mkdocs-click
+    :module: roboherd.__main__
+    :command: main
+    :prog_name: roboherd
+    :depth: 2

roboherd-0.1.2/docs/cow.md

@@ -0,0 +1 @@
+:::roboherd.cow

roboherd-0.1.2/docs/herd.md

@@ -0,0 +1 @@
+:::roboherd.herd

roboherd-0.1.2/docs/index.md

@@ -0,0 +1,297 @@
+# Roboherd
+
+Roboherd is a tool to build automated Fediverse actors. It does
+so by connecting to a server through the [Cattle Drive protocol](https://bovine.codeberg.page/cattle_grid/cattle_drive/) protocol. Once you have
+configured the connection, all other tasks can be done using
+python code and a toml configuration file.
+
+## Tour of the functionality
+
+We will now tour how to write bots with Roboherd. We start with
+a basic bot that does nothing except have a profile. Then we will
+start by adding features.
+
+### Basic bot aka how to configure the profile
+
+The configuration file defines the actor by a name and the used python file,
+e.g.
+
+```toml title="roboherd.toml"
+base_url = "https://dev.bovine.social"
+
+[cow.devnull]
+bot = "roboherd.examples.dev_null:bot"
+```
+
+Where the module is defined as
+
+```python title="roboherd/examples/dev_null.py"
+--8<-- "roboherd/examples/dev_null.py"
+```
+
+One should note that the above definition describes the properties of
+the actor. In mastodon this looks like
+
+??? info "Mastodon Screenshot"
+    ![Screen shot of @devnull@dev.bovine.social on mastodon.social](assets/mastodon.png)
+
+??? info "Actor Profile as json"
+    ```json
+    {
+        "attachment": [
+            {
+            "type": "PropertyValue",
+            "name": "Author",
+            "value": "acct:helge@mymath.rocks"
+            },
+            {
+            "type": "PropertyValue",
+            "name": "Source",
+            "value": "https://codeberg.org/bovine/roboherd"
+            }
+        ],
+        "@context": [
+            "https://www.w3.org/ns/activitystreams",
+            "https://w3id.org/security/v1",
+            {
+            "PropertyValue": {
+                "@id": "https://schema.org/PropertyValue",
+                "@context": {
+                "value": "https://schema.org/value",
+                "name": "https://schema.org/name"
+                }
+            }
+            }
+        ],
+        "publicKey": {
+            "id": "https://dev.bovine.social/actor/5Dhr1Bk_E_WuNik_ii0BBQ#legacy-key-1",
+            "owner": "https://dev.bovine.social/actor/5Dhr1Bk_E_WuNik_ii0BBQ",
+            "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvUWtZLOftKTRpNJ+t6Bq\nma6hyRKwcbl6LVuZl+dJ+lAfKpEPRx/2uo/1LkA4mUVEVewyhWMQ8SyIoRayuDqP\njDUaai4mohSg+ReNvmWXD4mgGB7XPc00A4Yk2R/u2hkmu8hWLU7260BTQwmpjsyK\nDG7QWvZYbob1Hyr1QabOpn4tUS3pOl6KqGw8ijNUtAYw22kZl/aZ0v/mk7+V2xhT\nsZbRAC/7o39sFvgGdRHsDwXbJX63aU+qpBc7UX42fdOH9pfmRl5Ps7xCfB1iSlQP\nR4BTGbJB9DOLYlvb2iTqh5cn37VYBxNG3haAv34Q3fBPONOe77CeV1abKTr8/jCG\nsQIDAQAB\n-----END PUBLIC KEY-----\n"
+        },
+        "id": "https://dev.bovine.social/actor/5Dhr1Bk_E_WuNik_ii0BBQ",
+        "type": "Service",
+        "inbox": "https://dev.bovine.social/inbox/nAy02r0LlQJ0WO5ry2-LFA",
+        "outbox": "https://dev.bovine.social/outbox/7JZSBh-1ZXgTXzkSDjGr-A",
+        "followers": "https://dev.bovine.social/followers/90-KDZpuvSif5KAL_TzoYQ",
+        "following": "https://dev.bovine.social/following/jrp61fFlLDA5HcYDN98JRA",
+        "preferredUsername": "devnull",
+        "name": "/dev/null",
+        "summary": "I don't do anything.",
+        "identifiers": [
+            "acct:devnull@dev.bovine.social",
+            "https://dev.bovine.social/actor/5Dhr1Bk_E_WuNik_ii0BBQ"
+        ],
+        "endpoints": {
+            "sharedInbox": "https://dev.bovine.social/shared_inbox"
+        }
+    }
+    ```
+
+Setting me as the author and the source code is contained in [meta_information][roboherd.cow.types.MetaInformation].
+
+```python title="roboherd/examples/meta.py"
+--8<-- "roboherd/examples/meta.py"
+```
+
+!!! todo
+    How to configure a profile picture [roboherd#10](https://codeberg.org/bovine/roboherd/issues/10)
+
+### Posting on startup
+
+By adding
+
+```python
+@bot.startup
+async def startup(publish_object: PublishObject, object_factory: ObjectFactory):
+    await publish_object(object_factory.note(content="Booo! 🐦").as_public().build())
+```
+
+one can post on startup. Here  [PublishObject][roboherd.annotations.PublishObject]
+and [ObjectFactory][roboherd.annotations.bovine.ObjectFactory]
+are annotations that are injected
+through [FastDepends](https://lancetnik.github.io/FastDepends/).
+
+PublishObject depends on the [simple storage extension of cattle_grid](https://bovine.codeberg.page/cattle_grid/extensions/simple_storage/), whereas
+ObjectFactory injects an [ObjectFactory][bovine.activitystreams.object_factory.ObjectFactory] provided by the [bovine](https://bovine.readthedocs.io/en/latest/) library.
+
+???info "Full source"
+    ```python title="roboherd/examples/scarecrow.py"
+    --8<-- "roboherd/examples/scarecrow.py"
+    ```
+
+### Replying to messages
+
+By adding a block such as
+
+```python
+@bot.incoming_create
+async def create(
+    raw: RawData, publish_object: PublishObject, object_factory: ObjectFactory
+):
+    note = (
+        object_factory.reply(
+            raw.get("object"),
+            content=reply_content(raw),
+        )
+        .as_public()
+        .build()
+    )
+
+    await publish_object(note)
+```
+
+one can reply to messages. Here [RawData][roboherd.annotations.RawData] is an annotation that will ensure that the received activity is injected
+through [FastDepends](https://lancetnik.github.io/FastDepends/).
+The same is true for [PublishObject][roboherd.annotations.PublishObject]
+and [ObjectFactory][roboherd.annotations.bovine.ObjectFactory]. The last
+one depends on [bovine](https://bovine.readthedocs.io/en/latest/).
+
+`@bot.incoming_create` indicates that the coroutine `create` should be
+called when a `Create` activity is received. See [roboherd.cow.RoboCow.incoming_create][].
+
+???info "Full source"
+    ```python title="roboherd/examples/json_echo.py"
+    --8<-- "roboherd/examples/json_echo.py"
+    ```
+
+### Scheduling a message
+
+By including
+
+```python
+@bot.cron("42 * * * *")
+async def crow(publisher: PublishObject, object_factory: ObjectFactory):
+    await publisher(
+        object_factory.note(content="cock-a-doodle-doo").as_public().build()
+    )
+```
+
+one can schedule a message to be published at the 42nd minute of every hour.
+Here `"42 * * * *"` is a cron expression.
+
+???info "Full source"
+    ```python title="roboherd/examples/rooster.py"
+    --8<-- "roboherd/examples/rooster.py"
+    ```
+
+!!!tip
+    Alternatively one can write [bots that post on startup](#posting-on-startup) and schedule them using cron.
+
+## Installation
+
+### Using the docker container
+
+By running
+
+```bash
+docker run --rm -ti -v .:/app helgekr/roboherd
+```
+
+you can run a docker container mounting the current directory.
+If the current directory contains a `roboherd.toml` file
+and the appropriate bots, one can run these bots
+by running
+
+```bash
+roboherd run
+```
+
+inside the container. Alternatively, this can be done directly
+by running
+
+```bash
+docker run --rm -v .:/app helgekr/roboherd roboherd run
+```
+
+### Installing roboherd as a python package
+
+To install roboherd with [bovine](https://bovine.readthedocs.io/en/latest/) support run
+
+```bash
+pip install roboherd[bovine]
+```
+
+You are then able to run the roboherd command either by
+
+```bash
+roboherd run
+```
+
+or
+
+```bash
+python -mroboherd run
+```
+
+## Configuration
+
+roboherd has three global configuration variables, e.g.
+
+```toml title="roboherd.toml"
+connection_string = "wss://NAME:PASSWORD@host.example/ws"
+base_url = "https://host.example"
+echo = false
+```
+
+`connection_string` points to the server providing a Cattle Drive endpoint. This connection string currently contains the authentication data.
+
+`base_url` specifies the domain being used to create the bots. With the above configuration file, it would lead to bots with Fediverse handle `acct:BOT-NAME@host.example`. This might be relaxed in the future with
+[roboherd#12](https://codeberg.org/bovine/roboherd/issues/12).
+
+Setting `echo` to `true` will  cause roboherd to print all messages performed through Cattle Drive to the console.
+
+### Overriding the configuration through environment variables
+
+Roboherd uses environment variables starting with `ROBOHERD_`
+as overrides for the configuration. This is done
+through [DynaConf](https://www.dynaconf.com/envvars/). So
+for example
+
+```bash
+ROBOHERD_CONNECTION_STRING=wss://NAME:PASSWORD@other.example/ws\
+    roboherd run
+```
+
+will connect to `other.example` instead of `host.example`.
+
+### Using dev.bovine.social
+
+In order to encourage experimentation, I host an _instance_ at
+[dev.bovine.social](https://dev.bovine.social/), where
+you can quickly sign up and deploy some bots.
+
+Getting start is simple, run
+
+```bash
+docker run --rm -v .:/app helgekr/roboherd\
+    roboherd register --name NAME --fediverse acct:your@handle.example
+```
+
+you will then be prompted for a password.
+Afterwards a `roboherd.toml` file with the appropriate configuration
+will be created. Now, you can write a bot, add it to `roboherd.toml`
+and run it via
+
+```bash
+docker run --rm -v .:/app helgekr/roboherd roboherd run
+```
+
+Please be respectful to the rest of the Fediverse when using
+this service.
+
+### console.bovine.social
+
+After signing up, you can open the
+[cattle_grid console](https://console.bovine.social/)
+and use it to explore your bots. First one has to sign in
+at the top right corner. Afterwards, one should be able
+to see the incoming and outgoing messages by selecting
+the appropriate points in the menu on the left.
+
+!!! warning
+    This still seems somewhat buggy, see
+    [cattle_grid#83](https://codeberg.org/bovine/cattle_grid/issues/83)
+
+The console also allows you to lookup Fediverse
+objects as seen through cattle_grid and perform actions
+manually.

roboherd-0.1.2/docs/util.md

@@ -0,0 +1 @@
+:::roboherd.util

roboherd-0.1.2/mkdocs.yml

@@ -0,0 +1,65 @@
+site_name: roboherd
+watch: [docs, mkdocs.yml, roboherd]
+
+repo_url: https://codeberg.org/bovine/roboherd/
+repo_name: bovine/roboherd
+theme:
+  name: material
+  icon:
+    repo: fontawesome/brands/git-alt
+  palette:
+    - scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - content.code.copy
+    - content.tabs.link
+    - navigation.footer
+    - navigation.sections
+markdown_extensions:
+  - smarty
+  - tables
+  - attr_list
+  - md_in_html
+  - pymdownx.emoji
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - admonition
+  - pymdownx.details
+  - mkdocs-click
+plugins:
+  - search
+  - mkdocstrings:
+      enable_inventory: true
+      handlers:
+        python:
+          inventories:
+            - https://docs.python.org/3/objects.inv
+            - https://docs.pydantic.dev/latest/objects.inv
+            - https://bovine.readthedocs.io/en/latest/objects.inv
+          options:
+            docstring_style: sphinx
+            heading_level: 1
+            show_root_heading: true
+            show_submodules: true
+            extensions:
+              - griffe_fieldz: { include_inherited: true }
+nav:
+  - Home: index.md
+  - "Commang Line Tool": cli.md
+  - "References":
+      - "roboherd.annotations": annotations.md
+      - "roboherd.cow": cow.md
+      - "roboherd.herd": herd.md
+      - "roboherd.util": util.md

roboherd-0.1.2/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "roboherd"
+version = "0.1.2"
+description = "A Fediverse bot framework"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "almabtrieb[mqtt]>=0.1.0a1",
+    "apscheduler>=3.11.0",
+    "click>=8.1.8",
+    "cron-descriptor>=1.4.5",
+    "dynaconf>=3.2.6",
+    "fast-depends>=2.4.12",
+    "tomli-w>=1.1.0",
+    "watchfiles>=1.0.4",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[project.scripts]
+roboherd = "roboherd.__main__:main"
+
+
+[project.optional-dependencies]
+bovine = ["bovine>=0.5.15"]
+
+[tool.uv]
+dev-dependencies = [
+    "pytest>=8.3.4",
+    "pytest-asyncio>=0.25.2",
+    "pytest-watcher>=0.4.3",
+    "mkdocs-material>=9.5.50",
+    "mkdocstrings-python>=1.13.0",
+    "griffe-fieldz>=0.2.1",
+    "mkdocs-click>=0.8.1",
+    "ruff>=0.9.6",
+]
+
+[tool.pytest.ini_options]
+addopts = "--doctest-modules"
+asyncio_mode = "auto"
+log_cli = 1
+log_cli_level = "info"
+doctest_optionflags = "NORMALIZE_WHITESPACE IGNORE_EXCEPTION_DETAIL ELLIPSIS"
+testpaths = ["roboherd/**/*.py"]

roboherd-0.1.2/resources/docker/Dockerfile

@@ -0,0 +1,9 @@
+FROM helgekr/bovine:0.5.18-python3.13
+
+ADD *.whl .
+RUN pip install *.whl
+
+RUN mkdir /app
+WORKDIR /app
+
+CMD ["/bin/sh"]

roboherd-0.1.2/resources/docker/build.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+
+set -eux
+
+uv build --wheel
+mv dist/* resources/docker/
+rm -rf dist
+
+cd resources/docker
+
+docker buildx build --push -t helgekr/roboherd .