argus-darkroom 0.1.0__tar.gz

argus_darkroom-0.1.0/.copier-answers.yml

@@ -0,0 +1,21 @@
+# Managed by Copier — do not edit by hand.
+# Run `copier update` in this repo to pull template changes.
+_commit: b53a3a4
+_src_path: /home/smk/argus-pkg-template
+author: smk762
+cli_name: argus-darkroom
+description: 'Guarded image generation for the Argus suite: prompts and outputs are
+    checked before anything is released.'
+dockerfile: Dockerfile
+github_owner: smk762
+has_cli: true
+has_server: true
+image_name: argus-darkroom
+package_name: argus_darkroom
+post_test: ''
+project_name: argus-darkroom
+python_min: '3.11'
+ruff_pin: 0.15.16
+test_extras: dev
+version_build_arg: false
+

argus_darkroom-0.1.0/.cursor/rules/git-workflow.mdc

@@ -0,0 +1,20 @@
+---
+description: Keep main releasable by doing work on dev in a worktree
+alwaysApply: true
+---
+
+# Git workflow
+
+`main` is the release branch. Do not commit on it, and do not push it.
+
+`dev` is `main` plus updates that are not released yet. Before starting work, fetch and merge `origin/main` into `dev`.
+
+Do each change in a worktree branched from `dev`. Open a pull request into `dev`. A release is a pull request from `dev` into `main`.
+
+```bash
+git fetch origin
+git switch dev && git merge origin/main
+git worktree add ../argus-darkroom-<topic> -b <topic> dev
+```
+
+Do not force-push `main`. Do not commit secrets.

argus_darkroom-0.1.0/.dockerignore

@@ -0,0 +1,11 @@
+# .git stays: hatch-vcs derives the version from it.
+.env
+.env.*
+!.env.example
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+darkroom-output/
+dist/
+build/

argus_darkroom-0.1.0/.env.example

@@ -0,0 +1,45 @@
+# Copy to .env. Compose reads it; nothing here is a secret, but .env is git-ignored all the same.
+
+# --- Required ---------------------------------------------------------------
+# SingGuard (agent-composer's /api/guard/check). Darkroom never runs unguarded: without this it refuses to start.
+SINGGUARD_URL=http://host.docker.internal:9150
+# ComfyUI models root (the folder that holds checkpoints/ and loras/). Mounted read-only; hashed for the record.
+# Use the directory ComfyUI actually lists — if it loads models via extra_model_paths.yaml, that folder, not models/.
+MODELS_ROOT=/path/to/ComfyUI/models
+
+# --- Backends, reached by URL (they run outside compose) ---------------------
+COMFYUI_URL=http://host.docker.internal:8188
+# NudeNet. Empty means SFW generation is unavailable (every SFW output would be omitted), so darkroom refuses it.
+NUDENET_URL=
+# Curator's POST /faces?body=true (InsightFace + MiVOLO, body crop and unmatched people). Empty falls back to the in-process [age] extra.
+AGE_URL=http://host.docker.internal:8101
+# Prompt expansion. Both must be set to turn it on.
+OLLAMA_URL=
+OLLAMA_MODEL=
+
+# --- Policy ------------------------------------------------------------------
+# 1 lets an NSFW policy enforce (and makes adult-granular the default). Anything else: SFW only.
+ALLOW_NSFW=0
+# cascade | fast | fast-slow | slow
+THINKING=cascade
+# 1 refuses every write: generation, pre-flight and record changes. Records stay readable.
+READ_ONLY=0
+# Origin(s) of the UI allowed to write, comma separated. Safelight's address as the browser sees it.
+CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
+
+# --- Development -------------------------------------------------------------
+# 1 adds POST /purge and the purge button in safelight: it deletes every record and image. Leave off elsewhere.
+DEVMODE=0
+
+# --- Publish -------------------------------------------------------------------
+# Host:port published for each service. 127.0.0.1 keeps them off the LAN.
+# Use 0.0.0.0:<port> only when the UI is opened as a LAN address (the browser then
+# calls that same host). Darkroom is not for public hosting.
+DARKROOM_PUBLISH=127.0.0.1:8106
+SAFELIGHT_PUBLISH=127.0.0.1:3000
+
+# --- Safelight -----------------------------------------------------------------
+# Where the browser reaches darkroom. Baked into the safelight image when it is built.
+DARKROOM_PUBLIC_URL=http://localhost:8106
+# Safelight's repo, as a build context, until it publishes an image.
+SAFELIGHT_CONTEXT=../argus-safelight

argus_darkroom-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    uses: smk762/argus-ci/.github/workflows/python-ci.yml@v1
+    with:
+      ruff-version: "0.15.16"
+      test-extras: "dev"
+
+  # The wire schema is a contract other repos generate code from: a model change must come with the regenerated file.
+  schema:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # hatch-vcs reads the version from git history
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv venv && uv pip install -e ".[cli]"
+      - run: uv run --no-sync argus-darkroom schema --check
+

argus_darkroom-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,163 @@
+name: Release to PyPI
+
+# Top-level (non-reusable) on purpose: PyPI trusted publishing cannot run inside
+# a reusable workflow. Keep this file in sync across the suite via `copier update`.
+
+on:
+  push:
+    tags: ["v*"]
+  # Sent by argus-cortex's release workflow. The image installs argus-cortex
+  # from the pyproject range at build time, so rebuilding the newest release's
+  # image is how a new cortex reaches it. Only the image jobs run: PyPI and the
+  # GitHub Release for that tag already exist.
+  repository_dispatch:
+    types: [cortex-released]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    # Not on a cortex dispatch, so the PyPI and Release jobs that chain off it
+    # skip too.
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  test-install:
+    runs-on: ubuntu-latest
+    needs: build
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Install wheel and smoke-test import
+        run: |
+          uv venv --python ${{ matrix.python-version }}
+          uv pip install dist/*.whl
+          uv run --no-sync python -c "import argus_darkroom; print(f'argus-darkroom {argus_darkroom.__version__} OK')"
+
+  publish-testpypi:
+    runs-on: ubuntu-latest
+    needs: test-install
+    environment: testpypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    runs-on: ubuntu-latest
+    # Ordered *after* the TestPyPI rehearsal so its outcome is visible first, but
+    # deliberately not gated on it. A TestPyPI-only fault — a missing trusted
+    # publisher, an index outage — must not silently withhold the real release:
+    # that failure mode shipped argus-proof images for two tags with no wheel on
+    # PyPI, and nothing surfaced it because publish-image is independent.
+    # Only the build + install gate is required; a TestPyPI failure still marks
+    # the whole run failed, so the problem stays loud.
+    needs: [test-install, publish-testpypi]
+    if: "!cancelled() && needs.test-install.result == 'success'"
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  release-tag:
+    # The tag the image jobs build: the pushed one, or on a cortex dispatch the
+    # newest final release. A pre-release never moved `latest`, so a dispatch
+    # does not rebuild one.
+    runs-on: ubuntu-latest
+    outputs:
+      tag: ${{ steps.tag.outputs.tag }}
+      sha: ${{ steps.tag.outputs.sha }}
+    steps:
+      - uses: actions/checkout@v4
+        if: github.event_name == 'repository_dispatch'
+      - id: tag
+        env:
+          CORTEX_VERSION: ${{ github.event.client_payload.version }}
+        run: |
+          if [ "$GITHUB_EVENT_NAME" != repository_dispatch ]; then
+            echo "tag=$GITHUB_REF_NAME" >> "$GITHUB_OUTPUT"
+            echo "sha=$GITHUB_SHA" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          refs=$(git ls-remote --tags origin 'refs/tags/v*')
+          tag=$(echo "$refs" | sed -n 's|.*refs/tags/\(v[0-9]*\.[0-9]*\.[0-9]*\)\(\^{}\)\{0,1\}$|\1|p' | sort -uV | tail -n1)
+          if [ -z "$tag" ]; then
+            echo "::notice::No release tag yet, so no image to rebuild for cortex $CORTEX_VERSION."
+            exit 0
+          fi
+          # An annotated tag lists its commit on the peeled ^{} line.
+          sha=$(echo "$refs" | awk -v t="refs/tags/$tag" '$2 == t {l = $1} $2 == t "^{}" {p = $1} END {print p ? p : l}')
+          echo "Rebuilding $tag ($sha) for cortex $CORTEX_VERSION."
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+          echo "sha=$sha" >> "$GITHUB_OUTPUT"
+
+  publish-image:
+    runs-on: ubuntu-latest
+    needs: [release-tag, test-install]
+    # On a cortex dispatch test-install is skipped (nothing was built for PyPI),
+    # so the job runs on the tag alone.
+    if: "!cancelled() && needs.release-tag.outputs.tag != '' && (needs.test-install.result == 'success' || github.event_name == 'repository_dispatch')"
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release-tag.outputs.tag }}
+          fetch-depth: 0 # hatch-vcs reads the tag from git history
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/argus-darkroom
+          labels: org.opencontainers.image.revision=${{ needs.release-tag.outputs.sha }}
+          tags: |
+            type=semver,pattern={{version}},value=${{ needs.release-tag.outputs.tag }}
+            type=semver,pattern={{major}}.{{minor}},value=${{ needs.release-tag.outputs.tag }}
+            type=raw,value=latest
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          # A dispatch rebuilds an unchanged context, so a cached install layer
+          # would keep the old argus-cortex.
+          no-cache: ${{ github.event_name == 'repository_dispatch' }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

argus_darkroom-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+# compose settings; .env.example is the committed template
+.env
+compose.override.yaml
+darkroom-output/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+# hatch-vcs writes this at build time (version derived from git tags)
+src/argus_darkroom/_version.py
+demo-data/

argus_darkroom-0.1.0/CLAUDE.md

@@ -0,0 +1,60 @@
+# argus-darkroom
+
+Guarded image generation. Read `spec.md` for the design and `README.md` for running it. This file is the rules that must
+not be broken and where things are.
+
+## Rules that must hold
+
+- **Nothing is written before the verdict.** No temp file, no cortex blob, no `SaveImage`/`PreviewImage` node. A
+  deleted or omitted image is never written, and its buffer is dropped. `tests/test_generate.py` lists the output root,
+  the system temp directory and the fake ComfyUI history before and after to prove it.
+- **Never run unguarded.** An empty `SINGGUARD_URL` refuses to start (`Settings.__post_init__`). A failed check is an
+  `unchecked` cell, never a pass. An unchecked enforcing cell deletes; an unchecked advisory cell is only shown.
+- **Every check judges the final prompt**, expansion included. The negative prompt is always part of pre-flight. Do not
+  add a path that checks only the user's text.
+- **Policies are chosen by name only.** Never accept policy text in a request. Policy texts, the illegal table and
+  `mode()` live in `argus_cortex.moderation.policies`; do not copy them here.
+- **Fail closed.** If you are unsure whether an error should refuse, delete or pass, it refuses or deletes.
+- **Never import NudeNet** (AGPL). Reach it over HTTP through cortex's `NudeNetClient`.
+- **The server binds to localhost by default.** Writes need `WriteGuard` and `cross_site_refuse`. `POST /purge` exists
+  only with `ARGUS_DARKROOM_DEVMODE` and answers 404 otherwise.
+- **The age is a tool's estimate.** Name it `age_estimate_years`, source `mivolo`. Never call it an age, and never send
+  it to SingGuard as context.
+- **No real sexual, violent or illegal content** in the repo or tests. Drive the illegal path with a fake verdict.
+
+## Layout
+
+| | |
+|---|---|
+| `engine.py` | `Engine`: `begin` validates, `_run` expands, pre-flights, renders, scans, decides, releases or destroys |
+| `outcome.py` | the outcome table (`decide`). Precedence: deleted, omitted (SFW), review, passed. Unit-test any change by cell combination |
+| `preflight.py`, `scan.py`, `guard.py` | the text check, the image scans, and the SingGuard wrapper that turns failures into `unchecked` |
+| `prompt.py` | `assemble_prompt`, and `frame` (folds line breaks so text cannot pose as the frame's labels) |
+| `expansion.py` | `OllamaExpander`. Ollama is never a guard |
+| `comfyui.py`, `workflow.py`, `modelfiles.py`, `hashing.py` | render over the websocket, the `$placeholder` template, model sha256s |
+| `age.py` | curator over `AGE_URL` (`POST /faces?body=true`), or in-process `detect_faces` behind the `[age]` extra |
+| `store.py` | `<id>.json` and `<id>.png` in the output root; atomic image write |
+| `models.py` | the versioned wire models. `schema/darkroom-wire.schema.json` is generated from them |
+| `demo/run.py`, `demo/smoke.py` | the real server and engine over the test fakes; a marker in the prompt picks the verdicts. Demo only: it turns `DEVMODE` on and uses fake models |
+| `server/app.py`, `cli.py`, `config.py`, `request.py` | HTTP, Typer, `ARGUS_DARKROOM_*`, the request model (`extra=forbid`) |
+
+## Working
+
+```bash
+make install && make test && make lint
+uv run --no-sync argus-darkroom schema --check   # after any change to models.py: run `schema`, commit the file
+```
+
+- `main` is releases, `dev` is work. Work in a worktree from `dev`, and open PRs into `dev`. CI runs on `main` only, so
+  run lint, tests and `schema --check` locally before every PR.
+- Use `docker compose`, not `docker-compose`.
+- The record is a wire contract (`record_version`). Adding a field is fine; renaming or removing one is a new version.
+  The blur decision lives only in `guard.nudenet.blur`, which is recorded for every NSFW-policy image (`exposed_score`
+  is `null` when NudeNet was unreachable). Each LoRA records the `trigger_words` the request supplied.
+- argus-safelight codes against the HTTP shapes in the README's API table (`/health`, `/policies`, `/models`, `/records`
+  paging, SSE event bodies). Change one and `make demo` plus `make smoke` show whether the UI still works; update
+  safelight's `types.ts` in step.
+- Tests use fake servers on real sockets (`tests/fakes.py`, `tests/fake_comfyui.py`, `tests/rig.py`). Prefer extending
+  them to mocking.
+- `scripts/preflight_eval.py` is run by hand against a real SingGuard that supports text-only checks (agent-composer
+  PR #4). It is not a test.

argus_darkroom-0.1.0/Dockerfile

@@ -0,0 +1,62 @@
+# syntax=docker/dockerfile:1
+FROM python:3.11-slim AS base
+
+# Pin past the eMudhra/emSign incident (discuss.python.org/t/109576). A floating
+# :latest tag can stay cached on a pre-0.13.4 digest.
+COPY --from=ghcr.io/astral-sh/uv:0.13.5 /uv /uvx /bin/
+
+WORKDIR /app
+
+# Distrust emSign ECC Root CA - G3 and the Comodo AAA cross-sign root, then
+# replace the base image's pip. pip < 26.2.2 trusts its vendored bundle in
+# addition to the system store.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates \
+    && sed -i \
+        -e 's|^mozilla/emSign_ECC_Root_CA_-_G3|!mozilla/emSign_ECC_Root_CA_-_G3|' \
+        -e 's|^mozilla/Comodo_AAA|!mozilla/Comodo_AAA|' \
+        /etc/ca-certificates.conf \
+    && update-ca-certificates --fresh >/dev/null \
+    && rm -rf /var/lib/apt/lists/* \
+    && python -m pip install --no-cache-dir \
+        "pip @ https://files.pythonhosted.org/packages/3f/06/3e4420302363fbb71be3c7f35ce042f54bfca330e3e66b3a2e3c4cca579f/pip-26.2.2-py3-none-any.whl#sha256=fd7f4dfa8190e014013b9f08f3e973f4e4c26ffd179a204895533a7254813a70"
+
+
+# hatch-vcs derives the version from git history, so this stage needs git and a build context that includes .git
+# (keep it out of .dockerignore). Only the wheel leaves this stage: git and the history stay behind.
+FROM base AS build
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends git \
+    && rm -rf /var/lib/apt/lists/*
+COPY . .
+RUN git config --global --add safe.directory /app && uv build --wheel --out-dir /wheel
+
+
+FROM base
+COPY --from=build /wheel /wheel
+RUN uv pip install --system --no-cache "certifi>=2026.10.19" "$(ls /wheel/*.whl)[server,cli]" \
+    && rm -rf /wheel
+
+# The age check (the `age` extra) pulls in onnxruntime and InsightFace and needs the MiVOLO model file, so it is left
+# out of the image; /health reports it as unavailable and records get `age: null`.
+
+# The example workflows are the default template; mount your own and set ARGUS_DARKROOM_WORKFLOW to use it.
+COPY examples ./examples
+ENV ARGUS_DARKROOM_OUTPUT_ROOT=/data \
+    ARGUS_DARKROOM_MODELS_ROOT=/models \
+    ARGUS_DARKROOM_WORKFLOW=/app/examples/workflows/sdxl.json
+
+# Records and images live in /data, so give the unprivileged user that and nothing else.
+RUN useradd --system --uid 10001 --no-create-home darkroom \
+    && mkdir /data \
+    && chown darkroom /data
+USER darkroom
+VOLUME /data
+
+# Bound to all interfaces so the port can be published; publish it on 127.0.0.1 (compose.yaml does). Darkroom is not
+# for public hosting. It refuses to start without ARGUS_DARKROOM_SINGGUARD_URL.
+EXPOSE 8106
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \
+    CMD ["python", "-c", "import urllib.request as u; u.urlopen('http://127.0.0.1:8106/health', timeout=4)"]
+ENTRYPOINT ["argus-darkroom"]
+CMD ["serve", "--host", "0.0.0.0", "--port", "8106"]

argus_darkroom-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smk762
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

argus_darkroom-0.1.0/Makefile

@@ -0,0 +1,33 @@
+UV ?= uv
+
+.PHONY: help install lint format test build demo smoke clean
+
+help:  ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'
+
+install:  ## Create venv and install with test extras
+	$(UV) venv
+	$(UV) pip install -e ".[dev]"
+
+lint:  ## Ruff check + format check
+	$(UV)x ruff@0.15.16 check src/ tests/
+	$(UV)x ruff@0.15.16 format --check src/ tests/
+
+format:  ## Ruff autoformat + autofix
+	$(UV)x ruff@0.15.16 format src/ tests/
+	$(UV)x ruff@0.15.16 check --fix src/ tests/
+
+test:  ## Run the test suite
+	$(UV) run --no-sync pytest --tb=short -q
+
+build:  ## Build sdist + wheel
+	$(UV) build
+
+demo:  ## Run the real server against fake backends (no GPU), on http://127.0.0.1:8106
+	$(UV) run --no-sync python demo/run.py
+
+smoke:  ## With `make demo` running: send every marker prompt and check the outcome
+	$(UV) run --no-sync python demo/smoke.py
+
+clean:  ## Remove build + cache artifacts
+	rm -rf dist build .venv *.egg-info .pytest_cache .ruff_cache src/argus_darkroom/_version.py