argus-scout 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- argus_scout-0.1.0/.copier-answers.yml +22 -0
- argus_scout-0.1.0/.dockerignore +19 -0
- argus_scout-0.1.0/.github/workflows/ci.yml +27 -0
- argus_scout-0.1.0/.github/workflows/docs.yml +25 -0
- argus_scout-0.1.0/.github/workflows/quickstart.yml +25 -0
- argus_scout-0.1.0/.github/workflows/release.yml +163 -0
- argus_scout-0.1.0/.github/workflows/suite.yml +14 -0
- argus_scout-0.1.0/.gitignore +12 -0
- argus_scout-0.1.0/.suite-rules-baseline.json +8 -0
- argus_scout-0.1.0/CLAUDE.md +179 -0
- argus_scout-0.1.0/Dockerfile +30 -0
- argus_scout-0.1.0/LICENSE +21 -0
- argus_scout-0.1.0/Makefile +33 -0
- argus_scout-0.1.0/PKG-INFO +181 -0
- argus_scout-0.1.0/README.md +134 -0
- argus_scout-0.1.0/deploy/quickstart/README.md +144 -0
- argus_scout-0.1.0/deploy/quickstart/compose.gpu.yaml +16 -0
- argus_scout-0.1.0/deploy/quickstart/compose.yaml +127 -0
- argus_scout-0.1.0/deploy/quickstart/config/.env.example +10 -0
- argus_scout-0.1.0/deploy/quickstart/config/.gitignore +6 -0
- argus_scout-0.1.0/deploy/quickstart/config/approvals.yaml +33 -0
- argus_scout-0.1.0/deploy/quickstart/config/heartbeat.yaml +51 -0
- argus_scout-0.1.0/deploy/quickstart/config/scout.yaml +67 -0
- argus_scout-0.1.0/deploy/quickstart/config/signals.yaml +328 -0
- argus_scout-0.1.0/deploy/quickstart/config/tariff.yaml +44 -0
- argus_scout-0.1.0/deploy/quickstart/prometheus.yml +21 -0
- argus_scout-0.1.0/docs/api.md +157 -0
- argus_scout-0.1.0/docs/channels.md +472 -0
- argus_scout-0.1.0/docs/cli.md +326 -0
- argus_scout-0.1.0/docs/config.md +443 -0
- argus_scout-0.1.0/docs/narrative.md +142 -0
- argus_scout-0.1.0/docs/operations.md +128 -0
- argus_scout-0.1.0/docs/signals.md +190 -0
- argus_scout-0.1.0/docs/sources.md +202 -0
- argus_scout-0.1.0/examples/approvals.yaml +33 -0
- argus_scout-0.1.0/examples/heartbeat.yaml +51 -0
- argus_scout-0.1.0/examples/persona.yaml +34 -0
- argus_scout-0.1.0/examples/signals.yaml +328 -0
- argus_scout-0.1.0/examples/tariff.yaml +44 -0
- argus_scout-0.1.0/gpu-tenant.yaml +33 -0
- argus_scout-0.1.0/pyproject.toml +80 -0
- argus_scout-0.1.0/src/argus_scout/__init__.py +16 -0
- argus_scout-0.1.0/src/argus_scout/_version.py +24 -0
- argus_scout-0.1.0/src/argus_scout/approvals.py +339 -0
- argus_scout-0.1.0/src/argus_scout/budget.py +315 -0
- argus_scout-0.1.0/src/argus_scout/channels/__init__.py +109 -0
- argus_scout-0.1.0/src/argus_scout/channels/audio.py +268 -0
- argus_scout-0.1.0/src/argus_scout/channels/base.py +252 -0
- argus_scout-0.1.0/src/argus_scout/channels/dispatcher.py +338 -0
- argus_scout-0.1.0/src/argus_scout/channels/echo.py +303 -0
- argus_scout-0.1.0/src/argus_scout/channels/mask.py +476 -0
- argus_scout-0.1.0/src/argus_scout/channels/redeliver.py +106 -0
- argus_scout-0.1.0/src/argus_scout/channels/registry.py +197 -0
- argus_scout-0.1.0/src/argus_scout/channels/snapcast.py +382 -0
- argus_scout-0.1.0/src/argus_scout/channels/text.py +120 -0
- argus_scout-0.1.0/src/argus_scout/channels/webhook.py +186 -0
- argus_scout-0.1.0/src/argus_scout/cli.py +466 -0
- argus_scout-0.1.0/src/argus_scout/config.py +802 -0
- argus_scout-0.1.0/src/argus_scout/configdoc.py +503 -0
- argus_scout-0.1.0/src/argus_scout/cycles.py +388 -0
- argus_scout-0.1.0/src/argus_scout/engine.py +309 -0
- argus_scout-0.1.0/src/argus_scout/events.py +113 -0
- argus_scout-0.1.0/src/argus_scout/examples/env.example +25 -0
- argus_scout-0.1.0/src/argus_scout/examples/scout.yaml +176 -0
- argus_scout-0.1.0/src/argus_scout/gpu.py +135 -0
- argus_scout-0.1.0/src/argus_scout/heartbeat.py +330 -0
- argus_scout-0.1.0/src/argus_scout/inbox.py +331 -0
- argus_scout-0.1.0/src/argus_scout/llm.py +355 -0
- argus_scout-0.1.0/src/argus_scout/memory.py +125 -0
- argus_scout-0.1.0/src/argus_scout/narrative.py +591 -0
- argus_scout-0.1.0/src/argus_scout/persona.py +154 -0
- argus_scout-0.1.0/src/argus_scout/prometheus.py +260 -0
- argus_scout-0.1.0/src/argus_scout/py.typed +0 -0
- argus_scout-0.1.0/src/argus_scout/recommendations.py +171 -0
- argus_scout-0.1.0/src/argus_scout/scheduler.py +323 -0
- argus_scout-0.1.0/src/argus_scout/server/__init__.py +0 -0
- argus_scout-0.1.0/src/argus_scout/server/app.py +195 -0
- argus_scout-0.1.0/src/argus_scout/server/deps.py +22 -0
- argus_scout-0.1.0/src/argus_scout/server/guards.py +394 -0
- argus_scout-0.1.0/src/argus_scout/server/metrics.py +173 -0
- argus_scout-0.1.0/src/argus_scout/server/routes/__init__.py +32 -0
- argus_scout-0.1.0/src/argus_scout/server/routes/events.py +116 -0
- argus_scout-0.1.0/src/argus_scout/server/routes/models.py +59 -0
- argus_scout-0.1.0/src/argus_scout/server/routes/reads.py +154 -0
- argus_scout-0.1.0/src/argus_scout/server/routes/recommendations.py +126 -0
- argus_scout-0.1.0/src/argus_scout/severity.py +29 -0
- argus_scout-0.1.0/src/argus_scout/signals.py +660 -0
- argus_scout-0.1.0/src/argus_scout/sources/__init__.py +30 -0
- argus_scout-0.1.0/src/argus_scout/sources/base.py +81 -0
- argus_scout-0.1.0/src/argus_scout/sources/json_poll.py +265 -0
- argus_scout-0.1.0/src/argus_scout/sources/registry.py +191 -0
- argus_scout-0.1.0/src/argus_scout/sources/webhook.py +114 -0
- argus_scout-0.1.0/src/argus_scout/store/__init__.py +31 -0
- argus_scout-0.1.0/src/argus_scout/store/base.py +303 -0
- argus_scout-0.1.0/src/argus_scout/store/sqlite.py +962 -0
- argus_scout-0.1.0/src/argus_scout/tariff.py +228 -0
- argus_scout-0.1.0/src/argus_scout/tariff_rules.py +565 -0
- argus_scout-0.1.0/tests/api_helpers.py +47 -0
- argus_scout-0.1.0/tests/conftest.py +20 -0
- argus_scout-0.1.0/tests/test_api.py +389 -0
- argus_scout-0.1.0/tests/test_api_guards.py +297 -0
- argus_scout-0.1.0/tests/test_api_hardening.py +474 -0
- argus_scout-0.1.0/tests/test_approvals.py +201 -0
- argus_scout-0.1.0/tests/test_budget.py +93 -0
- argus_scout-0.1.0/tests/test_budget_store.py +178 -0
- argus_scout-0.1.0/tests/test_channels.py +782 -0
- argus_scout-0.1.0/tests/test_cli.py +192 -0
- argus_scout-0.1.0/tests/test_config.py +270 -0
- argus_scout-0.1.0/tests/test_configdoc.py +29 -0
- argus_scout-0.1.0/tests/test_dockerfile.py +74 -0
- argus_scout-0.1.0/tests/test_docs_publishable.py +113 -0
- argus_scout-0.1.0/tests/test_echo.py +404 -0
- argus_scout-0.1.0/tests/test_engine.py +369 -0
- argus_scout-0.1.0/tests/test_gpu.py +233 -0
- argus_scout-0.1.0/tests/test_heartbeat.py +151 -0
- argus_scout-0.1.0/tests/test_inbox.py +166 -0
- argus_scout-0.1.0/tests/test_llm.py +172 -0
- argus_scout-0.1.0/tests/test_memory.py +86 -0
- argus_scout-0.1.0/tests/test_metrics.py +152 -0
- argus_scout-0.1.0/tests/test_narrative.py +278 -0
- argus_scout-0.1.0/tests/test_persona.py +46 -0
- argus_scout-0.1.0/tests/test_prometheus.py +279 -0
- argus_scout-0.1.0/tests/test_quickstart.py +89 -0
- argus_scout-0.1.0/tests/test_recommendation_races.py +222 -0
- argus_scout-0.1.0/tests/test_redeliver.py +262 -0
- argus_scout-0.1.0/tests/test_scheduler.py +543 -0
- argus_scout-0.1.0/tests/test_signals.py +303 -0
- argus_scout-0.1.0/tests/test_smoke.py +8 -0
- argus_scout-0.1.0/tests/test_sources.py +454 -0
- argus_scout-0.1.0/tests/test_status_reports.py +332 -0
- argus_scout-0.1.0/tests/test_store.py +441 -0
- argus_scout-0.1.0/tests/test_tariff.py +116 -0
- argus_scout-0.1.0/tests/test_tariff_rules.py +437 -0
- argus_scout-0.1.0/tests/test_voice_channels.py +793 -0
- argus_scout-0.1.0/tests/test_workflows.py +50 -0
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Managed by Copier — do not edit by hand.
|
|
2
|
+
# Run `copier update` in this repo to pull template changes.
|
|
3
|
+
_commit: aec30cd
|
|
4
|
+
_src_path: gh:smk762/argus-pkg-template
|
|
5
|
+
author: smk762
|
|
6
|
+
brand_mark: false
|
|
7
|
+
cli_name: argus-scout
|
|
8
|
+
description: 'Homelab intelligence for the Argus suite: reads your telemetry, reasons
|
|
9
|
+
about it, and reports back with briefings and recommendations it never acts on'
|
|
10
|
+
dockerfile: Dockerfile
|
|
11
|
+
github_owner: smk762
|
|
12
|
+
has_cli: true
|
|
13
|
+
has_server: true
|
|
14
|
+
image_name: argus-scout
|
|
15
|
+
package_name: argus_scout
|
|
16
|
+
post_test: ''
|
|
17
|
+
project_name: argus-scout
|
|
18
|
+
python_min: '3.12'
|
|
19
|
+
ruff_pin: 0.15.16
|
|
20
|
+
test_extras: dev
|
|
21
|
+
version_build_arg: false
|
|
22
|
+
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# NOTE: .git is deliberately *not* ignored -- hatch-vcs reads the version from
|
|
2
|
+
# git history at build time. Set `version_build_arg` if you want it excluded.
|
|
3
|
+
.github
|
|
4
|
+
.venv
|
|
5
|
+
venv
|
|
6
|
+
dist
|
|
7
|
+
build
|
|
8
|
+
*.egg-info
|
|
9
|
+
**/__pycache__
|
|
10
|
+
**/*.py[cod]
|
|
11
|
+
.pytest_cache
|
|
12
|
+
.ruff_cache
|
|
13
|
+
.mypy_cache
|
|
14
|
+
.coverage
|
|
15
|
+
htmlcov
|
|
16
|
+
# The quickstart's secrets and runtime state (deploy/quickstart/config) stay out of the image.
|
|
17
|
+
**/.env
|
|
18
|
+
deploy/quickstart/config/scout.db*
|
|
19
|
+
deploy/quickstart/config/scout-reports.log*
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [dev, main]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [dev, main]
|
|
8
|
+
|
|
9
|
+
concurrency:
|
|
10
|
+
group: ci-${{ github.ref }}
|
|
11
|
+
cancel-in-progress: true
|
|
12
|
+
|
|
13
|
+
permissions:
|
|
14
|
+
contents: read
|
|
15
|
+
|
|
16
|
+
jobs:
|
|
17
|
+
ci:
|
|
18
|
+
uses: smk762/argus-ci/.github/workflows/python-ci.yml@v1
|
|
19
|
+
with:
|
|
20
|
+
ruff-version: "0.15.16"
|
|
21
|
+
test-extras: "dev"
|
|
22
|
+
python-versions: '["3.12", "3.13"]'
|
|
23
|
+
|
|
24
|
+
suite-rules:
|
|
25
|
+
# argus-ci suite rules: lint rules that each eliminate a finding class. New violations fail;
|
|
26
|
+
# existing ones are in .suite-rules-baseline.json, which may only shrink.
|
|
27
|
+
uses: smk762/argus-ci/.github/workflows/suite-rules.yml@v1
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
name: Docs
|
|
2
|
+
|
|
3
|
+
# Published docs (README.md + docs/**/*.md) are imported by the demo UIs at dev
|
|
4
|
+
# HEAD, so check them on every push to dev as well as on tags.
|
|
5
|
+
# docs/cli.md is generated: regenerate it with `make docs` after changing the CLI.
|
|
6
|
+
|
|
7
|
+
on:
|
|
8
|
+
push:
|
|
9
|
+
branches: [dev, main]
|
|
10
|
+
tags: ["v*"]
|
|
11
|
+
pull_request:
|
|
12
|
+
branches: [dev, main]
|
|
13
|
+
|
|
14
|
+
permissions:
|
|
15
|
+
contents: read
|
|
16
|
+
|
|
17
|
+
jobs:
|
|
18
|
+
docs:
|
|
19
|
+
uses: smk762/argus-ci/.github/workflows/docs-check.yml@v1
|
|
20
|
+
with:
|
|
21
|
+
cli-module: argus_scout.cli
|
|
22
|
+
cli-name: argus-scout
|
|
23
|
+
install-extras: cli
|
|
24
|
+
secrets:
|
|
25
|
+
denylist: ${{ secrets.DOCS_DENYLIST }} # optional; unset = no private terms
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
name: Quickstart
|
|
2
|
+
|
|
3
|
+
# Not from argus-pkg-template: this repo's own check that deploy/quickstart still parses as compose.
|
|
4
|
+
# tests/test_quickstart.py (run by CI) checks the config and that its policy files match examples/.
|
|
5
|
+
|
|
6
|
+
on:
|
|
7
|
+
push:
|
|
8
|
+
branches: [dev, main]
|
|
9
|
+
pull_request:
|
|
10
|
+
branches: [dev, main]
|
|
11
|
+
|
|
12
|
+
permissions:
|
|
13
|
+
contents: read
|
|
14
|
+
|
|
15
|
+
jobs:
|
|
16
|
+
compose-config:
|
|
17
|
+
runs-on: ubuntu-latest
|
|
18
|
+
steps:
|
|
19
|
+
- uses: actions/checkout@v7
|
|
20
|
+
- name: docker compose config
|
|
21
|
+
working-directory: deploy/quickstart
|
|
22
|
+
run: |
|
|
23
|
+
docker compose version
|
|
24
|
+
docker compose -f compose.yaml config -q
|
|
25
|
+
docker compose -f compose.yaml -f compose.gpu.yaml config -q
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
name: Release to PyPI
|
|
2
|
+
|
|
3
|
+
# Top-level (non-reusable) on purpose: PyPI trusted publishing cannot run inside
|
|
4
|
+
# a reusable workflow. Keep this file in sync across the suite via `copier update`.
|
|
5
|
+
|
|
6
|
+
on:
|
|
7
|
+
push:
|
|
8
|
+
tags: ["v*"]
|
|
9
|
+
# Sent by argus-cortex's release workflow. The image installs argus-cortex
|
|
10
|
+
# from the pyproject range at build time, so rebuilding the newest release's
|
|
11
|
+
# image is how a new cortex reaches it. Only the image jobs run: PyPI and the
|
|
12
|
+
# GitHub Release for that tag already exist.
|
|
13
|
+
repository_dispatch:
|
|
14
|
+
types: [cortex-released]
|
|
15
|
+
|
|
16
|
+
permissions:
|
|
17
|
+
contents: read
|
|
18
|
+
id-token: write
|
|
19
|
+
|
|
20
|
+
jobs:
|
|
21
|
+
build:
|
|
22
|
+
# Not on a cortex dispatch, so the PyPI and Release jobs that chain off it
|
|
23
|
+
# skip too.
|
|
24
|
+
if: github.event_name == 'push'
|
|
25
|
+
runs-on: ubuntu-latest
|
|
26
|
+
steps:
|
|
27
|
+
- uses: actions/checkout@v7
|
|
28
|
+
with:
|
|
29
|
+
fetch-depth: 0
|
|
30
|
+
- uses: astral-sh/setup-uv@v7
|
|
31
|
+
with:
|
|
32
|
+
enable-cache: true
|
|
33
|
+
- run: uv build
|
|
34
|
+
- uses: actions/upload-artifact@v7
|
|
35
|
+
with:
|
|
36
|
+
name: dist
|
|
37
|
+
path: dist/
|
|
38
|
+
|
|
39
|
+
test-install:
|
|
40
|
+
runs-on: ubuntu-latest
|
|
41
|
+
needs: build
|
|
42
|
+
strategy:
|
|
43
|
+
matrix:
|
|
44
|
+
python-version: ["3.12", "3.13"]
|
|
45
|
+
steps:
|
|
46
|
+
- uses: actions/download-artifact@v8
|
|
47
|
+
with:
|
|
48
|
+
name: dist
|
|
49
|
+
path: dist/
|
|
50
|
+
- uses: astral-sh/setup-uv@v7
|
|
51
|
+
with:
|
|
52
|
+
enable-cache: true
|
|
53
|
+
- name: Install wheel and smoke-test import
|
|
54
|
+
run: |
|
|
55
|
+
uv venv --python ${{ matrix.python-version }}
|
|
56
|
+
uv pip install dist/*.whl
|
|
57
|
+
uv run --no-sync python -c "import argus_scout; print(f'argus-scout {argus_scout.__version__} OK')"
|
|
58
|
+
|
|
59
|
+
publish-testpypi:
|
|
60
|
+
runs-on: ubuntu-latest
|
|
61
|
+
needs: test-install
|
|
62
|
+
environment: testpypi
|
|
63
|
+
steps:
|
|
64
|
+
- uses: actions/download-artifact@v8
|
|
65
|
+
with:
|
|
66
|
+
name: dist
|
|
67
|
+
path: dist/
|
|
68
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
69
|
+
with:
|
|
70
|
+
repository-url: https://test.pypi.org/legacy/
|
|
71
|
+
|
|
72
|
+
publish-pypi:
|
|
73
|
+
runs-on: ubuntu-latest
|
|
74
|
+
# Ordered *after* the TestPyPI rehearsal so its outcome is visible first, but
|
|
75
|
+
# deliberately not gated on it. A TestPyPI-only fault — a missing trusted
|
|
76
|
+
# publisher, an index outage — must not silently withhold the real release:
|
|
77
|
+
# that failure mode shipped argus-proof images for two tags with no wheel on
|
|
78
|
+
# PyPI, and nothing surfaced it because publish-image is independent.
|
|
79
|
+
# Only the build + install gate is required; a TestPyPI failure still marks
|
|
80
|
+
# the whole run failed, so the problem stays loud.
|
|
81
|
+
needs: [test-install, publish-testpypi]
|
|
82
|
+
if: "!cancelled() && needs.test-install.result == 'success'"
|
|
83
|
+
environment: pypi
|
|
84
|
+
steps:
|
|
85
|
+
- uses: actions/download-artifact@v8
|
|
86
|
+
with:
|
|
87
|
+
name: dist
|
|
88
|
+
path: dist/
|
|
89
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
90
|
+
|
|
91
|
+
release-tag:
|
|
92
|
+
# The tag the image jobs build: the pushed one, or on a cortex dispatch the
|
|
93
|
+
# newest final release. A pre-release never moved `latest`, so a dispatch
|
|
94
|
+
# does not rebuild one.
|
|
95
|
+
runs-on: ubuntu-latest
|
|
96
|
+
outputs:
|
|
97
|
+
tag: ${{ steps.tag.outputs.tag }}
|
|
98
|
+
sha: ${{ steps.tag.outputs.sha }}
|
|
99
|
+
steps:
|
|
100
|
+
- uses: actions/checkout@v7
|
|
101
|
+
if: github.event_name == 'repository_dispatch'
|
|
102
|
+
- id: tag
|
|
103
|
+
env:
|
|
104
|
+
CORTEX_VERSION: ${{ github.event.client_payload.version }}
|
|
105
|
+
run: |
|
|
106
|
+
if [ "$GITHUB_EVENT_NAME" != repository_dispatch ]; then
|
|
107
|
+
echo "tag=$GITHUB_REF_NAME" >> "$GITHUB_OUTPUT"
|
|
108
|
+
echo "sha=$GITHUB_SHA" >> "$GITHUB_OUTPUT"
|
|
109
|
+
exit 0
|
|
110
|
+
fi
|
|
111
|
+
refs=$(git ls-remote --tags origin 'refs/tags/v*')
|
|
112
|
+
tag=$(echo "$refs" | sed -n 's|.*refs/tags/\(v[0-9]*\.[0-9]*\.[0-9]*\)\(\^{}\)\{0,1\}$|\1|p' | sort -uV | tail -n1)
|
|
113
|
+
if [ -z "$tag" ]; then
|
|
114
|
+
echo "::notice::No release tag yet, so no image to rebuild for cortex $CORTEX_VERSION."
|
|
115
|
+
exit 0
|
|
116
|
+
fi
|
|
117
|
+
# An annotated tag lists its commit on the peeled ^{} line.
|
|
118
|
+
sha=$(echo "$refs" | awk -v t="refs/tags/$tag" '$2 == t {l = $1} $2 == t "^{}" {p = $1} END {print p ? p : l}')
|
|
119
|
+
echo "Rebuilding $tag ($sha) for cortex $CORTEX_VERSION."
|
|
120
|
+
echo "tag=$tag" >> "$GITHUB_OUTPUT"
|
|
121
|
+
echo "sha=$sha" >> "$GITHUB_OUTPUT"
|
|
122
|
+
|
|
123
|
+
publish-image:
|
|
124
|
+
runs-on: ubuntu-latest
|
|
125
|
+
needs: [release-tag, test-install]
|
|
126
|
+
# On a cortex dispatch test-install is skipped (nothing was built for PyPI),
|
|
127
|
+
# so the job runs on the tag alone.
|
|
128
|
+
if: "!cancelled() && needs.release-tag.outputs.tag != '' && (needs.test-install.result == 'success' || github.event_name == 'repository_dispatch')"
|
|
129
|
+
permissions:
|
|
130
|
+
contents: read
|
|
131
|
+
packages: write
|
|
132
|
+
steps:
|
|
133
|
+
- uses: actions/checkout@v7
|
|
134
|
+
with:
|
|
135
|
+
ref: ${{ needs.release-tag.outputs.tag }}
|
|
136
|
+
fetch-depth: 0 # hatch-vcs reads the tag from git history
|
|
137
|
+
- uses: docker/setup-buildx-action@v4
|
|
138
|
+
- uses: docker/login-action@v4
|
|
139
|
+
with:
|
|
140
|
+
registry: ghcr.io
|
|
141
|
+
username: ${{ github.actor }}
|
|
142
|
+
password: ${{ secrets.GITHUB_TOKEN }}
|
|
143
|
+
- id: meta
|
|
144
|
+
uses: docker/metadata-action@v6
|
|
145
|
+
with:
|
|
146
|
+
images: ghcr.io/${{ github.repository_owner }}/argus-scout
|
|
147
|
+
labels: org.opencontainers.image.revision=${{ needs.release-tag.outputs.sha }}
|
|
148
|
+
tags: |
|
|
149
|
+
type=semver,pattern={{version}},value=${{ needs.release-tag.outputs.tag }}
|
|
150
|
+
type=semver,pattern={{major}}.{{minor}},value=${{ needs.release-tag.outputs.tag }}
|
|
151
|
+
type=raw,value=latest
|
|
152
|
+
- uses: docker/build-push-action@v7
|
|
153
|
+
with:
|
|
154
|
+
context: .
|
|
155
|
+
file: ./Dockerfile
|
|
156
|
+
push: true
|
|
157
|
+
tags: ${{ steps.meta.outputs.tags }}
|
|
158
|
+
labels: ${{ steps.meta.outputs.labels }}
|
|
159
|
+
# A dispatch rebuilds an unchanged context, so a cached install layer
|
|
160
|
+
# would keep the old argus-cortex.
|
|
161
|
+
no-cache: ${{ github.event_name == 'repository_dispatch' }}
|
|
162
|
+
cache-from: type=gha
|
|
163
|
+
cache-to: type=gha,mode=max
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
.venv/
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.pyc
|
|
4
|
+
dist/
|
|
5
|
+
build/
|
|
6
|
+
*.egg-info/
|
|
7
|
+
.pytest_cache/
|
|
8
|
+
.ruff_cache/
|
|
9
|
+
# hatch-vcs writes this at build time (version derived from git tags)
|
|
10
|
+
src/argus_scout/_version.py
|
|
11
|
+
# secrets: init writes .env.example, the real .env stays local
|
|
12
|
+
.env
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
# CLAUDE.md — argus-scout
|
|
2
|
+
|
|
3
|
+
Guidance for AI agents working in this repo. Human-facing usage lives in [README.md](README.md); this file is the orientation an agent needs to change code safely.
|
|
4
|
+
|
|
5
|
+
> Scaffolded from [`argus-pkg-template`](https://github.com/smk762/argus-pkg-template). Flesh out **Must never happen**, **Layout** and **Gotchas** below as the code grows — the suite conventions are already correct and shared.
|
|
6
|
+
|
|
7
|
+
## What this is
|
|
8
|
+
|
|
9
|
+
Homelab intelligence for the Argus suite: reads your telemetry, reasons about it, and reports back with briefings and recommendations it never acts on.
|
|
10
|
+
|
|
11
|
+
**Advisory only.** Scout reads (Prometheus via PromQL, status events sent to it) and reports (briefings, recommendations). It never executes, deploys or dispatches anything, and never scrapes or connects to the hosts it reports on. A standing approval may move a recommendation to `approved`; nothing moves it further except a person.
|
|
12
|
+
|
|
13
|
+
Development runs in phases tracked by the epic issue in this repo. The policy core was ported from a private deployment (mithrandir) with its globals removed: every module takes its config explicitly.
|
|
14
|
+
|
|
15
|
+
Shared code — the target taxonomy, wire-schema versioning, and the local/remote model contract — lives in **argus-cortex**; import it rather than re-implementing.
|
|
16
|
+
|
|
17
|
+
## Argus suite
|
|
18
|
+
<!-- argus-suite: keep this block; argus-ci checks for it -->
|
|
19
|
+
This repo is part of the Argus suite. The suite map below lists every sibling and what it owns; check it before
|
|
20
|
+
building something a sibling may already do. **On every release, update this repo's row and capabilities in
|
|
21
|
+
argus-cortex's SUITE.md** (a PR to argus-cortex in the same release).
|
|
22
|
+
|
|
23
|
+
@../argus-core/SUITE.md
|
|
24
|
+
|
|
25
|
+
Not checked out? Read https://github.com/smk762/argus-cortex/blob/dev/SUITE.md
|
|
26
|
+
|
|
27
|
+
## Must never happen
|
|
28
|
+
|
|
29
|
+
Each row names the test, CI job or lint that enforces it. Add a row for every rule this package must keep, and mark
|
|
30
|
+
it **UNENFORCED** until something checks it. When a rule bites, add a check rather than more prose.
|
|
31
|
+
|
|
32
|
+
| Never | Enforced by |
|
|
33
|
+
|---|---|
|
|
34
|
+
| A hand-edited version | `_version.py` is generated by hatch-vcs and gitignored |
|
|
35
|
+
| A new suite-rule violation (argus-ci's lint catalogue) | CI `suite-rules` job; `.suite-rules-baseline.json` may only shrink |
|
|
36
|
+
| A workflow testing a Python the package doesn't support | `tests/test_workflows.py` (every `python-version` in `.github/workflows/*.yml` satisfies `requires-python`) |
|
|
37
|
+
| A CLAUDE.md without the argus-suite block | CI `suite` job (argus-ci suite-check) |
|
|
38
|
+
| A state-changing route without the bearer token (failing closed), the read-only guard and the origin guard | `tests/test_api_guards.py`: `test_every_write_route_is_guarded` walks every route (through included routers) with `server.guards.unguarded_routes`, and `test_walker_flags_an_unguarded_route` proves it bites; the same walk drives real requests (`test_no_token_configured_refuses_every_write`, `test_missing_or_wrong_token_is_401`, `test_read_only_refuses_every_write_even_with_the_token`, `test_untrusted_origin_is_refused`, `test_oversized_bodies_are_413`) |
|
|
39
|
+
| A caller-supplied path outside a configured root | No route takes a filesystem path today. `tests/test_api_guards.py` (`test_no_route_touches_the_filesystem`: no mounts, no file APIs in `server/`); a route that needs one fences it under a root and adds a test |
|
|
40
|
+
| An unbounded request body | Write routes read through `argus_cortex.limits.read_body` (`server.guards.read_bounded` / `read_json`), never a FastAPI body parameter; `tests/test_api_guards.py` (`test_oversized_bodies_are_413`, `test_oversized_chunked_body_is_413`, `test_auth_runs_before_the_body_is_read`) |
|
|
41
|
+
| Scout moving a recommendation past `approved` | `tests/test_approvals.py` (`test_file_rule_auto_approves_and_audits`; `test_no_code_path_sets_deployed` walks `src/` and fails on any `Status.DEPLOYED` or `"deployed"` outside `recommendations.py`); `tests/test_engine.py` (`test_engine_never_moves_anything_past_approved`, `test_approved_is_never_retired_by_the_engine`) |
|
|
42
|
+
| A standing approval for a guarded proposal raised by the engine | `tests/test_engine.py` (`test_guardrails_refuse_auto_approval`) |
|
|
43
|
+
| A standing approval surviving escalation past a guardrail (it is retired and a fresh `proposed` one raised; a manual approval keeps its approval with a note) | `tests/test_engine.py` (`test_standing_approval_does_not_survive_escalation_past_a_guardrail`, `test_escalated_standing_approval_is_reproposed_despite_an_old_rejection`, `test_manual_approval_survives_escalation_with_a_note`) |
|
|
44
|
+
| A Prometheus outage read as "all clear" (retiring proposals as cleared) | `tests/test_engine.py` (`test_unknown_never_clears`, `test_analysis_cycle_raises_and_survives_an_outage`); `tests/test_signals.py` (`test_outage_is_unknown_and_keeps_pending_state`) |
|
|
45
|
+
| A rejected proposal re-raised without escalating or aging out | `tests/test_engine.py` (`test_rejected_key_is_not_reraised`, `test_escalation_beyond_the_rejected_severity_reraises`, `test_rejection_ttl_lets_a_key_back`) |
|
|
46
|
+
| A manual decision overwritten by a concurrent engine cycle | `SqliteStore.save_recommendation` checks `expected_status` and the lifecycle inside one `BEGIN IMMEDIATE` transaction (`StaleRecommendation` / `IllegalTransition`, nothing written); `tests/test_recommendation_races.py` (`test_manual_decision_survives_a_concurrent_engine_refresh`, `test_manual_approval_survives_a_concurrent_engine_retire`, `test_standing_approval_loses_to_a_person_who_decided_first`, `test_retire_first_then_stale_manual_approval_is_refused`, `test_store_refuses_an_illegal_transition`) |
|
|
47
|
+
| A read (or any route but `/health` and `/metrics`) served to a DNS-rebinding `Host` | `server.guards.HostGuard`, outermost: a `Host` that isn't an IP literal, `localhost` or a `server.trusted_hosts` name is a 400 (`server.guards.rebind_proof`, mirroring argus-cortex's same-host rule without importing its private helpers; `test_host_rule_matches_argus_cortex` checks parity); `unguarded_routes` fails if it is missing or not outermost. `tests/test_api_guards.py` (`test_the_host_guard_covers_every_route` walks every route and method, `test_walker_flags_a_host_guard_that_is_not_outermost`), `tests/test_api_hardening.py` (`test_a_rebinding_host_is_refused_on_every_route`, `test_ip_literals_and_localhost_pass`, `test_a_configured_trusted_host_passes_reads_and_same_origin_writes`) |
|
|
48
|
+
| A decision applied to content the person didn't see, or a decision (or engine write) reverting a newer save | every save bumps the recommendation's revision (migration 9, `recommendation_revisions`); `DecisionBody.revision` is required and `SqliteStore.update_recommendation` checks it and applies the decision to the stored row in one `BEGIN IMMEDIATE` transaction; the engine passes `expected_revision`. `tests/test_api_hardening.py` (`test_a_decision_on_content_the_person_never_saw_is_refused`, `test_a_decision_never_reverts_the_engines_escalation`, `test_the_revision_is_required`, `test_store_checks_and_bumps_the_revision`, `test_engine_save_is_refused_when_content_changed_since_its_load`) |
|
|
49
|
+
| An unauthenticated caller learning which sources exist (404/405 before the credential check) | `server.guards.source_auth` checks credentials first and answers a name that isn't a push source as a push source would (401, or 503); `tests/test_api_hardening.py` (`test_unauthenticated_pushes_get_the_same_401`, `test_no_server_token_closes_unknown_and_known_sources_alike`, `test_the_server_token_still_learns_what_is_wrong`) |
|
|
50
|
+
| The API schema and docs served without the bearer check when `read_auth` is on | `create_app` drops `/docs`, `/redoc` and `/openapi.json` under `read_auth`; `tests/test_api_hardening.py` (`test_docs_are_off_under_read_auth`) |
|
|
51
|
+
| Part of a push batch stored when a store error stops it (a retry then calling the stored part "refreshed") | `Inbox.ingest_many` stores the batch in one `SqliteStore.transaction()`; `tests/test_api_hardening.py` (`test_a_store_error_mid_batch_stores_nothing`) |
|
|
52
|
+
| A plugin's parse error leaking its internals or answering 500 | `tests/test_api_hardening.py` (`test_plugin_parse_errors_are_400_without_internals`) |
|
|
53
|
+
| A signal template reaching attributes, indexes or arbitrary format specs | `tests/test_signals.py` (`test_template_tricks_are_refused`) |
|
|
54
|
+
| A missing, bad or gappy tariff (or a Prometheus outage) crashing a tariff rule or reading as "all clear" | `tests/test_tariff_rules.py` (`test_shift_unknown_and_skipped`, `test_plan_comparison_unknown_paths`, `test_analysis_cycle_without_a_tariff_skips_only_tariff_rules`) |
|
|
55
|
+
| A plan comparison (a range query over weeks) running more than once a day, restarts included | `tests/test_tariff_rules.py` (`test_plan_comparison_runs_at_most_daily_even_across_restarts`; the schema refuses `every` under 1d in `test_bad_tariff_rules_are_skipped_with_reasons`) |
|
|
56
|
+
| A standing approval for a high-impact or critical proposal, whatever the rules say | `tests/test_approvals.py` (`test_guardrails_override_permissive_rules`, `test_runtime_rule_refused_for_guarded_proposal`); after approval too: `tests/test_engine.py` (`test_standing_approval_does_not_survive_escalation_past_a_guardrail`) |
|
|
57
|
+
| A bad edit to a policy or approvals file stopping status updates | `tests/test_heartbeat.py` (`test_bad_file_falls_back_to_defaults`), `tests/test_approvals.py` (`test_bad_rules_skipped_others_kept`), `tests/test_scheduler.py` (`test_bad_heartbeat_file_keeps_status_cycle_alive`) |
|
|
58
|
+
| A failing job (or source) stopping the scheduler or the other jobs | `tests/test_scheduler.py` (`test_failing_job_is_isolated_counted_and_retried`, `test_poll_jobs_ingest_and_one_failing_source_is_isolated`) |
|
|
59
|
+
| A restart repeating a briefing, or replaying missed ones in a burst | `tests/test_scheduler.py` (`test_no_double_fire_after_restart`, `test_no_catch_up_storm`) |
|
|
60
|
+
| A config change renaming a briefing job (losing its run history and re-firing it), or two briefings in one slot | job names are always `briefing:<kind>@HH:MM`; `tests/test_scheduler.py` (`test_briefing_job_names_do_not_depend_on_how_many_share_a_kind`), `tests/test_config.py` (`test_invalid_config_raises`: duplicate briefing) |
|
|
61
|
+
| LLM output parsed into an action (approving, rejecting or running anything) | `tests/test_narrative.py` (`test_model_output_is_never_parsed_into_an_action`: a model reply full of approve/deploy/JSON commands leaves every recommendation as it was and is stored verbatim as text); `llm.clean_output` strips control characters and `<think>` blocks (`tests/test_llm.py::test_output_is_cleaned_untrusted_text`) |
|
|
62
|
+
| A briefing silently skipped when the LLM is down, over its cap or not configured | `tests/test_narrative.py` (`test_budget_refusal_falls_back_to_template`, `test_llm_error_falls_back_to_template`, `test_no_model_and_no_llm_use_the_template`, `test_briefing_job_without_a_model_still_stores`): the template report is stored with `meta.path=template` and `meta.fallback_reason` |
|
|
63
|
+
| A model call over the daily `llm_calls` cap | `tests/test_llm.py` (`test_budget_charged_before_the_call_and_refused_over_cap`: charged before the call, refused calls never reach the model) |
|
|
64
|
+
| A memory path outside its root (`../`, absolute, or a symlink out), or scout writing an operator note | `tests/test_memory.py` (`test_traversal_is_refused`, `test_symlink_out_of_root_is_refused`, `test_scout_file_symlinked_out_is_never_written_through`, `test_scout_writes_only_its_own_file`) |
|
|
65
|
+
| A bad persona file stopping a briefing | `tests/test_persona.py` (`test_bad_file_degrades_to_default_and_recovers`, `test_missing_file_degrades_to_default`), `tests/test_narrative.py` (`test_bad_persona_degrades_and_is_recorded`) |
|
|
66
|
+
| A prompt that overflows a small model's context, or a cut that drops a severe fact before a minor one | `tests/test_narrative.py` (`test_truncation_drops_least_severe_first`, `test_selection_is_monotonic_by_tier`) |
|
|
67
|
+
| A crash loop resetting the daily usage caps | `tests/test_budget.py` (`test_counts_survive_restart`), `tests/test_budget_store.py` (`test_store_counts_survive_restart`) |
|
|
68
|
+
| The daily caps resetting at the host's midnight instead of `schedule.timezone`'s | `tests/test_budget_store.py` (`test_caps_reset_at_midnight_in_the_schedule_timezone`, `test_caps_follow_the_schedule_timezone_on_the_wall_clock`) |
|
|
69
|
+
| A CLI command that speaks or calls the model outside the daily caps | `tests/test_channels.py` (`test_cli_deliver_charges_the_speech_caps`); `brief` passes `budget_from_config` (`analyze` and `poll` charge nothing) |
|
|
70
|
+
| A URL in the config that passes `check config` and then fails at startup (bad port or no host) | `tests/test_config.py` (`test_invalid_config_raises`: `http://echo:80x`, `http://prom:99999`, and a source, channel and LLM URL) |
|
|
71
|
+
| Daily caps (`llm_calls`, `tts`, `speak`, any kind) exceeded, or counts lost, by concurrent processes (the server and a CLI `brief` sharing the store) | `SqliteStore.consume_usage`: one upsert whose `WHERE` is the limit check, inside `BEGIN IMMEDIATE`; `tests/test_budget_store.py` (`test_two_processes_lose_no_count_and_never_exceed_the_cap`, `test_four_connections_share_one_cap`, `test_server_and_cli_count_in_the_store`) |
|
|
72
|
+
| A briefing skipped because no GPU lease was granted | `tests/test_gpu.py` (`test_briefing_without_a_lease_falls_back_to_the_template`: stored from the template with `fallback_reason: gpu_unavailable`; `test_no_lease_is_gpu_unavailable_and_not_charged`) |
|
|
73
|
+
| Scout holding a GPU lease around echo synthesis (or anything but its own model call) | `tests/test_gpu.py` (`test_only_the_narrative_guard_takes_a_lease` walks `src/` for `.lease(`/`.alease(` outside `gpu.py`; `test_lease_is_released_before_generate_returns`); `tests/test_echo.py::test_no_gpu_lease_is_taken_around_synthesis` |
|
|
74
|
+
| A `gpu-tenant.yaml` that stops validating or drifts from the lease defaults | `tests/test_gpu.py` (`test_manifest_validates_and_matches_the_lease_defaults`) |
|
|
75
|
+
| Scout starting on an invalid top-level config (unlike the policy files, which degrade to defaults) | `tests/test_config.py` (`test_invalid_config_raises`, `test_serve_refuses_invalid_config`) |
|
|
76
|
+
| A list or mapping in `scout.yaml` whose entries are all commented out (null) failing the config | `config.NullAsEmptyList` / `NullAsEmptyDict` on every such field; `tests/test_config.py` (`test_entries_commented_out_at_any_depth_read_as_empty`) |
|
|
77
|
+
| The container image pointing at a missing entry point | `tests/test_dockerfile.py` (`test_image_command_targets_exist` resolves the CMD's console script and command, or a `module:attr`; `test_image_config_env_matches_the_serve_option`) |
|
|
78
|
+
| A secret value in the config model's repr or dumps (the YAML holds env-var names, not values) | `tests/test_config.py` (`test_secrets_resolve_from_dotenv_and_never_appear`); the model holds env-var names only, validated as names |
|
|
79
|
+
| Scout querying a host directly instead of Prometheus | `tests/test_prometheus.py`: `test_only_the_configured_prometheus_is_contacted` (real `afetch`, stubbed transport: every request goes to the configured host, GET, `/api/v1/query[_range]` only; a redirect elsewhere is refused) and `test_no_module_contacts_hosts_directly` (no module imports a network client; only `prometheus.py`, `sources/json_poll.py`, `channels/webhook.py`, `channels/mask.py`, `channels/snapcast.py` and `channels/echo.py` use `argus_cortex.net`'s fetch, only `channels/snapcast.py` opens a raw socket, to its configured snapserver's control port, and only `channels/mask.py` imports `websockets`, for argus-mask's source socket at its configured host, pinned by `check_url` with no redirects: `tests/test_voice_channels.py` `test_mask_ws_goes_only_to_the_configured_host`). Pollers fetch only their configured status URL (`tests/test_sources.py`: `test_poll_once_uses_the_guarded_fetch_with_config_host_allowed`, `test_poll_once_through_argus_cortex_net_reaches_a_lan_host`) |
|
|
80
|
+
| A webhook push accepted when no token is configured, or with another source's token | `tests/test_sources.py` (`test_webhook_token`, `test_webhook_token_falls_back_to_server_token_and_fails_closed`) |
|
|
81
|
+
| A webhook producer speaking as a different source, or half a malformed batch ingested | `tests/test_sources.py` (`test_webhook_rejects_malformed_bodies`), `tests/test_api_hardening.py` (`test_a_store_error_mid_batch_stores_nothing`) |
|
|
82
|
+
| A broken source or channel plugin, or bad `sources:`/`channels:` entry, stopping the others (a plugin model raising anything, not only a `ValidationError`) | `tests/test_sources.py` (`test_bad_source_entries_do_not_stop_the_others`, `test_a_plugin_model_raising_anything_fails_only_its_entry`), `tests/test_channels.py` (`test_bad_channel_entries_do_not_stop_the_others`, `test_a_plugin_model_raising_anything_fails_only_its_channel`), `tests/test_cli.py` (`test_poll_dry_run_reports_each_source`) |
|
|
83
|
+
| A polled source posting as another source (resetting its ack or announce state) | `sources/json_poll._envelope` forces `source = name` and skips an item naming another; config refuses `fields.source`. `tests/test_sources.py` (`test_a_polled_item_cannot_post_as_another_source`), `tests/test_config.py` (`test_invalid_config_raises`) |
|
|
84
|
+
| Two polled items collapsed into one event (an id derived from the summary alone) | `tests/test_sources.py` (`test_items_sharing_a_summary_get_distinct_stable_ids`, `test_configured_id_paths_identify_items_across_severity_changes`, `test_derived_id_ignores_volatile_fields_but_keeps_payload_identity`) |
|
|
85
|
+
| A cleared polled condition staying open, or a failed/partial poll clearing anything, or a system close faking a person's ack | `resolved_at` (migration 6), set by `Inbox.resolve_missing`, never `acked_by`. `tests/test_scheduler.py` (`test_poll_job_resolves_events_missing_from_a_successful_poll`, `test_poll_job_resolves_nothing_on_an_incomplete_poll_or_when_off`, `test_json_poll_cleared_item_resolves_end_to_end`), `tests/test_store.py` (`test_resolved_column_migration_keeps_open_events_open`), `tests/test_sources.py` (`test_poll_result_is_incomplete_when_an_item_was_skipped`) |
|
|
86
|
+
| A source setting inbox bookkeeping (ack, announce state) on the events it emits | `tests/test_inbox.py` (`test_ingest_normalises`) |
|
|
87
|
+
| Speech synthesised more than once per delivery, or a voice channel synthesising its own | `tests/test_channels.py` (`test_speech_is_synthesised_once_for_every_voice_channel`: one synthesis, the same audio object on every voice channel, `deliver()` never called on them; `test_third_party_voice_channel_from_an_entry_point`) |
|
|
88
|
+
| A failing, hanging or raising channel (or speech engine) blocking the others | `tests/test_channels.py` (`test_fan_out_and_a_failing_channel_never_blocks_the_others`, `test_a_failing_speaker_or_synthesiser_fails_voice_only`, `test_channels_run_concurrently`) |
|
|
89
|
+
| A duplicate delivery after a restart (the same report sent twice to one channel) | partial unique index `deliveries_sent` (one `ok` row per message and channel, migration 5); `tests/test_channels.py` (`test_no_duplicate_delivery_after_restart`, `test_concurrent_deliveries_of_one_message_send_once`, `test_a_briefing_job_writes_its_report_to_the_text_channel_once`, `test_cli_deliver_latest`) |
|
|
90
|
+
| A report spoken late (stale speech) by a retry | `channels/redeliver.py` sends a report older than `delivery.speak_max_age` (default 600 s) to text channels only; `tests/test_redeliver.py` (`test_no_stale_speech`: never synthesised or played; `test_speak_max_age_zero_never_respeaks`, `test_skips_do_not_count_toward_max_attempts_and_are_never_spoken_late`) |
|
|
91
|
+
| A cloned voice pushed to a face without disclosure | `SpeechAudio.cloned` (set by `EchoSynthesiser` whenever it asked for a `voice_clone_id`; echo's contract has no clone flag); over `transport: websocket` the `mask` channel pushes cloned audio only when the operator attests consent with `cloned_voice_consented: true` (default false: a permanent skip, before contacting mask, because mask's label asserts consent scout can't verify), and then the hello sets `disclose: true` exactly when the audio is cloned, so mask shows its disclosure label; over `transport: http` (the default) it skips cloned audio permanently, before contacting mask, unless `allow_cloned_voice: true` (default false, warned on every push), because `/push` can't carry the label. `tests/test_echo.py` (`test_speech_from_a_clone_is_marked_cloned`, `test_mask_refuses_a_cloned_voice_unless_allowed`, `test_a_refused_clone_is_reported_not_recorded_and_never_retried`), `tests/test_voice_channels.py` (`test_mask_ws_discloses_a_cloned_voice_and_not_a_synthetic_one`, `test_mask_ws_cloned_voice_needs_the_consent_attestation`, `test_mask_http_still_refuses_a_clone_whatever_the_attestation`). Snapcast (audio-only house playback) is deliberately not gated |
|
|
92
|
+
| A permanent failure retried forever, or any failure retried without bound | permanent refusals (a 4xx other than 408/429, from a webhook or from echo) are recorded in `delivery_refusals` (migration 8) and skipped by `undelivered_reports`; `tests/test_redeliver.py` (`test_permanent_failures_are_not_retried`, `test_a_webhook_4xx_is_permanent_and_a_429_is_not`, `test_retries_a_failed_channel_until_it_succeeds_and_stops_after_max_attempts`, `test_too_old_and_never_tried_channels_are_left_alone`, `test_a_channel_that_only_skipped_is_not_retried`) |
|
|
93
|
+
| A redelivery sending a report twice to a channel | the sweep goes through the dispatcher's store idempotency (`deliveries_sent`); `tests/test_redeliver.py` (`test_a_retry_that_succeeds_writes_one_ok_row_and_is_idempotent`) |
|
|
94
|
+
| Echo being down stopping text, or its failure going unrecorded | `EchoSynthesiser` raises `SynthesisError`, recorded on every voice channel; `tests/test_echo.py` (`test_echo_down_still_delivers_text_and_records_the_failure`, `test_unready_or_refusing_echo_raises_a_typed_error`) |
|
|
95
|
+
| Scout drifting from argus-echo's HTTP or resident contract | `tests/test_echo.py` (`test_request_and_response_follow_the_contract`, `test_a_cold_model_gets_the_load_timeout`, `test_build_request_and_stream_format`); the contract is re-implemented in `channels/echo.py` (argus-echo is not on PyPI), so a change to `argus_echo.contract` must be mirrored there by hand |
|
|
96
|
+
| A channel path outside its root (`../`, absolute, `{kind}` injection, a symlink out) | `tests/test_channels.py` (`test_text_channel_paths_outside_root_are_refused`) |
|
|
97
|
+
| Voice outside the heartbeat policy (quiet or rest hours), or the voice gate holding back text | `tests/test_channels.py` (`test_the_voice_gate_suppresses_voice_but_not_text`, `test_heartbeat_gates`); the dispatcher calls `heartbeat.broadcast_gate` / `voice_gate`, never a copy |
|
|
98
|
+
| A report delivered below the severity of its worst item (filtered off a `min_severity` channel, or held back in quiet hours when its item was let through) | `tests/test_status_reports.py` (`test_critical_status_report_reaches_a_critical_only_channel`, `test_briefing_severity_counts_items_and_open_recommendations`, `test_quiet_exempt_status_report_is_spoken_in_quiet_hours`, `test_critical_status_report_is_spoken_in_quiet_hours`) |
|
|
99
|
+
| A text-only, unspeakable or below-`voice.min_severity` item spoken inside a status report | `tests/test_status_reports.py` (`test_text_only_and_unspeakable_items_are_not_spoken`, `test_speech_holds_only_the_voice_eligible_items`, `test_unspeakable_report_skips_synthesis_whatever_the_gates_say`, `test_on_change_only_keeps_repeats_text_only`) |
|
|
100
|
+
| A recurred, new or escalated condition not reported, or an unchanged one repeated without `reannounce` | `tests/test_status_reports.py` (`test_a_condition_that_clears_and_recurs_is_reported_again`, `test_a_new_item_is_news_and_the_old_one_rides_along`, `test_an_item_clearing_is_not_news`, `test_an_item_clearing_reannounces_only_when_due`, `test_an_escalation_is_news`, `test_a_fresh_id_repeating_an_announced_item_is_not_news`, `test_an_item_held_back_by_quiet_hours_is_reported_after_them`) |
|
|
101
|
+
| A missing or stalled Snapcast FIFO reader hanging scout | `tests/test_voice_channels.py` (`test_snapcast_fifo_without_a_reader_fails_in_time_not_a_hang`, `test_snapcast_reader_that_stops_reading_fails_in_time`) |
|
|
102
|
+
| Scout creating or writing to a regular file in place of the Snapcast FIFO | `tests/test_voice_channels.py` (`test_snapcast_refuses_a_path_that_is_not_a_fifo`) |
|
|
103
|
+
| Snapcast group stream/volume left changed after speaking | `tests/test_voice_channels.py` (`test_snapcast_sets_volume_and_stream_then_restores_them`, `test_snapcast_restores_even_when_playback_fails`) |
|
|
104
|
+
| Speech pushed to an argus-mask face no screen can hear | `tests/test_voice_channels.py` (`test_mask_screen_not_ready_is_skipped_and_nothing_is_pushed`, `test_mask_push_refused_for_a_vanished_screen_is_skipped_and_errors_fail`; the push also sends `require_screen=true`; `test_mask_ws_not_ready_is_skipped_before_connecting`: the source socket has no `require_screen`, so `/health` is checked just before connecting) |
|
|
105
|
+
| The mask source socket hanging scout, or taking unbounded input | `tests/test_voice_channels.py` (`test_mask_ws_timeouts_and_early_close_fail_promptly`: connect, `ready` and push timeouts, a close before `done`; `test_mask_ws_caps_what_mask_may_send`; `test_mask_ws_pcm_arrives_intact_in_capped_frames`) |
|
|
106
|
+
| A missing voice extra (numpy) breaking any other channel | `tests/test_voice_channels.py` (`test_a_missing_extra_fails_only_that_channel`) |
|
|
107
|
+
| A channel POSTing anywhere but its configured URL, following a redirect, or sending without its configured credentials | `tests/test_prometheus.py` (`test_no_module_contacts_hosts_directly`); `tests/test_channels.py` (`test_webhook_payload_and_signature`, `test_webhook_refuses_to_send_without_its_secrets_or_to_another_host`) |
|
|
108
|
+
| A broken channel plugin or bad `channels:` entry stopping the other channels | `tests/test_channels.py` (`test_bad_channel_entries_do_not_stop_the_others`, `test_check_config_reports_a_bad_channel`) |
|
|
109
|
+
| The quickstart's config failing `check config`, its policy files drifting from `examples/`, an unpinned image, or a compose file that doesn't parse | `tests/test_quickstart.py`; CI `Quickstart` workflow (`docker compose config`) |
|
|
110
|
+
| A deployment's hostnames, IPs or persona in this repo | CI `docs` job (private IPs/paths/emails in published docs); examples use placeholders |
|
|
111
|
+
| `docs/config.md` drifting from the config schema | `tests/test_configdoc.py` (`test_config_reference_matches_the_schema`); regenerate with `make docs` |
|
|
112
|
+
| A published doc the handbook's import would refuse or mis-render (opsec hit, no `#` title, raw HTML, a broken relative link or anchor) | `tests/test_docs_publishable.py` |
|
|
113
|
+
|
|
114
|
+
## Layout
|
|
115
|
+
|
|
116
|
+
`src/argus_scout/` — the package. Key modules:
|
|
117
|
+
|
|
118
|
+
- `__init__.py` — version shim (`__version__` from `hatch-vcs`).
|
|
119
|
+
- `cli.py` — Typer app; entry point `argus-scout` (`[project.scripts]`). `init` writes a starter config; `check` validates config files (`check config` covers scout.yaml, every file it names and every source and channel entry); `deliver --config --latest [--kind] [--channel] [--force]` (re-sends the newest report; idempotent unless `--force`); `poll --config [--source] [--ingest]` (one poll, dry run by default); `analyze --config [--dry-run]` (one signal evaluation + engine cycle; `--dry-run` works on `SqliteStore.copy_of`); `brief --config --kind morning|evening|status [--dry-run] [--no-llm]` (writes one report and prints it; `--dry-run` stores nothing and doesn't persist the usage count); `tariff now`; `serve --config`.
|
|
120
|
+
- `config.py` — `ScoutConfig`, the one config file (`scout.yaml`): `files`, `store`, `sources` (built-in kinds `webhook` / `json_poll` validated here; any other kind loads as `PluginSource`, keys kept, and is validated by its plugin's `config_model` in `sources.build_sources`; plugin models subclass `SourceSettings`), `channels` (built-in `text` / `webhook`, plugin kinds as `PluginChannel` validated by `channels.build_channels`; every channel has `enabled`, `min_severity`, `kinds`, `timeout` from `ChannelSettings`), `schedule` (briefing kinds are `morning` / `evening` / `status`), `services` (`llm`: `backend` ollama|openai, `base_url`, `model`, `api_key_env`, `timeout`, `max_tokens`, `context_tokens`, `temperature`, `gpu` (`LLMGpuConfig`: `min_vram_mb`, `model_mb`, `priority`, `target`; present means a lease per call; `target` required for openai)), `budget` (`limits: {llm_calls: N}`, `block_manual`), `server`. `files` also names `persona` and `memory`. Pydantic v2, `extra="forbid"`, frozen. `load_config` resolves relative paths against the config's directory, loads `.env` beside it (never overriding the real env) and raises `ConfigError` on anything invalid. Secrets are env-var *names* (`token_env`, `auth_env`, `api_key_env`), read with `resolve_secret` as `SecretStr`.
|
|
121
|
+
- `severity.py` — `Severity` (info < notice < warning < critical), `coerce_severity`, `rank`.
|
|
122
|
+
- `events.py` — `StatusEvent`, the envelope every source sends; `fingerprint` (content identity) and `group_duplicates`.
|
|
123
|
+
- `heartbeat.py` — `HeartbeatPolicy` (defaults + YAML overrides, `origin` per key), `PolicyFile` (mtime reload), the `broadcast_gate` / `report_gate` / `voice_gate` chain and `explain()`, `reannounce_due` (per group, from `last_broadcast_at`). `voice.on_change_only` is applied by the status cycle; `voice.backoff_max_seconds` was never implemented and is ignored with a warning.
|
|
124
|
+
- `recommendations.py` — `Recommendation` (`to_dict` / `from_dict`; `key`, `expires_at`, `last_seen_at`, `retired_reason` default empty so older stored rows load), `Status`, `TRANSITIONS` (`proposed → retired` withdraws a stale proposal); `approve()` / `reject()` / `retire()` take an optional `now` and keep the audit trail.
|
|
125
|
+
- `prometheus.py` — `PrometheusClient(base_url, fetcher=)`: read-only `query` / `query_range` via `argus_cortex.net.afetch`, configured host the only one allowlisted, no redirects. Typed results (`Sample`, `Series`) and errors (`PrometheusUnavailable`, `PrometheusQueryError`, `PrometheusResponseError`, all `PrometheusError`): a failure is unknown, never an empty result.
|
|
126
|
+
- `signals.py` — declarative rules (`SignalRule`: `name`, `query`, `op`, `threshold`, `for`, `severity`, `escalate`, `labels_key`, `labels`, `rejection_ttl`, `expires_after`, `recommendation`). `parse_rules` / `load_signal_rules` skip bad rules with an error; `SignalRulesFile` (mtime reload). `render` / `template_fields`: allowlisted plain-name placeholders, precision-only specs on numbers, no `format_map`. `SignalState` (pending `for` clocks, persisted via the store). `async evaluate(rules, client, now, state=)` → `Evaluation` (a `list[SignalHit]` plus `evaluated` / `unknown` / `pending`); `dedup_key`; `make_hit` and `Evaluation.merge` are the seam for other evaluators (tariff rules). `kind:` picks a rule's schema (`rule_kinds()`; missing means `threshold`); `evaluate` runs only threshold rules but keeps every rule's pending state; `RuleBase` is the shared base (name, query, severity, rejection_ttl, expires_after, recommendation, template check).
|
|
127
|
+
- `tariff_rules.py` — the tariff-aware kinds. `TariffShiftRule` (`kind: tariff_shift`: `unit` W/kW/kWh, `min_shiftable`, `duration`, `periods`, `horizon` ≤ 1d, `min_saving`, `for`, `labels_key`) and `TariffPlanRule` (`kind: tariff_plan`: `unit`, `window`, `step`, `every` ≥ 1d, `min_saving`, `min_coverage`). `async evaluate_tariff(rules, client, tariff, now, tz=, state=, tariff_error=)` → `Evaluation`; no tariff / gaps / non-kWh / unknown period → `unknown` with `skipped: ...`; a plan rule's last run is kept in `SignalState` under `last_run`. Maths: `energy_kwh`, `shift_saving`, `cheaper_ahead`, `usage_points`, `plan_cost`, `comparable_plans`, `format_money` (minor → major units).
|
|
128
|
+
- `engine.py` — `RecommendationEngine(store, approvals, clock=, clear_grace=1h, default_ttl=7d)`. `run_cycle(hits)` → `CycleReport` (new / refreshed / auto_approved / retired / suppressed / unknown): dedup by key onto an open recommendation, rejection memory (suppressed unless severity escalates past the rejected one, or the rule's `rejection_ttl` has passed), standing approvals on `proposed` (guardrails win), a standing-approved recommendation escalating past a guardrail retired and re-proposed (`_escalated_past_standing`; a manual approval keeps its approval and gets an evidence note), proposed-only expiry (cleared past grace for an evaluated rule, or past `expires_at`; unknown never clears). `recent_rejections(limit)` → `Rejection`.
|
|
129
|
+
- `approvals.py` — `StandingApprovals` (file rules + runtime rules, optionally persisted via a `RuntimeRuleStore`), `guardrail_block`, `briefing_lines`.
|
|
130
|
+
- `budget.py` — `DailyBudget` (per-kind daily caps; counts in a `counter=` (`UsageCounter`: the store, atomic across processes), a single-process `state_path` JSON file, or memory; `on_change` hook for gauges), `budget_from_config(config, counter=, persist=, clock=)` (limits from `budget:`; the day rolls over at midnight in `schedule.timezone`; with `counter` the counts live in the store's `usage_counts` table and an old `usage.json` beside the store is imported once (merged by max, renamed `usage.json.migrated`)), `ManualOriginMiddleware`. The server and the CLI pass their store.
|
|
131
|
+
- `llm.py` — text generation on `argus_cortex.backends.RemoteBackend` (cortex owns the HTTP client, bearer header, timeout and retry policy: POSTs retried only when they never reached the server). `TextBackend.complete(prompt, max_tokens=)`; `OllamaBackend` (`/api/chat`, `stream: false`, `options.num_predict`), `OpenAICompatBackend` (`{base_url}/chat/completions`, `base_url` includes `/v1`; hosted providers via `api_key_env`); `build_backend(LLMConfig)`. `TextGenerator(backend, budget, call_guard=)`: `await generate(prompt, *, max_tokens, kind="llm_calls")` checks the cap (`LLMBudgetExceeded`, no lease waited for), enters `call_guard()` (the GPU lease: an async context manager, default no-op, held only for the HTTP round-trip), charges the budget, then makes the blocking call in a thread, sent to the grant's `base_url` if it has one (`TextBackend.at(url)`); no lease granted is `LLMGpuUnavailable` (`reason` `gpu_unavailable`, not charged), any other failure `LLMUnavailable` (`reason` tag). `clean_output`: output is untrusted text, never parsed. `estimate_tokens` = chars/4.
|
|
132
|
+
- `persona.py` — `Persona` (name, voice, style, do, dont, sign_off, `SpeakableStyle`); the field defaults are the neutral default persona (`examples/persona.yaml` mirrors them, tested). `system_prompt()` always starts with scout's `RULES` (advisory only, facts only, don't re-argue rejections). `PersonaFile(path)` (mtime reload; a bad or missing file → default, `error` set, logged).
|
|
133
|
+
- `memory.py` — `Memory(root, max_chars=)`: operator notes (`*.md`, one level, read-only, capped per file) and scout's own `SCOUT_FILE` (`scout-recent-rejections.md`, rewritten atomically, never through a symlink). `resolve(name)` fences every path under the root's real path (`MemoryPathError`). `render_rejection` quotes a rejection's reason.
|
|
134
|
+
- `gpu.py` — GPU leases (argus-iris broker via `argus_cortex.gpu`). `narrative_guard(llm, coordinator=)` → the call guard (or `None` without `services.llm.gpu`): one preemptible lease, kind `narrative`, priority `background` by default, target `ollama:<model>` or `gpu.target`. Coordinator from the host-wide `ARGUS_GPU_*` env (`coordinator_from_env`), deliberately no scout.yaml knob. `routed_url` (grant's host, configured path kept), `LEASE_ERRORS`, `TENANT`/`KIND`/`DEFAULTS` (match `gpu-tenant.yaml` at the repo root). Never leases around echo: speech is echo's GPU work.
|
|
135
|
+
- `narrative.py` — `Narrator(store, generator=, persona=, memory=, tariff=, tz=, clock=, max_tokens=, context_tokens=)`: `gather(kind, groups=)` → `Facts` (open groups, proposed + approved recommendations, `recent_rejections`, `TariffFact`, notes); `build_prompt` → (`Prompt`, `Selection`): fact lines get a priority tier (critical 1, warning 2, rejections 3, notice 4, info 5, notes 6; header and tariff 0), and `select_lines` takes them in tier order until the next doesn't fit in `(context_tokens - max_tokens) * 4 * 0.9` chars minus the system prompt (monotonic cut; "N more not shown" per section; notes also capped at `memory.max_chars`). `compose()` asks the model, else `render_template` (deterministic, same facts); `report(kind, groups=, use_llm=, dry_run=, meta=)` stores a `Report` with meta (`severity`, `quiet_exempt` and `title` from `delivery_meta`: the worst item, plus for a briefing proposed/approved recommendations, `info` when nothing is open; `path` llm|template, `fallback_reason` budget|gpu_unavailable|error|disabled|no_llm, model, token counts, persona, `fingerprints`, `facts`: ids used and omitted counts). `build_narrator(config, store, budget, tariff=, coordinator=)` (wires `gpu.narrative_guard`).
|
|
136
|
+
- `tariff.py` — `Tariff` / `Plan` / `TariffPeriod` / `TariffTier`; `current_period`, `next_period_change`, `coverage_gaps`, `tiered_cost` (units above a capped last tier pay its rate); `TariffFile` (mtime reload, `None` on a bad file). Rates are in the currency's minor unit.
|
|
137
|
+
- `scheduler.py` — asyncio `Scheduler(store, clock=, sleep=)`: `add(name, async_fn, trigger, retry_delay=)`, `tick(wait=)`, `run_now`, `run_forever`, `start()` / `stop()`. Triggers: `Every(seconds)` and `DailyAt(time, tz, grace=)` (per-local-date slots, so DST fires once; a missed slot runs late only within `grace`, never a backlog). Last successful run per job persists in the store's `job_runs`, so restarts neither repeat nor reset. A raising job is logged, counted and retried after `retry_delay`; a job never overlaps itself. Clock and sleep are injected: tests never sleep.
|
|
138
|
+
- `cycles.py` — the jobs: `StatusCycle(store, policy_file, inbox=)` (reloads the heartbeat policy every run, so a bad edit degrades to defaults; skips rest hours; decides each `Inbox.open_grouped()` group with `explain`; with a `narrator`, writes a `status` report of the groups `report_gate` passed, capped at `report.max_items`, when at least one is news (`is_news`: no event in the group has been announced in its current form, which the store resets on first sight, a fingerprint change and a recurrence, or `reannounce_due`); it then marks the included groups announced (`mark_announced`) and sets `meta.speakable` from the groups whose `Decision.voice` is true (only the news ones under `voice.on_change_only`), or `False`), `AnalysisCycle(store, rules=, client=, approvals=, tariff=, tz=)` (reloads the signals file, evaluates threshold and tariff rules and merges them, runs the engine; skips without Prometheus or rules, and on an unparseable file; an outage makes rules unknown and never raises), `BriefingJob(kind, store, narrator=, deliver=)` (writes, stores and delivers one report; template when the model can't), `PollJob(bound_source, inbox)` (one per polling source, ingests via `Inbox.ingest`; with the config's `resolve_missing` and a complete `PollResult`, resolves the source's events the poll no longer lists). `deliver(report)` is the no-op delivery seam (phase 5 injects the channels dispatcher via the jobs' and `register_jobs`' `deliver=`). `register_jobs(scheduler, config, store, policy_file, tariff=, budget=, narrator=, deliver=, dispatcher=)` (the runtime passes its `TariffFile`, shared by the analysis cycle and the narrator, its `DailyBudget`, and its `Dispatcher`, which adds the `redeliver` sweep) names them `status`, `analysis`, `redeliver`, `briefing:<kind>@HH:MM`, `poll:<source>`; the name keys the persisted bookkeeping.
|
|
139
|
+
- `store/` — persistence (stdlib `sqlite3`, no ORM). `base.py`: the `Store` Protocol plus `InboxEntry`, `Transition`, `Report`, `JobRun`. `sqlite.py`: `SqliteStore(path)` (`":memory:"` for tests) — status events keyed by `(source, event_id)` with first/last seen, ack, fingerprint index and announce state; recommendations with a `recommendation_transitions` audit table (`save_recommendation(rec, by=, reason=, expected_status=, expected_revision=)`: pass the status and revision you loaded, `None` status for a new row; a mismatch raises `StaleRecommendation`, a non-lifecycle status change `IllegalTransition`, both `StoreConflict`, nothing written; every load-then-save in the engine and the routes passes it, the engine logs and skips a conflict, a route answers 409); runtime standing-approval rules (`StandingApprovals(store=...)` loads and writes through; file rules never stored); reports; scheduler `job_runs` (migration 2); recommendation `key` column + index (migration 3; `recommendations_by_key`, `recent_rejections`); signal rules' pending state `signal_pending` (migration 4); delivery records `deliveries` (migration 5: `record_delivery`, `delivered_channels`, `list_deliveries`, `delivery_counts`); events' `resolved_at` (migration 6: `resolve_missing(source, keep)`, a system-side close that open queries and `open_event_counts` exclude and the next sighting clears; never touches `acked_by`); daily usage counts `usage_counts` (migration 7: `usage_counts(day)`, `consume_usage(day, kind, limit, allow_over=)` atomic check-and-increment, `merge_usage` by max; `DailyBudget`'s `UsageCounter`); recommendation revisions `recommendation_revisions` (migration 9, a side table so a replay is harmless: every save bumps it and sets `rec.revision`; a row without one reads as 0; `update_recommendation(rec_id, change, expected_revision=)` checks it and applies `change` to the stored row in one transaction, for the decision routes); `transaction()` groups store calls into one commit (nested calls join it); permanent delivery refusals `delivery_refusals` (migration 8, a side table so a replay is harmless: `record_delivery(..., permanent=)`, `DeliveryRecord.permanent`, `undelivered_reports(since, max_failures=)` → `PendingDelivery` for the redelivery sweep); `copy_of(path)` for dry runs; scrape-time counts for `/metrics` (`recommendation_counts`, `approval_counts`, `open_event_counts`); `prune()`. Migrations are ordered scripts in `MIGRATIONS`, tracked by `PRAGMA user_version` and applied on open: append, never edit a shipped one. One connection behind an `RLock` (shared by the app and scheduler threads), WAL, foreign keys on. Datetimes are UTC ISO text with fixed microseconds, so they compare as strings.
|
|
140
|
+
- `inbox.py` — `Inbox(store, clock=)`: `ingest()` / `ingest_many()` (one store transaction for a batch) → `IngestResult` (`Outcome`: new / duplicate / escalated / updated / refreshed / recurred), `ack()`, `resolve_missing(source, present)`, `open()`, `open_grouped()` (→ `EventGroup` by fingerprint, which includes the source). `parse_envelope` is the strict validator for envelopes arriving as data (`InvalidEvent` names the field); `normalise` clips, coerces and strips bookkeeping. Records only: never moves a recommendation or sends anything.
|
|
141
|
+
- `sources/` — status sources as plugins. `base.py`: `Source` / `PollingSource` (`async poll`) / `PushSource` (`parse`, `authorize`) protocols, `SourceError`, `SourceAuthError(status)`, `PollResult` (a list with `complete`). `registry.py`: kinds from the `argus_scout.sources` entry-point group (built-ins always present and can't be overridden); `build_sources(config)` → `Sources` (bound sources + per-entry errors). `webhook.py`: `parse_webhook`, `check_token` (argus-cortex `auth.check_bearer`, fails closed), no route. `json_poll.py`: `poll_once` via `argus_cortex.net.afetch`, `map_response` (dotted `items` / `fields`; ids from `id:` paths, else the item's `event_id`, else a hash of summary + payload + link, never severity or timestamps; colliding derived ids fall back to the raw item's hash with a warning; an item naming another source is skipped).
|
|
142
|
+
- `channels/` — delivery channels as plugins. `base.py`: `Delivery` (`from_report` / `from_event`; `key` is the idempotency key, `report:<id>` or `event:<source>/<id>:<hash>:<announce count>`; `speakable` is `meta.speakable` or the text through `plain_speech`), `DeliveryResult`, `SpeechAudio`, the `Channel` (`kind`, `config_model`, `async deliver`) / `VoiceChannel` (+ `async play(audio, message)`) / `Synthesiser` protocols, `NullSynthesiser`, `ChannelError(msg, permanent=)` and its `SynthesisError` (`DeliveryResult.permanent` too: a failure the sweep never retries). `registry.py`: kinds from the `argus_scout.channels` entry-point group (a class built with its validated config; built-ins can't be overridden); `build_channels(config)` → `Channels` (bound channels + per-entry errors). `dispatcher.py`: `Dispatcher(channels, synthesiser=, gates=, store=, budget=)`; `deliver(message, force=, only=)` → `DispatchReport` (filters, idempotency via the store, concurrent fan-out with per-channel timeouts, speech synthesised once for all voice channels when the message has a `speakable` and `gates.voice` allows); `HeartbeatGates(policy_file, tz=)` (rest hours, `broadcast_gate`, `voice_gate` for items, `sources.scout` routing for reports); `OpenGates` for tests. `text.py` (append, fenced with `argus_cortex.fs.safe_join` + `O_NOFOLLOW`, rotation), `webhook.py` (`build_payload` schema `argus-scout.delivery` v1, `sign` HMAC, bounded retry via `afetch`; documented in `docs/channels.md`). Voice kinds (built-ins whose numpy is imported only when a channel is built; the constructor raises `MissingExtra` naming the extra): `audio.py` (`decode` wav / `pcm_s16le` / `pcm_f32le` to `Pcm`, `remix`, `resample` linear, `encode` to a `SampleFormat` `rate:bits:channels`, 24-bit in 4 bytes as Snapcast does; `AudioFormatError` for anything else); `snapcast.py` (`SnapcastConfig`; FIFO fenced by `open_fifo`: must exist and be a FIFO, `O_NONBLOCK`, `ENXIO` retried to `open_timeout`; `write_fifo` select + deadline; `SnapcastRpc` JSON-RPC over raw TCP or HTTP to the `control` host only; `plan` = setup calls with their undo, restored in reverse in a `finally`); `mask.py` (`MaskConfig`; `readiness` from `GET /health`; `POST /push?require_screen=true` raw s16le with `X-Sample-Rate` / `X-Audio-Format` / `X-Channels`; not ready or a 409 returns `DeliveryResult(ok=True, status="skipped")`, which the dispatcher neither records nor counts as failed; `transport: websocket` uses mask's `WS /session/<face>/source` instead: JSON hello `{sample_rate, channels, format: s16le, seed, disclose}`, `ready`, binary PCM frames of at most `WS_FRAME_BYTES` paced at real time + 1 s, `{"type":"end"}`, `done`; a face "already has a source" is skipped; `websockets` imported lazily, connection pinned via `pin()` = one resolve + `argus_cortex.net.check_url`, `process_redirect` refuses every redirect, `proxy=None`, `compression=None`, `max_size` capped). `echo.py`: `EchoSynthesiser(EchoConfig)`, argus-echo's shared HTTP contract re-implemented (`POST /synthesise/stream`, PCM layout from `X-Sample-Rate`/`X-Audio-Format`/`X-Channels`, float32 converted to `pcm_s16le` or WAV) plus the resident contract (`GET /health` as cortex `ResidentHealth`: down or `error` fails fast, `unloaded`/`loading` gets `load_timeout`); bounded body, echo host only, never a GPU lease, failures raise `SynthesisError` (permanent for a 4xx other than 408/429). No `echo` voice channel: echo has no speaker. `redeliver.py`: `RedeliveryJob(store, dispatcher, DeliveryConfig)`, the `redeliver` job (`delivery: {retry_interval, retry_max_age, max_attempts, speak_max_age}`): reports only, failed channels only, never past `max_attempts` or a permanent refusal, text only once older than `speak_max_age`; a `skipped` result writes no row, so it never counts toward `max_attempts`. `build_dispatcher(config, store=, policy_file=, ...)` wires them for the server and the CLI.
|
|
143
|
+
- `server/app.py` — `create_app(config, *, store=, budget=, inbox=, sources=, clock=, sleep=, run_scheduler=)` (`[server]` extra). The lifespan builds a `Runtime` (store, policy file, inbox, tariff, usage caps counted in the store, scheduler, metrics registry) on `app.state.runtime`, starts the scheduler and stops it on shutdown; building the app opens nothing. `Runtime.sources` holds the bound sources; `Runtime.channels` / `Runtime.dispatcher` the channels, and `await Runtime.deliver(report)` sends a stored report through them (inbox items reach channels only inside status reports; `Delivery.from_event` and the `event` type are interface for a later single-item path). `deliver_reports(dispatcher)` is the `deliver=` callable passed to `register_jobs`, so briefings and status reports go out as they are stored. Routes: `/health`, `/metrics` (always open, to any `Host`), FastAPI's docs and schema (off under `read_auth`) and the API (`server/routes/`). `install_guards` + `include_routes` are the only API wiring here.
|
|
144
|
+
- `server/guards.py` — the security boundary. `install_guards(app, server)`: `HostGuard(trusted_hosts)` outermost (every request but `HOST_OPEN_PATHS` = `/health`, `/metrics`: a `Host` that isn't an IP, `localhost` or a `server.trusted_hosts` name is a 400, against DNS rebinding), then `WriteGuard(constant_refuse)` when `read_only` (the default), then `WriteGuard(cross_site_refuse(allowed_origins, trusted_hosts))`. `write_auth(server)` = `argus_cortex.auth.bearer(token_env)` (no `token_env` → always 503); `source_auth(server)` for the push route = the source plugin's `authorize` (webhook: its own `token_env`, else the server token), credentials first: a name that isn't a push source is 404/405 only to the server token, else the same 401/503 a push source gives; `read_auth(server)` when `server.read_auth`. Auth dependencies carry `AUTH_MARK`; `iter_routes(app)` flattens FastAPI 0.16x's lazily included routers and `unguarded_routes(app)` reports any write route without guards, and a missing or non-outermost `HostGuard`. `read_bounded` / `read_json` (caps `EVENTS_MAX_BYTES` 256 KiB, `ACTION_MAX_BYTES` 8 KiB): write routes take `Request` and read the body after auth.
|
|
145
|
+
- `server/routes/` — `events.py` (`POST /api/events/{source}`, all-or-nothing batch, per-event inbox outcome; `POST /api/events/{source}/{event_id}/ack`; `GET /api/events` grouped), `recommendations.py` (manual `approve` / `reject` with `{by, reason, revision}`, proposed only and at the viewed revision, 409 otherwise, applied to the stored row through `store.update_recommendation` with the app clock; `GET /api/recommendations?status=&limit=`, `GET /api/recommendations/{id}` with history; no route past `approved`), `reads.py` (`GET /api/reports/latest?kind=`, `GET /api/policy/explain`, `GET /wall` as text/plain with control characters stripped), `models.py` (request bodies, unknown keys refused).
|
|
146
|
+
- `server/deps.py` — `get_runtime(conn)` (503 when the app isn't running).
|
|
147
|
+
- `server/metrics.py` — `ScoutCollector`, a custom collector on its own `CollectorRegistry` (never the global one) that reads the store, usage caps, tariff file and scheduler at scrape time, so values survive restarts. Families: `scout_usage_used` / `scout_usage_limit{kind}`, `scout_tariff_loaded`, `scout_tariff_period{plan,period}`, `scout_tariff_rate{plan,period,currency,unit}`, `scout_tariff_next_change_seconds{next_period}`, `scout_recommendations{status}`, `scout_approvals_total{source}`, `scout_inbox_open_events{severity}`, `scout_job_runs_total` / `scout_job_errors_total` / `scout_job_last_success_timestamp_seconds` / `scout_job_running{job}`, `scout_deliveries_total{channel,result}`.
|
|
148
|
+
- `examples/` (repo root) — commented config for each policy file scout reads; tests load them, so they must stay valid.
|
|
149
|
+
- `configdoc.py` — generates `docs/config.md` from the config models (types, defaults, constraints, and each field's `description=` or the docstring under it). Each section's example is validated when it renders. Improve a key's docs in `config.py`, never in `docs/config.md`.
|
|
150
|
+
- `docs/` — the guides (`sources`, `signals`, `narrative`, `channels`, `api`, `operations`) plus the generated `cli.md` and `config.md`. argus-handbook imports README.md and `docs/*.md` from `dev`: keep a `#` title first, placeholders in backticks (raw HTML is dropped there), relative links, and no private addresses or paths.
|
|
151
|
+
- `src/argus_scout/examples/` — packaged templates `argus-scout init` writes (`scout.yaml`, `env.example` → `.env.example`); tests validate them.
|
|
152
|
+
- `deploy/quickstart/` — compose (scout, Prometheus, node exporter, Ollama), its `prometheus.yml` and `config/`. The policy files in `config/` are copies of `examples/`: change both (`tests/test_quickstart.py` fails on drift). `.github/workflows/quickstart.yml` is this repo's own (not copier-managed).
|
|
153
|
+
|
|
154
|
+
## Commands
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
make install # uv venv + editable install with the "dev" extras
|
|
158
|
+
make test # pytest --tb=short -q
|
|
159
|
+
make lint # ruff check + format --check (pinned ruff 0.15.16)
|
|
160
|
+
make format # ruff format + --fix
|
|
161
|
+
make docs # regenerate docs/cli.md (Typer) and docs/config.md (python -m argus_scout.configdoc)
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
Run one test: `uv run --no-sync pytest tests/test_x.py::test_name -q`.
|
|
165
|
+
|
|
166
|
+
## Conventions & gotchas
|
|
167
|
+
|
|
168
|
+
- **Versioning is git-tag-derived** (`hatch-vcs`). Never hand-edit a version; `src/argus_scout/_version.py` is generated (gitignored). Tag `vX.Y.Z` to release.
|
|
169
|
+
- **`src/` layout, `py.typed`, Pydantic v2, `structlog`.** Ruff line-length 120; keep it clean (`make lint`) before committing.
|
|
170
|
+
- **Any endpoint that does something is a boundary.** There's no auth by default — treat reaching the port as host access. Gate state-changing routes behind the shared read-only / origin guards, and fence any caller-supplied path under a configured root.
|
|
171
|
+
- Wire schemas (if any) are checked in and verified in CI — regenerate and commit when the types change, don't let the committed copy drift.
|
|
172
|
+
|
|
173
|
+
## Branches
|
|
174
|
+
|
|
175
|
+
`dev` is the default branch and the base for every PR. Cut feature branches from `origin/dev` and bring them up to date by merging `origin/dev`, never `main`. Never push work to `main` or open a PR against it, except the release PR from `dev`: `main` must never be ahead of `dev`, with one exception. A release fast-forwards `main` to a `dev` commit that passed CI (`git push origin origin/dev:main`), then tags it. If `main` is protected, the release is a reviewed PR from `dev` into `main`, and merging it leaves a merge commit on `main` alone. That merge commit is the one exception to the rule: it leaves `main` one commit ahead of `dev` with an identical tree. Leave it there and don't merge `main` back into `dev`. Anything else on `main` that `dev` lacks is a mistake (`git diff origin/dev origin/main` must be empty). Once `main` carries such a commit it can't be fast-forwarded, so later releases are PRs too.
|
|
176
|
+
|
|
177
|
+
## CI / release
|
|
178
|
+
|
|
179
|
+
CI runs via the shared [`argus-ci`](https://github.com/smk762/argus-ci) reusable workflow. `docs.yml` runs its `docs-check` on every push: published docs (`README.md`, `docs/**/*.md`) must hold no private IPs, home/server paths or personal emails (use placeholders like `<GPU_HOST>`), and `docs/cli.md` must match the CLI — run `make docs` after changing a command or a config model (`docs/config.md` is checked by a test, not by CI's docs job). Release publishes to PyPI (OIDC trusted publishing) + GHCR on `v*` tags. Run `copier update` to pull template (CI/release/tooling) changes.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# syntax=docker/dockerfile:1
|
|
2
|
+
FROM python:3.12-slim
|
|
3
|
+
|
|
4
|
+
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
|
|
5
|
+
|
|
6
|
+
WORKDIR /app
|
|
7
|
+
|
|
8
|
+
# hatch-vcs derives the version from git history, so the build context must
|
|
9
|
+
# include .git (keep it out of .dockerignore for this image) and the image must
|
|
10
|
+
# have the git binary -- python:*-slim does not ship one, and without it the
|
|
11
|
+
# install below fails with "unable to detect version".
|
|
12
|
+
RUN apt-get update \
|
|
13
|
+
&& apt-get install -y --no-install-recommends git \
|
|
14
|
+
&& rm -rf /var/lib/apt/lists/*
|
|
15
|
+
|
|
16
|
+
COPY . .
|
|
17
|
+
|
|
18
|
+
RUN uv pip install --system --no-cache ".[server]"
|
|
19
|
+
|
|
20
|
+
# Mount a config directory at /config (scout.yaml, its .env, and the files it names). Relative paths in
|
|
21
|
+
# scout.yaml resolve against it, so the default store (scout.db) lands there too and survives restarts.
|
|
22
|
+
# Point SCOUT_CONFIG elsewhere to use another file. `serve` refuses to start without a valid config.
|
|
23
|
+
ENV SCOUT_CONFIG=/config/scout.yaml
|
|
24
|
+
VOLUME ["/config"]
|
|
25
|
+
|
|
26
|
+
EXPOSE 8400
|
|
27
|
+
# Bound off loopback inside the container: set server.read_auth: true unless only trusted hosts reach the port
|
|
28
|
+
# (serve warns when it is off).
|
|
29
|
+
CMD ["argus-scout", "serve", "--host", "0.0.0.0", "--port", "8400"]
|
|
30
|
+
|