finbrain-python 0.2.1__tar.gz → 0.2.5__tar.gz

{finbrain_python-0.2.1 → finbrain_python-0.2.5}/.github/workflows/ci.yml

@@ -17,4 +17,5 @@ jobs:
             python-version: ${{ matrix.python }}
       - run: pip install -e .[dev]
       - run: ruff check .
+      - run: mypy
       - run: pytest -q

{finbrain_python-0.2.1 → finbrain_python-0.2.5}/.github/workflows/release.yml

@@ -24,14 +24,14 @@ jobs:
 
       # ─────────── push to TestPyPI first ───────────
       - name: Upload to TestPyPI
-        run: twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+        run: twine upload --skip-existing --repository-url https://test.pypi.org/legacy/ dist/*
         env:
           TWINE_USERNAME: __token__
           TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }}
 
       # ─────────── then to production PyPI ───────────
       - name: Upload to PyPI
-        run: twine upload dist/*
+        run: twine upload --skip-existing dist/*
         env:
           TWINE_USERNAME: __token__
           TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}

{finbrain_python-0.2.1 → finbrain_python-0.2.5}/CHANGELOG.md

@@ -5,6 +5,58 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.5] - 2026-06-18
+
+### Added
+
+- **Patent Filings Endpoint**: `fb.patent_filings.ticker("AAPL")` — fetch USPTO granted patents mapped to a ticker, with grant date, title, type, claim counts, citations, assignee, inventors, and CPC classifications (`/patent-filings/{SYMBOL}`)
+- **Patent Filings Screener**: `fb.screener.patent_filings()` — cross-ticker patent filings with summary stats (total patents, tickers, top CPC sections) (`/screener/patent-filings`)
+- **Patent Filings Plotting**: `fb.plot.patent_filings()` — visualize patent grants as bars sized by claim count on a secondary y-axis overlaid on a price chart, with hover details showing title, type, and CPC section
+- **Async Patent Filings**: Full async support via `AsyncPatentFilingsAPI`
+- **Patent Filings Tests**: Unit tests (`tests/test_patent_filings.py`), screener tests, integration tests, and plotting tests
+- **Sync Context Manager**: `FinBrainClient` now supports `with FinBrainClient(...) as fb:` and exposes `close()` to release the underlying HTTP session (parity with `AsyncFinBrainClient`)
+- **Exception Types**: Dedicated `BadGateway` (502), `ServiceUnavailable` (503), and `GatewayTimeout` (504) exceptions for transient gateway errors
+- **Analyst Ratings Plotting**: `fb.plot.analyst_ratings()` — overlay analyst rating actions and price targets on a price chart, with markers grouped and coloured by action category (upgrade/downgrade/initiate/maintain); fills the last remaining ticker-level dataset without a plot method
+
+### Fixed
+
+- **Date parameter handling**: `datetime.datetime` values passed to `date_from`/`date_to` are now truncated to `YYYY-MM-DD` instead of leaking a full ISO timestamp into the API query
+
+### Changed
+
+- **Retry coverage**: Transient gateway errors (502/503/504) are now retried alongside 500, with exponential back-off
+- **Internal**: Async endpoint date helper re-exports the synchronous `to_datestr` to keep a single source of truth
+- **Internal**: Plotting price-overlay methods now share `_resolve_price_column` and `_to_naive_index` helpers, removing ~250 lines of duplicated validation/timezone boilerplate across the chart methods
+- **Tooling**: Added `mypy` static type checking (validating the published `py.typed` surface) to the dev extra and CI; added a sync-client endpoint-parity test; release uploads now use `--skip-existing` for idempotent re-runs
+
+## [0.2.4] - 2026-03-30
+
+### Added
+
+- **Government Contracts Endpoint**: `fb.government_contracts.ticker("LMT")` — fetch U.S. government contract awards with award amounts, agencies, NAICS codes, and descriptions (`/government-contracts/{SYMBOL}`)
+- **Government Contracts Screener**: `fb.screener.government_contracts()` — cross-ticker government contracts with summary stats (`/screener/government-contracts`)
+- **Government Contracts Plotting**: `fb.plot.government_contracts()` — visualize contract award amounts as bars on a secondary y-axis overlaid on a price chart, with hover details showing agency, NAICS description, and contract description
+- **Async Government Contracts**: Full async support via `AsyncGovernmentContractsAPI`
+- **Government Contracts Tests**: Unit tests (`tests/test_government_contracts.py`), screener tests, integration tests, and plotting tests
+
+## [0.2.3] - 2026-03-17
+
+### Changed
+
+- **Reddit Mentions Screener**: Moved from `fb.reddit_mentions.screener()` to `fb.screener.reddit_mentions()` for consistency with other screener endpoints
+- **Plotting rename**: `fb.plot.reddit_mentions_screener()` renamed to `fb.plot.reddit_mentions_top()` to better reflect the chart's purpose (top N most mentioned tickers)
+
+## [0.2.2] - 2026-03-17
+
+### Added
+
+- **Reddit Mentions Endpoint**: `fb.reddit_mentions.ticker("TSLA")` — fetch per-subreddit mention counts with full timestamps (sampled every 4 hours) (`/reddit-mentions/{SYMBOL}`)
+- **Reddit Mentions Screener**: `fb.screener.reddit_mentions()` — cross-ticker Reddit mentions with aggregated totals and per-subreddit breakdowns (`/screener/reddit-mentions`)
+- **Reddit Mentions Plotting**: `fb.plot.reddit_mentions()` — stacked bars per subreddit overlaid on a price chart; `fb.plot.reddit_mentions_top()` — horizontal stacked bar chart of top N most mentioned tickers
+- **Async Reddit Mentions**: Full async support via `AsyncRedditMentionsAPI`
+- **Reddit Mentions Tests**: Unit tests, integration tests, and functional plotting tests
+- **Plotting Test Coverage**: Added functional tests for all 11 plotting methods
+
 ## [0.2.1] - 2026-03-12
 
 ### Added

{finbrain_python-0.2.1 → finbrain_python-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: finbrain-python
-Version: 0.2.1
+Version: 0.2.5
 Summary: Official Python client for the FinBrain API
 Author-email: Ahmet Salim Bilgin <ahmet@finbrain.tech>
 License-Expression: MIT
@@ -22,6 +22,8 @@ Requires-Dist: httpx>=0.24; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
 Dynamic: license-file
 
 # FinBrain Python SDK&nbsp;<!-- omit in toc -->
@@ -99,6 +101,26 @@ fb.corporate_lobbying.ticker("AAPL",
                              date_to="2025-06-30",
                              as_dataframe=True)
 
+# ---------- reddit mentions ----------
+fb.reddit_mentions.ticker("TSLA",
+                          date_from="2026-03-01",
+                          date_to="2026-03-17",
+                          as_dataframe=True)
+
+# ---------- government contracts ----------
+fb.government_contracts.ticker("LMT",
+                               date_from="2025-01-01",
+                               date_to="2025-12-31",
+                               limit=50,
+                               as_dataframe=True)
+
+# ---------- patent filings ----------
+fb.patent_filings.ticker("AAPL",
+                         date_from="2025-01-01",
+                         date_to="2025-12-31",
+                         limit=50,
+                         as_dataframe=True)
+
 # ---------- insider transactions ----------
 fb.insider_transactions.ticker("AMZN", as_dataframe=True)
 
@@ -130,6 +152,9 @@ fb.news.ticker("AMZN", limit=20, as_dataframe=True)
 fb.screener.sentiment(market="S&P 500", as_dataframe=True)
 fb.screener.predictions_daily(limit=100, as_dataframe=True)
 fb.screener.insider_trading(limit=50)
+fb.screener.reddit_mentions(limit=100, as_dataframe=True)
+fb.screener.government_contracts(limit=100, as_dataframe=True)
+fb.screener.patent_filings(limit=100, as_dataframe=True)
 
 # ---------- recent data ----------
 fb.recent.news(limit=100, as_dataframe=True)
@@ -244,6 +269,33 @@ fb.plot.corporate_lobbying("AAPL",
                            price_data=price_df,
                            date_from="2024-01-01",
                            date_to="2025-06-30")
+
+# Plot Reddit mentions (stacked bars per subreddit) on your price chart
+fb.plot.reddit_mentions("TSLA",
+                        price_data=price_df,
+                        date_from="2026-03-01",
+                        date_to="2026-03-17")
+
+# Plot patent grants (bars sized by claim count) on your price chart
+fb.plot.patent_filings("AAPL",
+                       price_data=price_df,
+                       date_from="2024-01-01",
+                       date_to="2025-06-30")
+
+# Plot analyst ratings & price targets (markers coloured by action) on your price chart
+fb.plot.analyst_ratings("AAPL",
+                        price_data=price_df,
+                        date_from="2024-01-01",
+                        date_to="2025-06-30")
+```
+
+```python
+# ---------- Reddit Mentions Screener Chart (no price data needed) ----------
+# Stacked horizontal bar chart of top 15 most mentioned tickers
+fb.plot.reddit_mentions_top(market="S&P 500")
+
+# Customize the number of tickers shown
+fb.plot.reddit_mentions_top(top_n=10, region="US")
 ```
 
 **Price Data Requirements:**
@@ -289,12 +341,18 @@ fb = FinBrainClient()  # reads from FINBRAIN_API_KEY env var
 | House trades         | `client.house_trades.ticker()`           | `/congress/house/{SYMBOL}`                  |
 | Senate trades        | `client.senate_trades.ticker()`          | `/congress/senate/{SYMBOL}`                 |
 | Corporate lobbying   | `client.corporate_lobbying.ticker()`     | `/lobbying/{SYMBOL}`                        |
+| Reddit mentions      | `client.reddit_mentions.ticker()`        | `/reddit-mentions/{SYMBOL}`                 |
+| Gov. contracts       | `client.government_contracts.ticker()`   | `/government-contracts/{SYMBOL}`            |
+| Patent filings       | `client.patent_filings.ticker()`         | `/patent-filings/{SYMBOL}`                  |
 | Insider transactions | `client.insider_transactions.ticker()`   | `/insider-trading/{SYMBOL}`                 |
 | LinkedIn             | `client.linkedin_data.ticker()`          | `/linkedin/{SYMBOL}`                        |
 | Options – Put/Call   | `client.options.put_call()`              | `/put-call-ratio/{SYMBOL}`                  |
 | Screener             | `client.screener.sentiment()`            | `/screener/sentiment`                       |
 |                      | `client.screener.predictions_daily()`    | `/screener/predictions/daily`               |
 |                      | `client.screener.insider_trading()`      | `/screener/insider-trading`                 |
+|                      | `client.screener.reddit_mentions()`      | `/screener/reddit-mentions`                 |
+|                      | `client.screener.government_contracts()` | `/screener/government-contracts`            |
+|                      | `client.screener.patent_filings()`       | `/screener/patent-filings`                  |
 |                      | ... and 8 more screener methods          |                                             |
 | Recent               | `client.recent.news()`                   | `/recent/news`                              |
 |                      | `client.recent.analyst_ratings()`        | `/recent/analyst-ratings`                   |
@@ -322,6 +380,9 @@ except BadRequest as exc:
 | 405         | `MethodNotAllowed`       | HTTP method not supported on endpoint |
 | 429         | `RateLimitError`         | Too many requests                     |
 | 500         | `ServerError`            | FinBrain internal error               |
+| 502         | `BadGateway`             | Invalid response from upstream server |
+| 503         | `ServiceUnavailable`     | Service temporarily unavailable       |
+| 504         | `GatewayTimeout`         | Upstream server timed out             |
 
 ---
 

{finbrain_python-0.2.1 → finbrain_python-0.2.5}/README.md

@@ -73,6 +73,26 @@ fb.corporate_lobbying.ticker("AAPL",
                              date_to="2025-06-30",
                              as_dataframe=True)
 
+# ---------- reddit mentions ----------
+fb.reddit_mentions.ticker("TSLA",
+                          date_from="2026-03-01",
+                          date_to="2026-03-17",
+                          as_dataframe=True)
+
+# ---------- government contracts ----------
+fb.government_contracts.ticker("LMT",
+                               date_from="2025-01-01",
+                               date_to="2025-12-31",
+                               limit=50,
+                               as_dataframe=True)
+
+# ---------- patent filings ----------
+fb.patent_filings.ticker("AAPL",
+                         date_from="2025-01-01",
+                         date_to="2025-12-31",
+                         limit=50,
+                         as_dataframe=True)
+
 # ---------- insider transactions ----------
 fb.insider_transactions.ticker("AMZN", as_dataframe=True)
 
@@ -104,6 +124,9 @@ fb.news.ticker("AMZN", limit=20, as_dataframe=True)
 fb.screener.sentiment(market="S&P 500", as_dataframe=True)
 fb.screener.predictions_daily(limit=100, as_dataframe=True)
 fb.screener.insider_trading(limit=50)
+fb.screener.reddit_mentions(limit=100, as_dataframe=True)
+fb.screener.government_contracts(limit=100, as_dataframe=True)
+fb.screener.patent_filings(limit=100, as_dataframe=True)
 
 # ---------- recent data ----------
 fb.recent.news(limit=100, as_dataframe=True)
@@ -218,6 +241,33 @@ fb.plot.corporate_lobbying("AAPL",
                            price_data=price_df,
                            date_from="2024-01-01",
                            date_to="2025-06-30")
+
+# Plot Reddit mentions (stacked bars per subreddit) on your price chart
+fb.plot.reddit_mentions("TSLA",
+                        price_data=price_df,
+                        date_from="2026-03-01",
+                        date_to="2026-03-17")
+
+# Plot patent grants (bars sized by claim count) on your price chart
+fb.plot.patent_filings("AAPL",
+                       price_data=price_df,
+                       date_from="2024-01-01",
+                       date_to="2025-06-30")
+
+# Plot analyst ratings & price targets (markers coloured by action) on your price chart
+fb.plot.analyst_ratings("AAPL",
+                        price_data=price_df,
+                        date_from="2024-01-01",
+                        date_to="2025-06-30")
+```
+
+```python
+# ---------- Reddit Mentions Screener Chart (no price data needed) ----------
+# Stacked horizontal bar chart of top 15 most mentioned tickers
+fb.plot.reddit_mentions_top(market="S&P 500")
+
+# Customize the number of tickers shown
+fb.plot.reddit_mentions_top(top_n=10, region="US")
 ```
 
 **Price Data Requirements:**
@@ -263,12 +313,18 @@ fb = FinBrainClient()  # reads from FINBRAIN_API_KEY env var
 | House trades         | `client.house_trades.ticker()`           | `/congress/house/{SYMBOL}`                  |
 | Senate trades        | `client.senate_trades.ticker()`          | `/congress/senate/{SYMBOL}`                 |
 | Corporate lobbying   | `client.corporate_lobbying.ticker()`     | `/lobbying/{SYMBOL}`                        |
+| Reddit mentions      | `client.reddit_mentions.ticker()`        | `/reddit-mentions/{SYMBOL}`                 |
+| Gov. contracts       | `client.government_contracts.ticker()`   | `/government-contracts/{SYMBOL}`            |
+| Patent filings       | `client.patent_filings.ticker()`         | `/patent-filings/{SYMBOL}`                  |
 | Insider transactions | `client.insider_transactions.ticker()`   | `/insider-trading/{SYMBOL}`                 |
 | LinkedIn             | `client.linkedin_data.ticker()`          | `/linkedin/{SYMBOL}`                        |
 | Options – Put/Call   | `client.options.put_call()`              | `/put-call-ratio/{SYMBOL}`                  |
 | Screener             | `client.screener.sentiment()`            | `/screener/sentiment`                       |
 |                      | `client.screener.predictions_daily()`    | `/screener/predictions/daily`               |
 |                      | `client.screener.insider_trading()`      | `/screener/insider-trading`                 |
+|                      | `client.screener.reddit_mentions()`      | `/screener/reddit-mentions`                 |
+|                      | `client.screener.government_contracts()` | `/screener/government-contracts`            |
+|                      | `client.screener.patent_filings()`       | `/screener/patent-filings`                  |
 |                      | ... and 8 more screener methods          |                                             |
 | Recent               | `client.recent.news()`                   | `/recent/news`                              |
 |                      | `client.recent.analyst_ratings()`        | `/recent/analyst-ratings`                   |
@@ -296,6 +352,9 @@ except BadRequest as exc:
 | 405         | `MethodNotAllowed`       | HTTP method not supported on endpoint |
 | 429         | `RateLimitError`         | Too many requests                     |
 | 500         | `ServerError`            | FinBrain internal error               |
+| 502         | `BadGateway`             | Invalid response from upstream server |
+| 503         | `ServiceUnavailable`     | Service temporarily unavailable       |
+| 504         | `GatewayTimeout`         | Upstream server timed out             |
 
 ---
 

{finbrain_python-0.2.1 → finbrain_python-0.2.5}/RELEASE.md

@@ -10,7 +10,7 @@ Starting from v0.1.6, we use **`v`-prefixed tags** (e.g., `v0.1.6`, `v0.2.0`, `v
 
 ### 1. Update CHANGELOG.md
 
-Edit `CHANGELOG.md` and move items from `[Unreleased]` to a new version section:
+Edit `CHANGELOG.md` and add a new version section at the top, above the previous release:
 
 ```markdown
 ## [0.1.6] - 2025-01-15

{finbrain_python-0.2.1 → finbrain_python-0.2.5}/pyproject.toml

@@ -45,9 +45,18 @@ dev = [
     "build",
     "twine",
     "ruff",                      # linter/formatter (optional)
+    "mypy",                      # static type checker (validates py.typed surface)
+    "types-requests",            # stubs for requests (mypy import-untyped otherwise)
 ]
 
 [tool.pytest.ini_options]
 markers = [
     "integration: hits the real FinBrain v2 API (requires FINBRAIN_API_KEY)",
 ]
+
+[tool.mypy]
+# Code targets >=3.9 but uses `from __future__ import annotations` throughout,
+# so checking against 3.10 (mypy's minimum target) is equivalent here.
+python_version = "3.10"
+files = ["src/finbrain"]
+ignore_missing_imports = true   # third-party libs (pandas, plotly, …) ship no stubs here

{finbrain_python-0.2.1 → finbrain_python-0.2.5}/src/finbrain/aio/client.py

@@ -23,10 +23,13 @@ from .endpoints.news import AsyncNewsAPI
 from .endpoints.screener import AsyncScreenerAPI
 from .endpoints.recent import AsyncRecentAPI
 from .endpoints.corporate_lobbying import AsyncCorporateLobbyingAPI
+from .endpoints.reddit_mentions import AsyncRedditMentionsAPI
+from .endpoints.government_contracts import AsyncGovernmentContractsAPI
+from .endpoints.patent_filings import AsyncPatentFilingsAPI
 
 
-# Which status codes merit a retry
-_RETRYABLE_STATUS = {500}
+# Which status codes merit a retry (transient server / gateway errors)
+_RETRYABLE_STATUS = {500, 502, 503, 504}
 # How long to wait between retries   (2, 4, 8 … seconds)
 _BACKOFF_BASE = 2
 
@@ -82,6 +85,9 @@ class AsyncFinBrainClient:
         self.screener = AsyncScreenerAPI(self)
         self.recent = AsyncRecentAPI(self)
         self.corporate_lobbying = AsyncCorporateLobbyingAPI(self)
+        self.reddit_mentions = AsyncRedditMentionsAPI(self)
+        self.government_contracts = AsyncGovernmentContractsAPI(self)
+        self.patent_filings = AsyncPatentFilingsAPI(self)
 
     async def __aenter__(self) -> "AsyncFinBrainClient":
         """Context manager entry."""
@@ -160,7 +166,7 @@ class AsyncFinBrainClient:
 
             # ── Error path ───────────────────────────────────
             if resp.status_code in _RETRYABLE_STATUS and attempt < self.retries:
-                # 500 – exponential back-off then retry
+                # Transient server/gateway error – exponential back-off then retry
                 await asyncio.sleep(_BACKOFF_BASE**attempt)
                 continue
 

finbrain_python-0.2.5/src/finbrain/aio/endpoints/_utils.py

@@ -0,0 +1,12 @@
+"""
+Shared utility functions for async endpoint modules.
+
+These helpers are identical to the synchronous ones, so they are re-exported
+from :mod:`finbrain.endpoints._utils` to keep a single source of truth.
+"""
+
+from __future__ import annotations
+
+from ...endpoints._utils import to_datestr
+
+__all__ = ["to_datestr"]

finbrain_python-0.2.5/src/finbrain/aio/endpoints/government_contracts.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+import pandas as pd
+import datetime as _dt
+from typing import TYPE_CHECKING, Dict, Any, List
+
+from ._utils import to_datestr
+
+if TYPE_CHECKING:
+    from ..client import AsyncFinBrainClient
+
+
+class AsyncGovernmentContractsAPI:
+    """Async wrapper for /government-contracts and /screener/government-contracts endpoints."""
+
+    def __init__(self, client: "AsyncFinBrainClient") -> None:
+        self._c = client
+
+    async def ticker(
+        self,
+        symbol: str,
+        *,
+        date_from: _dt.date | str | None = None,
+        date_to: _dt.date | str | None = None,
+        limit: int | None = None,
+        as_dataframe: bool = False,
+    ) -> Dict[str, Any] | pd.DataFrame:
+        """Fetch government contract awards for a symbol (async)."""
+        params: Dict[str, str] = {}
+        if date_from:
+            params["startDate"] = to_datestr(date_from)
+        if date_to:
+            params["endDate"] = to_datestr(date_to)
+        if limit is not None:
+            params["limit"] = str(limit)
+
+        path = f"government-contracts/{symbol.upper()}"
+
+        data: Dict[str, Any] = await self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            rows: List[Dict[str, Any]] = data.get("contracts", [])
+            df = pd.DataFrame(rows)
+            if not df.empty and "startDate" in df.columns:
+                df["startDate"] = pd.to_datetime(df["startDate"])
+                df.set_index("startDate", inplace=True)
+            return df
+
+        return data

finbrain_python-0.2.5/src/finbrain/aio/endpoints/patent_filings.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+import pandas as pd
+import datetime as _dt
+from typing import TYPE_CHECKING, Dict, Any, List
+
+from ._utils import to_datestr
+
+if TYPE_CHECKING:
+    from ..client import AsyncFinBrainClient
+
+
+class AsyncPatentFilingsAPI:
+    """Async wrapper for /patent-filings and /screener/patent-filings endpoints."""
+
+    def __init__(self, client: "AsyncFinBrainClient") -> None:
+        self._c = client
+
+    async def ticker(
+        self,
+        symbol: str,
+        *,
+        date_from: _dt.date | str | None = None,
+        date_to: _dt.date | str | None = None,
+        limit: int | None = None,
+        as_dataframe: bool = False,
+    ) -> Dict[str, Any] | pd.DataFrame:
+        """Fetch USPTO granted patents for a symbol (async)."""
+        params: Dict[str, str] = {}
+        if date_from:
+            params["startDate"] = to_datestr(date_from)
+        if date_to:
+            params["endDate"] = to_datestr(date_to)
+        if limit is not None:
+            params["limit"] = str(limit)
+
+        path = f"patent-filings/{symbol.upper()}"
+
+        data: Dict[str, Any] = await self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            rows: List[Dict[str, Any]] = data.get("patents", [])
+            df = pd.DataFrame(rows)
+            if not df.empty and "patentDate" in df.columns:
+                df["patentDate"] = pd.to_datetime(df["patentDate"])
+                df.set_index("patentDate", inplace=True)
+            return df
+
+        return data

finbrain_python-0.2.5/src/finbrain/aio/endpoints/reddit_mentions.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+import pandas as pd
+import datetime as _dt
+from typing import TYPE_CHECKING, Dict, Any, List
+
+from ._utils import to_datestr
+
+if TYPE_CHECKING:
+    from ..client import AsyncFinBrainClient
+
+
+class AsyncRedditMentionsAPI:
+    """Async wrapper for /reddit-mentions and /screener/reddit-mentions endpoints."""
+
+    def __init__(self, client: "AsyncFinBrainClient") -> None:
+        self._c = client
+
+    async def ticker(
+        self,
+        symbol: str,
+        *,
+        date_from: _dt.date | str | None = None,
+        date_to: _dt.date | str | None = None,
+        limit: int | None = None,
+        as_dataframe: bool = False,
+    ) -> Dict[str, Any] | pd.DataFrame:
+        """Fetch Reddit mention counts for a symbol across subreddits (async)."""
+        params: Dict[str, str] = {}
+        if date_from:
+            params["startDate"] = to_datestr(date_from)
+        if date_to:
+            params["endDate"] = to_datestr(date_to)
+        if limit is not None:
+            params["limit"] = str(limit)
+
+        path = f"reddit-mentions/{symbol.upper()}"
+
+        data: Dict[str, Any] = await self._c._request("GET", path, params=params)
+
+        if as_dataframe:
+            rows: List[Dict[str, Any]] = data.get("data", [])
+            df = pd.DataFrame(rows)
+            if not df.empty and "date" in df.columns:
+                df["date"] = pd.to_datetime(df["date"])
+                df.set_index("date", inplace=True)
+            return df
+
+        return data

{finbrain_python-0.2.1 → finbrain_python-0.2.5}/src/finbrain/aio/endpoints/screener.py

@@ -208,3 +208,41 @@ class AsyncScreenerAPI:
         """Screen monthly (12-month) predictions across tickers."""
         params = self._build_params(limit=limit, market=market, region=region)
         return await self._get("screener/predictions/monthly", params, as_dataframe)
+
+    # ── reddit mentions ────────────────────────────────────────
+
+    async def reddit_mentions(
+        self,
+        *,
+        limit: int | None = None,
+        market: str | None = None,
+        region: str | None = None,
+        as_dataframe: bool = False,
+    ) -> List[Dict[str, Any]] | pd.DataFrame:
+        """Screen Reddit mention counts across tickers (async)."""
+        params = self._build_params(limit=limit, market=market, region=region)
+        return await self._get("screener/reddit-mentions", params, as_dataframe)
+
+    # ── government contracts ──────────────────────────────────
+
+    async def government_contracts(
+        self,
+        *,
+        limit: int | None = None,
+        as_dataframe: bool = False,
+    ) -> List[Dict[str, Any]] | pd.DataFrame:
+        """Screen government contracts across all tickers (async)."""
+        params = self._build_params(limit=limit)
+        return await self._get("screener/government-contracts", params, as_dataframe)
+
+    # ── patent filings ────────────────────────────────────────
+
+    async def patent_filings(
+        self,
+        *,
+        limit: int | None = None,
+        as_dataframe: bool = False,
+    ) -> List[Dict[str, Any]] | pd.DataFrame:
+        """Screen USPTO patent filings across all tickers (async)."""
+        params = self._build_params(limit=limit)
+        return await self._get("screener/patent-filings", params, as_dataframe)

{finbrain_python-0.2.1 → finbrain_python-0.2.5}/src/finbrain/client.py

@@ -24,10 +24,13 @@ from .endpoints.news import NewsAPI
 from .endpoints.screener import ScreenerAPI
 from .endpoints.recent import RecentAPI
 from .endpoints.corporate_lobbying import CorporateLobbyingAPI
+from .endpoints.reddit_mentions import RedditMentionsAPI
+from .endpoints.government_contracts import GovernmentContractsAPI
+from .endpoints.patent_filings import PatentFilingsAPI
 
 
-# Which status codes merit a retry
-_RETRYABLE_STATUS = {500}
+# Which status codes merit a retry (transient server / gateway errors)
+_RETRYABLE_STATUS = {500, 502, 503, 504}
 # How long to wait between retries   (2, 4, 8 … seconds)
 _BACKOFF_BASE = 2
 
@@ -77,6 +80,22 @@ class FinBrainClient:
         self.screener = ScreenerAPI(self)
         self.recent = RecentAPI(self)
         self.corporate_lobbying = CorporateLobbyingAPI(self)
+        self.reddit_mentions = RedditMentionsAPI(self)
+        self.government_contracts = GovernmentContractsAPI(self)
+        self.patent_filings = PatentFilingsAPI(self)
+
+    # ---------- lifecycle ----------
+    def __enter__(self) -> "FinBrainClient":
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager exit — close the underlying HTTP session."""
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying ``requests.Session``."""
+        self.session.close()
 
     # ---------- private helpers ----------
     def _request(
@@ -127,7 +146,7 @@ class FinBrainClient:
 
             # ── Error path ───────────────────────────────────
             if resp.status_code in _RETRYABLE_STATUS and attempt < self.retries:
-                # 500 – exponential back-off then retry
+                # Transient server/gateway error – exponential back-off then retry
                 time.sleep(_BACKOFF_BASE**attempt)
                 continue
 

{finbrain_python-0.2.1 → finbrain_python-0.2.5}/src/finbrain/endpoints/_utils.py

@@ -28,10 +28,16 @@ def to_datestr(value: _dt.date | str) -> str:
 
     Examples
     --------
-    >>> from datetime import date
+    >>> from datetime import date, datetime
     >>> to_datestr(date(2025, 1, 15))
     '2025-01-15'
+    >>> to_datestr(datetime(2025, 1, 15, 9, 30))
+    '2025-01-15'
     >>> to_datestr("2025-01-15")
     '2025-01-15'
     """
+    # ``datetime`` subclasses ``date``; take the date part so the time
+    # component never leaks into the ``YYYY-MM-DD`` API parameter.
+    if isinstance(value, _dt.datetime):
+        return value.date().isoformat()
     return value.isoformat() if isinstance(value, _dt.date) else value