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

core_framework-4.1.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.1.0/.cursor/skills/building-pydantic-ai-agents

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

{core_framework-4.0.1 → core_framework-4.1.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.1.0}/.github/workflows/_deploy.yml

@@ -22,6 +22,8 @@ on:
         required: false
       EMAIL_API_KEY:
         required: false
+      AGENT_OPENAI_API_KEY:
+        required: false
       FIREBASE_CONFIG:
         required: true
       IMAGE_SERVER_SSH_PRIVATE_KEY:
@@ -98,6 +100,11 @@ 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_MODEL: ${{ vars.AGENT_MODEL }}
+          AGENT_OPENAI_API_KEY: ${{ secrets.AGENT_OPENAI_API_KEY }}
+          AGENT_OPENAI_BASE_URL: ${{ vars.AGENT_OPENAI_BASE_URL }}
+          AGENT_TIMEOUT_SECONDS: ${{ vars.AGENT_TIMEOUT_SECONDS || '120' }}
         run: |
           set -euo pipefail
 

{core_framework-4.0.1 → core_framework-4.1.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,7 @@ 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 }}
       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.1.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,7 @@ 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 }}
       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.1.0}/CHANGELOG.md

@@ -4,6 +4,21 @@ Notable changes to **core-framework** (import **`core_framework`**). Format foll
 
 ## [Unreleased]
 
+## [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 +799,5 @@ 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
+[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v4.1.0...HEAD

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: core-framework
-Version: 4.0.1
+Version: 4.1.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
@@ -21,6 +21,7 @@ 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[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.1.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.1.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.0.1 → core_framework-4.1.0}/config.toml

@@ -147,3 +147,6 @@ provider = "resend"
 api_key = ""
 from_address = ""
 from_name = ""
+
+[agent]
+enabled = false

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

@@ -135,3 +135,10 @@ provider = "$EMAIL_PROVIDER"
 api_key = "$EMAIL_API_KEY"
 from_address = "$EMAIL_FROM_ADDRESS"
 from_name = "$EMAIL_FROM_NAME"
+
+[agent]
+enabled = $AGENT_ENABLED
+model = "$AGENT_MODEL"
+openai_api_key = "$AGENT_OPENAI_API_KEY"
+openai_base_url = "$AGENT_OPENAI_BASE_URL"
+timeout_seconds = $AGENT_TIMEOUT_SECONDS

core_framework-4.1.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.1.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.0.1 → core_framework-4.1.0}/core_framework/api/admin/router.py

@@ -1,5 +1,6 @@
 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
@@ -15,6 +16,7 @@ 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)

{core_framework-4.0.1 → core_framework-4.1.0}/core_framework/api/comments/public/router.py

@@ -1,6 +1,6 @@
-from typing import Annotated, Any
+from typing import Annotated, Any, Literal
 
-from fastapi import APIRouter, Depends, Request
+from fastapi import APIRouter, Depends, Query, Request
 from ulid import ULID
 
 from core_framework.api.comments.public.schemas import CommentResponse
@@ -11,6 +11,7 @@ from core_framework.api.pagination import (
     PaginationResponse,
     TokenCursorQueryParams,
     paginate_cursor,
+    paginate_datetime_id_cursor,
 )
 from core_framework.api.users.shared.schemas import validate_user_id
 from core_framework.application.comments.public_service import (
@@ -77,14 +78,26 @@ async def get_comments(
     subject_id: CommentSubjectId,
     pagination_params: Annotated[TokenCursorQueryParams, Depends()],
     viewer_id: OptionalUserID,
+    sort: Annotated[Literal["newest", "votes"] | None, Query()] = None,
 ) -> Any:
+    ranked = sort == "votes"
     comments = await retrieve_comments(
         subject_kind=subject_kind,
         subject_id=subject_id,
         cursor=pagination_params.cursor,
         limit=pagination_params.limit,
         viewer_id=viewer_id if viewer_id else None,
+        order="votes" if ranked else "newest",
+        cursor_comment_id=pagination_params.cursor_string_id if ranked else None,
+        cursor_sort_key=pagination_params.cursor_id if ranked else 0,
     )
+    if ranked:
+        return paginate_datetime_id_cursor(
+            request=request,
+            items=comments,
+            pagination_params=pagination_params,
+            integer_key=lambda item: item["sort_key"],
+        )
     return paginate_cursor(
         request=request,
         items=comments,
@@ -100,13 +113,25 @@ async def get_replies(
     request: Request,
     pagination_params: Annotated[TokenCursorQueryParams, Depends()],
     viewer_id: OptionalUserID,
+    sort: Annotated[Literal["newest", "votes"] | None, Query()] = None,
 ) -> Any:
+    ranked = sort == "votes"
     replies = await retrieve_replies(
         parent_comment_id=str(comment_id),
         cursor=pagination_params.cursor,
         limit=pagination_params.limit,
         viewer_id=viewer_id if viewer_id else None,
+        order="votes" if ranked else "newest",
+        cursor_comment_id=pagination_params.cursor_string_id if ranked else None,
+        cursor_sort_key=pagination_params.cursor_id if ranked else 0,
     )
+    if ranked:
+        return paginate_datetime_id_cursor(
+            request=request,
+            items=replies,
+            pagination_params=pagination_params,
+            integer_key=lambda item: item["sort_key"],
+        )
     return paginate_cursor(
         request=request,
         items=replies,

{core_framework-4.0.1 → core_framework-4.1.0}/core_framework/api/pagination.py

@@ -1,4 +1,4 @@
-from collections.abc import Mapping, Sequence
+from collections.abc import Callable, Mapping, Sequence
 from datetime import datetime
 from enum import StrEnum
 from functools import cached_property
@@ -164,6 +164,50 @@ def paginate_username[T](
     }
 
 
+def paginate_datetime_id_cursor[T](
+    *,
+    request: Request,
+    items: Sequence[T],
+    pagination_params: TokenCursorQueryParams,
+    integer_key: Callable[[T], int] | None = None,
+    max_items: int = DEFAULT_MAX_ITEMS,
+) -> PaginationResult[T]:
+    """Paginate a descending keyset that ties on row id.
+
+    Encodes ``page_token`` from the last returned row. ``integer_key`` is the
+    vote count or hot score; omit it when the order is created-at plus id.
+    """
+    page_size = pagination_params.limit - 1
+    if len(items) <= page_size:
+        return {"items": items, "next_page_href": None}
+    page = list(items[:page_size])
+    new_retrieved = pagination_params.retrieved + len(page)
+    if new_retrieved >= max_items:
+        return {"items": page, "next_page_href": None}
+    last = page[-1]
+    created_at = _get_field(last, "created_at")
+    row_id = _get_field(last, "id")
+    if not isinstance(created_at, datetime):
+        raise TypeError(f"created_at must be datetime, got {type(created_at).__name__}")
+    if row_id is None or row_id == "":
+        raise TypeError(f"id must be a non-empty value, got {type(row_id).__name__}")
+    cursor_id = None if integer_key is None else integer_key(last)
+    if cursor_id is not None and (not isinstance(cursor_id, int) or isinstance(cursor_id, bool)):
+        raise TypeError(f"integer key must be int, got {type(cursor_id).__name__}")
+    token = _encode_datetime_page_token(
+        created_at,
+        new_retrieved,
+        cursor_id=cursor_id,
+        cursor_string_id=str(row_id),
+    )
+    base_url = request.url.remove_query_params(["page_token"])
+    next_url = base_url.include_query_params(limit=page_size, page_token=token)
+    return {
+        "items": page,
+        "next_page_href": f"{next_url.path}?{next_url.query}" if next_url.query else next_url.path,
+    }
+
+
 def paginate_offset[T](
     request: Request,
     items: Sequence[T],

{core_framework-4.0.1 → core_framework-4.1.0}/core_framework/api/posts/public/router.py

@@ -1,4 +1,4 @@
-from typing import Annotated, Any
+from typing import Annotated, Any, Literal
 
 from fastapi import APIRouter, Depends, Query, Request
 from ulid import ULID
@@ -9,6 +9,7 @@ from core_framework.api.pagination import (
     PaginationResponse,
     TokenCursorQueryParams,
     paginate_cursor,
+    paginate_datetime_id_cursor,
 )
 from core_framework.api.posts.public.schemas import PostResponse
 from core_framework.api.posts.schemas import validate_hashtag
@@ -20,6 +21,30 @@ from core_framework.application.posts.public_service import (
     retrieve_posts_by_user_id,
 )
 
+
+def _paginate_discovery_posts(
+    *,
+    request: Request,
+    items: list[dict[str, Any]],
+    pagination_params: TokenCursorQueryParams,
+    sort: Literal["newest", "votes", "hot"] | None,
+) -> Any:
+    if sort in ("votes", "hot"):
+        return paginate_datetime_id_cursor(
+            request=request,
+            items=items,
+            pagination_params=pagination_params,
+            integer_key=lambda item: item["sort_key"],
+        )
+    return paginate_cursor(
+        request=request,
+        items=items,
+        limit=pagination_params.limit,
+        cursor_field=PaginationCursorType.CREATED_AT,
+        retrieved=pagination_params.retrieved,
+    )
+
+
 router = APIRouter(
     prefix="/posts",
     tags=["posts - public"],
@@ -37,19 +62,23 @@ async def get_posts(
     viewer_id: OptionalUserID,
     pagination_params: Annotated[TokenCursorQueryParams, Depends()],
     following_only: Annotated[bool, Query()] = False,
+    sort: Annotated[Literal["newest", "votes", "hot"] | None, Query()] = None,
 ) -> Any:
+    ranked = sort in ("votes", "hot")
     posts = await retrieve_posts(
         viewer_id=viewer_id if viewer_id else None,
         cursor=pagination_params.cursor,
         limit=pagination_params.limit,
         only_from_following=following_only,
+        order="newest" if not ranked else sort,
+        cursor_post_id=pagination_params.cursor_string_id if ranked else None,
+        cursor_sort_key=pagination_params.cursor_id if ranked else 0,
     )
-    return paginate_cursor(
+    return _paginate_discovery_posts(
         request=request,
         items=posts,
-        limit=pagination_params.limit,
-        cursor_field=PaginationCursorType.CREATED_AT,
-        retrieved=pagination_params.retrieved,
+        pagination_params=pagination_params,
+        sort=sort,
     )
 
 
@@ -59,20 +88,24 @@ async def get_posts_by_user_id(
     request: Request,
     viewer_id: OptionalUserID,
     pagination_params: Annotated[TokenCursorQueryParams, Depends()],
+    sort: Annotated[Literal["newest", "votes", "hot"] | None, Query()] = None,
 ) -> Any:
     validated_user_id = validate_user_id(user_id=user_id)
+    ranked = sort in ("votes", "hot")
     posts = await retrieve_posts_by_user_id(
         user_id=validated_user_id,
         viewer_id=viewer_id if viewer_id else None,
         cursor=pagination_params.cursor,
         limit=pagination_params.limit,
+        order="newest" if not ranked else sort,
+        cursor_post_id=pagination_params.cursor_string_id if ranked else None,
+        cursor_sort_key=pagination_params.cursor_id if ranked else 0,
     )
-    return paginate_cursor(
+    return _paginate_discovery_posts(
         request=request,
         items=posts,
-        limit=pagination_params.limit,
-        cursor_field=PaginationCursorType.CREATED_AT,
-        retrieved=pagination_params.retrieved,
+        pagination_params=pagination_params,
+        sort=sort,
     )
 
 
@@ -87,21 +120,25 @@ async def get_posts_by_hashtag(
     viewer_id: OptionalUserID,
     pagination_params: Annotated[TokenCursorQueryParams, Depends()],
     following_only: Annotated[bool, Query()] = False,
+    sort: Annotated[Literal["newest", "votes", "hot"] | None, Query()] = None,
 ) -> Any:
     validated_hashtag = validate_hashtag(hashtag=hashtag)
+    ranked = sort in ("votes", "hot")
     posts = await retrieve_posts_by_hashtag(
         hashtag=validated_hashtag,
         viewer_id=viewer_id if viewer_id else None,
         cursor=pagination_params.cursor,
         limit=pagination_params.limit,
         only_from_following=following_only,
+        order="newest" if not ranked else sort,
+        cursor_post_id=pagination_params.cursor_string_id if ranked else None,
+        cursor_sort_key=pagination_params.cursor_id if ranked else 0,
     )
-    return paginate_cursor(
+    return _paginate_discovery_posts(
         request=request,
         items=posts,
-        limit=pagination_params.limit,
-        cursor_field=PaginationCursorType.CREATED_AT,
-        retrieved=pagination_params.retrieved,
+        pagination_params=pagination_params,
+        sort=sort,
     )
 
 

core_framework-4.1.0/core_framework/api/ratings/pagination.py

@@ -0,0 +1,23 @@
+from typing import Any
+
+from fastapi import Request
+
+from core_framework.api.pagination import PaginationResult, TokenCursorQueryParams, paginate_datetime_id_cursor
+from core_framework.constants import DEFAULT_MAX_ITEMS
+
+
+def paginate_rating_created_at_cursor(
+    *,
+    request: Request,
+    items: list[dict[str, Any]],
+    pagination_params: TokenCursorQueryParams,
+    include_sort_key_cursor: bool = False,
+    max_items: int = DEFAULT_MAX_ITEMS,
+) -> PaginationResult[dict[str, Any]]:
+    return paginate_datetime_id_cursor(
+        request=request,
+        items=items,
+        pagination_params=pagination_params,
+        integer_key=(lambda item: item["sort_key"]) if include_sort_key_cursor else None,
+        max_items=max_items,
+    )

{core_framework-4.0.1 → core_framework-4.1.0}/core_framework/api/ratings/public/router.py

@@ -35,8 +35,9 @@ async def get_rating_reviews(
     subject_id: RatingSubjectIdPath,
     viewer_id: OptionalUserID,
     pagination_params: Annotated[TokenCursorQueryParams, Depends()],
-    sort: Annotated[Literal["top"] | None, Query()] = None,
+    sort: Annotated[Literal["newest", "votes"] | None, Query()] = None,
 ) -> Any:
+    ranked = sort == "votes"
     reviews = await retrieve_rating_reviews(
         subject_kind=subject_kind,
         subject_id=subject_id,
@@ -44,14 +45,14 @@ async def get_rating_reviews(
         cursor=pagination_params.cursor,
         limit=pagination_params.limit,
         cursor_rating_id=pagination_params.cursor_string_id,
-        sort_by_upvote_count=sort == "top",
-        cursor_upvote_count=pagination_params.cursor_id,
+        order="votes" if ranked else "newest",
+        cursor_sort_key=pagination_params.cursor_id if ranked else 0,
     )
     return paginate_rating_created_at_cursor(
         request=request,
         items=reviews,
         pagination_params=pagination_params,
-        include_upvote_count_cursor=sort == "top",
+        include_sort_key_cursor=ranked,
     )
 
 

{core_framework-4.0.1 → core_framework-4.1.0}/core_framework/api/system/router.py

@@ -6,7 +6,9 @@ from cashews import cache
 from fastapi import APIRouter, Request, Response, status
 from structlog import get_logger
 
+from core_framework.application.agent.probe import check_agent_reachable
 from core_framework.core.runtime import CoreRuntime
+from core_framework.domains.agent import ModelReachability
 
 router = APIRouter(
     tags=["system"],
@@ -14,6 +16,7 @@ router = APIRouter(
 
 OK_STATUS: Final[str] = "OK"
 ERROR_STATUS: Final[str] = "ERROR"
+DISABLED_STATUS: Final[str] = "DISABLED"
 PROBE_TIMEOUT_SECONDS: Final[float] = 2.0
 
 logger = get_logger(__name__)
@@ -59,6 +62,21 @@ async def _probe_redis_queue(runtime: CoreRuntime) -> None:
     await runtime.redis_queue.redis_queue.ping()
 
 
+async def _probe_agent() -> str:
+    try:
+        async with timeout(PROBE_TIMEOUT_SECONDS):
+            reachability = await check_agent_reachable()
+    except Exception as exc:
+        # The message is not logged: a provider error can carry part of the API key.
+        logger.warning("Readiness probe failed", dependency="agent", error_type=type(exc).__name__)
+        return ERROR_STATUS
+    if reachability is ModelReachability.DISABLED:
+        return DISABLED_STATUS
+    if reachability is ModelReachability.OK:
+        return OK_STATUS
+    return ERROR_STATUS
+
+
 @router.get("/health")
 async def health_check() -> dict[str, str]:
     return {"status": OK_STATUS}
@@ -73,11 +91,13 @@ async def readiness_check(request: Request, response: Response) -> dict[str, str
         read_task = tg.create_task(_run_probe("read_postgres", _probe_read_postgres(runtime)))
         cashews_task = tg.create_task(_run_probe("cashews_cache", _probe_cashews_cache()))
         queue_task = tg.create_task(_run_probe("redis_queue", _probe_redis_queue(runtime)))
+        agent_task = tg.create_task(_probe_agent())
 
     write_postgres_status = write_task.result()
     read_postgres_status = read_task.result()
     cashews_cache_status = cashews_task.result()
     redis_queue_status = queue_task.result()
+    agent_status = agent_task.result()
 
     service_statuses = (
         write_postgres_status,
@@ -95,5 +115,6 @@ async def readiness_check(request: Request, response: Response) -> dict[str, str
         "read_postgres_status": read_postgres_status,
         "cashews_cache_status": cashews_cache_status,
         "redis_queue_status": redis_queue_status,
+        "agent_status": agent_status,
         "app_status": app_status,
     }

core_framework-4.1.0/core_framework/application/agent/probe.py

@@ -0,0 +1,12 @@
+import core_framework.domains.agent.dependencies as agent_deps
+from core_framework.domains.agent import ModelProbeResult, ModelReachability
+
+
+async def probe_model_call() -> ModelProbeResult:
+    """Run the fixed admin model-call probe."""
+    return await agent_deps.probe_model_call()
+
+
+async def check_agent_reachable() -> ModelReachability:
+    """Return whether the default model is off, reachable, or failed its lookup."""
+    return await agent_deps.check_agent_reachable()