systemr-cli 1.0.0__py3-none-any.whl

neo/display/tables.py

@@ -0,0 +1,53 @@
+"""Rich table helpers — dark, precise, institutional tables.
+
+System R brand: green accent on dark background. Labels in green,
+values in white. Matches DESIGN.md §4.3 typography rules.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.table import Table
+
+from neo.display.theme import GREEN, GREEN_DIM, DIM, console
+
+
+def kv_table(title: str, data: dict[str, Any], *, value_style: str = f"bold {GREEN}") -> None:
+    """Print a key-value table — labels in green, values in white."""
+    table = Table(
+        title=f"[bold {GREEN}]{title}[/]",
+        show_header=False,
+        border_style=DIM,
+        padding=(0, 2),
+        title_justify="left",
+    )
+    table.add_column("Key", style=GREEN_DIM, min_width=18)
+    table.add_column("Value", style=value_style)
+    for key, value in data.items():
+        table.add_row(key, str(value))
+    console.print(table)
+    console.print()
+
+
+def data_table(
+    title: str,
+    columns: list[tuple[str, str]],  # (name, style)
+    rows: list[list[str]],
+) -> None:
+    """Print a data table with brand-styled columns."""
+    table = Table(
+        title=f"[bold {GREEN}]{title}[/]",
+        border_style=DIM,
+        padding=(0, 1),
+        title_justify="left",
+        row_styles=[f"{GREEN_DIM}", ""],  # alternating subtle rows
+    )
+    for col_name, col_style in columns:
+        # Default to green if no style specified
+        style = col_style if col_style else GREEN
+        table.add_column(col_name, style=style, header_style=f"bold {GREEN}")
+    for row in rows:
+        table.add_row(*row)
+    console.print(table)
+    console.print()

neo/display/theme.py

@@ -0,0 +1,154 @@
+"""System R CLI display theme — dark, precise, institutional.
+
+Provides the canonical brand palette (from DESIGN.md §4.2),
+Rich theme, console instance, and print helpers.
+"""
+
+from rich.console import Console
+from rich.theme import Theme
+
+# ── System R brand palette ──────────────────────────────────────────
+# Canonical colors from systemr.ai. Do not modify without updating
+# DESIGN.md §4.2.
+
+WHITE = "#F5F5F5"          # Primary text — values, data, emphasis
+GRAY = "#A1A1AA"           # Secondary text — labels, descriptions
+DIM = "#52525B"            # Tertiary text — timestamps, hints
+MUTED = "#3F3F46"          # Borders, separators, disabled
+GREEN = "#3ECF8E"          # Brand accent — success, active, emphasis
+GREEN_DIM = "#34B87A"      # Secondary accent — hover, borders
+RED = "#EF4444"            # Errors, losses, short positions
+AMBER = "#F59E0B"          # Warnings, caution states
+BLUE = "#3B82F6"           # Info, neutral indicators
+BG = "#09090B"             # Terminal background
+
+# Legacy aliases (additive-only — old names from Matrix theme still work)
+DARK_BG = BG
+
+# ── Rich theme ──────────────────────────────────────────────────────
+
+SYSTEM_R_THEME = Theme({
+    # Core palette
+    "sr.white": f"bold {WHITE}",
+    "sr.gray": GRAY,
+    "sr.dim": DIM,
+    "sr.muted": MUTED,
+    "sr.accent": f"bold {GREEN}",
+    "sr.accent.dim": GREEN_DIM,
+    "sr.value": f"bold {WHITE}",
+    "sr.label": GRAY,
+
+    # Semantic
+    "sr.success": f"bold {GREEN}",
+    "sr.error": f"bold {RED}",
+    "sr.warn": f"bold {AMBER}",
+    "sr.info": f"bold {BLUE}",
+
+    # Trading-specific
+    "sr.long": f"bold {GREEN}",
+    "sr.short": f"bold {RED}",
+    "sr.profit": f"bold {GREEN}",
+    "sr.loss": f"bold {RED}",
+
+    # Legacy aliases (additive-only)
+    "neo.green": f"bold {GREEN}",
+    "neo.dim": DIM,
+    "neo.label": GREEN_DIM,
+    "neo.value": f"bold {WHITE}",
+    "neo.error": f"bold {RED}",
+    "neo.warn": f"bold {AMBER}",
+    "neo.header": f"bold {GREEN}",
+    "neo.muted": f"dim {GREEN_DIM}",
+})
+
+console = Console(theme=SYSTEM_R_THEME)
+
+# ── Indicators ──────────────────────────────────────────────────────
+
+ICON_THINKING = "◐"
+ICON_SUCCESS = "✓"
+ICON_ERROR = "✗"
+ICON_WARN = "!"
+ICON_INFO = "●"
+ICON_CONNECTED = "●"
+ICON_DISCONNECTED = "○"
+
+# ── Legacy banner (kept for backward compat) ────────────────────────
+
+NEO_BANNER = rf"""[{GREEN}]
+ ███╗   ██╗███████╗ ██████╗
+ ████╗  ██║██╔════╝██╔═══██╗
+ ██╔██╗ ██║█████╗  ██║   ██║
+ ██║╚██╗██║██╔══╝  ██║   ██║
+ ██║ ╚████║███████╗╚██████╔╝
+ ╚═╝  ╚═══╝╚══════╝ ╚═════╝[/]
+[{GREEN_DIM}] System R AI — Trading Operator[/]
+"""
+
+
+# ── Print helpers ───────────────────────────────────────────────────
+
+def print_banner() -> None:
+    """Print the System R home screen header.
+
+    SYSTEM R AI in brand green bold, version, tagline.
+    """
+    from neo import __version__
+    console.print()
+    console.print(f"  [{GREEN}][bold]SYSTEM R AI[/bold][/]  [{DIM}]V{__version__}[/]", highlight=False)
+    console.print()
+    console.print(f"  [{GRAY}]Trading operating system for agents[/]")
+    console.print()
+
+
+def neo_banner() -> str:
+    """Return legacy banner string.
+
+    Returns:
+        Rich-formatted banner string.
+    """
+    return f"[{GREEN}]SYSTEM R[/] [{GREEN_DIM}]Trading OS[/]"
+
+
+def print_error(msg: str) -> None:
+    """Print an error message.
+
+    Args:
+        msg: Error message text.
+    """
+    console.print(f"  [{RED}]{ICON_ERROR}[/] [{GRAY}]{msg}[/]")
+
+
+def print_success(msg: str) -> None:
+    """Print a success message.
+
+    Args:
+        msg: Success message text.
+    """
+    console.print(f"  [{GREEN}]{ICON_SUCCESS}[/] [{WHITE}]{msg}[/]")
+
+
+def print_warn(msg: str) -> None:
+    """Print a warning message.
+
+    Args:
+        msg: Warning message text.
+    """
+    console.print(f"  [{AMBER}]{ICON_WARN}[/] [{GRAY}]{msg}[/]")
+
+
+def print_info(msg: str) -> None:
+    """Print an info message.
+
+    Args:
+        msg: Info message text.
+    """
+    console.print(f"  [{BLUE}]{ICON_INFO}[/] [{GRAY}]{msg}[/]")
+
+
+def print_separator() -> None:
+    """Print a separator line.
+
+    Uses 48 thin dashes in MUTED color.
+    """
+    console.print(f"  [{MUTED}]{'─' * 48}[/]")

neo/hooks.py

@@ -0,0 +1,170 @@
+"""Hooks system — pre/post event automation.
+
+Mirrors Claude Code's hook architecture with trading-specific events.
+Hooks are shell commands configured in ~/.systemr/config.json.
+
+Event types:
+  PreTrade     — before any order is placed (confirmation approved)
+  PostTrade    — after an order is confirmed executed
+  PreSession   — when a chat session starts
+  PostSession  — when a chat session ends
+  RuleViolation — when a trading rule is violated
+  KillSwitch   — when kill switch is activated
+  LowBalance   — when credits drop below threshold
+  Error        — when an error occurs
+
+Config format in config.json:
+{
+  "hooks": {
+    "PreTrade": [{"command": "echo 'Trade incoming'"}],
+    "PostTrade": [{"command": "say 'Trade executed'"}]
+  }
+}
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from enum import Enum
+from typing import Any
+
+import structlog
+
+from neo.config import CONFIG_FILE
+
+logger = structlog.get_logger(module="hooks")
+
+
+class HookEvent(Enum):
+    """Hook event types matching Claude Code's architecture.
+
+    Extended with OpenClaw-inspired events:
+    - BEFORE_TOOL_CALL: inspect tool name + args before execution, can block
+    - COMPACT_BEFORE: auto-flush memories before context compaction
+    """
+
+    PRE_TRADE = "PreTrade"
+    POST_TRADE = "PostTrade"
+    PRE_SESSION = "PreSession"
+    POST_SESSION = "PostSession"
+    RULE_VIOLATION = "RuleViolation"
+    KILL_SWITCH = "KillSwitch"
+    LOW_BALANCE = "LowBalance"
+    ERROR = "Error"
+    # New: OpenClaw-inspired events
+    BEFORE_TOOL_CALL = "BeforeToolCall"
+    COMPACT_BEFORE = "CompactBefore"
+
+
+# Maximum time a hook can run before being killed
+_HOOK_TIMEOUT_SECONDS = 10
+
+
+def fire_hook(
+    event: HookEvent,
+    context: dict[str, Any] | None = None,
+) -> list[str]:
+    """Fire all hooks registered for the given event.
+
+    Hooks are non-blocking — they run with a timeout and failures
+    are logged but never propagate to the caller.
+
+    Args:
+        event: The hook event type to fire.
+        context: Optional dict passed as SYSTEMR_HOOK_CONTEXT env var.
+
+    Returns:
+        List of hook stdout outputs (empty strings filtered out).
+    """
+    hooks = _load_hooks(event)
+    if not hooks:
+        return []
+
+    outputs: list[str] = []
+    for hook in hooks:
+        command = hook.get("command", "")
+        if not command:
+            continue
+        try:
+            env = dict(os.environ)
+            if context:
+                env["SYSTEMR_HOOK_CONTEXT"] = json.dumps(context)
+
+            result = subprocess.run(
+                command,
+                shell=True,
+                capture_output=True,
+                text=True,
+                timeout=_HOOK_TIMEOUT_SECONDS,
+                env=env,
+            )
+            if result.stdout.strip():
+                outputs.append(result.stdout.strip())
+            logger.debug(
+                "hook_fired", hook_event=event.value,
+                command=command[:50], exit_code=result.returncode,
+            )
+        except subprocess.TimeoutExpired:
+            logger.warning("hook_timeout", hook_event=event.value, command=command[:50])
+        except Exception as exc:
+            logger.warning("hook_error", hook_event=event.value, error=str(exc))
+
+    return outputs
+
+
+def _load_hooks(event: HookEvent) -> list[dict[str, str]]:
+    """Load hooks for a specific event from config.json.
+
+    Args:
+        event: The hook event type.
+
+    Returns:
+        List of hook dicts with "command" key. Empty if no config.
+    """
+    if not CONFIG_FILE.exists():
+        return []
+    try:
+        config = json.loads(CONFIG_FILE.read_text())
+        hooks = config.get("hooks", {})
+        return hooks.get(event.value, [])
+    except (json.JSONDecodeError, KeyError):
+        return []
+
+
+def register_hook(event: HookEvent, command: str) -> None:
+    """Register a new hook for an event in config.json.
+
+    Args:
+        event: The hook event type.
+        command: Shell command to execute.
+    """
+    config: dict[str, Any] = {}
+    if CONFIG_FILE.exists():
+        try:
+            config = json.loads(CONFIG_FILE.read_text())
+        except json.JSONDecodeError:
+            config = {}
+
+    hooks = config.setdefault("hooks", {})
+    event_hooks: list[dict[str, str]] = hooks.setdefault(event.value, [])
+    event_hooks.append({"command": command})
+
+    CONFIG_FILE.write_text(json.dumps(config, indent=2))
+    logger.info("hook_registered", hook_event=event.value, command=command[:50])
+
+
+def list_hooks() -> dict[str, list[dict[str, str]]]:
+    """List all registered hooks.
+
+    Returns:
+        Dict mapping event names to lists of hook dicts.
+    """
+    if not CONFIG_FILE.exists():
+        return {}
+    try:
+        config = json.loads(CONFIG_FILE.read_text())
+        return config.get("hooks", {})
+    except (json.JSONDecodeError, KeyError):
+        return {}

neo/logging.py

@@ -0,0 +1,56 @@
+"""Structured logging for System R CLI.
+
+All production logging goes through structlog. The Rich console
+is used for user-facing display only — not for logging.
+
+Usage:
+    from neo.logging import get_logger
+    logger = get_logger()
+    logger.info("trade_executed", symbol="TSLA", shares=160)
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+import structlog
+
+
+def configure_logging(*, debug: bool = False) -> None:
+    """Configure structlog for the CLI.
+
+    In production mode (debug=False), logs go to stderr at WARNING level
+    to keep stdout clean for the user. In debug mode, logs go to stderr
+    at DEBUG level with full console rendering.
+
+    Args:
+        debug: If True, log at DEBUG level with full tracebacks.
+               If False, log at WARNING level, JSON format, stderr only.
+    """
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.dev.ConsoleRenderer() if debug else structlog.processors.JSONRenderer(),
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(
+            logging.DEBUG if debug else logging.WARNING,
+        ),
+        context_class=dict,
+        logger_factory=structlog.PrintLoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+
+def get_logger(**initial_context: str) -> structlog.stdlib.BoundLogger:
+    """Get a bound structlog logger.
+
+    Args:
+        **initial_context: Key-value pairs to bind to every log entry.
+
+    Returns:
+        A bound structlog logger instance.
+    """
+    return structlog.get_logger(**initial_context)

neo/model_failover.py

@@ -0,0 +1,193 @@
+"""Model failover chain — automatic fallback on stream failure.
+
+When the primary model fails (timeout, 429, 5xx), tries the next model
+in the configured fallback chain. Tracks cooldowns per model to avoid
+retrying a model that just failed.
+
+Inspired by OpenClaw's two-stage failover with cooldown tracking and
+session pinning. Simplified for System R: no auth rotation, just model
+fallback with cooldown.
+
+No bare print() — logging via structlog.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import structlog
+
+from neo.config import CONFIG_FILE, ensure_systemr_home
+
+logger = structlog.get_logger(module="model_failover")
+
+# Default cooldown: 60 seconds after a failure
+DEFAULT_COOLDOWN_SECONDS: float = 60.0
+
+# Maximum cooldown: 15 minutes
+MAX_COOLDOWN_SECONDS: float = 900.0
+
+# Default fallback chain
+DEFAULT_FALLBACKS: list[str] = [
+    "anthropic.claude-sonnet-4-6",
+    "anthropic.claude-haiku-4-5-20251001",
+]
+
+
+@dataclass
+class ModelCooldown:
+    """Tracks failure state for a single model.
+
+    Attributes:
+        model: Model identifier.
+        failed_at: Unix timestamp of last failure.
+        cooldown_until: Unix timestamp when cooldown expires.
+        error_count: Consecutive failure count.
+    """
+
+    model: str
+    failed_at: float = 0.0
+    cooldown_until: float = 0.0
+    error_count: int = 0
+
+    @property
+    def is_cooled_down(self) -> bool:
+        """True if the model is available (cooldown expired)."""
+        return time.time() >= self.cooldown_until
+
+    def record_failure(self) -> None:
+        """Record a failure and extend cooldown with exponential backoff."""
+        self.error_count += 1
+        self.failed_at = time.time()
+        # Exponential backoff: 60s, 120s, 240s, ... capped at 15min
+        backoff = min(
+            DEFAULT_COOLDOWN_SECONDS * (2 ** (self.error_count - 1)),
+            MAX_COOLDOWN_SECONDS,
+        )
+        self.cooldown_until = self.failed_at + backoff
+        logger.info(
+            "model_cooldown_set",
+            model=self.model,
+            error_count=self.error_count,
+            cooldown_seconds=backoff,
+        )
+
+    def record_success(self) -> None:
+        """Reset cooldown state after a successful call."""
+        if self.error_count > 0:
+            logger.info(
+                "model_cooldown_reset",
+                model=self.model,
+                was_error_count=self.error_count,
+            )
+        self.error_count = 0
+        self.cooldown_until = 0.0
+
+
+@dataclass
+class FailoverChain:
+    """Manages model selection with automatic failover.
+
+    Attributes:
+        primary: Primary model to use.
+        fallbacks: Ordered list of fallback models.
+        cooldowns: Per-model cooldown state.
+        pinned_model: Model pinned for current session (sticks until failure).
+    """
+
+    primary: str = ""
+    fallbacks: list[str] = field(default_factory=list)
+    cooldowns: dict[str, ModelCooldown] = field(default_factory=dict)
+    pinned_model: str | None = None
+
+    def get_model(self) -> str:
+        """Return the best available model (pinned > primary > fallbacks).
+
+        Returns:
+            Model identifier string.
+        """
+        # If pinned and not in cooldown, use it
+        if self.pinned_model:
+            cd = self.cooldowns.get(self.pinned_model)
+            if cd is None or cd.is_cooled_down:
+                return self.pinned_model
+
+        # Try primary
+        cd = self.cooldowns.get(self.primary)
+        if cd is None or cd.is_cooled_down:
+            return self.primary
+
+        # Try fallbacks in order
+        for model in self.fallbacks:
+            cd = self.cooldowns.get(model)
+            if cd is None or cd.is_cooled_down:
+                logger.info("model_failover", from_model=self.primary, to_model=model)
+                return model
+
+        # All models in cooldown — use primary anyway (best effort)
+        logger.warning("all_models_in_cooldown", primary=self.primary)
+        return self.primary
+
+    def on_success(self, model: str) -> None:
+        """Record successful call — pin model for session, reset cooldown.
+
+        Args:
+            model: The model that succeeded.
+        """
+        self.pinned_model = model
+        if model in self.cooldowns:
+            self.cooldowns[model].record_success()
+
+    def on_failure(self, model: str) -> None:
+        """Record failed call — set cooldown, unpin if pinned.
+
+        Args:
+            model: The model that failed.
+        """
+        if model not in self.cooldowns:
+            self.cooldowns[model] = ModelCooldown(model=model)
+        self.cooldowns[model].record_failure()
+
+        # Unpin so next call tries a different model
+        if self.pinned_model == model:
+            self.pinned_model = None
+
+
+def load_failover_chain() -> FailoverChain:
+    """Load failover configuration from ~/.systemr/config.json.
+
+    Config format:
+    {
+        "model": {
+            "primary": "anthropic.claude-sonnet-4-6",
+            "fallbacks": ["anthropic.claude-haiku-4-5-20251001"]
+        }
+    }
+
+    Returns:
+        Configured FailoverChain instance.
+    """
+    chain = FailoverChain()
+
+    if CONFIG_FILE.exists():
+        try:
+            config = json.loads(CONFIG_FILE.read_text())
+            model_config = config.get("model", {})
+            chain.primary = model_config.get("primary", "")
+            chain.fallbacks = model_config.get("fallbacks", DEFAULT_FALLBACKS)
+        except (json.JSONDecodeError, TypeError):
+            logger.warning("config_parse_error", path=str(CONFIG_FILE))
+
+    if not chain.primary:
+        chain.primary = DEFAULT_FALLBACKS[0] if DEFAULT_FALLBACKS else ""
+        chain.fallbacks = DEFAULT_FALLBACKS[1:] if len(DEFAULT_FALLBACKS) > 1 else []
+
+    logger.info(
+        "failover_chain_loaded",
+        primary=chain.primary,
+        fallbacks=chain.fallbacks,
+    )
+    return chain