argus-puppet 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.
Files changed (79) hide show
  1. argus_puppet-0.1.0/.copier-answers.yml +22 -0
  2. argus_puppet-0.1.0/.dockerignore +11 -0
  3. argus_puppet-0.1.0/.github/workflows/ci.yml +27 -0
  4. argus_puppet-0.1.0/.github/workflows/docs.yml +25 -0
  5. argus_puppet-0.1.0/.github/workflows/release.yml +187 -0
  6. argus_puppet-0.1.0/.github/workflows/suite.yml +14 -0
  7. argus_puppet-0.1.0/.gitignore +12 -0
  8. argus_puppet-0.1.0/.suite-rules-baseline.json +8 -0
  9. argus_puppet-0.1.0/CLAUDE.md +144 -0
  10. argus_puppet-0.1.0/Dockerfile +73 -0
  11. argus_puppet-0.1.0/LICENSE +21 -0
  12. argus_puppet-0.1.0/Makefile +35 -0
  13. argus_puppet-0.1.0/PKG-INFO +237 -0
  14. argus_puppet-0.1.0/README.md +185 -0
  15. argus_puppet-0.1.0/compose.yaml +76 -0
  16. argus_puppet-0.1.0/docs/cli.md +338 -0
  17. argus_puppet-0.1.0/docs/conditioning.md +265 -0
  18. argus_puppet-0.1.0/docs/deploy.md +183 -0
  19. argus_puppet-0.1.0/docs/index.md +112 -0
  20. argus_puppet-0.1.0/docs/metrics.md +369 -0
  21. argus_puppet-0.1.0/docs/models.md +142 -0
  22. argus_puppet-0.1.0/docs/pose-vector.md +169 -0
  23. argus_puppet-0.1.0/docs/server.md +337 -0
  24. argus_puppet-0.1.0/gpu-tenant.yaml +25 -0
  25. argus_puppet-0.1.0/pyproject.toml +82 -0
  26. argus_puppet-0.1.0/schema/puppet-wire.schema.json +1651 -0
  27. argus_puppet-0.1.0/src/argus_puppet/__init__.py +16 -0
  28. argus_puppet-0.1.0/src/argus_puppet/_version.py +24 -0
  29. argus_puppet-0.1.0/src/argus_puppet/age.py +150 -0
  30. argus_puppet-0.1.0/src/argus_puppet/cli.py +816 -0
  31. argus_puppet-0.1.0/src/argus_puppet/compare.py +180 -0
  32. argus_puppet-0.1.0/src/argus_puppet/config.py +174 -0
  33. argus_puppet-0.1.0/src/argus_puppet/embedding.py +590 -0
  34. argus_puppet-0.1.0/src/argus_puppet/estimator.py +340 -0
  35. argus_puppet-0.1.0/src/argus_puppet/extract.py +279 -0
  36. argus_puppet-0.1.0/src/argus_puppet/gpu.py +149 -0
  37. argus_puppet-0.1.0/src/argus_puppet/labels.py +323 -0
  38. argus_puppet-0.1.0/src/argus_puppet/library.py +417 -0
  39. argus_puppet-0.1.0/src/argus_puppet/metrics.py +369 -0
  40. argus_puppet-0.1.0/src/argus_puppet/models.py +729 -0
  41. argus_puppet-0.1.0/src/argus_puppet/primary.py +72 -0
  42. argus_puppet-0.1.0/src/argus_puppet/py.typed +0 -0
  43. argus_puppet-0.1.0/src/argus_puppet/registry.py +134 -0
  44. argus_puppet-0.1.0/src/argus_puppet/render.py +637 -0
  45. argus_puppet-0.1.0/src/argus_puppet/runtime.py +240 -0
  46. argus_puppet-0.1.0/src/argus_puppet/sampling.py +228 -0
  47. argus_puppet-0.1.0/src/argus_puppet/server/__init__.py +1 -0
  48. argus_puppet-0.1.0/src/argus_puppet/server/app.py +577 -0
  49. argus_puppet-0.1.0/src/argus_puppet/sidecars.py +77 -0
  50. argus_puppet-0.1.0/src/argus_puppet/skeleton.py +356 -0
  51. argus_puppet-0.1.0/src/argus_puppet/weights.py +212 -0
  52. argus_puppet-0.1.0/tests/conftest.py +206 -0
  53. argus_puppet-0.1.0/tests/posegen.py +255 -0
  54. argus_puppet-0.1.0/tests/synthetic_poses.py +100 -0
  55. argus_puppet-0.1.0/tests/test_age.py +112 -0
  56. argus_puppet-0.1.0/tests/test_cli.py +367 -0
  57. argus_puppet-0.1.0/tests/test_compare.py +251 -0
  58. argus_puppet-0.1.0/tests/test_config.py +85 -0
  59. argus_puppet-0.1.0/tests/test_embedding.py +325 -0
  60. argus_puppet-0.1.0/tests/test_estimator.py +259 -0
  61. argus_puppet-0.1.0/tests/test_extract.py +285 -0
  62. argus_puppet-0.1.0/tests/test_gpu.py +81 -0
  63. argus_puppet-0.1.0/tests/test_gpu_tenant.py +20 -0
  64. argus_puppet-0.1.0/tests/test_labels.py +182 -0
  65. argus_puppet-0.1.0/tests/test_library.py +447 -0
  66. argus_puppet-0.1.0/tests/test_metrics.py +405 -0
  67. argus_puppet-0.1.0/tests/test_models.py +286 -0
  68. argus_puppet-0.1.0/tests/test_must_never.py +220 -0
  69. argus_puppet-0.1.0/tests/test_primary.py +51 -0
  70. argus_puppet-0.1.0/tests/test_real_model.py +63 -0
  71. argus_puppet-0.1.0/tests/test_registry.py +37 -0
  72. argus_puppet-0.1.0/tests/test_render.py +508 -0
  73. argus_puppet-0.1.0/tests/test_runtime.py +198 -0
  74. argus_puppet-0.1.0/tests/test_sampling.py +189 -0
  75. argus_puppet-0.1.0/tests/test_server.py +313 -0
  76. argus_puppet-0.1.0/tests/test_server_sets.py +262 -0
  77. argus_puppet-0.1.0/tests/test_skeleton.py +114 -0
  78. argus_puppet-0.1.0/tests/test_smoke.py +8 -0
  79. argus_puppet-0.1.0/tests/test_weights.py +217 -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-puppet
8
+ description: 'Body pose for the Argus suite: whole-body keypoints, pose embeddings,
9
+ diversity and coverage metrics, and ControlNet pose conditioning (:8220)'
10
+ dockerfile: Dockerfile
11
+ github_owner: smk762
12
+ has_cli: true
13
+ has_server: true
14
+ image_name: argus-puppet
15
+ package_name: argus_puppet
16
+ post_test: uv run --no-sync argus-puppet schema --check
17
+ project_name: argus-puppet
18
+ python_min: '3.11'
19
+ ruff_pin: 0.15.16
20
+ test_extras: dev,server,cli,cpu
21
+ version_build_arg: true
22
+
@@ -0,0 +1,11 @@
1
+ # Allow-list: the image needs only what builds the wheel, plus the GPU tenant manifest.
2
+ # The version comes in as the VERSION build-arg, so .git is not needed (the Dockerfile installs no git).
3
+ *
4
+ !pyproject.toml
5
+ !README.md
6
+ !LICENSE
7
+ !gpu-tenant.yaml
8
+ !src/
9
+ src/argus_puppet/_version.py
10
+ **/__pycache__
11
+ **/*.py[cod]
@@ -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,server,cli,cpu"
22
+ post-test: "uv run --no-sync argus-puppet schema --check"
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_puppet.cli
22
+ cli-name: argus-puppet
23
+ install-extras: cli
24
+ secrets:
25
+ denylist: ${{ secrets.DOCS_DENYLIST }} # optional; unset = no private terms
@@ -0,0 +1,187 @@
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.11", "3.12"]
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_puppet; print(f'argus-puppet {argus_puppet.__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
+ # LOCAL EDIT (not from argus-pkg-template, which has no GPU-variant option yet; re-apply after `copier update`):
130
+ # the CPU image keeps its tags; the CUDA build (Dockerfile GPU=1) is the same tags with "-gpu"
131
+ # (0.1.0-gpu, 0.1-gpu, latest-gpu). Mirrors argus-curator's release workflow.
132
+ strategy:
133
+ matrix:
134
+ include:
135
+ - gpu: "0"
136
+ suffix: ""
137
+ - gpu: "1"
138
+ suffix: "-gpu"
139
+ permissions:
140
+ contents: read
141
+ packages: write
142
+ steps:
143
+ - uses: actions/checkout@v7
144
+ with:
145
+ ref: ${{ needs.release-tag.outputs.tag }}
146
+ # The version reaches the image as the VERSION build-arg, so no git history is needed.
147
+ fetch-depth: 1
148
+ - uses: docker/setup-buildx-action@v4
149
+ - uses: docker/login-action@v4
150
+ with:
151
+ registry: ghcr.io
152
+ username: ${{ github.actor }}
153
+ password: ${{ secrets.GITHUB_TOKEN }}
154
+ - id: meta
155
+ uses: docker/metadata-action@v6
156
+ with:
157
+ images: ghcr.io/${{ github.repository_owner }}/argus-puppet
158
+ flavor: |
159
+ suffix=${{ matrix.suffix }},onlatest=true
160
+ labels: org.opencontainers.image.revision=${{ needs.release-tag.outputs.sha }}
161
+ tags: |
162
+ type=semver,pattern={{version}},value=${{ needs.release-tag.outputs.tag }}
163
+ type=semver,pattern={{major}}.{{minor}},value=${{ needs.release-tag.outputs.tag }}
164
+ # LOCAL EDIT (as argus-forge): only a final release moves `latest`/`latest-gpu`; a `v0.2.0-rc1` tag must not.
165
+ type=raw,value=latest,enable=${{ !contains(needs.release-tag.outputs.tag, '-') }}
166
+ # The package version, from the tag: meta's version carries the "-gpu" suffix.
167
+ - id: ver
168
+ env:
169
+ TAG: ${{ needs.release-tag.outputs.tag }}
170
+ run: echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
171
+ # The image has no git and the context no .git, so the version goes in as a build-arg
172
+ # (SETUPTOOLS_SCM_PRETEND_VERSION in the Dockerfile).
173
+ - uses: docker/build-push-action@v7
174
+ with:
175
+ context: .
176
+ file: ./Dockerfile
177
+ push: true
178
+ build-args: |
179
+ VERSION=${{ steps.ver.outputs.version }}
180
+ GPU=${{ matrix.gpu }}
181
+ tags: ${{ steps.meta.outputs.tags }}
182
+ labels: ${{ steps.meta.outputs.labels }}
183
+ # A dispatch rebuilds an unchanged context, so a cached install layer
184
+ # would keep the old argus-cortex.
185
+ no-cache: ${{ github.event_name == 'repository_dispatch' }}
186
+ cache-from: type=gha,scope=image${{ matrix.suffix }}
187
+ cache-to: type=gha,mode=max,scope=image${{ matrix.suffix }}
@@ -0,0 +1,14 @@
1
+ name: Suite
2
+ on:
3
+ push:
4
+ branches: [dev, main]
5
+ tags: ["v*"]
6
+ pull_request:
7
+ branches: [dev, main]
8
+
9
+ permissions:
10
+ contents: read
11
+
12
+ jobs:
13
+ suite:
14
+ uses: smk762/argus-ci/.github/workflows/suite-check.yml@v1
@@ -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_puppet/_version.py
11
+ # agent worktrees and local Claude Code state
12
+ .claude/worktrees/
@@ -0,0 +1,8 @@
1
+ {
2
+ "version": 1,
3
+ "tools": {
4
+ "ruff": "0.15.16",
5
+ "semgrep": "1.180.0"
6
+ },
7
+ "entries": []
8
+ }
@@ -0,0 +1,144 @@
1
+ # CLAUDE.md — argus-puppet
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
+ Body pose for the Argus suite: whole-body keypoints, pose embeddings, diversity and coverage metrics, and ControlNet pose conditioning (:8220)
10
+
11
+ Shared code — the target taxonomy, wire-schema versioning, and the local/remote model contract — lives in **argus-cortex**; import it rather than re-implementing.
12
+
13
+ ## Argus suite
14
+ <!-- argus-suite: keep this block; argus-ci checks for it -->
15
+ This repo is part of the Argus suite. The suite map below lists every sibling and what it owns; check it before
16
+ building something a sibling may already do. **On every release, update this repo's row and capabilities in
17
+ argus-cortex's SUITE.md** (a PR to argus-cortex in the same release).
18
+
19
+ @../argus-core/SUITE.md
20
+
21
+ Not checked out? Read https://github.com/smk762/argus-cortex/blob/dev/SUITE.md
22
+
23
+ ## Must never happen
24
+
25
+ Each row names the test, CI job or lint that enforces it. Add a row for every rule this package must keep, and mark
26
+ it **UNENFORCED** until something checks it. When a rule bites, add a check rather than more prose.
27
+
28
+ | Never | Enforced by |
29
+ |---|---|
30
+ | A hand-edited version | `_version.py` is generated by hatch-vcs and gitignored |
31
+ | A new suite-rule violation (argus-ci's lint catalogue) | CI `suite-rules` job; `.suite-rules-baseline.json` may only shrink |
32
+ | A CLAUDE.md without the argus-suite block | CI `suite` job (argus-ci suite-check) |
33
+ | A state-changing route without the read-only and origin guards, or a caller-supplied path outside a configured root | `tests/test_must_never.py::test_every_unsafe_route_refuses_another_site`, `::test_read_only_mode_refuses_every_unsafe_route` (walk every POST/PUT/PATCH/DELETE route; `EXPECTED_UNSAFE` lists the five today), `::test_a_scan_path_escaping_the_data_root_is_refused` (`/pose/scan`, `/stats`, `/compare` paths) |
34
+ | Blocking inference or file I/O inside an `async def` route | suite-rules `blocking-in-async` (CI `suite-rules`); `tests/test_server.py::test_inference_runs_off_the_event_loop`, `tests/test_server_sets.py::test_compute_runs_off_the_event_loop` |
35
+ | An uncapped request: a body, a pose set (the distance matrix is O(N^2)) or a render canvas past its limit | `tests/test_server_sets.py::test_set_size_and_body_caps`, `::test_render_caps_pixels_and_people`; `tests/test_server.py::test_pose_errors_map_to_status_codes` |
36
+ | A body read past its cap on any route (chunked or declared, `/pose/scan` and multipart `/pose` included), or a set body validated before its results and people are counted | `tests/test_must_never.py::test_every_unsafe_route_refuses_an_over_cap_body_without_reading_it` (walks every unsafe route; `BODY_TYPES` names any non-JSON body); `tests/test_server.py::test_a_chunked_multipart_past_the_cap_is_refused_before_it_is_read_to_the_end`, `::test_the_scan_body_is_capped_checked_and_never_echoed`; `tests/test_server_sets.py::test_the_set_cap_bites_before_the_body_is_validated`, `::test_people_are_counted_before_the_body_is_validated` |
37
+ | A body read without a deadline (a slow client holding an admission slot) | `tests/test_must_never.py::test_every_unsafe_route_cuts_off_a_stalled_body_and_frees_its_slot` (every unsafe route: 408, no slot held); `tests/test_server.py::test_a_stalled_upload_is_408_and_frees_its_slot`; `tests/test_server_sets.py::test_a_stalled_json_body_is_408_and_frees_the_compute_slot` |
38
+ | A library entry from a frame that failed the age check (a face or body under 18, or not checkable) when the check is on | `tests/test_library.py::test_no_library_entry_comes_from_a_frame_that_failed_the_age_check`, `::test_the_age_check_keeps_out_minors_and_fails_closed`; `tests/test_cli.py::test_library_build_age_check`; `tests/test_age.py::test_anything_that_cannot_vouch_is_unavailable` (incl. a body whose `face_index` is not a returned face's) |
39
+ | An image sent to the age service without `--age-check`/`age_gate`, or to a URL a caller supplied | `tests/test_library.py::test_without_the_age_check_nothing_is_sent`, `tests/test_cli.py::test_without_age_check_no_estimator_is_built`; the URL is `Settings.age_url` only (`tests/test_age.py`) |
40
+ | A non-permissive estimator weight or an unpinned model file | `tests/test_must_never.py::test_every_model_is_permissive_and_pinned` (licence allow-list Apache-2.0/MIT/BSD; 64-hex sha256 for the file and any archive) |
41
+ | A model session built from bytes other than those just hashed (a memo vouching, or the file reopened after the check) | `tests/test_runtime.py::test_load_session_hashes_the_bytes_it_loads`, `::test_the_hash_memo_is_invalidated_by_any_change_to_the_file` |
42
+ | A pre-release tag moving `latest` / `latest-gpu` | `tests/test_must_never.py::test_only_a_final_release_moves_latest` |
43
+ | A tracked image, video or model file, or an image hidden in a base64 literal | `tests/test_must_never.py` (`git ls-files` media/model suffixes; base64 runs decoded for image magic) |
44
+ | A wire schema that drifts from `models.py` | CI `post-test`: `argus-puppet schema --check`; `tests/test_cli.py` |
45
+
46
+ ## Layout
47
+
48
+ `src/argus_puppet/` — the package. Key modules:
49
+
50
+ - `__init__.py` — version shim (`__version__` from `hatch-vcs`).
51
+ - `skeleton.py` — the COCO-WholeBody 133 layout as data: names, part slices (`BODY`, `FEET`, `FACE`, `LEFT_HAND`,
52
+ `RIGHT_HAND`, `PARTS`), `Joint` indices, limbs, `FLIP_PAIRS`/`FLIP_PERMUTATION`/`flip_horizontal`, and the OpenPose-18
53
+ convention (`to_openpose18`, limbs, colours, hand edges). Pure numpy, no I/O. Index keypoints through it, never by
54
+ bare numbers elsewhere.
55
+ - `models.py` — the Pydantic v2 wire contract (`puppet_version`, `PUPPET_VERSION`). Only top-level payloads
56
+ (`PoseResult`, `PoseSetStats`, `PoseSetComparison`, `PoseLibrary`, `Health`, `ScanSummary`) subclass the versioned
57
+ base; the request bodies (`ScanRequest`, `StatsRequest`, `CompareRequest`, `RenderRequest`, `PoseSetSource`,
58
+ `BarePose`) and `RenderOptions`/`MetricParams` are in the schema too. `MetricParams()` holds every metric default.
59
+ Once released, add a field: bump the minor and note it in the version comment; rename or remove one: a new major.
60
+ Then `make schema` and commit `schema/puppet-wire.schema.json`. Sidecars are `<stem>.pose.json` (`SIDECAR_SUFFIX`,
61
+ `sidecar_path`).
62
+ - `registry.py` — the pinned model table (`PinnedModel`, `MODELS`, `DEFAULT_*`/`LIGHT_*`, `model_ref`). Data only; a new
63
+ model needs a permissive licence and its sha256, or `tests/test_must_never.py` fails.
64
+ - `config.py` — `Settings.from_env()` (`ARGUS_PUPPET_*`), `ConfigError`, and `DEFAULT_PORT` (the only code constant for the port;
65
+ it may change).
66
+ - `runtime.py` — ONNX Runtime plumbing: `providers(device)` (CUDA only when ORT really has it), the capped CUDA arena
67
+ (`kSameAsRequested`, `Settings.gpu_mem_limit_mb` else 1024 MB per session), cached `load_session` built from the
68
+ bytes `read_model` just read and hashed (never reopened by path, no memo on the load path), `check_model` for
69
+ health/verify (hash memoised by path, device, inode, size, mtime and ctime), `ModelUnavailable` (ends with the
70
+ `argus-puppet models fetch` hint). onnxruntime is optional: never import it at module level.
71
+ - `estimator.py` — the numpy + ORT + Pillow pipeline (YOLOX raw head, then RTMPose SimCC; matches rtmlib to ~0 px).
72
+ `Estimator` protocol (`estimate(image) -> list[PersonPose]`, `provenance()`), `OnnxEstimator`, and
73
+ `get_estimator(settings, ...)`, which tests monkeypatch so the suite runs with no model files.
74
+ - `primary.py` — the primary subject: curator's `area * (0.5 + 0.5 * det_score)`, or the body best matching a
75
+ primary-face hint (mean of IoU and face coverage), falling back to area x score.
76
+ - `gpu.py` — leases from argus-iris via `argus_cortex.gpu` (kind `pose`, figures kept in step with `gpu-tenant.yaml`
77
+ by `tests/test_gpu.py`); none on CPU; `parse_priority` for `X-Argus-Priority`; `folder_lease` holds one lease per
78
+ folder run and hands it back on `should_yield()`.
79
+ - `extract.py` — the library API: `pose_image(bytes|path) -> PoseResult`, `pose_folder(root) -> Iterator[ImageOutcome]`
80
+ (atomic sorted-key sidecars, skip-existing, `sidecar_collision`, unreadable images reported), `scan() -> ScanSummary`.
81
+ Images decode through `argus_cortex.limits.open_image` with EXIF orientation.
82
+ - `sidecars.py` — read sidecars back: `find_sidecars`, `load_sidecar(s)`, `load_sidecars_with_paths`,
83
+ `image_for_sidecar` (the image a sidecar sits beside).
84
+ - `embedding.py` — the pose vector (body-17, hip-centred, robust torso scale, masked joints) and the mirror-invariant
85
+ distance (`pose_distance`, chunked `pairwise_distances`/`cross_distances`). Pure numpy. See `docs/pose-vector.md`.
86
+ - `labels.py` — `pose_labels(kp)`: stance / arms / facing from geometry rules (named threshold constants).
87
+ - `metrics.py` — `pose_set_stats(results, params=)`: diversity, average-linkage clusters (NN-chain, `average_linkage`,
88
+ `cluster_ids`), coverage, 2D projection; `keypoint_distance_matrix` (the library's distance), `shared_estimator`.
89
+ - `compare.py` — `compare_pose_sets(outputs, reference, threshold=0.08, params=)`: nearest reference per output (null
90
+ when none is comparable), memorised share over matched outputs, coverage JS divergence. See `docs/metrics.md`.
91
+ - `render.py` — OpenPose-convention control images from scratch (numpy + Pillow): `render_pose/array/png`,
92
+ `canvas_size`, `canvas_transform`; `RenderOptions` carries fit/stroke/margin/primary, keywords override. Limbs
93
+ reproduce `cv2.ellipse2Poly` + `fillConvexPoly` in numpy (`_ellipse_polygon`, `_fill_convex_polygon`; pixel-exact
94
+ at stroke scale 1, never import OpenCV); geometry is truncated on the annotator's grid (canvas / k) as it does.
95
+ - `sampling.py` — generic `deduplicate` and `farthest_point_sample` over a distance matrix (NaN = incomparable).
96
+ - `library.py` — `build_library` (real distance, `pose_labels`, average-linkage clusters and 0.08 dedupe by default;
97
+ optional `AgeGate`), `sample`, `render_entries`, `save_library`/`load_library`. See `docs/conditioning.md`.
98
+ - `age.py` — the age fail-safe: `AgeEstimator` protocol, `HttpAgeEstimator` (argus-curator `POST /faces?body=true` at
99
+ `Settings.age_url` via `argus_cortex.net.fetch`, one host allowed, timeout + deadline, no redirects),
100
+ `min_age_from_payload` (fails closed). Callers exclude anything that raised or read `None`.
101
+ - `weights.py` — `models list|fetch|verify`: downloads via `argus_cortex.net.fetch` from `ALLOWED_HOSTS` only,
102
+ archive sha256 then the one zip member (never `extractall`), onnx sha256 + size, atomic write.
103
+ - `cli.py` — Typer app; entry point `argus-puppet` (`[project.scripts]`): `pose`, `stats`, `compare`, `render`,
104
+ `library build|sample`, `serve`, `models list|fetch|verify`, `schema`, `version`. Heavy imports inside commands; logs
105
+ go to stderr (the callback configures structlog) so `--json` stdout stays parseable. Run `make docs` after.
106
+ - `server/app.py` — `create_app(settings, *, estimator=, coordinator=)` (and a lazy module-level `app` for uvicorn):
107
+ `GET /health`, `POST /pose` (writes nothing; inference via `asyncio.to_thread`, bounded concurrency -> 503), `POST
108
+ /pose/scan` (the one write; `path` fenced under `Settings.data_root` with `safe_join`), `POST /stats`, `/compare`
109
+ (sets inline or as sidecar folders fenced like `/pose/scan`; `max_set_results` per set) and `/render` (PNG;
110
+ `max_pixels`, `max_people`). Every body is read through `read_capped` (its cap counted as it streams, declared
111
+ length or not; `Settings.body_timeout_s` deadline -> 408); JSON bodies through `read_json` on top (`max_json_bytes`,
112
+ 16 KiB for `/pose/scan`, 4 MiB for `/render`; set bodies pre-counted on the raw bytes by `set_precheck`; 422 without
113
+ echoing input), compute through `asyncio.to_thread` under `AppState.compute_admit`. A new route reads its body
114
+ through these, never `request.body()`/`.form()` or a FastAPI body parameter. `install_guards` wires them so a
115
+ request meets CORS (outermost), then the read-only guard, then the origin guard. Shared state for new routes:
116
+ `app.state.puppet` (`AppState`).
117
+ - `gpu-tenant.yaml` (repo root) — the argus-iris tenant manifest (kind `pose`); `tests/test_gpu_tenant.py` validates it.
118
+
119
+ ## Commands
120
+
121
+ ```bash
122
+ make install # uv venv + editable install with the dev,server,cli,cpu extras
123
+ make schema # regenerate schema/puppet-wire.schema.json (CI checks it)
124
+ make test # pytest --tb=short -q
125
+ make lint # ruff check + format --check (pinned ruff 0.15.16)
126
+ make format # ruff format + --fix
127
+ ```
128
+
129
+ Run one test: `uv run --no-sync pytest tests/test_x.py::test_name -q`.
130
+
131
+ ## Conventions & gotchas
132
+
133
+ - **Versioning is git-tag-derived** (`hatch-vcs`). Never hand-edit a version; `src/argus_puppet/_version.py` is generated (gitignored). Tag `vX.Y.Z` to release.
134
+ - **`src/` layout, `py.typed`, Pydantic v2, `structlog`.** Ruff line-length 120; keep it clean (`make lint`) before committing.
135
+ - **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.
136
+ - 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.
137
+
138
+ ## Branches
139
+
140
+ `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.
141
+
142
+ ## CI / release
143
+
144
+ 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. Release publishes to PyPI (OIDC trusted publishing) + GHCR on `v*` tags. Run `copier update` to pull template (CI/release/tooling) changes.
@@ -0,0 +1,73 @@
1
+ # syntax=docker/dockerfile:1
2
+ #
3
+ # argus-puppet: the pose service on :8220. One file, two images:
4
+ #
5
+ # docker build --build-arg VERSION=0.1.0 -t argus-puppet . # CPU (:<version>)
6
+ # docker build --build-arg VERSION=0.1.0 --build-arg GPU=1 -t argus-puppet:gpu . # CUDA (:<version>-gpu)
7
+ #
8
+ # Models are not baked in: mount a volume at /models and fill it with `argus-puppet models fetch` (docs/deploy.md).
9
+ FROM python:3.11-slim
10
+
11
+ # Pin past the eMudhra/emSign incident (discuss.python.org/t/109576). A floating
12
+ # :latest tag can stay cached on a pre-0.13.4 digest.
13
+ COPY --from=ghcr.io/astral-sh/uv:0.13.5 /uv /uvx /bin/
14
+
15
+ # Distrust emSign ECC Root CA - G3 and the Comodo AAA cross-sign root.
16
+ RUN apt-get update \
17
+ && apt-get install -y --no-install-recommends ca-certificates \
18
+ && sed -i \
19
+ -e 's|^mozilla/emSign_ECC_Root_CA_-_G3|!mozilla/emSign_ECC_Root_CA_-_G3|' \
20
+ -e 's|^mozilla/Comodo_AAA|!mozilla/Comodo_AAA|' \
21
+ /etc/ca-certificates.conf \
22
+ && update-ca-certificates --fresh >/dev/null \
23
+ && rm -rf /var/lib/apt/lists/*
24
+
25
+ WORKDIR /app
26
+
27
+ # The version is handed in (the release tag without the "v"), so the build context carries no .git and the image
28
+ # needs no git binary: hatch-vcs (setuptools-scm) reads SETUPTOOLS_SCM_PRETEND_VERSION instead of walking history.
29
+ # It must be the plain name -- hatch-vcs ignores the ..._FOR_ARGUS_PUPPET spelling. It is exported only for the
30
+ # install below, not baked into the image's environment. The default keeps a bare `docker build .` working.
31
+ ARG VERSION=0.0.0.dev0
32
+ # GPU=1 builds the CUDA image: the [gpu] extra (onnxruntime-gpu, NVML and the broker client) instead of [cpu], with
33
+ # the CUDA and cuDNN runtimes as NVIDIA's pip wheels (onnxruntime-gpu[cuda,cudnn]) so the base stays python-slim;
34
+ # argus_puppet.runtime preloads them through onnxruntime.preload_dlls(). It needs the NVIDIA container runtime and a
35
+ # driver new enough for the CUDA major that onnxruntime-gpu targets. The default (0) is the CPU image.
36
+ ARG GPU=0
37
+
38
+ COPY . .
39
+
40
+ RUN export SETUPTOOLS_SCM_PRETEND_VERSION="$VERSION" \
41
+ && if [ "$GPU" = "1" ]; then \
42
+ uv pip install --system --no-cache "certifi>=2026.10.19" ".[server,cli,gpu]" "onnxruntime-gpu[cuda,cudnn]" \
43
+ # The CPU onnxruntime wheel shares onnxruntime-gpu's module directory and wins if anything pulled it in: \
44
+ # drop it and lay the GPU build back down, then fail the build unless the CUDA provider is really there. \
45
+ && if uv pip show --system onnxruntime >/dev/null 2>&1; then \
46
+ ort_gpu="$(uv pip show --system onnxruntime-gpu | sed -n 's/^Version: //p')" \
47
+ && uv pip uninstall --system onnxruntime \
48
+ && uv pip install --system --no-cache --reinstall --no-deps "onnxruntime-gpu==$ort_gpu"; \
49
+ fi \
50
+ && python -c "import onnxruntime as o, sys; p = o.get_available_providers(); print('providers:', p); sys.exit(0 if 'CUDAExecutionProvider' in p else 'CUDAExecutionProvider missing')"; \
51
+ else \
52
+ uv pip install --system --no-cache "certifi>=2026.10.19" ".[server,cli,cpu]"; \
53
+ fi \
54
+ && argus-puppet version
55
+
56
+ # Unprivileged at run time. /models is the model volume (the image ships none); a named volume inherits this
57
+ # ownership, so `argus-puppet models fetch` can write into it. The home directory is where onnxruntime keeps its
58
+ # small per-user state; without a writable one it warns on every start.
59
+ RUN useradd --uid 10001 --user-group --create-home --home-dir /home/puppet --shell /usr/sbin/nologin puppet \
60
+ && mkdir -p /models \
61
+ && chown puppet:puppet /models
62
+ ENV ARGUS_PUPPET_MODEL_DIR=/models \
63
+ ARGUS_GPU_TENANT_MANIFEST=/app/gpu-tenant.yaml \
64
+ PYTHONUNBUFFERED=1
65
+ VOLUME /models
66
+ USER puppet
67
+
68
+ EXPOSE 8220
69
+ # GET /health may hash the model files once on its first call, hence the generous start period. No curl in slim.
70
+ HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
71
+ CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8220/health', timeout=8)"]
72
+ # 0.0.0.0 inside the container; which host address it is published on is compose's (or `docker run -p`'s) choice.
73
+ CMD ["argus-puppet", "serve", "--host", "0.0.0.0", "--port", "8220"]
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 smk762
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,35 @@
1
+ UV ?= uv
2
+
3
+ .PHONY: help install lint format test build clean docs schema
4
+
5
+ help: ## Show this help
6
+ @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-12s\033[0m %s\n", $$1, $$2}'
7
+
8
+ install: ## Create venv and install with test extras
9
+ $(UV) venv
10
+ $(UV) pip install -e ".[dev,server,cli,cpu]"
11
+
12
+ lint: ## Ruff check + format check
13
+ $(UV)x ruff@0.15.16 check src/ tests/
14
+ $(UV)x ruff@0.15.16 format --check src/ tests/
15
+
16
+ format: ## Ruff autoformat + autofix
17
+ $(UV)x ruff@0.15.16 format src/ tests/
18
+ $(UV)x ruff@0.15.16 check --fix src/ tests/
19
+
20
+ test: ## Run the test suite
21
+ $(UV) run --no-sync pytest --tb=short -q
22
+
23
+ schema: ## Regenerate the committed wire schema (CI fails if it drifts)
24
+ $(UV) run --no-sync argus-puppet schema
25
+
26
+ docs: ## Regenerate docs/cli.md from the Typer CLI (CI fails if it drifts)
27
+ $(UV) pip install -e ".[cli]"
28
+ mkdir -p docs
29
+ $(UV) run --no-sync python -m typer argus_puppet.cli utils docs --name argus-puppet --output docs/cli.md
30
+
31
+ build: ## Build sdist + wheel
32
+ $(UV) build
33
+
34
+ clean: ## Remove build + cache artifacts
35
+ rm -rf dist build .venv *.egg-info .pytest_cache .ruff_cache src/argus_puppet/_version.py