finance-pulse 0.1.0__py3-none-any.whl

finance_pulse/__init__.py

@@ -0,0 +1,5 @@
+"""Finance Pulse: financial news as structured, sourced statements (https://fintopic.news/docs)."""
+from .client import RAPIDAPI, Backend, FinancePulse, FinancePulseError
+
+__all__ = ["FinancePulse", "FinancePulseError", "Backend", "RAPIDAPI"]
+__version__ = "0.1.0"

finance_pulse/client.py

@@ -0,0 +1,327 @@
+"""Client for the Finance Pulse API (version 2.0, the /v2 endpoints), served through RapidAPI.
+
+Every method returns the API's JSON as plain dicts, unchanged: {"data": ..., "next_cursor": ..., "snapshot": ...}.
+The API reference is at https://fintopic.news/docs/reference.
+"""
+from __future__ import annotations
+
+import json
+import math
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterator, Mapping, Optional, Sequence, Union
+from urllib.parse import quote
+
+import httpx
+
+PRICING_URL = "https://rapidapi.com/evankos/api/finance-pulse/pricing"
+
+
+@dataclass(frozen=True)
+class Backend:
+    """Where the API is reached and how a key is sent. The API itself (paths, parameters, responses) is the same
+    behind every backend."""
+    base_url: str
+    key_header: str                      # the header that carries the key
+    key_env: str                         # environment variable read when no api_key is passed
+    signup_url: str                      # where to get a key
+    key_prefix: str = ""                 # e.g. "Bearer "
+    extra_headers: Mapping[str, str] = field(default_factory=dict)
+
+    def headers(self, api_key: str) -> dict:
+        return {self.key_header: self.key_prefix + api_key, **self.extra_headers}
+
+
+RAPIDAPI = Backend(base_url="https://finance-pulse.p.rapidapi.com", key_header="X-RapidAPI-Key",
+                   key_env="RAPIDAPI_KEY", signup_url=PRICING_URL,
+                   extra_headers={"X-RapidAPI-Host": "finance-pulse.p.rapidapi.com"})
+BUILD_INTERVAL_SECONDS = 150      # the API builds a new snapshot about this often; polling faster returns the same data
+
+Many = Union[str, Sequence[str], None]
+
+
+class FinancePulseError(Exception):
+    """Any failed request. `status` is the HTTP status, or 0 when no answer arrived (timeout, network). `title`,
+    `detail` and `param` come from the API's problem+json body when there is one (a gateway's own errors, e.g.
+    RapidAPI's 429 for the plan's quota, only have a message). `retry_after` is the Retry-After header in seconds."""
+
+    def __init__(self, status: int, title: str, detail: Optional[str] = None, param: Optional[str] = None,
+                 retry_after: Optional[float] = None):
+        self.status, self.title, self.detail, self.param, self.retry_after = status, title, detail, param, retry_after
+        text = f"{status} {title}" if status else title
+        if detail:
+            text += f": {detail}"
+        if param:
+            text += f" (parameter: {param})"
+        super().__init__(text)
+
+    @property
+    def transient(self) -> bool:
+        """True when the same request may succeed later: no answer, or a server-side (5xx) error."""
+        return self.status == 0 or self.status >= 500
+
+
+def _many(value: Many) -> Optional[str]:
+    """Several values go out comma-separated in one parameter (the API reads them as OR)."""
+    if value is None:
+        return None
+    return value if isinstance(value, str) else ",".join(value)
+
+
+def _segment(value: str) -> str:
+    return quote(str(value), safe="")
+
+
+class FinancePulse:
+    """Finance Pulse API client.
+
+        fp = FinancePulse()                      # key from the RAPIDAPI_KEY environment variable
+        for s in fp.statements(symbol="NVDA", importance_min="high", limit=5)["data"]:
+            print(s["published_at"], s["sentiment"], s["statement"])
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, backend: Backend = RAPIDAPI,
+                 base_url: Optional[str] = None, timeout: float = 30.0,
+                 transport: Optional[httpx.BaseTransport] = None):
+        api_key = (api_key or os.environ.get(backend.key_env) or "").strip()
+        if not api_key:
+            raise ValueError(f"No API key: pass api_key= or set {backend.key_env}. "
+                             f"Get a free key at {backend.signup_url}")
+        if not (api_key.isascii() and api_key.isprintable()):
+            raise ValueError(f"The API key ({backend.key_env}) contains characters a key cannot have; copy it again")
+        self.backend = backend
+        # Redirects are followed by hand in get(): httpx would send the key header to whatever host one names.
+        self._http = httpx.Client(base_url=base_url or backend.base_url, timeout=timeout, transport=transport,
+                                  headers=backend.headers(api_key))
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "FinancePulse":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    # ---- transport ---------------------------------------------------------------------------------------------
+
+    def get(self, path: str, **params: Any) -> dict:
+        """GET any path of the API, e.g. "/v2/meta". None values are dropped, booleans are sent as true/false.
+        Raises FinancePulseError for every failure, including timeouts and network errors (status 0)."""
+        if not path.startswith("/") or path.startswith("//"):
+            raise ValueError("path must start with a single '/': the key is only ever sent to the API's own host")
+        query = {key: (str(value).lower() if isinstance(value, bool) else str(value))
+                 for key, value in params.items() if value is not None}
+        try:
+            response = self._http.get(path, params=query)
+            for _ in range(3):          # a merged theme answers 308 to its successor, on the same host
+                if not response.has_redirect_location:
+                    break
+                target = response.url.join(response.headers["location"])
+                if (target.scheme, target.host, target.port) != (response.url.scheme, response.url.host, response.url.port):
+                    raise FinancePulseError(response.status_code, "Redirect to another origin refused",
+                                            f"{target.scheme}://{target.netloc.decode()}")
+                response = self._http.get(target)
+        except httpx.HTTPError as exc:
+            raise FinancePulseError(0, "Could not reach the API", f"{type(exc).__name__}: {exc}".rstrip(": ")) from exc
+        try:
+            body = response.json()
+        except ValueError:
+            body = None
+        if response.is_success:
+            if not isinstance(body, dict) or "data" not in body:
+                raise FinancePulseError(response.status_code, "Unexpected response",
+                                        "the body is not the API's JSON envelope")
+            return body
+        if not isinstance(body, dict):
+            body = {}
+        title = body.get("title") or body.get("message") or body.get("detail") or response.reason_phrase
+        detail = body.get("detail") if body.get("title") else None
+        try:
+            retry_after = max(0.0, float(response.headers.get("retry-after", "")))
+        except ValueError:              # absent, or an HTTP date
+            retry_after = None
+        if retry_after is not None and not math.isfinite(retry_after):
+            retry_after = None
+        raise FinancePulseError(response.status_code, str(title), detail, body.get("param"), retry_after)
+
+    def _pages(self, path: str, params: dict, max_items: Optional[int]) -> Iterator[dict]:
+        seen = 0
+        while True:
+            page = self.get(path, **params)
+            for row in page["data"]:
+                yield row
+                seen += 1
+                if max_items is not None and seen >= max_items:
+                    return
+            if not page.get("next_cursor"):
+                return
+            params = {**params, "cursor": page["next_cursor"]}
+
+    # ---- statements --------------------------------------------------------------------------------------------
+
+    def statements(self, *, symbol: Many = None, sector: Many = None, theme_id: Optional[str] = None,
+                   topic_id: Optional[str] = None, sentiment: Many = None, importance_min: Optional[str] = None,
+                   source_type: Many = None, since: Optional[str] = None, until: Optional[str] = None,
+                   has_image: Optional[bool] = None, limit: int = 50, cursor: Optional[str] = None) -> dict:
+        """Search statements across all topics, newest first by the article's post time. One page.
+        symbol, sector, sentiment and source_type take one value or a list (OR)."""
+        return self.get("/v2/statements", symbol=_many(symbol), sector=_many(sector), theme_id=theme_id,
+                        topic_id=topic_id, sentiment=_many(sentiment), importance_min=importance_min,
+                        source_type=_many(source_type), since=since, until=until, has_image=has_image, limit=limit,
+                        cursor=cursor)
+
+    def iter_statements(self, *, max_items: Optional[int] = 500, **filters: Any) -> Iterator[dict]:
+        """Statements across pages (each page is one request). Takes the filters of statements().
+        max_items=None reads to the end of the window."""
+        filters.setdefault("limit", 100)
+        for key in ("symbol", "sector", "sentiment", "source_type"):
+            if key in filters:
+                filters[key] = _many(filters[key])
+        return self._pages("/v2/statements", filters, max_items)
+
+    def statement(self, statement_id: str) -> dict:
+        return self.get(f"/v2/statements/{_segment(statement_id)}")
+
+    def feed(self, *, cursor: Optional[str] = None, symbol: Many = None, sector: Many = None,
+             theme_id: Optional[str] = None, topic_id: Optional[str] = None, sentiment: Many = None,
+             importance_min: Optional[str] = None, source_type: Many = None, limit: int = 100) -> dict:
+        """Statements in the order they entered the API, after `cursor`. Without a cursor: the last 24 hours.
+        next_cursor is always set; store it and pass it on the next call."""
+        return self.get("/v2/feed", cursor=cursor, symbol=_many(symbol), sector=_many(sector), theme_id=theme_id,
+                        topic_id=topic_id, sentiment=_many(sentiment), importance_min=importance_min,
+                        source_type=_many(source_type), limit=limit)
+
+    def poll_feed(self, *, cursor: Optional[str] = None, cursor_file: Union[str, Path, None] = None,
+                  interval: float = BUILD_INTERVAL_SECONDS, max_polls: Optional[int] = None,
+                  **filters: Any) -> Iterator[dict]:
+        """Yield new statements as they enter the API, forever (or for max_polls successful polls). Takes the
+        filters of feed().
+
+        With cursor_file the position survives restarts: a statement is recorded as handled when you ask for
+        the next one, so after a crash or a `break` nothing is skipped and only the statement you were working on
+        is delivered again (dedupe on `id` if that matters). Two limits:
+        - The first run starts 24 hours back, and there is no position to store until its first page has been
+          fully handled. A restart before that begins again 24 hours before the restart, so statements of that
+          first page that were not handled and are older than that are not delivered.
+        - After a long pause the poller reads the whole backlog since its saved position, page after page
+          without sleeping, one request per `limit` statements. Delete the file to start 24 hours back instead.
+        Without cursor_file every start begins 24 hours back. A saved position belongs to the filters it was
+        reached with: use one cursor file per set of filters.
+
+        A page that comes back full is followed immediately; otherwise the poller sleeps `interval` seconds, which
+        should not be lower than the API's 150 s build interval. Temporary failures (timeouts, network errors,
+        5xx) are retried with a growing pause of up to 5 minutes; other errors, such as a used-up quota (429),
+        are raised.
+        """
+        path = Path(cursor_file) if cursor_file else None
+        handled: set = set()
+        if path is not None and not path.parent.is_dir():
+            raise ValueError(f"The directory of cursor_file does not exist: {path.parent}")
+        if path is not None and path.exists():
+            try:
+                state = json.loads(path.read_text())
+                saved, ids = state["cursor"], state.get("handled", [])
+                if not (saved is None or isinstance(saved, str)) or not isinstance(ids, list) \
+                        or not all(isinstance(i, str) for i in ids):
+                    raise TypeError
+                handled = set(ids)
+            except (ValueError, KeyError, TypeError) as exc:
+                raise ValueError(f"{path} is not a poll_feed cursor file; delete it to start 24 hours back") from exc
+            if cursor is None:
+                cursor = saved
+            else:
+                handled = set()        # an explicit cursor overrides the file
+
+        def save(position: Optional[str], done: set) -> None:
+            if path is None:
+                return
+            tmp = path.with_name(path.name + ".tmp")
+            tmp.write_text(json.dumps({"cursor": position, "handled": sorted(done)}))
+            os.replace(tmp, path)       # never leaves a half-written file
+
+        save(cursor, handled)           # fails now, not after the first statement, if the file cannot be written
+        limit = filters["limit"] = filters.get("limit") or 100
+        polls = failures = 0
+        while max_polls is None or polls < max_polls:
+            try:
+                page = self.feed(cursor=cursor, **filters)
+            except FinancePulseError as exc:
+                if not exc.transient:
+                    raise
+                failures += 1
+                time.sleep(min(300, exc.retry_after or 10 * 2 ** min(failures - 1, 5)))
+                continue
+            failures = 0
+            polls += 1
+            for statement in page["data"]:
+                if statement["id"] in handled:
+                    continue            # delivered before the restart
+                yield statement
+                handled.add(statement["id"])
+                save(cursor, handled)
+            # The page is behind the new cursor; ids handled earlier that it did not contain (the previous run
+            # used a larger limit) are still ahead and stay recorded.
+            handled -= {statement["id"] for statement in page["data"]}
+            cursor = page["next_cursor"]
+            save(cursor, handled)
+            if len(page["data"]) < limit and (max_polls is None or polls < max_polls):
+                time.sleep(interval)
+
+    # ---- signals -----------------------------------------------------------------------------------------------
+
+    def series(self, *, symbol: Optional[str] = None, sector: Optional[str] = None, theme_id: Optional[str] = None,
+               topic_id: Optional[str] = None, interval: str = "day", since: Optional[str] = None,
+               until: Optional[str] = None, source_type: Many = None, importance_min: Optional[str] = None) -> dict:
+        """Hourly or daily statement counts, sentiment and distinct sources for exactly one entity (zero-filled).
+        The last bucket is the current, still incomplete hour or day."""
+        return self.get("/v2/series", symbol=symbol, sector=sector, theme_id=theme_id, topic_id=topic_id,
+                        interval=interval, since=since, until=until, source_type=_many(source_type),
+                        importance_min=importance_min)
+
+    def symbols(self, *, period: str = "w", sort: str = "mentions", sector: Optional[str] = None,
+                kind: Many = None, min_mentions: int = 3, limit: int = 500) -> dict:
+        """Symbol screener. period: d (24 h), w (7 d), window. sort: mentions, sources, score, change.
+        kind narrows to entity kinds, e.g. ["equity", "etf"] for tradable tickers (all kinds are in meta()).
+        Each row carries the entity's `kind` and `name`. `change` is null for period="window". limit: up to
+        20000 (every symbol: period="window", min_mentions=1, limit=20000)."""
+        return self.get("/v2/symbols", period=period, sort=sort, sector=sector, kind=_many(kind),
+                        min_mentions=min_mentions, limit=limit)
+
+    def sectors(self, *, period: str = "w", sort: str = "mentions") -> dict:
+        """The 11 GICS sectors with the same statistics as symbols()."""
+        return self.get("/v2/sectors", period=period, sort=sort)
+
+    # ---- developments ------------------------------------------------------------------------------------------
+
+    def trending(self, *, kind: Optional[str] = None, theme_id: Optional[str] = None,
+                 symbol: Optional[str] = None) -> dict:
+        """Developments the most outlets picked up. kind: live (last 2 hours) or slot (2-hour slots, 7 days)."""
+        return self.get("/v2/trending", kind=kind, theme_id=theme_id, symbol=symbol)
+
+    def topics(self, *, theme_id: Optional[str] = None, symbol: Many = None, sector: Optional[str] = None,
+               ids: Many = None, updated_since: Optional[str] = None, min_statements: int = 1,
+               sort: str = "recent", limit: int = 50, cursor: Optional[str] = None) -> dict:
+        """Topics (developments). sort: recent, size, oldest, velocity. ids: up to 50 topic ids.
+        A topic's `revision` changes whenever the topic or its last-7-day statements change."""
+        return self.get("/v2/topics", theme_id=theme_id, symbol=_many(symbol), sector=sector, ids=_many(ids),
+                        updated_since=updated_since, min_statements=min_statements, sort=sort, limit=limit,
+                        cursor=cursor)
+
+    def topic(self, topic_id: str) -> dict:
+        """One topic with its statement counts per source type and its 20 newest statements."""
+        return self.get(f"/v2/topics/{_segment(topic_id)}")
+
+    def themes(self, *, symbol: Many = None, sector: Many = None, sort: str = "size") -> dict:
+        """All themes with their statistics, or only those with statements about a symbol or sector.
+        sort: size (statements), topics, recent (last statement), velocity (last 24 h). Not paged."""
+        return self.get("/v2/themes", symbol=_many(symbol), sector=_many(sector), sort=sort)
+
+    def theme(self, theme_id: str) -> dict:
+        return self.get(f"/v2/themes/{_segment(theme_id)}")
+
+    def meta(self) -> dict:
+        """The window, counts, known data incidents and every accepted filter value."""
+        return self.get("/v2/meta")

finance_pulse/mcp_server.py

@@ -0,0 +1,270 @@
+"""MCP server for Finance Pulse: lets an assistant query financial news as sourced statements.
+
+Run:  RAPIDAPI_KEY=... uvx finance-pulse        (stdio transport; `finance-pulse-mcp` is the same command)
+
+Every tool is one API request (plans have a monthly request quota), so results are trimmed to the fields an
+assistant needs and default to small pages.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from typing import Annotated, Literal, Optional
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+from . import __version__
+from .client import RAPIDAPI, FinancePulse, FinancePulseError
+
+BACKEND = RAPIDAPI
+
+Sector = Literal["CommunicationServices", "ConsumerDiscretionary", "ConsumerStaples", "Energy", "Financials",
+                 "HealthCare", "Industrials", "InformationTechnology", "Materials", "RealEstate", "Utilities"]
+Sentiment = Literal["bullish", "bearish", "neutral"]
+Importance = Literal["low", "medium", "high", "ultra"]
+SourceType = Literal["news", "speculative", "reddit"]
+
+# Argument types: the description sits on the field, where the model reads it when it fills the call.
+Symbols = Annotated[Optional[str], Field(description="Ticker or entity code, e.g. NVDA. Comma-separate several (OR), up to 10.")]
+OneSymbol = Annotated[Optional[str], Field(description="One ticker or entity code, e.g. NVDA")]
+SectorArg = Annotated[Optional[Sector], Field(description="GICS sector")]
+ThemeId = Annotated[Optional[str], Field(description="Theme id from `themes` or `reference`")]
+TopicId = Annotated[Optional[str], Field(description="Topic (development) id, as returned in topic_id or topics[].id")]
+Time = Annotated[Optional[str], Field(description="ISO-8601 time, e.g. 2026-10-01T00:00:00Z")]
+Cursor = Annotated[Optional[str], Field(description="next_cursor from the previous call, for the next page")]
+PageSize = Annotated[int, Field(ge=1, le=100, description="How many to return, 1-100")]
+
+INSTRUCTIONS = """Finance Pulse turns financial news into statements: one-sentence facts extracted from articles,
+each with sentiment (bullish/bearish/neutral), importance (low/medium/high/ultra), symbols, GICS sectors, the
+source and the article's publication time. Statements about the same development are clustered into topics, and
+topics belong to themes. Data covers a rolling window of about two months and is rebuilt every few minutes.
+
+Each tool call uses one request of the user's plan quota, so prefer one well-filtered call over several:
+news about a company or sector -> search_statements; what is big right now -> trending; which names are getting
+unusual attention -> screen; how coverage or tone changed over time -> sentiment_series; which broad subjects a
+company or sector is in the news for -> themes.
+Cite `source` and `published_at` when you quote a statement; `source_type` says whether it comes from news,
+speculative analysis or reddit. Symbols are codes extracted by a language model: most equities match their
+ticker, but macro entities are codes too (FED, ECB, CRUDE, US10Y). Sentiment describes the statement, not a
+price forecast. Every result carries `lag_days`, the age of the newest statement in days: if it is well above
+zero, news collection is behind, so say the data may be stale. Call `reference` when you need theme ids or want
+to know about gaps in the data."""
+
+server = MCPServer("finance-pulse", title="Finance Pulse", instructions=INSTRUCTIONS, version=__version__,
+                   website_url="https://fintopic.news/docs")
+
+READ_ONLY = ToolAnnotations(read_only_hint=True, destructive_hint=False, idempotent_hint=True, open_world_hint=True)
+
+_client: Optional[FinancePulse] = None
+
+
+def client() -> FinancePulse:
+    global _client
+    if _client is None:
+        if not (os.environ.get(BACKEND.key_env) or "").strip():
+            raise ToolError(f"{BACKEND.key_env} is not set for the finance-pulse server. Add it to the server's "
+                            f"env in the MCP client's configuration; get a free key at {BACKEND.signup_url}")
+        try:
+            _client = FinancePulse(backend=BACKEND)
+        except ValueError as exc:       # a key that cannot be one
+            raise ToolError(str(exc)) from exc
+    return _client
+
+
+def _call(method: str, *args, **kwargs) -> dict:
+    """One API request; errors become messages the assistant can act on (ToolError text reaches the model,
+    any other exception is reported only as "Error executing tool")."""
+    api = client()
+    try:
+        return getattr(api, method)(*args, **kwargs)
+    except FinancePulseError as exc:
+        if exc.status == 429:
+            raise ToolError(f"The plan's request quota or rate limit is used up ({exc.title}). "
+                            f"Plans: {BACKEND.signup_url}") from exc
+        if exc.status in (401, 403):
+            raise ToolError(f"{BACKEND.key_env} is missing, wrong or not subscribed to Finance Pulse ({exc.title}). "
+                            f"Subscribe (there is a free plan): {BACKEND.signup_url}") from exc
+        if exc.transient:
+            raise ToolError(f"Finance Pulse could not be reached or is temporarily unavailable ({exc}). "
+                            f"Try again in a minute.") from exc
+        raise ToolError(str(exc)) from exc
+
+
+def _statement(s: dict) -> dict:
+    out = {"id": s["id"], "statement": s["statement"], "published_at": s["published_at"],
+           "sentiment": s["sentiment"], "importance": s["importance"], "source_type": s.get("source_type"),
+           "symbols": s.get("symbols") or [], "sectors": s.get("sectors") or [],
+           "source": s.get("source_domain") or "", "url": s.get("source_url"),
+           "topic_id": s.get("topic_id"), "topic": s.get("topic_name")}
+    if s.get("entities"):                       # what each symbol code stands for
+        out["entities"] = [{k: e.get(k) for k in ("code", "name", "kind")} for e in s["entities"]]
+    return out
+
+
+def _topic(t: dict) -> dict:
+    latest = t.get("latest_statement") or {}
+    out = {"id": t["id"], "name": t["name"], "theme_id": t.get("theme_id"), "updated_at": t.get("updated_at"),
+           "statements": t.get("statements"), "sources": t.get("sources"),
+           "statements_7d": t.get("statements_7d"), "statements_24h": t.get("statements_24h"),
+           "statements_4h": t.get("statements_4h"),
+           "sentiment": t.get("sentiment"), "symbols": (t.get("symbols") or [])[:8],
+           "latest_statement": latest.get("statement"), "latest_source": latest.get("source_domain")}
+    if "trending" in t:
+        out["trending"] = t["trending"]
+    return out
+
+
+def _fresh(response: dict) -> dict:
+    snapshot = response.get("snapshot") or {}
+    return {"built_at": snapshot.get("built_at"), "window_start": snapshot.get("window_start"),
+            "lag_days": snapshot.get("lag_days")}
+
+
+@server.tool(title="Search news statements", annotations=READ_ONLY)
+def search_statements(
+        symbol: Symbols = None, sector: SectorArg = None, theme_id: ThemeId = None, topic_id: TopicId = None,
+        sentiment: Annotated[Optional[Sentiment], Field(description="Only statements with this sentiment")] = None,
+        importance_min: Annotated[Optional[Importance], Field(description="Minimum importance; high = key facts only")] = None,
+        source_type: Annotated[Optional[SourceType], Field(description="news leaves out speculative analysis and reddit")] = None,
+        since: Time = None, until: Time = None, limit: PageSize = 15, cursor: Cursor = None) -> dict:
+    """Search extracted news statements, newest first. Use for "what is the news saying about X".
+
+    symbol: ticker or entity code, e.g. NVDA; comma-separate several (OR), no spaces inside a code.
+    importance_min=high keeps only key facts. source_type=news leaves out speculative analysis and reddit.
+    since/until: ISO-8601 times on the article's publication time, e.g. 2026-10-01T00:00:00Z.
+    limit: 1-100. Pass next_cursor back as cursor for the next page (null means no more).
+    """
+    r = _call("statements", symbol=symbol, sector=sector, theme_id=theme_id, topic_id=topic_id, sentiment=sentiment,
+              importance_min=importance_min, source_type=source_type, since=since, until=until, limit=limit,
+              cursor=cursor)
+    return {"statements": [_statement(s) for s in r["data"]], "next_cursor": r.get("next_cursor"), **_fresh(r)}
+
+
+@server.tool(title="Trending developments", annotations=READ_ONLY)
+def trending(
+        kind: Annotated[Literal["live", "slot"], Field(description="live = last 2 hours; slot = 2-hour slots over 7 days")] = "live",
+        symbol: OneSymbol = None, theme_id: ThemeId = None,
+        limit: Annotated[int, Field(ge=1, le=300, description="How many to return, taken from the top of the API's ranking; `total` in the result says how many there are")] = 15) -> dict:
+    """The developments most outlets are reporting. Use for "what is moving / what is the big news right now".
+
+    kind=live: the last 2 hours; kind=slot: the top stories of each 2-hour slot over the last 7 days.
+    For the whole day rather than the last 2 hours, use find_topics with sort=velocity (last 24 hours).
+    kind=slot lists up to 10 stories per slot over 7 days, so raise limit when you need more than the top of it;
+    each item's `trending` labels say which slots it was in and at what rank.
+    Each item has its distinct source count, sentiment counts and newest statement. symbol: one code only.
+    """
+    r = _call("trending", kind=kind, symbol=symbol, theme_id=theme_id)
+    return {"topics": [_topic(t) for t in r["data"][:limit]], "total": len(r["data"]), **_fresh(r)}
+
+
+@server.tool(title="Get one development", annotations=READ_ONLY)
+def get_topic(topic_id: Annotated[str, Field(description="Topic (development) id, as returned in topic_id or topics[].id")]) -> dict:
+    """One development in full: its counts, how many of its statements come from news, speculative analysis and
+    reddit (source_mix), and its 20 newest statements, each with its outlet. For older statements call
+    search_statements with topic_id and the returned statements_cursor as cursor."""
+    r = _call("topic", topic_id)
+    t = r["data"]
+    return {**_topic(t), "created_at": t.get("created_at"), "source_mix": t.get("source_mix"),
+            "statements_page": [_statement(s) for s in t.get("statements_page") or []],
+            "statements_cursor": t.get("statements_cursor"), **_fresh(r)}
+
+
+@server.tool(title="Find developments", annotations=READ_ONLY)
+def find_topics(
+        symbol: Symbols = None, sector: SectorArg = None, theme_id: ThemeId = None,
+        sort: Literal["recent", "size", "velocity", "oldest"] = "velocity",
+        min_statements: Annotated[int, Field(ge=1, description="Leave out developments with fewer statements")] = 3,
+        limit: PageSize = 15, cursor: Cursor = None) -> dict:
+    """List developments for a symbol, sector or theme. sort=velocity: most statements in the last 24 hours;
+    size: most statements in the window; recent: latest statement first. symbol: comma-separate several (OR)."""
+    r = _call("topics", symbol=symbol, sector=sector, theme_id=theme_id, sort=sort, min_statements=min_statements,
+              limit=limit, cursor=cursor)
+    return {"topics": [_topic(t) for t in r["data"]], "next_cursor": r.get("next_cursor"), **_fresh(r)}
+
+
+@server.tool(title="Themes", annotations=READ_ONLY)
+def themes(symbol: Symbols = None, sector: SectorArg = None,
+           sort: Annotated[Literal["size", "topics", "recent", "velocity"], Field(description="size = statements; topics = developments; recent = last statement; velocity = statements in the last 24 hours")] = "size") -> dict:
+    """The standing subjects the news is grouped into (Energy, Central banks & rates, ...), each with its number
+    of developments and statements, 24-hour volume, distinct sources and sentiment counts. With symbol or sector:
+    only the themes that have statements about it; the counts are still those of the whole theme, so use
+    search_statements with theme_id and symbol for the symbol's own statements. Use the returned id as theme_id
+    in the other tools."""
+    r = _call("themes", symbol=symbol, sector=sector, sort=sort)
+    keep = ("id", "name", "topics", "statements", "statements_24h", "statements_4h", "sources", "sentiment",
+            "sentiment_score", "updated_at")
+    return {"themes": [{k: t.get(k) for k in keep} for t in r["data"]], **_fresh(r)}
+
+
+@server.tool(title="News volume and sentiment over time", annotations=READ_ONLY)
+def sentiment_series(symbol: OneSymbol = None, sector: SectorArg = None, theme_id: ThemeId = None,
+                     topic_id: TopicId = None, interval: Literal["day", "hour"] = "day",
+                     since: Time = None, until: Time = None) -> dict:
+    """News volume and sentiment over time for exactly one of symbol, sector, theme_id or topic_id.
+
+    Each bucket: t (UTC start), count, bullish, bearish, neutral, sources (distinct outlets) and
+    score = (bullish - bearish) / count. Buckets with no statements are omitted here. Unless `until` is set, the
+    series ends at the current, still incomplete day or hour: do not read a low last bucket as a drop. interval=hour covers at most 14 days and
+    defaults to the last 7; interval=day defaults to the whole window.
+    """
+    if sum(bool(v) for v in (symbol, sector, theme_id, topic_id)) != 1:
+        raise ToolError("Pass exactly one of symbol, sector, theme_id, topic_id")
+    r = _call("series", symbol=symbol, sector=sector, theme_id=theme_id, topic_id=topic_id, interval=interval,
+              since=since, until=until)
+    buckets = [{k: b.get(k) for k in ("t", "count", "bullish", "bearish", "neutral", "sources", "score")}
+               for b in r["data"]["buckets"] if b.get("count")]
+    return {"entity": r["data"]["entity"], "interval": interval, "buckets": buckets,
+            "empty_buckets_omitted": len(r["data"]["buckets"]) - len(buckets), **_fresh(r)}
+
+
+@server.tool(title="Screen symbols or sectors by news attention", annotations=READ_ONLY)
+def screen(
+        rank: Literal["symbols", "sectors"] = "symbols",
+        period: Annotated[Literal["d", "w", "window"], Field(description="d = 24 hours, w = 7 days, window = everything held")] = "d",
+        sort: Literal["change", "mentions", "sources", "score"] = "change", sector: SectorArg = None,
+        entity_kinds: Annotated[Optional[str], Field(description='Comma-separated entity kinds, e.g. "equity,etf"')] = None,
+        min_mentions: Annotated[int, Field(ge=1, description="Leave out codes with fewer mentions")] = 3,
+        limit: Annotated[int, Field(ge=1, le=500, description="How many rows to return")] = 20) -> dict:
+    """Rank symbols (or the 11 GICS sectors) by news attention. Use for "which tickers are suddenly in the news".
+
+    period: d = last 24 hours, w = last 7 days, window = everything held. sort=change ranks by the rise in
+    mentions against the previous period (not available for period=window; use sort=mentions there).
+    Each row: mentions, topics, sources (distinct outlets), sentiment counts, score and change.
+    Only for rank=symbols: sector limits the screen to one sector; min_mentions drops rarely mentioned codes;
+    entity_kinds narrows the kind of entity, comma-separated, from: equity, etf, index, rate, fx, crypto,
+    commodity, org, private, country. Without it the list mixes companies with rates, commodities and central
+    banks; pass "equity,etf" for tradable tickers.
+    """
+    if rank == "sectors":
+        if sector or entity_kinds:
+            raise ToolError("sector and entity_kinds only apply to rank=symbols")
+        r = _call("sectors", period=period, sort=sort)
+    else:
+        r = _call("symbols", period=period, sort=sort, sector=sector, kind=entity_kinds, min_mentions=min_mentions,
+                  limit=limit)
+    return {"rank": rank, "period": period, "rows": r["data"][:limit], **_fresh(r)}
+
+
+@server.tool(title="Data window, themes and accepted values", annotations=READ_ONLY)
+def reference() -> dict:
+    """The data's window and size, known data incidents (outages, delays), the themes with their ids, and the
+    accepted sector, sentiment, importance, source-type and entity-kind values. Call once; it rarely changes."""
+    r = _call("meta")
+    return {**r["data"], **_fresh(r)}
+
+
+def main() -> None:
+    if sys.stdin.isatty():
+        print("finance-pulse is an MCP server: it talks to an MCP client (Claude, Cursor, ...) over stdin/stdout.\n"
+              "Setup: https://github.com/SlothyAfk/finance-pulse-python#readme", file=sys.stderr)
+        sys.exit(2)                     # no MCP client starts a server with a terminal as its stdin
+    logging.getLogger("httpx").setLevel(logging.WARNING)    # one INFO line per request otherwise fills client logs
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

finance_pulse-0.1.0.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.5
+Name: finance-pulse
+Version: 0.1.0
+Summary: Python client and MCP server for the Finance Pulse API: financial news as structured, sourced statements with sentiment, clustered into developments.
+Project-URL: Homepage, https://fintopic.news/docs
+Project-URL: Documentation, https://fintopic.news/docs/reference
+Project-URL: Get an API key, https://rapidapi.com/evankos/api/finance-pulse/pricing
+Project-URL: Repository, https://github.com/SlothyAfk/finance-pulse-python
+Project-URL: Issues, https://github.com/SlothyAfk/finance-pulse-python/issues
+Author: FinTopic
+License-Expression: MIT
+License-File: LICENSE
+Keywords: finance,llm,mcp,news,rag,rapidapi,sentiment,stocks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2
+Requires-Dist: pydantic>=2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Finance Pulse: Python client and MCP server
+
+<!-- mcp-name: io.github.SlothyAfk/finance-pulse -->
+
+Financial news as structured, sourced data. [Finance Pulse](https://fintopic.news/docs) reads financial news as it
+is published and turns every article into **statements**: one-sentence facts with sentiment, importance, tickers,
+sector, source and publication time. Statements about the same development are clustered into **topics**, and
+topics into 19 **themes**. [fintopic.news](https://fintopic.news/) is a front page built on the same API.
+
+This package gives you two ways to use it:
+
+- a **Python client** for scripts, notebooks and pipelines;
+- an **MCP server**, so Claude, Cursor and other MCP clients can query the news directly.
+
+**You need a RapidAPI key that is subscribed to Finance Pulse.** Create a RapidAPI account, open the
+[plans page](https://rapidapi.com/evankos/api/finance-pulse/pricing) and subscribe to a plan: Basic is free and is
+enough to try everything below. Then copy your `X-RapidAPI-Key` from the API's page on RapidAPI (the endpoint playground shows it). A key that
+is not subscribed to a plan is answered with 403.
+
+## Use it from Claude or Cursor (MCP)
+
+The server runs with `uvx`, which is part of [uv](https://docs.astral.sh/uv/getting-started/installation/):
+install uv first. The package itself needs no separate install.
+
+**Claude Code**
+
+```bash
+claude mcp add --env RAPIDAPI_KEY=YOUR_RAPIDAPI_KEY --transport stdio finance-pulse -- uvx finance-pulse
+```
+
+**Claude Desktop** and **Cursor**
+
+- Claude Desktop: Settings > Developer > Edit Config opens `claude_desktop_config.json`
+  (macOS `~/Library/Application Support/Claude/`, Windows `%APPDATA%\Claude\`). Quit and restart Claude Desktop
+  completely afterwards.
+- Cursor: `~/.cursor/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "finance-pulse": {
+      "command": "uvx",
+      "args": ["finance-pulse"],
+      "env": { "RAPIDAPI_KEY": "YOUR_RAPIDAPI_KEY" }
+    }
+  }
+}
+```
+
+If the server does not start in Claude Desktop, it usually cannot find `uvx`: put the full path (the output of
+`which uvx`, or `where uvx` on Windows) in `"command"`.
+
+`uvx` keeps the version it installed first. To move to a new release, use `finance-pulse@latest` in place of
+`finance-pulse` once, or run `uv cache clean finance-pulse`.
+
+Then ask things like:
+
+- "What is the news saying about Nvidia today? Only the key facts, with sources."
+- "Which tickers are suddenly getting more coverage than yesterday?"
+- "What are the top developing stories in Energy, and how did the biggest one grow?"
+- "Show me Tesla's daily news sentiment for the last two weeks."
+
+### Tools
+
+| Tool | What it does |
+|---|---|
+| `search_statements` | Statements by symbol, sector, theme, topic, sentiment, minimum importance and time range |
+| `trending` | The developments most outlets are reporting now, or per 2-hour slot over 7 days |
+| `find_topics` | Developments for a symbol, sector or theme, by velocity, size or recency |
+| `get_topic` | One development: counts, its mix of news, analysis and reddit statements, newest statements with their outlets |
+| `sentiment_series` | Daily or hourly news volume and sentiment for a symbol, sector, theme or topic |
+| `screen` | Symbols (optionally only equities and ETFs) or sectors ranked by news attention and its change against the previous period |
+| `themes` | The standing subjects with their volume and sentiment, optionally only those a symbol or sector appears in |
+| `reference` | The data window, known data incidents, theme ids and accepted filter values |
+
+Each tool call is one API request. Results are trimmed and default to small pages, so the free plan goes a long way.
+
+## Use it from Python
+
+```bash
+pip install finance-pulse
+export RAPIDAPI_KEY=YOUR_RAPIDAPI_KEY
+```
+
+The MCP SDK is installed with the package even if you only use the client.
+
+```python
+from datetime import datetime, timedelta, timezone
+
+from finance_pulse import FinancePulse
+
+fp = FinancePulse()          # or FinancePulse("YOUR_RAPIDAPI_KEY")
+
+# The newest key facts about a ticker
+for s in fp.statements(symbol="NVDA", importance_min="high", limit=5)["data"]:
+    print(s["published_at"][:16], s["sentiment"], s["statement"], f"({s['source_domain']})")
+
+# Which tickers are suddenly in the news (kind= leaves out rates, central banks, countries, ...)
+for row in fp.symbols(period="d", sort="change", kind=["equity", "etf"], limit=10)["data"]:
+    print(row["id"], row["mentions"], row["change"])
+
+# Daily news volume and sentiment, last two weeks
+since = (datetime.now(timezone.utc) - timedelta(days=14)).strftime("%Y-%m-%dT00:00:00Z")
+for b in fp.series(symbol="TSLA", interval="day", since=since)["data"]["buckets"]:
+    print(b["t"][:10], b["count"], b["score"])
+
+# What most outlets are reporting right now
+for t in fp.trending(kind="live")["data"][:10]:
+    print(t["sources"], "sources:", t["name"])
+```
+
+Every method returns the API's JSON unchanged: `{"data": ..., "next_cursor": ..., "snapshot": {...}}`. The
+`snapshot` block says how fresh the data is.
+
+### Follow the news without missing anything
+
+`poll_feed` yields every new statement in the order it entered the API and keeps its position in a file, so it
+survives restarts: after a crash nothing is skipped and only the statement you were working on is delivered
+again. The first run, with no saved position, starts 24 hours back, and the position is first stored once that
+first page has been handled. After a long pause the poller reads the whole backlog since its saved position, one
+request per 100 statements; delete the cursor file to start 24 hours back instead.
+
+```python
+for s in fp.poll_feed(sector="Energy", importance_min="high", cursor_file="energy.cursor.json"):
+    print(s["indexed_at"], s["statement"], s["source_url"])
+```
+
+The API builds new data about every 2.5 minutes, so the poller waits 150 seconds between polls by default. One
+poller at that rate makes about 576 requests a day. Timeouts and server errors are retried; a used-up quota (429)
+is raised.
+
+### More than one page
+
+```python
+rows = list(fp.iter_statements(symbol=["NVDA", "AMD"], importance_min="medium", max_items=1000))
+```
+
+Each page of 100 is one request. Without `max_items` it stops after 500 rows; `max_items=None` reads to the end
+of the window.
+
+### Errors
+
+```python
+from finance_pulse import FinancePulseError
+
+try:
+    fp.statements(symbol="S&P")
+except FinancePulseError as e:
+    print(e.status, e.title, e.detail, e.param)
+    # 400 | Invalid symbol | 'S&P' is not a ticker | symbol
+```
+
+A `429` means the plan's request quota or rate limit is used up. Timeouts and network failures are raised as
+`FinancePulseError` too, with `status` 0; `e.transient` is true for those and for 5xx answers.
+
+### Methods
+
+| Method | Endpoint |
+|---|---|
+| `statements`, `iter_statements`, `statement` | `/v2/statements`, `/v2/statements/{id}` |
+| `feed`, `poll_feed` | `/v2/feed` |
+| `series` | `/v2/series` |
+| `symbols`, `sectors` | `/v2/symbols`, `/v2/sectors` |
+| `trending` | `/v2/trending` |
+| `topics`, `topic` | `/v2/topics`, `/v2/topics/{id}` |
+| `themes`, `theme` | `/v2/themes`, `/v2/themes/{id}` |
+| `meta` | `/v2/meta` |
+
+The package targets Finance Pulse API 2.0 (the `/v2` endpoints). Parameters and response fields are documented in
+the [API reference](https://fintopic.news/docs/reference), and the
+[guides](https://fintopic.news/docs) show complete worked examples.
+
+## What the data is, and is not
+
+- **Symbols are codes extracted by a language model**, not exchange tickers. Most equities match their ticker;
+  macro entities are codes too (`FED`, `ECB`, `CRUDE`, `US10Y`). Map the codes you trade before relying on them.
+- **Sentiment describes the statement**, not a price forecast. A symbol's sentiment is the count of its
+  statements' labels.
+- **The window is a rolling 62 days.** `meta()` lists known outages and delays under `incidents`.
+
+See [the docs](https://fintopic.news/docs) for the full list of caveats.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The tests use canned responses and make no API requests.
+
+### Releasing
+
+1. Set the new version in `src/finance_pulse/__init__.py` and in `server.json` (two places).
+2. Build and upload to PyPI (`uv build && uv publish`). From GitHub Actions, use `pypa/gh-action-pypi-publish`
+   v1.14.2 or newer: older versions reject the metadata version this build writes.
+3. Only then run `mcp-publisher publish`: the registry verifies the package on PyPI (it looks for the
+   `mcp-name` line in its description), so the release must be there first.
+
+## Licence
+
+MIT

finance_pulse-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+finance_pulse/__init__.py,sha256=bHyDS9PDbvMNYsMA4IvfPYJvSKXO1iWouUGAShjC4QI,265
+finance_pulse/client.py,sha256=i-8nQeSI67PZK23uXXFpYbFWmSi9dRV6TBQb--6YCKI,18510
+finance_pulse/mcp_server.py,sha256=q524TpGDU3cjlEqeZnP9i0Q4Ku_cbVil5aAz8F0IIYI,17010
+finance_pulse/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+finance_pulse-0.1.0.dist-info/METADATA,sha256=GnuvkZnbsk1J4oSmqZJluylaCTwb553JopFHlqxCN8U,10030
+finance_pulse-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+finance_pulse-0.1.0.dist-info/entry_points.txt,sha256=SHJwhQXrKvhBFdUif1h7p9eIxmAY-I3yQmXQqamhOn8,114
+finance_pulse-0.1.0.dist-info/licenses/LICENSE,sha256=OwopmkKt7yS4Gl0Z7OF0Git4oqP0YPNEFm0BaSdSai0,1065
+finance_pulse-0.1.0.dist-info/RECORD,,

finance_pulse-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

finance_pulse-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+finance-pulse = finance_pulse.mcp_server:main
+finance-pulse-mcp = finance_pulse.mcp_server:main

finance_pulse-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FinTopic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.