Summary
Several public functions in pulseengine/core/ return plain dict without specifying key/value types. While from __future__ import annotations is present, PEP 8 and mypy best-practices recommend using TypedDict or at minimum dict[str, ...] for complex return signatures, to make the API self-documenting and enable static analysis.
Affected functions
| Module |
Function |
Current return type |
price.py |
compute_price_metrics |
dict |
price.py |
compute_momentum_metrics |
dict |
signals.py |
compute_signal_score |
dict |
signals.py |
correlate_news |
list[dict] |
signals.py |
detect_events |
list[dict] |
Proposed change
Define TypedDict classes in pulseengine/core/ (e.g. a new pulseengine/core/types.py) and update return annotations:
from typing import TypedDict
class PriceMetrics(TypedDict, total=False):
latest_price: float
change_1d: float | None
change_7d: float | None
change_30d: float | None
high_30d: float
low_30d: float
volatility: float
trend: str
class MomentumMetrics(TypedDict):
rsi: float
roc_10d: float
trend_strength: float
momentum_accel: float
This is a low-risk, zero-runtime-overhead improvement that dramatically improves IDE support and catches caller-side bugs.
Summary
Several public functions in
pulseengine/core/return plaindictwithout specifying key/value types. Whilefrom __future__ import annotationsis present, PEP 8 and mypy best-practices recommend usingTypedDictor at minimumdict[str, ...]for complex return signatures, to make the API self-documenting and enable static analysis.Affected functions
price.pycompute_price_metricsdictprice.pycompute_momentum_metricsdictsignals.pycompute_signal_scoredictsignals.pycorrelate_newslist[dict]signals.pydetect_eventslist[dict]Proposed change
Define
TypedDictclasses inpulseengine/core/(e.g. a newpulseengine/core/types.py) and update return annotations:This is a low-risk, zero-runtime-overhead improvement that dramatically improves IDE support and catches caller-side bugs.