inference-bot 8c85c912e8 allowances: add a would_deactivate PREVIEW (deactivation stays gated off)
Report mode (and a send run while ALLOWANCE_DEACTIVATE is off) now reports a
member whose reminder is past the grace window as would_deactivate, with the
reminder date, grace length and deadline in the evidence. The real action is
unchanged and still needs BOTH ALLOWANCE_POLICY=on AND ALLOWANCE_DEACTIVATE=on.

The lapse decision is extracted into a pure function (allowance_lapse_decision)
so it is unit-testable against a synthetic reminder time:
tests/test_allowance_lapse.py (would_deactivate past grace; in_grace inside).
2026-11-04 18:46:54 +00:00

Member Portal — membership middleware for the Inference Cooperative

Reconciles three systems into one membership lifecycle:

System Role Source of truth for
Open Collective Billing Who is a paying member
Cloudron Identity/SSO Who can log in
LiteLLM Inference Who can use models, and how much

Architecture

Open Collective (billing)
        │ webhook
        ▼
┌─────────────────────────────┐
│  Member Portal (this app)   │
│  - OC webhook handler       │
│  - Cloudron user management │
│  - LiteLLM key management   │
│  - key-injection proxy      │
└─────────────────────────────┘
        ▲
        │ X-User-Email header (LibreChat forwards identity)
        │
LibreChat ──→ Member Portal ──→ LiteLLM ──→ backend

The three responsibilities

  1. Webhook handler (POST /webhook/opencollective) — listens for Open Collective membership events and activates/deactivates members.
  2. Key injector (/v1/*) — reads the member's email from the X-User-Email header, looks up their LiteLLM key, and forwards the request to the gateway with that key.
  3. Admin (/health, /) — health and status.

Configuration (environment variables)

Variable Purpose
CLOUDRON_API Cloudron API origin (auto-set by Cloudron)
CLOUDRON_TOKEN Cloudron API token (Read+Write)
MEMBERS_GROUP_ID Cloudron group ID for members (grants chat access)
LITELLM_BASE LiteLLM gateway URL
LITELLM_MASTER_KEY LiteLLM master key
OPENCOLLECTIVE_WEBHOOK_SECRET Optional webhook signature secret
PORTAL_KEK Required. Base64-encoded 32-byte key-encryption key. Member chat keys (members.key_token) are stored AES-256-GCM-encrypted at rest (enc1: prefix) and decrypted in memory only when served (dashboard, LibreChat key feed, LiteLLM management). Generate with python3 -c "import base64,os;print(base64.b64encode(os.urandom(32)).decode())". If unset, the portal runs but refuses to encrypt new keys, keeps legacy plaintext, and logs CRITICAL. Rotating it requires re-encrypting every row (decrypt with the old key, encrypt with the new).
ALLOWANCE_POLICY report (default) | on. report computes every allowance decision and changes nothing; on performs renewals and sends the one reminder. Deactivation is gated separately by ALLOWANCE_DEACTIVATE.
ALLOWANCE_DEACTIVATE off (default) | on. When on, a member who was reminded and is still unpaid after the grace window is moved to the inactive group. Defaults off so renewals/reminders can run before anyone loses access.
PAYMENT_GRACE_DAYS Days after the single reminder before an unpaid member is deactivated (default 7).

Tier budgets

Governance decision (set in Loomio). Defaults:

  • free — $2/month of tokens
  • member — $15/month
  • supporter — $30/month

LibreChat wiring

Point LibreChat's custom endpoint at this portal (not directly at LiteLLM), and add the identity header:

endpoints:
  custom:
    - name: "Inference Cooperative"
      apiKey: "${LITELLM_KEY}"
      baseURL: "https://portal.inference.coop/v1"
      headers:
        X-User-Email: "{{LIBRECHAT_USER_EMAIL}}"
      models:
        default: ["deepseek-v4-flash", "gpt-oss-120b"]
        fetch: true

Status

Scaffold — the three handlers are stubbed with the correct integration points. Remaining work before production:

  • Verify Open Collective webhook event names + payload shape → order.processed (every payment), new member (first only), firstPayment flag
  • Verify Cloudron user-creation API payload (role/group assignment) → POST /api/v1/users with {username, email, displayName, role, active} → group assignment via PUT /api/v1/users/:userId/groups with {groupIds: [...]}
  • Add a persistent store (SQLite) for email→key mapping → key/list returns token strings (not objects), so we store email→token locally
  • Verify LiteLLM key/generate + key/list payload shapes against live gateway → key/generate returns {key: "sk-..."}; key/list returns {keys: ["<token>", ...]}
  • Add HMAC signature verification for the OC webhook (if OC supports it)
  • Wire the OIDC addon for admin access

Scheduled tasks (scheduler addon)

Three jobs run inside the container via CloudronManifest.json → addons.scheduler:

  • membership_sweep (nightly 3am) — sweep.sh calls the portal's own /admin/sweep (auth: X-Admin-Token = WEBHOOK_TOKEN) to reconcile members against the live Open Collective list: provisions missed signups, deactivates lapsed members, syncs Loomio + Matrix. Idempotent; a missed webhook self-heals within 24 hours. The same sweep also runs the payment-driven allowance reconciliation (below).
  • rag_refresh (nightly 3:30am) — rag_refresh.py pulls this repo's sibling docs from the Gitea raw API (public, no credentials), uploads changed files to Open WebUI (OWUI_API_KEY), attaches them to the shared knowledge collection (DOCS_KNOWLEDGE_ID), reindexes, and re-grants the members group. State persists in /app/data/rag_refresh_state.json.
  • metrics_snapshot (nightly 3:15am) — metrics_snapshot.py records one row per day into the metrics_daily table: members, newsletter subscribers, Matrix membership, spend, request counts, and energy/CO₂. A source that cannot be read yields NULL for that metric rather than a zero. spend_usd is the co-op-wide total and deliberately spans every team, the co-op's own operator accounts included; operator_spend_usd is the breakout of that portion, served through /broker/metrics so the member dashboard can show the co-op's own share alongside the total. --backfill rebuilds history idempotently. Methodology: Energy and carbon metrics.

Verify after any manifest change: the deploy log must show setupAddons: ... scheduler ... listing all three tasks, and each script must succeed when run manually inside the container.

Allowance renewal (payment-driven, join-day anchored)

Each member has a monthly allowance (MEMBER_BUDGET, currently $15). The allowance renews on the day of the month the member joined, never on the day Open Collective happened to charge them — OC aligns every member's charge onto the collective's common billing day, so anchoring to the payment date let an early charge move the boundary and skip a cycle entirely. The join day is stored per member (members.anchor_day) and the reset is pinned there.

Whether the allowance renews is decided by asking Open Collective directly, on the sweep's own schedule (not inferred from webhook delivery): a member with a live recurring contribution (order status ACTIVE or PROCESSING — a payment in flight is not a missed payment) renews; a member with no live recurring contribution gets one reminder email, and is deactivated only after PAYMENT_GRACE_DAYS. One-time payments are not an allowance cycle — they top up the non-expiring credit balance and are untouched here. There are no annual contributors (verified 2026-11-04: 104 orders, 87 MONTHLY, 17 ONETIME, zero annual), so only the monthly case is implemented.

Every decision (renewed / reminded / deactivated, plus the payment date or its absence) is written to allowance_log and answerable from that record. Run POST /admin/allowance?mode=report (X-Admin-Token) for a no-op report that changes nothing; mode=send performs renewals and sends the reminder and requires ALLOWANCE_POLICY=on. Deactivation additionally requires ALLOWANCE_DEACTIVATE=on.

Energy & carbon metrics

The daily snapshot also computes energy (Wh) and carbon (gCO₂e) from output tokens, using per-model factors whose provenance varies: measured for GreenPT, assumed equal for one sibling model, and an explicit order-of-magnitude estimate for providers that disclose nothing. Only output tokens count, and a day with no measured tokens is recorded as NULL rather than zero.

Energy and carbon metrics documents the factor table, the formulas, the tripwire that catches unit errors, the schedule, and — most importantly — which parts are measurements and which are estimates. What members are told is in co-op/docs/energy.md.

S
Description
Membership middleware: syncs Open Collective members with Cloudron users and LiteLLM keys
Readme
15 MiB
0 Stars 2 Watchers 0 Forks
Languages
Python 99.4%
Shell 0.5%
Dockerfile 0.1%