Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/najmulhossainnj/Hedge-fund-backend/llms.txt

Use this file to discover all available pages before exploring further.

The News Sentiment API exposes the platform’s FinBERT-powered NLP pipeline as three focused endpoints. Under the hood, the system uses the ProsusAI/finbert model from HuggingFace Transformers, loaded lazily and cached in process memory so repeated inference calls within a worker session do not reload weights from disk. Article-level scores are additionally cached in Redis by SHA-256 content hash (7-day TTL) so large daily universe runs avoid redundant inference on articles that appeared the previous day. The pipeline produces four scores per article — positive, negative, neutral, and an uncertainty value derived from the Shannon entropy of the softmax distribution — which directly align to the feature columns consumed by the Feature Engine.

​
Score Raw Texts

​
POST
endpoint
/api/v1/news/score
Scores a batch of raw news strings with FinBERT and returns one ArticleScore per input text. This endpoint is stateless — no database, feature store, or market data is involved. Empty or whitespace-only strings are automatically replaced with "neutral" before scoring. The model processes inputs in batches of 16 and truncates each article to 512 tokens (the BERT maximum). For very large batches, expect proportionally longer latency; there is no async streaming on this endpoint.
This endpoint returns 503 Service Unavailable if torch and transformers are not installed in the running worker environment. In deployments where GPU inference is delegated to a separate worker, call that worker’s equivalent endpoint directly.

​
Request Body

​
texts
list[string]
required
List of news strings to score. Minimum 1 item, maximum 500 items. Each string is truncated to 512 BERT tokens internally.

​
Response

​
scores
list[ArticleScore]
One score object per input text, in the same order as the request.
​
n_scored
integer
Count of articles successfully scored. Equals the length of the scores list.
curl -X POST https://api.example.com/api/v1/news/score \
  -H "Content-Type: application/json" \
  -d '{
    "texts": [
      "Apple reports record quarterly earnings, beating analyst expectations by 12%",
      "Federal Reserve signals further interest rate hikes amid persistent inflation",
      "Company announces routine board of directors meeting scheduled for next month"
    ]
  }'

{
  "scores": [
    {
      "positive": 0.9231,
      "negative": 0.0412,
      "neutral": 0.0357,
      "uncertainty": 0.1183
    },
    {
      "positive": 0.0318,
      "negative": 0.8874,
      "neutral": 0.0808,
      "uncertainty": 0.1946
    },
    {
      "positive": 0.0891,
      "negative": 0.0643,
      "neutral": 0.8466,
      "uncertainty": 0.2304
    }
  ],
  "n_scored": 3
}

​
Aggregate Daily Sentiment

​
POST
endpoint
/api/v1/news/aggregate
Orchestrates a full pipeline: fetches news articles and OHLCV price data for a symbol from the Market Data Layer, scores every article with FinBERT (using the per-article Redis cache), then aggregates raw per-article scores into mean daily bars aligned to actual trading days from the price index. Days with no news coverage receive NaN scores and an article_volume of 0. This is the same pipeline invoked internally by the news.finbert_sentiment and news.sentiment_momentum feature plugins during automated research sessions.
Returns 502 Bad Gateway if the Market Data Layer is unreachable or raises an exception during the OHLCV or news fetch. Returns 422 Unprocessable Entity if the Market Data Layer returns an empty OHLCV frame for the requested symbol and date range. Returns 503 Service Unavailable if FinBERT dependencies are missing.

​
Request Body

​
symbol
string
required
Instrument ticker symbol (e.g. "AAPL", "TSLA").
​
start_date
datetime
required
ISO 8601 start datetime for the data window.
​
end_date
datetime
required
ISO 8601 end datetime for the data window.
​
text_col
string
default:"headline"
Column name in the news DataFrame that contains the article text to score. Override if your Market Data connector uses a different column name (e.g. "title" or "body").
​
date_col
string
default:"published_at"
Column name in the news DataFrame that contains the publication timestamp. The pipeline coerces this column to UTC-aware datetimes and normalises to trade date.

​
Response

​
symbol
string
The ticker symbol that was requested.
​
n_days
integer
Number of trading day rows in the data array.
​
data
list[object]
Array of daily sentiment records, one per trading day in the requested range.
curl -X POST https://api.example.com/api/v1/news/aggregate \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "AAPL",
    "start_date": "2023-11-01T00:00:00Z",
    "end_date": "2023-11-15T00:00:00Z",
    "text_col": "headline",
    "date_col": "published_at"
  }'

{
  "symbol": "AAPL",
  "n_days": 11,
  "data": [
    {
      "date": "2023-11-01",
      "positive_score": 0.6124,
      "negative_score": 0.1831,
      "neutral_score": 0.2045,
      "uncertainty_score": 0.3712,
      "article_volume": 8
    },
    {
      "date": "2023-11-02",
      "positive_score": null,
      "negative_score": null,
      "neutral_score": null,
      "uncertainty_score": null,
      "article_volume": 0
    },
    {
      "date": "2023-11-03",
      "positive_score": 0.4389,
      "negative_score": 0.3201,
      "neutral_score": 0.2410,
      "uncertainty_score": 0.5823,
      "article_volume": 14
    }
  ]
}

​
List News Feature Plugins

​
GET
endpoint
/api/v1/news/features
Returns all feature plugin keys registered under the news.* namespace in the platform’s feature registry. These are the same keys the FeatureDiscoveryAgent resolves when it detects "sentiment" or "news" in a research query.
The plugin keys returned here are identical to those available in feature generation requests via the Feature Engine. Pass them in the plugin_key field of a Feature creation request, or reference them directly in a research query (e.g. "use news.finbert_sentiment for TSLA").

​
Response

​
plugins
list[string]
List of fully-qualified news feature plugin key strings (e.g. "news.finbert_sentiment", "news.sentiment_momentum").
curl https://api.example.com/api/v1/news/features

{
  "plugins": [
    "news.finbert_sentiment",
    "news.sentiment_momentum"
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us