Sentiment Analysis Model
Relevant source files
The following files were used as context for generating this wiki page:The Sentiment Analysis module is a core component of the OnChain Sage Data Processing Layer. Its primary purpose is to analyze real-time social media text, such as tweets, to gauge market sentiment for various crypto assets. This sentiment score is a critical input for the Signal Aggregator to generate actionable trading signals.
The system is designed with a modular, data-first approach, allowing for multiple sentiment analysis backends. These include rule-based methods like VADER and keyword matching, as well as machine learning models using TensorFlow. The choice of backend and its parameters are configurable, providing flexibility for different analysis needs.
Sources: ARCHITECTURE.md, apps/data-processing/processors/sentiment.py, apps/data-processing/config/pipeline.yaml
Architecture and Components
The sentiment analysis functionality is built around an abstract base class, SentimentAnalyzer, which defines a standard analyze method. This allows for a pluggable architecture where different analysis strategies can be implemented and used interchangeably.
Sources: apps/data-processing/processors/sentiment.py:8-18
The following diagram illustrates the class hierarchy of the available sentiment analyzers.
This class diagram shows the abstract SentimentAnalyzer and its concrete implementations, along with the CompositeSentimentAnalyzer that uses one of them.
Sources: apps/data-processing/processors/sentiment.py, apps/data-processing/processors/sentiment_analysis.py
Analyzer Implementations
VaderSentimentAnalyzer
This analyzer uses the VADER (Valence Aware Dictionary and sEntiment Reasoner) library. It calculates polarity scores (neg, neu, pos, compound) for a given text. The final output score is the compound score normalized to a range of [0, 1]. A label of 'positive', 'negative', or 'neutral' is assigned based on this normalized score.
Sources: apps/data-processing/processors/sentiment.py:20-50, apps/data-processing/sentiment.py
TensorFlowSentimentAnalyzer
This implementation leverages a pre-trained model from the Hugging Face library, specifically "distilbert-base-uncased-finetuned-sst-2-english". It uses the transformers pipeline for sentiment-analysis. The output score is adjusted so that a higher score always indicates more positive sentiment.
Sources: apps/data-processing/processors/sentiment.py:52-79
KeywordSentimentAnalyzer
A rule-based analyzer that uses predefined dictionaries of positive and negative keywords, each with an assigned weight. It calculates a sentiment score based on the weighted count of positive and negative keywords found in the text. If no keywords are found, it returns a neutral score of 0.5.
| Type | Keywords (with weights) |
|---|---|
| Positive | bullish (1.0), moon (0.8), buy (0.6), long (0.6), up (0.4) |
| Negative | bearish (1.0), dump (0.8), sell (0.6), short (0.6), down (0.4) |
The table above shows a sample of keywords and their weights.
Sources: apps/data-processing/processors/sentiment.py:81-127
CryptoSentimentAnalyzer
This is another, more specialized keyword-based analyzer with an extensive, crypto-specific vocabulary. It calculates a score between -1.0 (very negative) and 1.0 (very positive) based on the ratio of positive to negative keywords found. It also identifies the specific keywords that contributed to the score.
Sources: apps/data-processing/processors/sentiment_analysis.py:26-143
Composite Analysis
The CompositeSentimentAnalyzer provides a more holistic sentiment score by combining the textual analysis from a selected backend with social media engagement metrics. It calculates a weighted average of the text sentiment score and normalized scores for likes, retweets, and comments.
The final weighted score is then used to assign a sentiment category (e.g., strong_positive, neutral, strong_negative) based on configurable thresholds.
Sources: apps/data-processing/processors/sentiment.py:129-206, apps/data-processing/config/pipeline.yaml:18-30
The data flow for the composite analyzer is as follows:
This flowchart shows how the CompositeSentimentAnalyzer combines text analysis with engagement metrics to produce a final score.
Sources: apps/data-processing/processors/sentiment.py:148-180
TensorFlow LSTM Model Training
A dedicated script, tf_sentiment.py, outlines a complete pipeline for training a custom Bidirectional LSTM model for sentiment analysis. This process is more advanced than the other analyzers and involves scraping data, preprocessing, labeling, and model training.
The pipeline can be summarized in the following steps:
- Scrape Data: Tweets are scraped using
Nitterfor a given query (e.g., '#crypto'). - Preprocess Text: The tweet text is cleaned by removing URLs, mentions, hashtags, emojis, and stopwords.
- Label Data: The cleaned text is labeled ('POSITIVE' or 'NEGATIVE') using the pre-trained
distilbert-base-uncased-finetuned-sst-2-englishmodel from Hugging Face. - Vectorize Text: The text corpus is converted into numerical vectors using
tf.keras.layers.TextVectorization. - Load Embeddings: Pre-trained GloVe word embeddings (
glove.6B.100d.txt) are loaded to create an embedding matrix for the vocabulary. - Build Model: A
tf.keras.Modelis constructed with anEmbeddinglayer (initialized with GloVe embeddings), aBidirectional(LSTM)layer, and a finalDenseoutput layer with a sigmoid activation for binary classification. - Train Model: The model is trained on the prepared dataset.
- Save Artifacts: The trained model (
sentiment_lstm_model.h5) and the text vectorizer (text_vectorizer.pkl) are saved to disk for later use in prediction.
Sources: apps/data-processing/models/sentiment/tf_sentiment.py
The following diagram visualizes this training pipeline:
This diagram shows the end-to-end process for training the custom TensorFlow LSTM sentiment model.
Sources: apps/data-processing/models/sentiment/tf_sentiment.py
Configuration
The behavior of the sentiment analysis module is controlled via the sentiment section in config/pipeline.yaml. This allows developers to easily switch backends or tune parameters without changing the code.
| Parameter | Type | Description | Default/Example |
|---|---|---|---|
backend | string | The analysis engine to use. Options: vader, tensorflow, keyword. | vader |
weights | object | Weights for the CompositeSentimentAnalyzer. Defines the importance of text vs. engagement metrics. | - |
weights.text | float | Weight for the text sentiment score. | 0.4 |
weights.likes | float | Weight for the normalized likes score. | 0.2 |
weights.retweets | float | Weight for the normalized retweets score. | 0.2 |
weights.comments | float | Weight for the normalized comments score. | 0.2 |
thresholds | object | Score thresholds for categorizing sentiment in the CompositeSentimentAnalyzer. | - |
Sources: apps/data-processing/config/pipeline.yaml:17-30, apps/data-processing/processors/sentiment.py:136-138
API Endpoints
The sentiment_analysis.py script exposes a Flask-based API for on-demand sentiment analysis.
Sources: apps/data-processing/processors/sentiment_analysis.py:321-393
The following sequence diagram illustrates a call to the /api/analyze/tweet endpoint.
This diagram shows the interaction flow for analyzing a single tweet via the API.
Sources: apps/data-processing/processors/sentiment_analysis.py:324-340
Endpoint Details
POST /api/analyze/tweet
Analyzes a single string of text provided in the request body.
- Request Body:
{ "text": "This is the text to be analyzed." } - Response Body:
{ "input_text": "This is the text to be analyzed.", "sentiment_analysis": { "sentiment": "neutral", "score": 0.0, "keywords_found": { ... } } }
Sources: apps/data-processing/processors/sentiment_analysis.py:324-340
POST /api/ingest
Triggers a full pipeline to ingest recent tweets from the X (Twitter) API, analyze them, and save the results. Accepts optional parameters to override the default query.
- Request Body (Optional):
{ "query": "(\"solana\" OR \"SOL\") lang:en -is:retweet", "max_results": 50, "tag": "solana_analysis" } - Response Body:
{ "success": true, "summary": { ... }, "tweets_analyzed": 50, "output_files": ["analyzed_solana_analysis.pkl", "analyzed_solana_analysis.csv"] }
Sources: apps/data-processing/processors/sentiment_analysis.py:342-366
Summary
The OnChain Sage project employs a versatile and multi-faceted approach to sentiment analysis. It provides simple, fast analyzers like VADER and keyword matching for quick assessments, a composite analyzer that factors in social engagement, and a complete pipeline for training a sophisticated, custom deep learning model. This modularity, combined with clear configuration and API access, makes the sentiment analysis system a robust and extensible foundation for the platform's data-driven trading signals.
Sources: ARCHITECTURE.md, apps/data-processing/processors/sentiment.py, apps/data-processing/models/sentiment/tf_sentiment.py