pytrader-sdk 1.0.1__py3-none-any.whl

pytrader/__init__.py

@@ -0,0 +1,104 @@
+"""
+PyPSX SDK - run strategies locally, stream telemetry to the backend, and
+monitor everything from the dashboard.
+
+Bots execute entirely on the founder's machines via the SDK. The backend acts
+as an authenticated data + telemetry hub (no remote strategy execution).
+"""
+
+# Primary client - dual-endpoint REST client (doesn't trigger trader_core)
+from .client import TradingClient, PyPSXClient, PyTrader
+
+# Authentication (doesn't trigger trader_core)
+from .auth import AuthenticationError, require_token, validate_token
+
+# Export indicators (doesn't trigger trader_core)
+from . import indicators
+
+# Deprecated: Trader class for local execution (kept for backward compatibility)
+# Lazy imports to avoid loading trader_core (which imports backtesting engine) 
+# when backend only needs data services like PyPSXService
+def __getattr__(name: str):
+    """Lazy import for Trader and related classes to avoid loading trader_core on package import."""
+    import sys
+    
+    # Get the current module
+    module = sys.modules[__name__]
+    
+    if name == "Trader":
+        from .trader import Trader
+        # Store in module dict so 'from pytrader import Trader' works after first access
+        setattr(module, "Trader", Trader)
+        return Trader
+    if name == "Strategy":
+        from .strategy import Strategy
+        setattr(module, "Strategy", Strategy)
+        return Strategy
+    if name == "load_strategy":
+        from .strategy_loader import load_strategy
+        setattr(module, "load_strategy", load_strategy)
+        return load_strategy
+    if name == "list_strategies":
+        from .strategy_loader import list_strategies
+        setattr(module, "list_strategies", list_strategies)
+        return list_strategies
+    if name == "register_strategy":
+        from .strategy_loader import register_strategy
+        setattr(module, "register_strategy", register_strategy)
+        return register_strategy
+    if name == "start_dashboard":
+        from .dashboard import start_dashboard
+        setattr(module, "start_dashboard", start_dashboard)
+        return start_dashboard
+    if name == "run_backtest":
+        from .sdk import run_backtest
+        setattr(module, "run_backtest", run_backtest)
+        return run_backtest
+    if name == "start_paper_trading":
+        from .sdk import start_paper_trading
+        setattr(module, "start_paper_trading", start_paper_trading)
+        return start_paper_trading
+    if name == "Streamer":
+        from .streamer import Streamer
+        setattr(module, "Streamer", Streamer)
+        return Streamer
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+# BACKEND-ONLY: These components are for backend internal use only.
+# SDK users should NOT import these - they are not part of the public API.
+# They are kept in the package for backend to use, but not exported to SDK users.
+# from .trader_core import (
+#     BacktestEngine,
+#     BacktestConfig,
+#     TradingEngine,
+#     EngineConfig,
+#     TradeMetrics,
+#     PortfolioService,
+# )
+
+__version__ = "2.1.1"
+
+__all__ = [
+    # Primary API - account-aware client
+    "TradingClient",
+    "PyPSXClient",
+    "PyTrader",
+    # Authentication
+    "AuthenticationError",
+    "require_token",
+    "validate_token",
+    # Deprecated - kept for backward compatibility
+    "Trader",
+    "Strategy",
+    "run_backtest",
+    "start_paper_trading",
+    "start_dashboard",
+    "load_strategy",
+    "list_strategies",
+    "register_strategy",
+    "Streamer",
+    # Utilities
+    "indicators",
+    # NOTE: Backend-only components (BacktestEngine, TradingEngine, etc.) are NOT exported
+    # SDK users must use PyTrader client only. Backend components are for internal use.
+]

pytrader/auth.py

@@ -0,0 +1,376 @@
+"""
+Token authentication for PyTrader SDK.
+
+Validates API tokens against the backend service. If the backend is unreachable,
+an allow-listed set of "trusted" tokens can still run locally for development
+and paper trading scenarios.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional, Set, Dict, Any
+
+import httpx
+import warnings
+from datetime import datetime, timezone, timedelta
+
+from .config import settings
+
+DEFAULT_BACKEND_URL = settings.backend_url
+TRUSTED_DEFAULT_TOKENS = {
+    "ahmer-token",
+    "amaan-token",
+    "sadiq-token",
+    "iba-token",
+    "demo-token",
+    "dev-token",
+}
+
+
+class AuthenticationError(Exception):
+    """Raised when token authentication fails."""
+    pass
+
+
+class BackendUnavailableError(AuthenticationError):
+    """Raised when the backend cannot be reached for validation."""
+
+
+@dataclass(frozen=True)
+class AccountContext:
+    account_id: str
+    mode: str
+    bot_id: str
+
+    @property
+    def is_paper(self) -> bool:
+        return self.mode == "PAPER"
+
+
+def resolve_account_context(
+    *,
+    account_id: Optional[str] = None,
+    bot_id: Optional[str] = None,
+    mode: str = "PAPER",
+) -> AccountContext:
+    normalized_mode = mode.upper()
+
+    if account_id:
+        if account_id == "live-brokerage":
+            return AccountContext(account_id="live-brokerage", mode="LIVE", bot_id="")
+        if account_id == "paper-main":
+            return AccountContext(account_id="paper-main", mode="PAPER", bot_id="manual")
+        if account_id.startswith("PYPSX-"):
+            # New immutable paper account ids (e.g., PYPSX-366XBGVOO4).
+            return AccountContext(account_id=account_id, mode="PAPER", bot_id="manual")
+        if account_id.startswith("paper-bot:"):
+            resolved_bot_id = account_id.split("paper-bot:", 1)[1].strip()
+            if not resolved_bot_id:
+                raise ValueError("paper-bot account_id must include a bot identifier.")
+            return AccountContext(account_id=account_id, mode="PAPER", bot_id=resolved_bot_id)
+        raise ValueError(
+            "Unsupported account_id. Expected one of: live-brokerage, PYPSX-<id>, paper-main, paper-bot:<id>."
+        )
+
+    normalized_bot_id = (bot_id or "").strip()
+    if normalized_mode == "LIVE":
+        return AccountContext(account_id="live-brokerage", mode="LIVE", bot_id="")
+    if not normalized_bot_id or normalized_bot_id == "manual":
+        return AccountContext(account_id="paper-main", mode="PAPER", bot_id="manual")
+    return AccountContext(
+        account_id=f"paper-bot:{normalized_bot_id}",
+        mode="PAPER",
+        bot_id=normalized_bot_id,
+    )
+
+
+def _load_trusted_tokens() -> Set[str]:
+    from_env = {
+        token.strip()
+        for token in os.getenv("PYTRADER_TRUSTED_TOKENS", "").split(",")
+        if token.strip()
+    }
+    return TRUSTED_DEFAULT_TOKENS.union(from_env)
+
+
+def validate_token(api_token: str, backend_url: str) -> bool:
+    """
+    Validate an API token against the backend service.
+    
+    Args:
+        api_token: API token to validate
+        backend_url: Backend API URL (MANDATORY)
+    
+    Returns:
+        True if token is valid, False otherwise
+    
+    Raises:
+        AuthenticationError: If validation fails, backend is unreachable, or returns 401/403
+    """
+    if not api_token:
+        raise AuthenticationError("API token is required")
+    
+    if not backend_url:
+        raise BackendUnavailableError(
+            "Backend URL is required. Set PYTRADER_BACKEND_URL environment variable."
+        )
+    
+    try:
+        response = httpx.get(
+            f"{backend_url.rstrip('/')}/health",
+            headers={"X-PyTrader-Token": api_token},
+            timeout=5.0,
+        )
+        
+        # Hard error on 401/403
+        if response.status_code == 401:
+            raise AuthenticationError("Invalid API token (401 Unauthorized). Please check your token and try again.")
+        if response.status_code == 403:
+            raise AuthenticationError("Access forbidden (403). Your token may not have permission for this operation.")
+        
+        # 5xx responses mean the backend itself is unavailable / suspended —
+        # treat them as BackendUnavailableError so callers can apply
+        # trusted-token fallback logic rather than failing hard.
+        if response.status_code >= 500:
+            raise BackendUnavailableError(
+                f"Backend at {backend_url} returned {response.status_code} "
+                f"(service unavailable). "
+                f"Response: {response.text[:200] if response.text else 'No response body'}"
+            )
+
+        # Hard error on any other non-200 status
+        if response.status_code != 200:
+            raise AuthenticationError(
+                f"Backend returned error status {response.status_code}. "
+                f"Response: {response.text[:200] if response.text else 'No response body'}"
+            )
+        
+        # Verify response can be parsed
+        try:
+            data = response.json()
+            if not isinstance(data, dict):
+                raise AuthenticationError("Backend returned invalid response format. Expected JSON object.")
+        except Exception as e:
+            raise AuthenticationError(f"Backend response cannot be verified: {e}")
+        
+        return True
+        
+    except httpx.RequestError as e:
+        raise BackendUnavailableError(
+            f"Backend is unreachable at {backend_url}. "
+            f"Cannot validate token. Error: {e}. "
+            f"Please ensure the backend is running and PYTRADER_BACKEND_URL is correct."
+        ) from e
+    except AuthenticationError:
+        # Re-raise authentication errors
+        raise
+    except Exception as e:
+        # Hard error on any other exception
+        raise AuthenticationError(f"Token validation error: {e}") from e
+
+
+def require_token(api_token: Optional[str] = None, backend_url: Optional[str] = None) -> str:
+    """
+    Require and validate an API token. Backend URL is MANDATORY.
+    
+    NO FALLBACKS. NO WARNINGS. NO OFFLINE EXECUTION.
+    
+    Args:
+        api_token: API token (can be from parameter, PYTRADER_API_TOKEN, or PYTRADER_TOKEN env var)
+        backend_url: Backend API URL (can be from parameter or PYTRADER_BACKEND_URL env var)
+    
+    Returns:
+        Validated token string
+    
+    Raises:
+        AuthenticationError: If token is missing, backend URL is missing, backend is unreachable, 
+                            or token validation fails
+    """
+    # Get token from parameter or env var (support both old and new env var names)
+    resolved_token = api_token or os.getenv("PYTRADER_API_TOKEN") or os.getenv("PYTRADER_TOKEN")
+    
+    if not resolved_token:
+        raise AuthenticationError(
+            "API token is required. "
+            "Please provide a token: "
+            "1. Pass api_token='your-token' to the function, "
+            "2. Set PYTRADER_API_TOKEN environment variable, "
+            "3. Contact your administrator to get a token"
+        )
+    
+    # Get backend URL from parameter, env var, or default deployment
+    resolved_backend_url = backend_url or os.getenv("PYTRADER_BACKEND_URL") or DEFAULT_BACKEND_URL
+    trusted_tokens = _load_trusted_tokens()
+    is_trusted_token = resolved_token in trusted_tokens
+    
+    if not resolved_backend_url:
+        if is_trusted_token:
+            warnings.warn(
+                "Backend URL is not configured; continuing in trusted-token mode.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+            return resolved_token
+        raise AuthenticationError(
+            "Backend URL is required. "
+            "Please set PYTRADER_BACKEND_URL environment variable or pass backend_url parameter. "
+            "The SDK cannot validate untrusted tokens without a backend connection."
+        )
+    
+    try:
+        validate_token(resolved_token, resolved_backend_url)
+    except BackendUnavailableError as exc:
+        if is_trusted_token:
+            warnings.warn(
+                f"{exc} Proceeding because the token is in the trusted allow list.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+        else:
+            raise
+    
+    return resolved_token
+
+
+class BotAuthSession:
+    """
+    Manages bot authentication lifecycle (bot_api_key -> JWT access/refresh tokens).
+
+    The application only ever deals with this class; it never sees the JWTs directly.
+    """
+
+    def __init__(
+        self,
+        *,
+        user_id: str,
+        bot_id: str,
+        bot_api_key: str,
+        backend_url: Optional[str] = None,
+        timeout: float = 10.0,
+    ) -> None:
+        self.user_id = user_id
+        self.bot_id = bot_id
+        self.bot_api_key = bot_api_key
+        self.backend_url = (backend_url or DEFAULT_BACKEND_URL).rstrip("/")
+        self._client = httpx.Client(timeout=timeout)
+        self._access_token: Optional[str] = None
+        self._refresh_token: Optional[str] = None
+        self._api_token: Optional[str] = None
+        self._access_expires_at: Optional[datetime] = None
+        self._refresh_expires_at: Optional[datetime] = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        self._client.close()
+
+    def login(self) -> None:
+        """
+        Perform the initial handshake with POST /auth/bot/login.
+        """
+        if not self.backend_url:
+            raise BackendUnavailableError("Backend URL is required for bot login.")
+
+        payload = {
+            "user_id": self.user_id,
+            "bot_id": self.bot_id,
+            "bot_api_key": self.bot_api_key,
+        }
+        resp = self._client.post(f"{self.backend_url}/auth/bot/login", json=payload)
+        try:
+            resp.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            raise AuthenticationError(
+                f"Bot login failed ({e.response.status_code}): {e.response.text[:200]}"
+            ) from e
+
+        data = resp.json()
+        self._set_tokens_from_response(data)
+
+    def refresh(self) -> None:
+        """
+        Refresh the access token using POST /auth/bot/refresh.
+        """
+        if not self._refresh_token:
+            raise AuthenticationError("No refresh token available for bot session.")
+        if not self.backend_url:
+            raise BackendUnavailableError("Backend URL is required for bot refresh.")
+
+        payload = {"refresh_token": self._refresh_token}
+        resp = self._client.post(f"{self.backend_url}/auth/bot/refresh", json=payload)
+        try:
+            resp.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            raise AuthenticationError(
+                f"Bot token refresh failed ({e.response.status_code}): {e.response.text[:200]}"
+            ) from e
+
+        data = resp.json()
+        self._set_tokens_from_response(data)
+
+    def auth_headers(self) -> Dict[str, str]:
+        """
+        Return Authorization header, performing proactive refresh if needed.
+        """
+        self._ensure_token_fresh()
+        if not self._access_token:
+            raise AuthenticationError("Access token unavailable after login/refresh.")
+        headers = {
+            "Authorization": f"Bearer {self._access_token}",
+            "x-trading-mode": "paper",
+        }
+        if self._api_token:
+            headers["X-PyTrader-Token"] = self._api_token
+        return headers
+
+    def handle_401_and_retry(self, method: str, url: str, **kwargs: Any) -> httpx.Response:
+        """
+        Helper to transparently refresh on 401 and retry once.
+        """
+        base_headers = dict(kwargs.pop("headers", {}) or {})
+        request_headers = dict(base_headers)
+        request_headers.update(self.auth_headers())
+        resp = self._client.request(method, url, headers=request_headers, **kwargs)
+        if resp.status_code != 401:
+            return resp
+
+        # Attempt silent refresh once
+        self.refresh()
+        retry_headers = dict(base_headers)
+        retry_headers.update(self.auth_headers())
+        resp = self._client.request(method, url, headers=retry_headers, **kwargs)
+        return resp
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _set_tokens_from_response(self, data: Dict[str, Any]) -> None:
+        self._access_token = data.get("access_token")
+        self._refresh_token = data.get("refresh_token")
+        self._api_token = data.get("api_token")
+
+        now = datetime.now(timezone.utc)
+        # access_token expiry (seconds)
+        access_expires_in = int(data.get("expires_in", 0))
+        refresh_expires_in = int(data.get("refresh_expires_in", 0))
+
+        # Subtract 5 minutes from access expiry for proactive refresh window
+        self._access_expires_at = now + timedelta(seconds=max(0, access_expires_in - 300))
+        self._refresh_expires_at = now + timedelta(seconds=refresh_expires_in) if refresh_expires_in else None
+
+    def _ensure_token_fresh(self) -> None:
+        now = datetime.now(timezone.utc)
+        if self._access_token and self._access_expires_at and now < self._access_expires_at:
+            return
+        # If access token is missing/expired but refresh is still valid, use it
+        if self._refresh_token and (self._refresh_expires_at is None or now < self._refresh_expires_at):
+            self.refresh()
+            return
+        # Otherwise, do a full login again
+        self.login()
+

pytrader/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Command-line interfaces for the PyTrader SDK."""
+
+__all__ = ["paper_trading"]
+
+

pytrader/cli/paper_trading.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+from ..strategy_loader import BUILTIN_STRATEGIES
+from ..trader import Trader
+
+
+def _parse_symbols(raw: str) -> List[str]:
+    parts: List[str] = []
+    for token in (segment.strip().upper() for segment in raw.replace(",", " ").split()):
+        if token:
+            parts.append(token)
+    if not parts:
+        raise argparse.ArgumentTypeError("At least one symbol must be provided.")
+    return parts
+
+
+def _load_strategy_config(config_arg: Optional[str]) -> Dict[str, Any]:
+    if not config_arg:
+        return {}
+
+    config_arg = config_arg.strip()
+    path = Path(config_arg)
+    try:
+        if path.exists() and path.is_file():
+            return json.loads(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise argparse.ArgumentTypeError(f"Unable to read config file: {exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise argparse.ArgumentTypeError(f"Invalid JSON in config file: {exc}") from exc
+
+    try:
+        return json.loads(config_arg)
+    except json.JSONDecodeError as exc:
+        raise argparse.ArgumentTypeError(f"Invalid JSON config string: {exc}") from exc
+
+
+def _build_strategy(name: str, config: Dict[str, Any]):
+    key = name.lower().strip()
+    strategy_cls = BUILTIN_STRATEGIES.get(key)
+    if not strategy_cls:
+        raise SystemExit(
+            f"Unknown strategy '{name}'. "
+            f"Available templates: {', '.join(sorted(BUILTIN_STRATEGIES.keys()))}"
+        )
+    try:
+        return strategy_cls(**config)
+    except TypeError as exc:
+        raise SystemExit(f"Invalid configuration for '{name}': {exc}") from exc
+
+
+def _resolve_log_path(base: Optional[str], suffix: str, bot_id: str) -> Path:
+    if base:
+        path = Path(base).expanduser()
+    else:
+        log_dir = Path("logs") / "paper_cli"
+        log_dir.mkdir(parents=True, exist_ok=True)
+        timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+        path = log_dir / f"{bot_id}-{timestamp}-{suffix}"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pytrader-paper",
+        description="Local terminal-only paper trading runner for PyPSX strategies.",
+    )
+    parser.add_argument(
+        "--strategy",
+        required=True,
+        help="Strategy template name (e.g., sma_momentum, dual_sma_momentum, vwap_reversion).",
+        choices=sorted(BUILTIN_STRATEGIES.keys()),
+    )
+    parser.add_argument(
+        "--symbols",
+        required=True,
+        help="Comma or space separated list of PSX symbols (e.g., OGDC, HBL, MEBL).",
+    )
+    parser.add_argument(
+        "--config",
+        help="Strategy configuration as JSON string or path to JSON file.",
+    )
+    parser.add_argument(
+        "--token",
+        required=True,
+        help="API token for PyPSX data access (kept locally, never sent to cloud).",
+    )
+    parser.add_argument(
+        "--capital",
+        type=float,
+        default=1_000_000.0,
+        help="Initial virtual cash for the portfolio (default: 1,000,000).",
+    )
+    parser.add_argument(
+        "--position-notional",
+        type=float,
+        default=100_000.0,
+        help="Target notional allocated per trade (default: 100,000).",
+    )
+    parser.add_argument(
+        "--cycle-minutes",
+        type=int,
+        default=15,
+        help="Polling cycle duration in minutes (default: 15).",
+    )
+    parser.add_argument(
+        "--max-cycles",
+        type=int,
+        default=None,
+        help="Optional limit on cycles to run before exiting (default: run indefinitely).",
+    )
+    parser.add_argument(
+        "--bot-id",
+        help="Optional identifier used for log filenames. Defaults to strategy name.",
+    )
+    parser.add_argument(
+        "--metrics-path",
+        help="Optional path for metrics CSV output. Defaults to logs/paper_cli/<bot>_metrics.csv.",
+    )
+    parser.add_argument(
+        "--trades-path",
+        help="Optional path for trades CSV output. Defaults to logs/paper_cli/<bot>_trades.csv.",
+    )
+    parser.add_argument(
+        "--warm-start",
+        action="store_true",
+        help="Replay from market open using previously saved state (explicit opt-in).",
+    )
+    parser.add_argument(
+        "--cold-start",
+        action="store_true",
+        help="(Deprecated) Force cold start. Cold start is now the default.",
+    )
+    parser.add_argument(
+        "--detailed",
+        action="store_true",
+        help="Enable verbose per-cycle logging in the terminal.",
+    )
+    parser.add_argument(
+        "--log-dir",
+        help="Directory for additional log artifacts (default: logs/).",
+    )
+    return parser
+
+
+def main(argv: Optional[Iterable[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    symbols = _parse_symbols(args.symbols)
+    config = _load_strategy_config(args.config)
+    strategy = _build_strategy(args.strategy, config)
+
+    bot_id = args.bot_id or f"paper-{args.strategy}"
+    metrics_path = _resolve_log_path(args.metrics_path, "metrics.csv", bot_id)
+    trades_path = _resolve_log_path(args.trades_path, "trades.csv", bot_id)
+
+    trader = Trader(
+        strategy=strategy,
+        symbols=symbols,
+        cycle_minutes=args.cycle_minutes,
+        initial_cash=args.capital,
+        position_notional=args.position_notional,
+        bot_id=bot_id,
+    )
+
+    warm_start = args.warm_start
+    if args.cold_start:
+        warm_start = False
+
+    try:
+        log_dir = Path(args.log_dir).expanduser() if args.log_dir else Path("logs")
+        log_dir.mkdir(parents=True, exist_ok=True)
+        trader.run_paper_trading(
+            token=args.token,
+            warm_start=warm_start,
+            max_cycles=args.max_cycles,
+            metrics_path=metrics_path,
+            trades_path=trades_path,
+            log_dir=log_dir,
+            detailed_logs=args.detailed,
+        )
+        return 0
+    except KeyboardInterrupt:
+        print("\nPaper trading stopped by user.")
+        return 0
+    except Exception as exc:  # pragma: no cover - CLI guardrail
+        print(f"Paper trading failed: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+
+