stapel-reviews

Target-generic reviews and ratings: an author rates and reviews an opaque host-defined target (target_type + target_key), driven by a per-target-type policy registry (who may review, pre/post moderation, one-review-per-author, owner responses) whose authority questions are answered by host comm callbacks. The module owns the per-target aggregate (avg/count over published reviews) and emits a generic visibility-change fact carrying it, so a host catalog maintains its own rating projection without calling back.

Part of the Stapel framework — composable Django apps that deploy as a monolith or as microservices without changing module code.

Install

pip install stapel-reviews

At a glance

Documentation

OpenAPI · capabilities.json · llms.txt (for agents)

What this is

A generic review core — Review (author + rating + body about an opaque target) and Response (the target owner's reply) — driven entirely by a per-target-type policy registry. The module ships knowing nothing about what gets reviewed: a host registers its target types (a seller, a listing, a driver, a course), each with a policy, and answers the domain questions — "may this author review?", "who owns this target?" — through comm Function callbacks, so the module never imports a host model.

Quick start

INSTALLED_APPS = [
    # ...
    "stapel_reviews",
]

# urls.py
path("reviews/", include("stapel_reviews.urls"))

Concepts

• Target — opaque: target_type (a key the host registered) + target_key (an opaque host string — a UUID, a slug, a composite). No FK to any host model; the module is domain-blind.
• Policy — per target type: who may review (can_review comm callback), pre/post moderation, one-review-per-author, whether owner responses are allowed (allow_response), who may moderate/respond (can_moderate comm callback).
• Aggregate — the module owns avg/count over published reviews per target, and emits a generic fact carrying it on every visibility change, so a host catalog maintains its own rating projection (§10) without calling back.

STAPEL_REVIEWS = {
    "TARGET_TYPES": {
        "seller": {
            "can_review": "marketplace.buyer_of_seller",   # host comm Function
            "can_moderate": "marketplace.is_seller_owner",
            "moderation": "post",
            "one_per_author": True,
            "allow_response": True,
        },
        "listing": {"moderation": "pre"},
    },
}

from stapel_reviews import services

review = services.create_review(
    target_type="seller", target_key="s-42", author=user, rating=5, body="great",
)
services.moderate_review(review, actor=owner, action="hide", reason="spam")
services.respond(review, author=owner, body="thanks for the feedback")
agg = services.aggregate("seller", "s-42")   # Aggregate(avg=..., count=...)

Settings

All configuration lives in the STAPEL_REVIEWS namespace (dict setting, flat setting, or env var — resolved lazily):

comm surface

Host rating projection

The two batch Functions are the halves a host Projection over reviews is declared against — one keyed read for live traffic, one snapshot for rebuild:

class ListingReviewSummaryProjection(Projection):
    consumes = ("reviews.review.published", "reviews.review.hidden")
    source_key = "target_key"
    live_query = "reviews.aggregates_by_keys"      # local mode reads through it
    source_of_truth = "reviews.aggregates_export"  # rebuild() / drift_check()

Moderation verdicts

An external moderation module owns the decision; this module owns applying it. When a case about a review resolves, moderation.completed arrives and the review is hidden (rejected) or published (approved) — needs_review and dismissed deliberately move nothing. The verdict is applied as services.SYSTEM_ACTOR, the one actor that gets past the fail-closed can_moderate gate: authorization already happened where the verdict was made, and asking a target type with no can_moderate callback would deny the platform its own decision. Redelivery is a no-op — idempotency is by state, and no table of processed event ids is kept.

Extension points

See MODULE.md — the agent-facing map of every fork-free seam (the TARGET_TYPES registry and its policy callbacks, the projection emits, the aggregate Function, serializer seams, settings).

Development

pip install -e . && pip install pytest pytest-django ruff
./setup-hooks.sh
pytest tests/

License

MIT — see LICENSE.

_{This page is assembled by stapel-readme from docs/readme.md plus the contract artifacts in docs/. Edit the prose in docs/readme.md; the badges, facts and links above and below it are generated — do not hand-edit README.md.}