core-framework 4.0.1__tar.gz → 4.2.0__tar.gz

core_framework-4.2.0/.agents/skills/building-pydantic-ai-agents

@@ -0,0 +1 @@
+../../.venv/lib/python3.14/site-packages/pydantic_ai/.agents/skills/building-pydantic-ai-agents

core_framework-4.2.0/.cursor/skills/building-pydantic-ai-agents

@@ -0,0 +1 @@
+../../.agents/skills/building-pydantic-ai-agents

{core_framework-4.0.1 → core_framework-4.2.0}/.cursor/skills/code-review/SKILL.md

@@ -28,12 +28,23 @@ Do **not** flag documented accepted trade-offs in **`docs/platform/architecture-
 
 **Spec sources** (first that applies): docs the user named; design/flow docs the change clearly belongs to; matching `docs/design/*-design.md` / `docs/domains/**/*-design.md` plus the paired flow doc. If none exist, skip this check — do not mention that there is no spec.
 
+## Reachability and impact
+
+Before keeping a race, edge case, or error-path finding, state who can trigger it and what it harms. Severity follows both.
+
+- **Who triggers it:** a correct client, a buggy client, or a deliberate caller (attacker).
+- **What it harms:** data corruption or lost writes; another user's data or existence (trust boundary); availability beyond what ordinary requests already allow; or only the caller's own request failing.
+
+**Drop** a finding when the only trigger is the caller's own invalid or contradictory request and the only outcome is that request failing, even with the wrong status (e.g. a deadlock that needs an illegal request to collide with a legal one, where the illegal one was already going to fail). Mention it only if the user asks for edge cases.
+
+**Keep** deliberate-caller findings that cross a trust boundary (another user's rows, enumeration, auth bypass) or give an attacker more load or disruption than ordinary requests allow. Do not drop a finding just because a correct client would not hit it.
+
 ## Output format (required)
 
 **Actionable findings only**, under `## Findings`:
 
 - Bugs, wrong behavior, improvements, optimizations, doc/code contradictions, parallel implementation drift (sibling flows that diverge without documented reason), **Residue** after an implementation or refactor, spec gaps / extras / mismatches.
-- One numbered list, prioritized by severity. Each item: file context, what is wrong, fix direction.
+- One numbered list, prioritized by severity (see **Reachability and impact**). Each item: file context, what is wrong, who can trigger it, fix direction.
 - **Do not** praise, summarize strengths, pad with checklist pass narratives, or emit empty-axis sentences.
 - One-line scope is fine. If there is nothing to address, say so in one sentence — no `## Findings` heading.
 

{core_framework-4.0.1 → core_framework-4.2.0}/.github/workflows/_deploy.yml

@@ -22,6 +22,14 @@ on:
         required: false
       EMAIL_API_KEY:
         required: false
+      AGENT_OPENAI_API_KEY:
+        required: false
+      AGENT_ANTHROPIC_API_KEY:
+        required: false
+      ENTITLEMENT_SECRET_API_KEY:
+        required: false
+      ENTITLEMENT_WEBHOOK_SIGNING_SECRET:
+        required: false
       FIREBASE_CONFIG:
         required: true
       IMAGE_SERVER_SSH_PRIVATE_KEY:
@@ -98,6 +106,18 @@ jobs:
           EMAIL_API_KEY: ${{ secrets.EMAIL_API_KEY }}
           EMAIL_FROM_ADDRESS: ${{ vars.EMAIL_FROM_ADDRESS }}
           EMAIL_FROM_NAME: ${{ vars.EMAIL_FROM_NAME }}
+          AGENT_ENABLED: ${{ vars.AGENT_ENABLED || 'false' }}
+          AGENT_PROVIDER: ${{ vars.AGENT_PROVIDER || 'openai' }}
+          AGENT_MODEL: ${{ vars.AGENT_MODEL }}
+          AGENT_OPENAI_API_KEY: ${{ secrets.AGENT_OPENAI_API_KEY }}
+          AGENT_OPENAI_BASE_URL: ${{ vars.AGENT_OPENAI_BASE_URL }}
+          AGENT_ANTHROPIC_API_KEY: ${{ secrets.AGENT_ANTHROPIC_API_KEY }}
+          AGENT_TIMEOUT_SECONDS: ${{ vars.AGENT_TIMEOUT_SECONDS || '120' }}
+          ENTITLEMENT_ENABLED: ${{ vars.ENTITLEMENT_ENABLED || 'false' }}
+          ENTITLEMENT_SECRET_API_KEY: ${{ secrets.ENTITLEMENT_SECRET_API_KEY }}
+          ENTITLEMENT_PROJECT_ID: ${{ vars.ENTITLEMENT_PROJECT_ID }}
+          ENTITLEMENT_WEBHOOK_SIGNING_SECRET: ${{ secrets.ENTITLEMENT_WEBHOOK_SIGNING_SECRET }}
+          ENTITLEMENT_ALERT_ADDRESS: ${{ vars.ENTITLEMENT_ALERT_ADDRESS }}
         run: |
           set -euo pipefail
 

{core_framework-4.0.1 → core_framework-4.2.0}/.github/workflows/dev-ci-cd.yaml

@@ -121,7 +121,7 @@ jobs:
     needs: [app-docker, worker-docker]
     permissions:
       contents: read
-    uses: ./.github/workflows/_deploy.yml
+    uses: $/.github/workflows/_deploy.yml
     with:
       env_name: development
       dockerhub_username: ${{ vars.DOCKERHUB_USERNAME }}
@@ -130,6 +130,10 @@ jobs:
       WRITE_POSTGRES_PASSWORD: ${{ secrets.WRITE_POSTGRES_PASSWORD }}
       READ_POSTGRES_PASSWORD: ${{ secrets.READ_POSTGRES_PASSWORD }}
       EMAIL_API_KEY: ${{ secrets.EMAIL_API_KEY }}
+      AGENT_OPENAI_API_KEY: ${{ secrets.AGENT_OPENAI_API_KEY }}
+      AGENT_ANTHROPIC_API_KEY: ${{ secrets.AGENT_ANTHROPIC_API_KEY }}
+      ENTITLEMENT_SECRET_API_KEY: ${{ secrets.ENTITLEMENT_SECRET_API_KEY }}
+      ENTITLEMENT_WEBHOOK_SIGNING_SECRET: ${{ secrets.ENTITLEMENT_WEBHOOK_SIGNING_SECRET }}
       FIREBASE_CONFIG: ${{ secrets.FIREBASE_CONFIG }}
       IMAGE_SERVER_SSH_PRIVATE_KEY: ${{ secrets.IMAGE_SERVER_SSH_PRIVATE_KEY }}
       IMAGE_SERVER_KNOWN_HOSTS: ${{ secrets.IMAGE_SERVER_KNOWN_HOSTS }}

{core_framework-4.0.1 → core_framework-4.2.0}/.github/workflows/manual-deployment.yaml

@@ -36,7 +36,7 @@ jobs:
     needs: validate
     permissions:
       contents: read
-    uses: ./.github/workflows/_deploy.yml
+    uses: $/.github/workflows/_deploy.yml
     with:
       env_name: ${{ inputs.environment }}
       dockerhub_username: ${{ vars.DOCKERHUB_USERNAME }}
@@ -46,6 +46,10 @@ jobs:
       WRITE_POSTGRES_PASSWORD: ${{ secrets.WRITE_POSTGRES_PASSWORD }}
       READ_POSTGRES_PASSWORD: ${{ secrets.READ_POSTGRES_PASSWORD }}
       EMAIL_API_KEY: ${{ secrets.EMAIL_API_KEY }}
+      AGENT_OPENAI_API_KEY: ${{ secrets.AGENT_OPENAI_API_KEY }}
+      AGENT_ANTHROPIC_API_KEY: ${{ secrets.AGENT_ANTHROPIC_API_KEY }}
+      ENTITLEMENT_SECRET_API_KEY: ${{ secrets.ENTITLEMENT_SECRET_API_KEY }}
+      ENTITLEMENT_WEBHOOK_SIGNING_SECRET: ${{ secrets.ENTITLEMENT_WEBHOOK_SIGNING_SECRET }}
       FIREBASE_CONFIG: ${{ secrets.FIREBASE_CONFIG }}
       IMAGE_SERVER_SSH_PRIVATE_KEY: ${{ secrets.IMAGE_SERVER_SSH_PRIVATE_KEY }}
       IMAGE_SERVER_KNOWN_HOSTS: ${{ secrets.IMAGE_SERVER_KNOWN_HOSTS }}

{core_framework-4.0.1 → core_framework-4.2.0}/CHANGELOG.md

@@ -4,6 +4,32 @@ Notable changes to **core-framework** (import **`core_framework`**). Format foll
 
 ## [Unreleased]
 
+## [4.2.0] - 2026-10-08
+
+### Added
+
+- **Model provider:** a host selects **openai** (default) or **anthropic**. Startup builds only that provider. **`SupportedModel`** adds **`claude-opus-5`**, **`claude-sonnet-5`**, and **`claude-haiku-5-5`**. An omitted or blank **`model`** is **`gpt-6-luna`** for OpenAI and **`claude-haiku-5-5`** for Anthropic. **`claude-haiku-5-5`** is the Claude API id. The pinned Pydantic AI release classifies the Opus and Sonnet ids and leaves Haiku on its generic Anthropic profile (native JSON-schema output off, adaptive thinking and effort off, sampling settings forwarded) until a pin classifies that id. An explicit **`model`** must belong to the selected provider. Secret **`AGENT_ANTHROPIC_API_KEY`** is required only when enabled and the provider is Anthropic. The Anthropic client uses **`https://api.anthropic.com`** and ignores **`ANTHROPIC_API_KEY`**, **`ANTHROPIC_BASE_URL`**, **`ANTHROPIC_CUSTOM_HEADERS`**, **`ANTHROPIC_WEBHOOK_SIGNING_KEY`**, and **`ANTHROPIC_LOG`**. **`responses_model`** returns that provider's content-free model, or raises when the requested member belongs to the other provider.
+- **Entitlement grants:** a signed RevenueCat webhook replaces paid tiers and leaves complimentary tiers. A refused grant returns **200**, leaves that user's paid rows, and emails the operator at most once per reason and entitlement id per hour. Admin complimentary grant and remove return **204**. Account removal tries the RevenueCat customer delete when entitlements are on, then deletes the user's grant and cursor rows. A failed customer delete is logged and removal continues.
+- **Entitlement RevenueCat adapter:** fetch active entitlements, load the project entitlement list, and delete a customer. A missing customer is an empty active list on fetch and success on delete. A **409** with **`retryable`** false on delete is success, because the delete is already queued. **400**, **401**, **403**, and **422** on delete are not retried. A retryable error or a network failure waits and retries up to three times. Wired only while entitlements are on. The API loads the entitlement list before it accepts traffic and does not start if that load fails. It retries a few times; **401** and **403** fail immediately. An empty list is success. The worker does not load the list.
+- **Entitlement repository:** replace paid grants, insert or delete a complimentary grant, and read active tiers from the replica. A webhook delivery stores its event id and advances each user's sync cursor in one transaction. An older event timestamp does not overwrite a newer snapshot.
+- **Entitlement HTTP:** `PUT` and `DELETE /admin/users/{target_user_id}/entitlements/{tier_id}` stay mounted and return **204**. `POST /webhooks/revenuecat` and `GET /users/me/entitlements` mount only when `[entitlement].enabled` is true. A webhook signature failure is **401**. A tier gate allows its route while entitlements are off and returns **403** **Entitlement required** when they are on and the caller has no qualifying tier.
+- **Entitlement domain (scaffold):** package `core_framework/domains/entitlement`, `[postgres_schemas].schema_entitlement` (default `entitlement`), and Alembic tree `alembic/entitlement/` in `ALEMBIC_DOMAINS`. Revision `b7ed2400e94e` creates `paid_grants`, `complimentary_grants`, `sync_cursors`, and `deliveries` (no foreign key to the user schema; `deliveries` has no `user_id`). Optional `[entitlement]` Settings (`enabled` default false). A blank secret key, project id, or webhook signing secret fails load only when enabled. The secret key, project id, and webhook signing secret are stripped; a CR or LF in a non-blank stripped secret or alert address fails load.
+
+## [4.1.0] - 2026-09-28
+
+### Breaking
+
+- **Review list sort:** `GET /ratings/{subject_kind}/{subject_id}/reviews?sort=top` is **422**. Use `sort=votes` (stored upvote count, then `created_at`, then `id`, all descending). No alias. See **`docs/domains/ratings/retrieve_ratings.md`** and **`docs/design/list-sort-design.md`**.
+
+### Added
+
+- **List sort:** Post discovery (`GET /posts`, `GET /posts/hashtags/{hashtag}`, `GET /posts/users/{user_id}`) accepts `sort` of `newest`, `votes`, or `hot`. Comment subject and reply lists accept `newest` and `votes`. Omit `sort` stays newest-first. Self-history and by-user comment/rating history do not declare `sort`. See **`docs/design/list-sort-design.md`**.
+- **Post discovery rank:** Run **`cf-alembic`** before API and worker start so **post** applies **`954f00734f36`** (empty **`post_discovery_rank`**; index **`idx_post_discovery_rank_hot_created_post`** on **`(hot_score desc, created_at desc, post_id desc)`**). Post create inserts a rank row in that table. The table is empty at ship, so **`sort=hot`** contains only posts created after the migration.
+- **Post votes index:** Run **`cf-alembic`** so **post** applies **`0a89b4c23746`** (`idx_post_stats_like_created_post` on **`post_stats (like_count desc, created_at desc, post_id desc)`**). Post discovery **`sort=votes`** orders from that index.
+- **Model-call probe:** `POST /admin/agent/probe` (admin role) runs one fixed prompt on the configured model and returns **disabled**, **completed** (with the reply text), or **failed**. Model calls that are off do not call OpenAI. See **`docs/domains/agent/model_call_probe.md`**.
+- **Readiness:** `GET /readiness` adds **`agent_status`**: **DISABLED** when model calls are off (no OpenAI call), otherwise **OK** or **ERROR** from one lookup of the default model (no completion). A key without model read permission reports **ERROR**. It does not change **`app_status`** or the **503**.
+- **Model calls (agent capability):** OpenAI connection for [Pydantic AI](https://github.com/pydantic/pydantic-ai) callers. **`pydantic-ai-slim[openai]`** is a normal dependency. Optional **`[agent]`** Settings (**`enabled`** default **false**, **`model`**, **`openai_api_key`**, **`openai_base_url`**, **`timeout_seconds`** default **120**); deploy variables **`AGENT_ENABLED`**, **`AGENT_MODEL`**, **`AGENT_OPENAI_BASE_URL`**, **`AGENT_TIMEOUT_SECONDS`** and secret **`AGENT_OPENAI_API_KEY`**. When enabled, a blank key fails Settings load and startup builds one OpenAI provider (own HTTP client, no SDK retries, timeout per request phase); the OpenAI library’s own environment variables have no effect. **`responses_model`** (**`core_framework.domains.agent.dependencies`**) returns a content-free instrumented Responses model with OpenAI response storage off by default (agent or run settings may turn it on), or **`disabled`** when off; **`SupportedModel`** and **`disabled`** export from **`core_framework.domains.agent`**. Hosts that never call a model change nothing. See **`docs/design/model-call-design.md`** and **`docs/library/package-api.md`**.
+
 ## [4.0.1] - 2026-09-17
 
 ### Fixed
@@ -784,4 +810,6 @@ First **SemVer-stable** release per **`docs/library/package-api.md`**.
 [3.3.0]: https://github.com/NepNepFFXIV/core-framework/compare/v3.2.0...v3.3.0
 [4.0.0]: https://github.com/NepNepFFXIV/core-framework/compare/v3.3.0...v4.0.0
 [4.0.1]: https://github.com/NepNepFFXIV/core-framework/compare/v4.0.0...v4.0.1
-[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v4.0.1...HEAD
+[4.1.0]: https://github.com/NepNepFFXIV/core-framework/compare/v4.0.1...v4.1.0
+[4.2.0]: https://github.com/NepNepFFXIV/core-framework/compare/v4.1.0...v4.2.0
+[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v4.2.0...HEAD

{core_framework-4.0.1 → core_framework-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: core-framework
-Version: 4.0.1
+Version: 4.2.0
 Summary: Core framework package (import as core_framework)
 Project-URL: Homepage, https://github.com/NepNepFFXIV/core-framework
 Project-URL: Repository, https://github.com/NepNepFFXIV/core-framework
@@ -15,12 +15,13 @@ Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: asyncssh>=2.24.0
 Requires-Dist: brotli-asgi>=1.6.0
 Requires-Dist: cashews[redis]>=7.5.0
-Requires-Dist: device-detector>=6.4.0
+Requires-Dist: device-detector<6.5,>=6.4.0
 Requires-Dist: fastapi[standard]>=0.141.1
 Requires-Dist: firebase-admin>=7.5.0
 Requires-Dist: httpx[http2]>=0.28.1
 Requires-Dist: itsdangerous>=2.2.0
 Requires-Dist: mashumaro[orjson]>=3.22
+Requires-Dist: openai<3.20,>=3.19.2
 Requires-Dist: opentelemetry-api<1.45,>=1.44.0
 Requires-Dist: opentelemetry-exporter-otlp-proto-http<1.45,>=1.44.0
 Requires-Dist: opentelemetry-instrumentation-asyncpg<0.66,>=0.65b0
@@ -32,6 +33,7 @@ Requires-Dist: opentelemetry-semantic-conventions<0.66,>=0.65b0
 Requires-Dist: orjson>=3.12.0
 Requires-Dist: pillow-heif>=1.7.0
 Requires-Dist: pillow>=12.3.0
+Requires-Dist: pydantic-ai-slim[anthropic,openai]<3,>=2.51.0
 Requires-Dist: pyinstrument>=5.1.3
 Requires-Dist: python-ulid>=4.0.1
 Requires-Dist: resend[async]>=2.44.0

core_framework-4.2.0/alembic/entitlement/alembic/env.py

@@ -0,0 +1,77 @@
+import asyncio
+from logging.config import fileConfig
+
+from sqlalchemy import pool, text
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+from alembic import context
+from core_framework.core.settings import load_default_settings
+
+settings = load_default_settings()
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Interpret the config file for Python logging.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = None
+
+config.set_main_option("sqlalchemy.url", settings.write_postgres.alembic_postgres_url)
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode."""
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    quoted_schema_name = f'"{settings.postgres_schemas.schema_entitlement.replace('"', '""')}"'
+
+    with context.begin_transaction():
+        context.execute(text(f"set search_path to {quoted_schema_name}"))
+        context.run_migrations()
+
+
+def do_run_migrations(connection: Connection) -> None:
+    quoted_schema_name = f'"{settings.postgres_schemas.schema_entitlement.replace('"', '""')}"'
+
+    connection.execute(text(f"create schema if not exists {quoted_schema_name}"))
+    connection.execute(text(f"set search_path to {quoted_schema_name}"))
+    connection.commit()
+
+    context.configure(connection=connection, target_metadata=target_metadata)
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    """Run migrations in 'online' mode."""
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

core_framework-4.2.0/alembic/entitlement/alembic/versions/b7ed2400e94e_entitlement_schema.py

@@ -0,0 +1,58 @@
+"""create entitlement schema tables
+
+Revision ID: b7ed2400e94e
+Revises:
+Create Date: 2026-10-01 11:11:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "b7ed2400e94e"
+down_revision: str | Sequence[str] | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        create table paid_grants (
+            user_id varchar(128) not null,
+            tier_id integer not null,
+            expires_at timestamptz not null,
+            synced_at timestamptz not null,
+            primary key (user_id, tier_id),
+            constraint paid_grants_tier_id_positive check (tier_id >= 1)
+        );
+    """)
+
+    op.execute("""
+        create table complimentary_grants (
+            user_id varchar(128) not null,
+            tier_id integer not null,
+            granted_by varchar(128) not null,
+            granted_at timestamptz not null,
+            primary key (user_id, tier_id),
+            constraint complimentary_grants_tier_id_positive check (tier_id >= 1)
+        );
+    """)
+
+    op.execute("""
+        create table sync_cursors (
+            user_id varchar(128) primary key,
+            last_event_timestamp timestamptz not null
+        );
+    """)
+
+    op.execute("""
+        create table deliveries (
+            event_id varchar(255) primary key,
+            applied_at timestamptz not null
+        );
+    """)
+
+
+def downgrade() -> None:
+    raise RuntimeError("downgrade is not supported for this revision")

core_framework-4.2.0/alembic/post/alembic/versions/0a89b4c23746_post_stats_like_created_post_index.py

@@ -0,0 +1,27 @@
+"""index post_stats for discovery votes order
+
+Revision ID: 0a89b4c23746
+Revises: 954f00734f36
+Create Date: 2026-09-23 15:44:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "0a89b4c23746"
+down_revision: str | Sequence[str] | None = "954f00734f36"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        create index if not exists idx_post_stats_like_created_post
+        on post_stats (like_count desc, created_at desc, post_id desc);
+    """)
+
+
+def downgrade() -> None:
+    op.execute("drop index if exists idx_post_stats_like_created_post;")

core_framework-4.2.0/alembic/post/alembic/versions/954f00734f36_post_add_post_discovery_rank.py

@@ -0,0 +1,37 @@
+"""add empty post_discovery_rank for stored hot discovery
+
+Revision ID: 954f00734f36
+Revises: 1602f054c545
+Create Date: 2026-09-20 12:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "954f00734f36"
+down_revision: str | Sequence[str] | None = "1602f054c545"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        create table post_discovery_rank (
+            post_id varchar(26) primary key references posts(id) on delete cascade,
+            hot_score bigint not null,
+            created_at timestamptz not null,
+            computed_at timestamptz not null
+        );
+    """)
+
+    op.execute("""
+        create index if not exists idx_post_discovery_rank_hot_created_post
+        on post_discovery_rank (hot_score desc, created_at desc, post_id desc);
+    """)
+
+
+def downgrade() -> None:
+    op.execute("drop index if exists idx_post_discovery_rank_hot_created_post;")
+    op.execute("drop table if exists post_discovery_rank;")

core_framework-4.2.0/alembic/post/alembic/versions/b3c61daef9b5_post_add_post_bookmarks.py

@@ -0,0 +1,37 @@
+"""add post_bookmarks
+
+Revision ID: b3c61daef9b5
+Revises: 0a89b4c23746
+Create Date: 2026-10-06 05:13:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "b3c61daef9b5"
+down_revision: str | Sequence[str] | None = "0a89b4c23746"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        create table post_bookmarks (
+            user_id varchar(128) not null,
+            post_id varchar(26) not null references posts(id) on delete cascade,
+            saved_at timestamptz not null default now(),
+            primary key (user_id, post_id)
+        );
+    """)
+
+    op.execute("""
+        create index if not exists idx_post_bookmarks_user_saved_post
+        on post_bookmarks (user_id, saved_at desc, post_id desc);
+    """)
+
+
+def downgrade() -> None:
+    op.execute("drop index if exists idx_post_bookmarks_user_saved_post;")
+    op.execute("drop table if exists post_bookmarks;")

core_framework-4.2.0/alembic/rating/alembic.ini

@@ -0,0 +1,52 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts.
+# this is typically a path given in POSIX (e.g. forward slashes)
+# format, relative to the token %(here)s which refers to the location of this
+# ini file
+script_location = %(here)s/alembic
+
+# sys.path path, will be prepended to sys.path if present.
+prepend_sys_path = .
+
+path_separator = os
+
+sqlalchemy.url = driver://user:pass@localhost/dbname
+
+
+[post_write_hooks]
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

core_framework-4.2.0/alembic/user/alembic/README

@@ -0,0 +1 @@
+Generic single-database configuration with an async dbapi.

core_framework-4.2.0/alembic/user/alembic/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}

{core_framework-4.0.1 → core_framework-4.2.0}/config.toml

@@ -134,6 +134,7 @@ schema_notification = "notification"
 schema_media = "media"
 schema_analytics = "analytics"
 schema_rating = "rating"
+schema_entitlement = "entitlement"
 
 [redis]
 host = "127.0.0.1"
@@ -147,3 +148,19 @@ provider = "resend"
 api_key = ""
 from_address = ""
 from_name = ""
+
+[agent]
+enabled = false
+provider = "openai"
+model = ""
+openai_api_key = ""
+openai_base_url = ""
+anthropic_api_key = ""
+timeout_seconds = 300
+
+[entitlement]
+enabled = false
+secret_api_key = ""
+project_id = ""
+webhook_signing_secret = ""
+alert_address = ""

{core_framework-4.0.1 → core_framework-4.2.0}/config.toml.template

@@ -122,6 +122,7 @@ schema_notification = "notification"
 schema_media = "media"
 schema_analytics = "analytics"
 schema_rating = "rating"
+schema_entitlement = "entitlement"
 
 [redis]
 host = "$REDIS_HOST"
@@ -135,3 +136,19 @@ provider = "$EMAIL_PROVIDER"
 api_key = "$EMAIL_API_KEY"
 from_address = "$EMAIL_FROM_ADDRESS"
 from_name = "$EMAIL_FROM_NAME"
+
+[agent]
+enabled = $AGENT_ENABLED
+provider = "$AGENT_PROVIDER"
+model = "$AGENT_MODEL"
+openai_api_key = "$AGENT_OPENAI_API_KEY"
+openai_base_url = "$AGENT_OPENAI_BASE_URL"
+anthropic_api_key = "$AGENT_ANTHROPIC_API_KEY"
+timeout_seconds = $AGENT_TIMEOUT_SECONDS
+
+[entitlement]
+enabled = $ENTITLEMENT_ENABLED
+secret_api_key = "$ENTITLEMENT_SECRET_API_KEY"
+project_id = "$ENTITLEMENT_PROJECT_ID"
+webhook_signing_secret = "$ENTITLEMENT_WEBHOOK_SIGNING_SECRET"
+alert_address = "$ENTITLEMENT_ALERT_ADDRESS"

core_framework-4.2.0/core_framework/api/admin/agent/router.py

@@ -0,0 +1,19 @@
+from typing import Any
+
+from fastapi import APIRouter, Depends
+
+from core_framework.api.admin.agent.schemas import ModelProbeResponse
+from core_framework.api.dependencies import check_admin_role
+from core_framework.application.agent.probe import probe_model_call
+
+router = APIRouter(
+    prefix="/agent",
+    tags=["agent - admin"],
+    dependencies=[Depends(check_admin_role)],
+)
+
+
+@router.post("/probe", response_model=ModelProbeResponse)
+async def post_model_call_probe() -> Any:
+    result = await probe_model_call()
+    return ModelProbeResponse(status=result.status, output=result.output)

core_framework-4.2.0/core_framework/api/admin/agent/schemas.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel
+
+from core_framework.domains.agent import ModelProbeStatus
+
+
+class ModelProbeResponse(BaseModel):
+    status: ModelProbeStatus
+    output: str | None

core_framework-4.2.0/core_framework/api/admin/entitlements/router.py

@@ -0,0 +1,41 @@
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Path, status
+
+from core_framework.api.dependencies import RequiredUserID, check_admin_role
+from core_framework.api.users.shared.schemas import validate_user_id
+from core_framework.application.entitlement.grant_service import grant_complimentary_tier, remove_complimentary_tier
+
+router = APIRouter(
+    prefix="/users",
+    tags=["entitlements - admin"],
+    dependencies=[Depends(check_admin_role)],
+)
+
+
+@router.put("/{target_user_id}/entitlements/{tier_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def put_complimentary_entitlement(
+    actor_id: RequiredUserID,
+    target_user_id: str,
+    tier_id: Annotated[int, Path(ge=1)],
+) -> None:
+    validated_target_user_id = validate_user_id(user_id=target_user_id)
+    await grant_complimentary_tier(
+        actor_id=actor_id,
+        target_user_id=validated_target_user_id,
+        tier_id=tier_id,
+    )
+
+
+@router.delete("/{target_user_id}/entitlements/{tier_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_complimentary_entitlement(
+    actor_id: RequiredUserID,
+    target_user_id: str,
+    tier_id: Annotated[int, Path(ge=1)],
+) -> None:
+    validated_target_user_id = validate_user_id(user_id=target_user_id)
+    await remove_complimentary_tier(
+        actor_id=actor_id,
+        target_user_id=validated_target_user_id,
+        tier_id=tier_id,
+    )

{core_framework-4.0.1 → core_framework-4.2.0}/core_framework/api/admin/router.py

@@ -1,8 +1,10 @@
 from fastapi import APIRouter, Depends
 
+from core_framework.api.admin.agent.router import router as agent_router
 from core_framework.api.admin.analytics.router import router as analytics_router
 from core_framework.api.admin.cache.router import router as cache_router
 from core_framework.api.admin.comments.router import router as comments_router
+from core_framework.api.admin.entitlements.router import router as entitlements_router
 from core_framework.api.admin.moderation.router import router as moderation_router
 from core_framework.api.admin.outbox.router import router as outbox_router
 from core_framework.api.admin.posts.router import router as posts_router
@@ -15,10 +17,12 @@ router = APIRouter(
     dependencies=[Depends(check_admin_identity), Depends(check_moderator_or_admin)],
 )
 
+router.include_router(agent_router)
 router.include_router(cache_router)
 router.include_router(analytics_router)
 router.include_router(outbox_router)
 router.include_router(users_router)
+router.include_router(entitlements_router)
 router.include_router(moderation_router)
 router.include_router(posts_router)
 router.include_router(comments_router)