Skip to content

feat: add type annotations to all public functions in pulseengine/core/ that currently use untyped dict return types #53

@Codex-Crusader

Description

@Codex-Crusader

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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions