sentimove 1.0.0__tar.gz

sentimove-1.0.0/.gitignore

@@ -0,0 +1,163 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# VS Code
+.vscode/
+
+# macOS
+.DS_Store
+
+# Windows
+Thumbs.db
+ehthumbs.db
+
+# Fundis specific - local data (DO NOT COMMIT)
+.fundis/
+~/.fundis/
+
+# Test files
+test_*.py
+!tests/test_*.py
+
+# Temporary files
+*.tmp
+*.bak
+*.swp
+*~

sentimove-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yototec Ltd
+
+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.

sentimove-1.0.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: sentimove
+Version: 1.0.0
+Summary: Python client for SentiMove intelligence data - events, signals, and patterns from SentiChain.
+Project-URL: Homepage, https://sentimove.com
+Project-URL: Repository, https://github.com/Yototec/sentimove-sdk
+Project-URL: Bug Tracker, https://github.com/Yototec/sentimove-sdk/issues
+Author-email: Edward Chen <rchen@yototec.com>
+License: MIT
+License-File: LICENSE
+Keywords: crypto,events,intelligence,patterns,sentichain,sentiment,sentimove,signals
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: requests<3.0.0,>=2.32.0
+Description-Content-Type: text/markdown
+
+# SentiMove
+
+Python client for SentiMove intelligence data: events, signals, and patterns from [SentiChain](https://sentichain.com).
+
+SentiMove Intelligence is the engine behind [SentiMove](https://sentimove.com). This package provides programmatic access to the same structured output that powers both the SentiMove live map view and its terminal mode.
+
+This package was previously published as [`fundis`](https://pypi.org/project/fundis/). `FundisClient` and `FundisError` remain available as aliases, so switching is a one-line import change.
+
+## Installation
+
+```bash
+pip install sentimove
+```
+
+## Quick Start
+
+```python
+from sentimove import SentiMoveClient
+
+client = SentiMoveClient()
+
+# Get classified events for an asset
+events = client.get_events("BTC")
+for event in events:
+    print(f"[{event.type}] {event.sentiment}: {event.summary}")
+
+# Get a directional signal with rationale
+signal = client.get_signal("BTC")
+if signal:
+    print(f"Direction: {signal.direction}, Confidence: {signal.confidence}")
+    print(f"Rationale: {signal.rationale}")
+    for cat, summary in signal.categories.items():
+        if summary:
+            print(f"  {cat}: {summary}")
+
+# List active tickers (fetched from the live API)
+tickers = client.list_tickers()
+print(tickers)
+
+# Request a new ticker (requires API key)
+client_with_key = SentiMoveClient(api_key="your-sentichain-api-key")
+client_with_key.request_ticker("ADA")
+```
+
+Migrating from `fundis`: replace `from fundis import FundisClient` with `from sentimove import FundisClient` (or use `SentiMoveClient`). Methods, arguments and return types are unchanged.
+
+## API Reference
+
+### `SentiMoveClient(api_key="", base_url="https://api.sentimove.com", timeout=30.0)`
+
+Create a client instance. Intelligence data is publicly available. An API key is only needed for ticker requests and billing-related operations on SentiChain.
+
+### `client.get_events(ticker) -> list[Event]`
+
+Fetch the latest classified events for a ticker. Each event contains:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `timestamp` | `str` | ISO 8601 timestamp |
+| `type` | `str` | Event category: `macro`, `industry`, `price`, or `asset` |
+| `sentiment` | `str` | `bullish`, `bearish`, or `neutral` |
+| `summary` | `str` | One-sentence event description |
+
+### `client.get_signal(ticker) -> Signal | None`
+
+Fetch the latest directional signal for a ticker. Returns None if no signal data exists. Otherwise returns:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `direction` | `str` | `LONG`, `SHORT`, or `FLAT` |
+| `confidence` | `float` | 0.0 to 1.0 |
+| `rationale` | `str` | 1-2 sentence explanation of the call |
+| `categories` | `dict` | One-sentence summaries for `macro`, `industry`, `price`, `asset` |
+| `patterns` | `list[Pattern]` | Detected event patterns with keywords and descriptions |
+
+The SDK preserves the backend signal enum values (`LONG`, `SHORT`, `FLAT`). The SentiMove frontend maps those values to the softer UI wording `Bullish`, `Bearish`, and `Neutral`.
+
+### `client.list_tickers() -> list[str]`
+
+Return the list of active ticker symbols from the live API.
+
+### `client.request_ticker(ticker) -> bool`
+
+Request a new ticker to be added to the pipeline. Requires an API key. Returns True if the request was submitted (pending admin approval), False if the ticker already exists.
+
+This endpoint is still available at the SDK/API layer even though the current SentiMove web UI does not expose a public request-ticker form.
+
+## Requirements
+
+- Python 3.10+
+
+## Release
+
+`sentimove` is distributed as a client package rather than a long-running service.
+
+| Item | Value |
+|------|-------|
+| Distribution | PyPI package (`sentimove`) |
+| Source Repo | `https://github.com/Yototec/sentimove-sdk` |
+| Primary Runtime Target | `https://api.sentimove.com` (`https://api.fundis.ai` is an alias) |
+| Registration / billing dependency | `https://api.sentichain.com` |
+| Server deploy required | No |
+
+Release verification is package-oriented:
+
+1. Install the package in a clean Python environment
+2. Call `get_events()`, `get_signal()`, and `list_tickers()` against the live API
+3. Publish a new PyPI release only after those calls succeed
+
+The legacy `fundis` package is maintained on the `fundis-1.x` branch.
+
+## SentiMove Integration Notes
+
+SentiMove combines two runtime data surfaces:
+
+- live asset-header USD prices come client-side from Hyperliquid
+- structured market intelligence comes from SentiMove Intelligence via `api.sentimove.com`
+- both the SentiMove 3D map and terminal mode consume the same intelligence surface
+
+This SDK only exposes the intelligence surface. It is not the source of the public live price header shown on `sentimove.com`.
+
+## Links
+
+- [SentiMove](https://sentimove.com) - 3D consumer product
+- [SentiChain](https://sentichain.com) - Blockchain platform and API keys
+- [GitHub](https://github.com/Yototec/sentimove-sdk) - Source code
+- [PyPI](https://pypi.org/project/sentimove/) - Package registry
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

sentimove-1.0.0/README.md

@@ -0,0 +1,131 @@
+# SentiMove
+
+Python client for SentiMove intelligence data: events, signals, and patterns from [SentiChain](https://sentichain.com).
+
+SentiMove Intelligence is the engine behind [SentiMove](https://sentimove.com). This package provides programmatic access to the same structured output that powers both the SentiMove live map view and its terminal mode.
+
+This package was previously published as [`fundis`](https://pypi.org/project/fundis/). `FundisClient` and `FundisError` remain available as aliases, so switching is a one-line import change.
+
+## Installation
+
+```bash
+pip install sentimove
+```
+
+## Quick Start
+
+```python
+from sentimove import SentiMoveClient
+
+client = SentiMoveClient()
+
+# Get classified events for an asset
+events = client.get_events("BTC")
+for event in events:
+    print(f"[{event.type}] {event.sentiment}: {event.summary}")
+
+# Get a directional signal with rationale
+signal = client.get_signal("BTC")
+if signal:
+    print(f"Direction: {signal.direction}, Confidence: {signal.confidence}")
+    print(f"Rationale: {signal.rationale}")
+    for cat, summary in signal.categories.items():
+        if summary:
+            print(f"  {cat}: {summary}")
+
+# List active tickers (fetched from the live API)
+tickers = client.list_tickers()
+print(tickers)
+
+# Request a new ticker (requires API key)
+client_with_key = SentiMoveClient(api_key="your-sentichain-api-key")
+client_with_key.request_ticker("ADA")
+```
+
+Migrating from `fundis`: replace `from fundis import FundisClient` with `from sentimove import FundisClient` (or use `SentiMoveClient`). Methods, arguments and return types are unchanged.
+
+## API Reference
+
+### `SentiMoveClient(api_key="", base_url="https://api.sentimove.com", timeout=30.0)`
+
+Create a client instance. Intelligence data is publicly available. An API key is only needed for ticker requests and billing-related operations on SentiChain.
+
+### `client.get_events(ticker) -> list[Event]`
+
+Fetch the latest classified events for a ticker. Each event contains:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `timestamp` | `str` | ISO 8601 timestamp |
+| `type` | `str` | Event category: `macro`, `industry`, `price`, or `asset` |
+| `sentiment` | `str` | `bullish`, `bearish`, or `neutral` |
+| `summary` | `str` | One-sentence event description |
+
+### `client.get_signal(ticker) -> Signal | None`
+
+Fetch the latest directional signal for a ticker. Returns None if no signal data exists. Otherwise returns:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `direction` | `str` | `LONG`, `SHORT`, or `FLAT` |
+| `confidence` | `float` | 0.0 to 1.0 |
+| `rationale` | `str` | 1-2 sentence explanation of the call |
+| `categories` | `dict` | One-sentence summaries for `macro`, `industry`, `price`, `asset` |
+| `patterns` | `list[Pattern]` | Detected event patterns with keywords and descriptions |
+
+The SDK preserves the backend signal enum values (`LONG`, `SHORT`, `FLAT`). The SentiMove frontend maps those values to the softer UI wording `Bullish`, `Bearish`, and `Neutral`.
+
+### `client.list_tickers() -> list[str]`
+
+Return the list of active ticker symbols from the live API.
+
+### `client.request_ticker(ticker) -> bool`
+
+Request a new ticker to be added to the pipeline. Requires an API key. Returns True if the request was submitted (pending admin approval), False if the ticker already exists.
+
+This endpoint is still available at the SDK/API layer even though the current SentiMove web UI does not expose a public request-ticker form.
+
+## Requirements
+
+- Python 3.10+
+
+## Release
+
+`sentimove` is distributed as a client package rather than a long-running service.
+
+| Item | Value |
+|------|-------|
+| Distribution | PyPI package (`sentimove`) |
+| Source Repo | `https://github.com/Yototec/sentimove-sdk` |
+| Primary Runtime Target | `https://api.sentimove.com` (`https://api.fundis.ai` is an alias) |
+| Registration / billing dependency | `https://api.sentichain.com` |
+| Server deploy required | No |
+
+Release verification is package-oriented:
+
+1. Install the package in a clean Python environment
+2. Call `get_events()`, `get_signal()`, and `list_tickers()` against the live API
+3. Publish a new PyPI release only after those calls succeed
+
+The legacy `fundis` package is maintained on the `fundis-1.x` branch.
+
+## SentiMove Integration Notes
+
+SentiMove combines two runtime data surfaces:
+
+- live asset-header USD prices come client-side from Hyperliquid
+- structured market intelligence comes from SentiMove Intelligence via `api.sentimove.com`
+- both the SentiMove 3D map and terminal mode consume the same intelligence surface
+
+This SDK only exposes the intelligence surface. It is not the source of the public live price header shown on `sentimove.com`.
+
+## Links
+
+- [SentiMove](https://sentimove.com) - 3D consumer product
+- [SentiChain](https://sentichain.com) - Blockchain platform and API keys
+- [GitHub](https://github.com/Yototec/sentimove-sdk) - Source code
+- [PyPI](https://pypi.org/project/sentimove/) - Package registry
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

sentimove-1.0.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sentimove"
+version = "1.0.0"
+description = "Python client for SentiMove intelligence data - events, signals, and patterns from SentiChain."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  { name = "Edward Chen", email = "rchen@yototec.com" },
+]
+license = { text = "MIT" }
+dependencies = [
+  "requests>=2.32.0,<3.0.0",
+]
+keywords = [
+  "sentimove",
+  "sentichain",
+  "intelligence",
+  "sentiment",
+  "crypto",
+  "events",
+  "signals",
+  "patterns",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://sentimove.com"
+Repository = "https://github.com/Yototec/sentimove-sdk"
+"Bug Tracker" = "https://github.com/Yototec/sentimove-sdk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sentimove"]

sentimove-1.0.0/sentimove/__init__.py

@@ -0,0 +1,23 @@
+"""SentiMove - Python client for SentiChain intelligence data."""
+
+from sentimove.client import SentiMoveClient
+from sentimove.exceptions import APIError, AuthenticationError, FundisError, SentiMoveError
+from sentimove.types import Event, Pattern, Signal
+
+__version__ = "1.0.0"
+
+# Name used by the former fundis package; behaves exactly like SentiMoveClient.
+FundisClient = SentiMoveClient
+
+__all__ = [
+    "SentiMoveClient",
+    "FundisClient",
+    "Event",
+    "Signal",
+    "Pattern",
+    "SentiMoveError",
+    "FundisError",
+    "AuthenticationError",
+    "APIError",
+    "__version__",
+]

sentimove-1.0.0/sentimove/client.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+import requests
+
+from sentimove.exceptions import APIError, SentiMoveError
+from sentimove.types import Event, Pattern, Signal
+
+
+class SentiMoveClient:
+    """Thin client for querying SentiMove intelligence data via the API.
+
+    Parameters
+    ----------
+    api_key:
+        A valid SentiChain API key (used for ticker requests and billing).
+    base_url:
+        Root URL for the SentiMove intelligence API.
+    timeout:
+        HTTP request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: str = "",
+        base_url: str = "https://api.sentimove.com",
+        timeout: float = 30.0,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._session = requests.Session()
+
+    def get_events(self, ticker: str) -> list[Event]:
+        """Fetch the latest classified events for *ticker*.
+
+        Returns a list of :class:`Event` objects parsed from the most recent
+        pipeline chunk.
+        """
+        ticker = ticker.upper().strip()
+        if not ticker:
+            raise SentiMoveError("ticker must be a non-empty string.")
+
+        raw = self._fetch_reasoning(ticker=ticker, summary_type="sm_events")
+
+        if raw is None:
+            return []
+
+        items = self._parse_json(raw)
+        if not isinstance(items, list):
+            return []
+
+        events: list[Event] = []
+        for item in items:
+            events.append(
+                Event(
+                    timestamp=str(item.get("timestamp", "")),
+                    type=str(item.get("event", "asset")).lower(),
+                    sentiment=str(item.get("sentiment", "neutral")).lower(),
+                    summary=str(item.get("summary", "")),
+                )
+            )
+        return events
+
+    def get_signal(self, ticker: str) -> Optional[Signal]:
+        """Fetch the latest directional signal for *ticker*.
+
+        Returns a :class:`Signal` object with direction, confidence,
+        rationale, category summaries, and detected patterns.
+        Returns None if no signal data exists for this ticker.
+        """
+        ticker = ticker.upper().strip()
+        if not ticker:
+            raise SentiMoveError("ticker must be a non-empty string.")
+
+        raw = self._fetch_reasoning(ticker=ticker, summary_type="sm_signal")
+
+        if raw is None:
+            return None
+
+        data = self._parse_json(raw)
+        if not isinstance(data, dict):
+            raise APIError("Signal data is not a JSON object.")
+
+        patterns: list[Pattern] = []
+        for p in data.get("patterns", []):
+            if isinstance(p, dict):
+                patterns.append(
+                    Pattern(
+                        keywords=p.get("keywords", []),
+                        event_indices=p.get("event_indices", []),
+                        description=p.get("description", ""),
+                    )
+                )
+
+        return Signal(
+            direction=str(data.get("direction", "FLAT")),
+            confidence=float(data.get("confidence", 0.0)),
+            rationale=str(data.get("rationale", "")),
+            categories=data.get("categories", {}),
+            patterns=patterns,
+        )
+
+    def list_tickers(self) -> list[str]:
+        """Return the list of active ticker symbols from the API."""
+        url = f"{self._base_url}/agent/tickers"
+        try:
+            resp = self._session.get(url, timeout=self._timeout)
+        except requests.RequestException as exc:
+            raise APIError(f"Request failed: {exc}") from exc
+
+        if resp.status_code != 200:
+            raise APIError(
+                f"Unexpected response from API (HTTP {resp.status_code}).",
+                status_code=resp.status_code,
+            )
+
+        data: dict[str, Any] = resp.json()
+        tickers = data.get("tickers", [])
+        if not isinstance(tickers, list):
+            raise APIError("Tickers response is not a list.")
+        return tickers
+
+    def request_ticker(self, ticker: str) -> bool:
+        """Request a new ticker to be added to the pipeline.
+
+        Requires an API key set on the client. Returns True if the request
+        was submitted, False if the ticker already exists.
+        """
+        ticker = ticker.upper().strip()
+        if not ticker:
+            raise SentiMoveError("ticker must be a non-empty string.")
+        if not self._api_key:
+            raise SentiMoveError("api_key is required to request a ticker.")
+
+        url = f"{self._base_url}/agent/tickers/request"
+        try:
+            resp = self._session.post(
+                url,
+                json={"ticker": ticker, "api_key": self._api_key},
+                timeout=self._timeout,
+            )
+        except requests.RequestException as exc:
+            raise APIError(f"Request failed: {exc}") from exc
+
+        if resp.status_code != 200:
+            raise APIError(
+                f"Unexpected response from API (HTTP {resp.status_code}).",
+                status_code=resp.status_code,
+            )
+
+        data: dict[str, Any] = resp.json()
+        return data.get("status") == "pending"
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _fetch_reasoning(self, ticker: str, summary_type: str) -> str | None:
+        url = f"{self._base_url}/agent/get_reasoning_last"
+        params = {"ticker": ticker, "summary_type": summary_type}
+
+        try:
+            resp = self._session.get(url, params=params, timeout=self._timeout)
+        except requests.RequestException as exc:
+            raise APIError(f"Request failed: {exc}") from exc
+
+        if resp.status_code != 200:
+            raise APIError(
+                f"Unexpected response from API (HTTP {resp.status_code}).",
+                status_code=resp.status_code,
+            )
+
+        data: dict[str, Any] = resp.json()
+        reasoning = data.get("reasoning")
+
+        if reasoning is None:
+            return None
+
+        return str(reasoning)
+
+    @staticmethod
+    def _parse_json(raw: str) -> Any:
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise APIError(f"Failed to parse reasoning JSON: {exc}") from exc

sentimove-1.0.0/sentimove/exceptions.py

@@ -0,0 +1,18 @@
+class SentiMoveError(Exception):
+    """Base exception for all SentiMove client errors."""
+
+
+class AuthenticationError(SentiMoveError):
+    """Raised when the API key is missing, invalid, or has insufficient points."""
+
+
+class APIError(SentiMoveError):
+    """Raised when the SentiChain API returns an unexpected response."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        self.status_code = status_code
+        super().__init__(message)
+
+
+# Name used by the former fundis package.
+FundisError = SentiMoveError

sentimove-1.0.0/sentimove/types.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Event:
+    """A single classified sentiment event from the SentiMove pipeline."""
+
+    timestamp: str
+    type: str
+    sentiment: str
+    summary: str
+
+
+@dataclass(frozen=True)
+class Pattern:
+    """A group of converging events sharing common keywords."""
+
+    keywords: list[str]
+    event_indices: list[int]
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class Signal:
+    """Directional signal from the SentiMove intelligence pipeline."""
+
+    direction: str
+    confidence: float
+    rationale: str
+    categories: dict[str, str | None] = field(default_factory=dict)
+    patterns: list[Pattern] = field(default_factory=list)