Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(tools): add sentiment analysis tool (#939)

卫斯李6ad0e8d25961
diff --git a/agent/src/tools/sentiment_tool.py b/agent/src/tools/sentiment_tool.py
new file mode 100644
index 000000000..c439bc208
--- /dev/null
+++ b/agent/src/tools/sentiment_tool.py
@@ -0,0 +1,146 @@
+"""Read-only market sentiment analysis tool.
+
+Two capabilities:
+1. ``sentiment_score`` — score arbitrary text [-1, 1] with a lexicon-based scorer
+2. ``fear_greed_index`` — fetch the current crypto Fear & Greed Index
+
+All computation is pure Python; the Fear & Greed call is a single HTTP GET
+to the free, no-auth alternative.me API.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.request
+from typing import Any
+
+from src.agent.tools import BaseTool
+
+logger = logging.getLogger(__name__)
+
+# ── Lexicon (subset, extensible) ─────────────────────────────────────────────
+_POSITIVE: frozenset[str] = frozenset({
+ "beat", "beats", "bullish", "buy", "cheap", "crush", "crushed",
+ "crushing", "gain", "gained", "gaining", "gains", "green",
+ "growth", "high", "higher", "hit", "improve", "improved",
+ "jump", "jumped", "lead", "leading", "leads", "long", "low",
+ "opportunity", "outperform", "outperformed", "profit", "profitable",
+ "profits", "raise", "raised", "raises", "rally", "rallied",
+ "rebound", "record", "rise", "rises", "rising", "rose",
+ "strong", "stronger", "surge", "surged", "surges", "top",
+ "undervalued", "up", "upgrade", "upgraded", "upside", "win",
+})
+
+_NEGATIVE: frozenset[str] = frozenset({
+ "bearish", "bleed", "bottom", "bust", "crash", "crashed",
+ "cut", "cuts", "cutting", "decline", "declined", "declining",
+ "deficit", "downgrade", "downgraded", "downside", "drop", "dropped",
+ "dropping", "fall", "falling", "fell", "fined", "firing",
+ "frozen", "headwind", "headwinds", "investigation",
+ "lawsuit", "layoff", "layoffs", "litigation", "lose", "loses",
+ "losing", "loss", "losses", "low", "lower", "lowered",
+ "miss", "missed", "missing", "negative", "overvalued", "penalty",
+ "plunge", "plunged", "poor", "probe", "recall", "red",
+ "risk", "risks", "sanction", "scandal", "sell", "selling",
+ "short", "shrink", "sliding", "slump", "slumped", "turmoil",
+ "underperform", "volatile", "volatility", "warn", "warned", "warns", "warning",
+ "weak", "weaker", "worry", "worries", "worse", "worst",
+})
+
+
+def _tokenize(text: str) -> list[str]:
+ """Lowercase, split, and strip common punctuation from each token."""
+ stripped = [tok.strip(".,;:!?\"'()[]{}") for tok in text.split()]
+ return [tok.lower() for tok in stripped if tok and tok.isalpha()]
+
+
+def _score_text(text: str) -> dict[str, Any]:
+ """Score one text snippet in [-1, 1].
+
+ Returns a dict with ``score`` (float), ``positive`` (int), and ``negative`` (int).
+ """
+ tokens = _tokenize(text)
+ if not tokens:
+ return {"score": 0.0, "positive": 0, "negative": 0}
+ pos = sum(1 for t in tokens if t in _POSITIVE)
+ neg = sum(1 for t in tokens if t in _NEGATIVE)
+ hits = pos + neg
+ if hits == 0:
+ return {"score": 0.0, "positive": 0, "negative": 0}
+ return {"score": round((pos - neg) / hits, 4), "positive": pos, "negative": neg}
+
+
+def _fetch_fear_greed() -> dict[str, Any] | None:
+ """Fetch the latest crypto Fear & Greed Index from alternative.me."""
+ url = "https://api.alternative.me/fng/?limit=1"
+ try:
+ req = urllib.request.Request(url, headers={"User-Agent": "Vibe-Trading/1.0"})
+ with urllib.request.urlopen(req, timeout=10) as resp:
+ body = json.loads(resp.read().decode())
+ except Exception as exc:
+ logger.debug("Fear & Greed fetch failed: %s", exc)
+ return None
+ data = body.get("data", [])
+ if not data:
+ return None
+ item = data[0]
+ return {
+ "value": int(item.get("value", 0)),
+ "classification": item.get("value_classification", "unknown"),
+ }
+
+
+class SentimentTool(BaseTool):
+ """Analyze market sentiment from text and external indices.
+
+ Two modes:
+ - ``sentiment_score``: score any free-text (news headline, tweet, etc.) on [-1, 1]
+ - ``fear_greed_index``: fetch the crypto Fear & Greed Index (0-100, lower = more fear)
+ """
+
+ name = "sentiment"
+ description = (
+ "Analyze market sentiment. Two modes: (1) 'sentiment_score' scores "
+ "arbitrary text on -1 (bearish) to 1 (bullish); (2) 'fear_greed_index' "
+ "returns the crypto Fear & Greed Index (0-100, lower = more fear). "
+ 'Example: {"mode": "sentiment_score", "text": "Tesla beats earnings estimates"}'
+ )
+ parameters = {
+ "type": "object",
+ "properties": {
+ "mode": {
+ "type": "string",
+ "enum": ["sentiment_score", "fear_greed_index"],
+ "description": (
+ "'sentiment_score' to score text; "
+ "'fear_greed_index' for the crypto F&G index."
+ ),
+ },
+ "text": {
+ "type": "string",
+ "description": "Text to analyze (required when mode='sentiment_score').",
+ },
+ },
+ "required": ["mode"],
+ }
+ repeatable = True
+ is_readonly = True
+
+ def execute(self, **kwargs: Any) -> str:
+ mode = str(kwargs.get("mode", "")).strip()
+
+ if mode == "fear_greed_index":
+ fg = _fetch_fear_greed()
+ if fg is None:
+ return json.dumps({"ok": False, "error": "Failed to fetch Fear & Greed Index"})
+ return json.dumps({"ok": True, "mode": mode, **fg})
+
+ if mode == "sentiment_score":
+ text = str(kwargs.get("text", "")).strip()
+ if not text:
+ return json.dumps({"ok": False, "error": "text is required for mode 'sentiment_score'"})
+ result = _score_text(text)
+ return json.dumps({"ok": True, "mode": mode, "text": text[:500], **result})
+
+ return json.dumps({"ok": False, "error": f"Unknown mode: {mode!r}"})
diff --git a/agent/tests/test_sentiment_tool.py b/agent/tests/test_sentiment_tool.py
new file mode 100644
index 000000000..542913fc6
--- /dev/null
+++ b/agent/tests/test_sentiment_tool.py
@@ -0,0 +1,183 @@
+"""Tests for the sentiment analysis tool."""
+
+import json
+from unittest.mock import patch
+
+from src.tools.sentiment_tool import (
+ SentimentTool,
+ _score_text,
+ _tokenize,
+)
+
+
+class TestTokenize:
+ def test_empty(self):
+ assert _tokenize("") == []
+
+ def test_punctuation_only(self):
+ assert _tokenize("!!! $$$") == []
+
+ def test_mixed(self):
+ tokens = _tokenize("Tesla beats earnings ESTIMATES!!!")
+ assert "tesla" in tokens
+ assert "beats" in tokens
+ assert "earnings" in tokens
+ assert "estimates" in tokens
+ assert "!!!" not in " ".join(tokens)
+
+
+class TestScoreText:
+ def test_strongly_bullish(self):
+ r = _score_text("profit surge growth rally record beat upgrade strong")
+ assert r["score"] == 1.0
+ assert r["positive"] == 8
+ assert r["negative"] == 0
+
+ def test_strongly_bearish(self):
+ r = _score_text("crash plunge loss decline drop scandal weak downgrade")
+ assert r["score"] == -1.0
+ assert r["positive"] == 0
+ assert r["negative"] == 8
+
+ def test_neutral(self):
+ r = _score_text("Tesla announced quarterly results today")
+ assert r["score"] == 0.0
+ assert r["positive"] == 0
+ assert r["negative"] == 0
+
+ def test_flat_is_neutral(self):
+ """'flat' was removed from negative terms — financial neutral."""
+ r = _score_text("markets flat today")
+ assert r["score"] == 0.0
+
+ def test_mixed(self):
+ r = _score_text("profit beat expectations but future outlook worry decline")
+ # profit, beat = 2 pos; worry, decline = 2 neg; (2-2)/4 = 0
+ assert r["score"] == 0.0
+
+ def test_slightly_bullish(self):
+ r = _score_text("earnings beat profit growth outlook worry")
+ # 4 positive (beat, profit, growth) vs 1 negative (worry) → (3-1)/4 = 0.5
+ # Actually: beat, profit, growth = 3 pos; worry = 1 neg; score = (3-1)/4 = 0.5
+ assert r["score"] == 0.5
+
+ def test_real_headlines(self):
+ """Verify scoring makes sense on realistic financial headlines."""
+ assert _score_text("Tesla crushes earnings estimates, stock surges")["score"] > 0.5
+ assert _score_text("Company warns of revenue miss, shares plunge")["score"] < -0.5
+ assert _score_text("Fed holds rates steady as expected")["score"] == 0.0
+
+ def test_empty_text(self):
+ r = _score_text("")
+ assert r["score"] == 0.0
+ assert r["positive"] == 0
+
+ def test_no_alpha_tokens(self):
+ r = _score_text("123 456 !!! ???")
+ assert r["score"] == 0.0
+
+
+class TestSentimentTool:
+ def test_missing_mode(self):
+ tool = SentimentTool()
+ result = json.loads(tool.execute())
+ assert result["ok"] is False
+ assert "Unknown mode" in result["error"]
+
+ def test_unknown_mode(self):
+ tool = SentimentTool()
+ result = json.loads(tool.execute(mode="invalid"))
+ assert result["ok"] is False
+
+ def test_sentiment_score_missing_text(self):
+ tool = SentimentTool()
+ result = json.loads(tool.execute(mode="sentiment_score"))
+ assert result["ok"] is False
+ assert "text" in result["error"]
+
+ def test_sentiment_score_success(self):
+ tool = SentimentTool()
+ result = json.loads(tool.execute(mode="sentiment_score", text="profit surge growth"))
+ assert result["ok"] is True
+ assert result["score"] == 1.0
+
+ def test_sentiment_text_truncated(self):
+ tool = SentimentTool()
+ long_text = "bullish " * 1000
+ result = json.loads(tool.execute(mode="sentiment_score", text=long_text))
+ assert result["ok"] is True
+ assert len(result["text"]) <= 500
+
+ def test_fear_greed_success(self):
+ tool = SentimentTool()
+ mock_data = json.dumps({
+ "data": [{"value": "28", "value_classification": "Fear"}]
+ }).encode()
+ with patch("urllib.request.urlopen", return_value=type("m", (), {"read": lambda s: mock_data, "__enter__": lambda s: s, "__exit__": lambda s,*a: None})()):
+ result = json.loads(tool.execute(mode="fear_greed_index"))
+ assert result["ok"] is True
+ assert result["value"] == 28
+ assert result["classification"] == "Fear"
+
+ def test_fear_greed_failure(self):
+ tool = SentimentTool()
+ with patch("urllib.request.urlopen", side_effect=OSError("network down")):
+ result = json.loads(tool.execute(mode="fear_greed_index"))
+ assert result["ok"] is False
+ assert "Failed to fetch" in result["error"]
+
+ def test_fear_greed_empty_data(self):
+ tool = SentimentTool()
+ mock_data = json.dumps({"data": []}).encode()
+ with patch("urllib.request.urlopen", return_value=type("m", (), {"read": lambda s: mock_data, "__enter__": lambda s: s, "__exit__": lambda s,*a: None})()):
+ result = json.loads(tool.execute(mode="fear_greed_index"))
+ assert result["ok"] is False
+
+ def test_fear_greed_malformed_json(self):
+ tool = SentimentTool()
+ mock_data = b"not json"
+ with patch("urllib.request.urlopen", return_value=type("m", (), {"read": lambda s: mock_data, "__enter__": lambda s: s, "__exit__": lambda s,*a: None})()):
+ result = json.loads(tool.execute(mode="fear_greed_index"))
+ assert result["ok"] is False
+
+ def test_fear_greed_missing_value(self):
+ tool = SentimentTool()
+ mock_data = json.dumps({"data": [{"value_classification": "Neutral"}]}).encode()
+ with patch("urllib.request.urlopen", return_value=type("m", (), {"read": lambda s: mock_data, "__enter__": lambda s: s, "__exit__": lambda s,*a: None})()):
+ result = json.loads(tool.execute(mode="fear_greed_index"))
+ assert result["ok"] is True
+ assert result["value"] == 0 # default int
+
+ def test_sentiment_unicode(self):
+ """Non-ASCII text should not crash."""
+ tool = SentimentTool()
+ result = json.loads(tool.execute(mode="sentiment_score", text="特斯拉 profit 增长 surge 🚀"))
+ assert result["ok"] is True
+ assert result["score"] == 1.0 # profit + surge
+
+ def test_sentiment_very_long(self):
+ """Very long text should not crash or timeout."""
+ tool = SentimentTool()
+ result = json.loads(tool.execute(mode="sentiment_score", text="profit " * 5000))
+ assert result["ok"] is True
+ # 5000 "profit" tokens → all positive → score = 1.0
+ assert result["score"] == 1.0
+
+ def test_sentiment_no_alpha(self):
+ tool = SentimentTool()
+ result = json.loads(tool.execute(mode="sentiment_score", text="12345 67890 !@#$%"))
+ assert result["ok"] is True
+ assert result["score"] == 0.0
+
+ def test_non_string_text_coerced(self):
+ """Non-string text should be coerced to string, not crash."""
+ tool = SentimentTool()
+ result = json.loads(tool.execute(mode="sentiment_score", text=12345))
+ assert result["ok"] is True
+ assert isinstance(result["text"], str)
+
+ def test_non_string_mode_coerced(self):
+ """Non-string mode should be coerced."""
+ tool = SentimentTool()
+ result = json.loads(tool.execute(mode=999))
+ assert result["ok"] is False