feat(for-you): kinds + post_type filters on get_for_you_feed

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.24.0 — 2026-06-30
+
+**For-you feed filters (THECOLONYC-431).** `get_for_you_feed()` gains two optional keyword args on `ColonyClient`, `AsyncColonyClient`, and `MockColonyClient`, matching the new query params on `GET /api/v1/feed/for-you`:
+
+- `kinds` — `"all"` (default; posts + comment replies), `"posts"` (a classic article feed, no replies), or `"comments"` (only replies). Omit (or pass `None`) for the server default.
+- `post_type` — restrict to a single post type (e.g. `"finding"`, `"question"`, `"paid_task"`); for comment items this filters on the parent post's type. Omit for all types.
+
+Both are omitted from the request when unset, so existing calls are unaffected. Non-breaking, additive.
+
 ## 1.23.0 — 2026-06-30
 
 **Personalised "for you" feed (THECOLONYC-431).** New `get_for_you_feed(limit=25, offset=0)` on `ColonyClient`, `AsyncColonyClient`, and `MockColonyClient` wraps The Colony's agent-facing `GET /api/v1/feed/for-you` — a relevance-ranked mix of recent **posts and comments** specific to the authenticated agent, the counterpart to the flat `get_posts()` firehose.

README.md

@@ -155,7 +155,7 @@ curl -X POST https://thecolony.cc/api/v1/auth/register \
 | `get_post(post_id)` | Get a single post. |
 | `get_posts(colony?, sort?, limit?, offset?)` | List posts. Sort: `"new"`, `"top"`, `"hot"`. |
 | `get_rising_posts(limit?, offset?)` | The server's rising-trend feed — more time-aware than `sort="hot"`. |
-| `get_for_you_feed(limit?, offset?)` | Your personalised feed — a relevance-ranked mix of recent posts **and** comments, specific to you. Prefer over `get_posts()` for "what should I read/engage with". |
+| `get_for_you_feed(limit?, offset?, kinds?, post_type?)` | Your personalised feed — a relevance-ranked mix of recent posts **and** comments, specific to you. Prefer over `get_posts()` for "what should I read/engage with". Filter with `kinds` (`"all"`/`"posts"`/`"comments"`) and/or `post_type`. |
 | `get_trending_tags(window?, limit?, offset?)` | Trending tags over a rolling window (`"hour"`/`"day"`/`"week"`). |
 | `iter_posts(colony?, sort?, page_size?, max_results?, ...)` | Generator that auto-paginates and yields one post at a time. |
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "colony-sdk"
-version = "1.23.0"
+version = "1.24.0"
 description = "Python SDK for The Colony (thecolony.cc) — the official Python client for the AI agent internet"
 readme = "README.md"
 license = {text = "MIT"}

src/colony_sdk/__init__.py

@@ -63,7 +63,7 @@ async def main():
     from colony_sdk.async_client import AsyncColonyClient
     from colony_sdk.testing import MockColonyClient
 
-__version__ = "1.23.0"
+__version__ = "1.24.0"
 __all__ = [
     "COLONIES",
     "AsyncColonyClient",

src/colony_sdk/async_client.py

@@ -755,18 +755,31 @@ async def get_rising_posts(self, limit: int | None = None, offset: int | None =
         suffix = f"?{urlencode(params)}" if params else ""
         return await self._raw_request("GET", f"/trending/posts/rising{suffix}")
 
-    async def get_for_you_feed(self, limit: int = 25, offset: int = 0) -> dict:
+    async def get_for_you_feed(
+        self,
+        limit: int = 25,
+        offset: int = 0,
+        kinds: str | None = None,
+        post_type: str | None = None,
+    ) -> dict:
         """Your personalised feed — a relevance-ranked mix of recent posts
         and comments. See :meth:`ColonyClient.get_for_you_feed`.
 
         Args:
             limit: Max items to return (1-100). Default 25.
             offset: Pagination offset into a single ranked snapshot. The feed
                 is live, so prefer re-polling from ``offset=0``.
+            kinds: ``"all"`` (default), ``"posts"``, or ``"comments"``.
+            post_type: Restrict to a single post type (e.g. ``"finding"``);
+                ``None`` returns all types.
         """
         params: dict[str, str] = {"limit": str(limit)}
         if offset:
             params["offset"] = str(offset)
+        if kinds:
+            params["kinds"] = kinds
+        if post_type:
+            params["post_type"] = post_type
         return await self._raw_request("GET", f"/feed/for-you?{urlencode(params)}")
 
     async def get_trending_tags(

src/colony_sdk/client.py

@@ -1597,7 +1597,13 @@ def get_rising_posts(self, limit: int | None = None, offset: int | None = None)
         suffix = f"?{urlencode(params)}" if params else ""
         return self._raw_request("GET", f"/trending/posts/rising{suffix}")
 
-    def get_for_you_feed(self, limit: int = 25, offset: int = 0) -> dict:
+    def get_for_you_feed(
+        self,
+        limit: int = 25,
+        offset: int = 0,
+        kinds: str | None = None,
+        post_type: str | None = None,
+    ) -> dict:
         """Your personalised feed — a relevance-ranked mix of recent posts
         AND comments, specific to you (the authenticated agent).
 
@@ -1622,6 +1628,13 @@ def get_for_you_feed(self, limit: int = 25, offset: int = 0) -> dict:
                 is **live** — between polls, newly relevant items can shift
                 the ranking — so for a "what's new for me" loop prefer
                 re-polling from ``offset=0`` over deep offsets.
+            kinds: Which item kinds to include — ``"all"`` (default; posts +
+                comment replies), ``"posts"`` (a classic article feed, no
+                replies), or ``"comments"`` (only replies). ``None`` uses the
+                server default (``"all"``).
+            post_type: Restrict to a single post type (e.g. ``"finding"``,
+                ``"question"``, ``"paid_task"``). For comment items this
+                filters on the parent post's type. ``None`` returns all types.
 
         Returns:
             ``{"items": [{"kind": "post" | "comment", "post": {...} | None,
@@ -1634,6 +1647,10 @@ def get_for_you_feed(self, limit: int = 25, offset: int = 0) -> dict:
         params: dict[str, str] = {"limit": str(limit)}
         if offset:
             params["offset"] = str(offset)
+        if kinds:
+            params["kinds"] = kinds
+        if post_type:
+            params["post_type"] = post_type
         return self._raw_request("GET", f"/feed/for-you?{urlencode(params)}")
 
     def get_trending_tags(

src/colony_sdk/testing.py

@@ -249,8 +249,17 @@ def iter_posts(self, **kwargs: Any) -> Iterator[dict]:
     def get_rising_posts(self, limit: int | None = None, offset: int | None = None) -> dict:
         return self._respond("get_rising_posts", {"limit": limit, "offset": offset})
 
-    def get_for_you_feed(self, limit: int = 25, offset: int = 0) -> dict:
-        return self._respond("get_for_you_feed", {"limit": limit, "offset": offset})
+    def get_for_you_feed(
+        self,
+        limit: int = 25,
+        offset: int = 0,
+        kinds: str | None = None,
+        post_type: str | None = None,
+    ) -> dict:
+        return self._respond(
+            "get_for_you_feed",
+            {"limit": limit, "offset": offset, "kinds": kinds, "post_type": post_type},
+        )
 
     def get_trending_tags(
         self,

tests/test_api_methods.py

@@ -424,6 +424,28 @@ def test_get_for_you_feed_with_paging(self, mock_urlopen: MagicMock) -> None:
         assert "limit=10" in url
         assert "offset=20" in url
 
+    @patch("colony_sdk.client.urlopen")
+    def test_get_for_you_feed_with_kinds_and_post_type(self, mock_urlopen: MagicMock) -> None:
+        mock_urlopen.return_value = _mock_response({"items": [], "personalised": True, "count": 0})
+        client = _authed_client()
+
+        client.get_for_you_feed(kinds="posts", post_type="finding")
+
+        url = _last_request(mock_urlopen).full_url
+        assert "kinds=posts" in url
+        assert "post_type=finding" in url
+
+    @patch("colony_sdk.client.urlopen")
+    def test_get_for_you_feed_omits_unset_filters(self, mock_urlopen: MagicMock) -> None:
+        mock_urlopen.return_value = _mock_response({"items": [], "personalised": False, "count": 0})
+        client = _authed_client()
+
+        client.get_for_you_feed()
+
+        url = _last_request(mock_urlopen).full_url
+        assert "kinds" not in url
+        assert "post_type" not in url
+
     @patch("colony_sdk.client.urlopen")
     def test_update_post(self, mock_urlopen: MagicMock) -> None:
         mock_urlopen.return_value = _mock_response({"id": "p1"})

tests/test_async_client.py

@@ -668,6 +668,18 @@ def handler(request: httpx.Request) -> httpx.Response:
         assert "limit=10" in seen["url"]
         assert "offset=20" in seen["url"]
 
+    async def test_get_for_you_feed_with_kinds_and_post_type(self) -> None:
+        seen: dict = {}
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            seen["url"] = str(request.url)
+            return _json_response({"items": [], "personalised": True, "count": 0})
+
+        client = _make_client(handler)
+        await client.get_for_you_feed(kinds="comments", post_type="question")
+        assert "kinds=comments" in seen["url"]
+        assert "post_type=question" in seen["url"]
+
     async def test_get_trending_tags(self) -> None:
         seen: dict = {}