Metadata-Version: 2.4
Name: finbrain-python
Version: 0.3.0
Summary: Official Python client for the FinBrain API
Author-email: Ahmet Salim Bilgin <ahmet@finbrain.tech>
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31
Requires-Dist: typer[all]>=0.12
Requires-Dist: pandas>=2.2
Requires-Dist: plotly>=6.0
Requires-Dist: numpy>=1.22.4
Provides-Extra: async
Requires-Dist: httpx>=0.24; extra == "async"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: responses; extra == "dev"
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 -->

[![PyPI version](https://img.shields.io/pypi/v/finbrain-python.svg)](https://pypi.org/project/finbrain-python/)
[![CI](https://github.com/ahmetsbilgin/finbrain-python/actions/workflows/ci.yml/badge.svg)](https://github.com/ahmetsbilgin/finbrain-python/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE)

**Official Python client** for the [FinBrain API v2](https://docs.finbrain.tech).
Fetch deep-learning price predictions, sentiment scores, insider trades, LinkedIn metrics, options data, news and more — with a single import.

*Python ≥ 3.9  •  requests, pandas, numpy & plotly  •  asyncio optional.*

---

## ✨ Features

- One-line auth (`FinBrainClient(api_key="…")`) with Bearer token
- Complete v2 endpoint coverage (predictions, sentiments, options, insider, news, screener, etc.)
- Transparent retries & custom error hierarchy (`FinBrainError`)
- Response envelope auto-unwrapping (v2 `{success, data, meta}` format)
- Async parity with `finbrain.aio` (`httpx`)
- Auto-version from Git tags (setuptools-scm)
- MIT-licensed, fully unit-tested

---

## 🚀 Quick start

Install the SDK:

```bash
pip install finbrain-python
```

Create a client and fetch data:

```python
from finbrain import FinBrainClient

fb = FinBrainClient(api_key="YOUR_KEY")        # create once, reuse below

# ---------- discovery ----------
fb.available.markets()                         # list markets with regions
fb.available.tickers("daily", as_dataframe=True)
fb.available.regions()                         # markets grouped by region

# ---------- app ratings ----------
fb.app_ratings.ticker("AMZN",
                      date_from="2025-01-01",
                      date_to="2025-06-30",
                      as_dataframe=True)

# One row per app per date instead of one blended row per date
# — see "App ratings: the per-app view" below.
fb.app_ratings.ticker("AMZN",
                      date_from="2025-01-01",
                      date_to="2025-06-30",
                      as_dataframe=True,
                      per_app=True)

# ---------- analyst ratings ----------
fb.analyst_ratings.ticker("AMZN",
                          date_from="2025-01-01",
                          date_to="2025-06-30",
                          as_dataframe=True)

# ---------- house trades ----------
# Rows include `disclosureDate`, `owner`, `amountRaw` and `amountFlag`
# alongside the transaction `date` — see "Congressional trade fields" below.
fb.house_trades.ticker("AMZN",
                       date_from="2025-01-01",
                       date_to="2025-06-30",
                       as_dataframe=True)

# ---------- senate trades ----------
fb.senate_trades.ticker("META",
                        date_from="2025-01-01",
                        date_to="2025-06-30",
                        as_dataframe=True)

# ---------- corporate lobbying ----------
fb.corporate_lobbying.ticker("AAPL",
                             date_from="2024-01-01",
                             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)

# ---------- LinkedIn metrics ----------
fb.linkedin_data.ticker("AMZN",
                        date_from="2025-01-01",
                        date_to="2025-06-30",
                        as_dataframe=True)

# ---------- options put/call ----------
fb.options.put_call("AMZN",
                    date_from="2025-01-01",
                    date_to="2025-06-30",
                    as_dataframe=True)

# ---------- price predictions ----------
fb.predictions.ticker("AMZN", as_dataframe=True)

# ---------- news sentiment ----------
fb.sentiments.ticker("AMZN",
                     date_from="2025-01-01",
                     date_to="2025-06-30",
                     as_dataframe=True)

# ---------- news articles ----------
fb.news.ticker("AMZN", limit=20, as_dataframe=True)

# ---------- screener (cross-ticker) ----------
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)
fb.screener.congress_house(limit=50)     # rows carry `disclosureDate` and `owner`
fb.screener.congress_senate(limit=50)

# ---------- recent data ----------
fb.recent.news(limit=100, as_dataframe=True)
fb.recent.analyst_ratings(limit=50)
```

### Congressional trade fields

House and Senate trade rows carry **two** dates, and the gap between them is
the reporting lag — often weeks:

| Field            | Meaning                                                          |
| ---------------- | ---------------------------------------------------------------- |
| `date`           | Transaction date — when the member actually bought or sold        |
| `disclosureDate` | Public disclosure date — when the periodic transaction report ran |

Rows also identify **whose account** traded and how the filed amount was
normalized:

| Field        | Meaning                                                                                                                                          |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `owner`      | Beneficial owner of the account: `SELF`, `SP` (spouse), `DC` (dependent child), `JT` (joint), or an account code                                 |
| `amountRaw`  | The amount string as originally filed — set only when `amount` was rewritten to the canonical STOCK Act bracket, `null` otherwise                |
| `amountFlag` | `null` on clean rows; `review` or `ambiguous` when the filed amount could not be safely normalized (then `amount` keeps the raw string as filed) |

`amount` is normalized to the ten statutory STOCK Act brackets (e.g.
`"$1,001 - $15,000"`) whenever the filed string is an unambiguous formatting
variant of one; open-ended filing categories like `"Over $1,000,000"` are
kept as filed. A filing with no usable amount at all reports `amount` as
`"Unknown"` with `amountFlag` = `review`. Senate filings that leave the owner
column blank report `owner` as `UNKNOWN`; House filings that leave it blank
report `SELF`, per the House PTR-form instructions.

`disclosureDate` and `owner` are nullable. Historical rows were backfilled
in place by the pipeline's reconcile upload, so nulls are rare — but code
should still handle them. With `as_dataframe=True`, `date` is the **index**
and the other fields are columns whose missing values read as `None` or
`NaN` depending on your pandas version — test them with `pandas.isna()`
rather than `is None`. Note that `.dropna()` on such a frame will discard
every row with any missing field — use `.dropna(subset=[...])`.
All four fields — `owner`, `amountRaw`, `amountFlag` and `disclosureDate` —
are also present on `fb.screener.congress_house()` and
`fb.screener.congress_senate()` rows.

### Company identifier (`cik`)

Rows from the four SEC/government datasets — `fb.insider_transactions`,
`fb.government_contracts`, `fb.corporate_lobbying`, and `fb.patent_filings`
(ticker endpoints and their async equivalents) — carry `cik`, the SEC
**Central Index Key** of the company as of that record:

| Field | Meaning                                                                                     |
| ----- | ------------------------------------------------------------------------------------------- |
| `cik` | SEC Central Index Key of the company, as a 10-digit zero-padded string (`"0000320193"`) |

`cik` is a **string, not a number** — the leading zeros are part of the
identifier, so keep the column as text when loading into other tools. Rows
without an entity resolution (for example, records of companies absent from
the SEC's public company file) carry `null`; with `as_dataframe=True` the
column stays object-typed and missing values read as `None`. Use it to join
FinBrain rows to SEC-keyed datasets (EDGAR filings, financial statements,
13F holdings) or to your own security master.

`date_from` / `date_to` bound the **transaction** date, not the disclosure
date — a trade executed inside the window is returned even if it was disclosed
after `date_to`.

```python
trades = fb.house_trades.ticker("AMZN")["trades"]
lag_days = [
    (pd.Timestamp(t["disclosureDate"]) - pd.Timestamp(t["date"])).days
    for t in trades
    if t["disclosureDate"]
]

# Only the member's own trades, skipping flagged amounts
own = [
    t for t in trades
    if t["owner"] == "SELF" and t["amountFlag"] is None
]
```

### App ratings: the per-app view (`per_app=True`)

A company can publish many apps — Apple has 140 on iOS. The default frame
reports **one row per date**, carrying the company's biggest app on each
store, so a portfolio collapses to two numbers. `per_app=True` returns the
granular alternative: one row per app per observation, with no blending and no
derived company score, so you decide which apps matter and how to weight them.

```python
apps = fb.app_ratings.ticker(
    "AMZN",
    date_from="2025-01-01",
    date_to="2025-06-30",
    as_dataframe=True,
    per_app=True,
)

apps.columns
# ['date', 'platform', 'app_id', 'app_name',
#  'score', 'ratings_count', 'install_count']

# Which apps exist, and how big each is
apps.groupby(["platform", "app_id", "app_name"])["ratings_count"].max()

# One app's own series
apps[apps["app_id"] == "com.amazon.mShop.android.shopping"]
```

| Column          | Meaning                                                          |
| --------------- | ---------------------------------------------------------------- |
| `platform`      | `ios` or `android`                                                |
| `app_id`        | App Store numeric id or Play package name; `null` — see below     |
| `app_name`      | App title as published on the store                               |
| `score`         | Average rating, 0–5                                               |
| `ratings_count` | Number of ratings                                                 |
| `install_count` | Play Store only — Apple publishes no install count, so `null` on `ios` |

Three things to know:

- **Not indexed by date.** A single date carries one row per app, so a date
  index would not be unique. The blended frame (`per_app=False`, the default)
  is still indexed by `date` and is unchanged.
- **`app_id` is `null` on older observations**, collected before the API keyed
  rows per app. Those rows carry the platform but not the app identity — we
  know the store, not which app produced the number. Filter them with
  `apps["app_id"].notna()` if you need identified apps only.
- **Purely additive.** `per_app=False` behaviour is untouched, and an API that
  predates the per-app view returns an empty frame rather than an error.

## ⚡ Async Usage

For async/await support, install with the `async` extra:

```bash
pip install finbrain-python[async]
```

Then use `AsyncFinBrainClient` with `httpx`:

```python
import asyncio
from finbrain.aio import AsyncFinBrainClient

async def main():
    async with AsyncFinBrainClient(api_key="YOUR_KEY") as fb:
        # All methods are async and return the same data structures
        markets = await fb.available.markets()

        # Fetch predictions
        predictions = await fb.predictions.ticker("AMZN", as_dataframe=True)

        # Fetch sentiment data
        sentiment = await fb.sentiments.ticker(
            "AMZN",
            date_from="2025-01-01",
            date_to="2025-06-30",
            as_dataframe=True
        )

        # All other endpoints work the same way
        app_ratings = await fb.app_ratings.ticker("AMZN", as_dataframe=True)
        analyst_ratings = await fb.analyst_ratings.ticker("AMZN", as_dataframe=True)
        news = await fb.news.ticker("AMZN", limit=10)
        screener = await fb.screener.sentiment(market="S&P 500")

asyncio.run(main())
```

**Note**: The async client uses `httpx.AsyncClient` and must be used with `async with` context manager for proper resource cleanup.

## 📈 Plotting

Plot helpers in a nutshell

- `show` – defaults to True, so the chart appears immediately.

- `as_json=True` – skips display and returns the figure as a Plotly-JSON string, ready to embed elsewhere.

```python
# ---------- App Ratings Chart - Apple App Store or Google Play Store ----------
fb.plot.app_ratings("AMZN",
                    store="app",                # "play" for Google Play Store
                    date_from="2025-01-01",
                    date_to="2025-06-30")

# Chart one specific app rather than the company's biggest on that store.
# Ids come from the per_app frame; the app must live on the store you pass.
fb.plot.app_ratings("AMZN",
                    store="play",
                    app_id="com.amazon.mShop.android.shopping",
                    date_from="2025-01-01",
                    date_to="2025-06-30")

# ---------- LinkedIn Metrics Chart ----------
fb.plot.linkedin("AMZN",
                 date_from="2025-01-01",
                 date_to="2025-06-30")

# ---------- Put-Call Ratio Chart ----------
fb.plot.options("AMZN",
                kind="put_call",
                date_from="2025-01-01",
                date_to="2025-06-30")

# ---------- Predictions Chart ----------
fb.plot.predictions("AMZN")         # prediction_type="monthly" for monthly predictions

# ---------- Sentiments Chart ----------
fb.plot.sentiments("AMZN",
                   date_from="2025-01-01",
                   date_to="2025-06-30")

# ---------- Insider Transactions, House & Senate Trades, Corporate Lobbying (requires user price data) ----------
# These plots overlay transaction markers on a price chart.
# Since FinBrain doesn't provide historical prices, you must provide your own:

import pandas as pd

# Example: Load your price data from any legal source
# (broker API, licensed data provider, CSV file, etc.)
price_df = pd.DataFrame({
    "close": [150.25, 151.30, 149.80],  # Your price data
    "date": pd.date_range("2025-01-01", periods=3)
}).set_index("date")

# Plot insider transactions on your price chart
fb.plot.insider_transactions("AAPL", price_data=price_df)

# Plot House member trades on your price chart
fb.plot.house_trades("NVDA",
                     price_data=price_df,
                     date_from="2025-01-01",
                     date_to="2025-06-30")

# Plot Senate member trades on your price chart
fb.plot.senate_trades("META",
                      price_data=price_df,
                      date_from="2025-01-01",
                      date_to="2025-06-30")

# Plot corporate lobbying spend on your price chart
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:**

- DataFrame with DatetimeIndex
- Must contain a price column: `close`, `Close`, `price`, `Price`, `adj_close`, or `Adj Close`
- Obtain from legal sources: broker API, Bloomberg, Alpha Vantage, FMP, etc.

## 🔑 Authentication

To call the API you need an **API key**, obtained by purchasing a **FinBrain API subscription**.
*(The Terminal-only subscription does **not** include an API key.)*

1. Subscribe at <https://www.finbrain.tech> → FinBrain API.
2. Copy the key from your dashboard.
3. Pass it once when you create the client:

```python
from finbrain import FinBrainClient
fb = FinBrainClient(api_key="YOUR_KEY")
```

Or set the `FINBRAIN_API_KEY` environment variable and omit the argument:

```python
fb = FinBrainClient()  # reads from FINBRAIN_API_KEY env var
```

---

## 📚 Supported endpoints

| Category             | Method                                   | v2 Path                                     |
|----------------------|------------------------------------------|---------------------------------------------|
| Discovery            | `client.available.markets()`             | `/markets`                                  |
|                      | `client.available.tickers()`             | `/tickers`                                  |
|                      | `client.available.regions()`             | `/regions`                                  |
| Predictions          | `client.predictions.ticker()`            | `/predictions/{daily\|monthly}/{SYMBOL}`    |
| Sentiments           | `client.sentiments.ticker()`             | `/sentiment/{SYMBOL}`                       |
| News                 | `client.news.ticker()`                   | `/news/{SYMBOL}`                            |
| App ratings          | `client.app_ratings.ticker()`            | `/app-ratings/{SYMBOL}`                     |
| Analyst ratings      | `client.analyst_ratings.ticker()`        | `/analyst-ratings/{SYMBOL}`                 |
| 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`                   |

---

## 🛠️ Error-handling

```python
from finbrain.exceptions import BadRequest
try:
    fb.predictions.ticker("MSFT", prediction_type="weekly")
except BadRequest as exc:
    print("Invalid parameters:", exc)
    print("Error code:", exc.error_code)        # e.g. "VALIDATION_ERROR"
    print("Details:", exc.error_details)         # structured details dict
```

| HTTP status | Exception class          | Meaning                               |
|-------------|--------------------------|---------------------------------------|
| 400         | `BadRequest`             | The request is invalid or malformed   |
| 401         | `AuthenticationError`    | API key missing or incorrect          |
| 403         | `PermissionDenied`       | Authenticated, but not authorised     |
| 404         | `NotFound`               | Resource or endpoint not found        |
| 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             |

---

## 🔄 Versioning & release

- Semantic Versioning (`MAJOR.MINOR.PATCH`)

- Version auto-generated from Git tags (setuptools-scm)

```bash
git tag -a v0.2.0 -m "v2 API migration"
git push --tags # GitHub Actions builds & uploads to PyPI
```

---

## 🧑‍💻 Development

```bash
git clone https://github.com/finbrain-tech/finbrain-python
cd finbrain-python
python -m venv .venv && source .venv/bin/activate
pip install -e .[dev]

ruff check . # lint / format
pytest -q # unit tests (mocked)
```

---

## 🤝 Contributing

1. Fork → create a feature branch

2. Add tests & run `ruff check --fix`

3. Ensure `pytest` & CI pass

4. Open a PR — thanks!

---

## 🔒 Security

Please report vulnerabilities to **<info@finbrain.tech>**.
We respond within 48 hours.

---

## 📜 License

MIT — see [LICENSE](LICENSE).

---

© 2026 FinBrain Technologies — Built with ❤️ for the quant community.
