systemr-cli 1.0.0__py3-none-any.whl

neo/credits.py

@@ -0,0 +1,98 @@
+"""Session credit tracking — per-response and per-session cost tracking.
+
+All credit values use Decimal to prevent floating-point accumulation errors
+over long trading sessions.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from decimal import Decimal
+from typing import Any
+
+from neo.types import to_decimal
+
+LOW_BALANCE_THRESHOLD = Decimal("50")
+
+
+@dataclass
+class SessionCredits:
+    """Track credit usage across a chat session.
+
+    All financial accumulators use Decimal. The summary() method
+    returns values suitable for display.
+
+    Attributes:
+        total_credits: Accumulated credits used this session.
+        tools_called: Number of tool calls observed.
+        trades_placed: Number of trade actions executed.
+        messages_sent: Number of messages sent.
+        start_time: Unix timestamp when session started.
+        last_balance: Most recent balance from API.
+        low_balance_warned: Whether low balance warning was shown.
+    """
+
+    total_credits: Decimal = field(default_factory=lambda: Decimal("0"))
+    tools_called: int = 0
+    trades_placed: int = 0
+    messages_sent: int = 0
+    start_time: float = field(default_factory=time.time)
+    last_balance: Decimal | None = None
+    low_balance_warned: bool = False
+
+    def add_response(
+        self,
+        credits_used: Decimal | float | None = None,
+        balance: Decimal | float | None = None,
+        tools: int = 0,
+        trade: bool = False,
+    ) -> None:
+        """Record a response's credit usage.
+
+        Args:
+            credits_used: Credits consumed by this response.
+            balance: Remaining balance reported by API.
+            tools: Number of tools called in this response.
+            trade: Whether this response involved a trade action.
+        """
+        self.messages_sent += 1
+        if credits_used is not None:
+            self.total_credits += to_decimal(credits_used)
+        if balance is not None:
+            self.last_balance = to_decimal(balance)
+        self.tools_called += tools
+        if trade:
+            self.trades_placed += 1
+
+    @property
+    def duration_minutes(self) -> int:
+        """Return session duration in minutes."""
+        return int((time.time() - self.start_time) / 60)
+
+    @property
+    def is_low_balance(self) -> bool:
+        """Check if balance is below the warning threshold.
+
+        Returns:
+            True if balance is known and below LOW_BALANCE_THRESHOLD.
+        """
+        if self.last_balance is None:
+            return False
+        return self.last_balance < LOW_BALANCE_THRESHOLD
+
+    def summary(self) -> dict[str, Any]:
+        """Return a summary dict for display.
+
+        Returns:
+            Dict with credits_used, tools_called, trades_placed,
+            messages, duration_min, and balance.
+        """
+        return {
+            "credits_used": float(self.total_credits),
+            "tools_called": self.tools_called,
+            "trades_placed": self.trades_placed,
+            "messages": self.messages_sent,
+            "duration_min": self.duration_minutes,
+            "balance": float(self.last_balance) if self.last_balance is not None else None,
+        }

neo/cron.py

@@ -0,0 +1,365 @@
+"""Cron scheduler — local scheduled tasks for System R CLI.
+
+Three schedule types (inspired by OpenClaw's cron system):
+  at    — one-shot ISO 8601 timestamp
+  every — fixed interval in seconds
+  cron  — 5-field cron expression with timezone
+
+Jobs persist to ~/.systemr/cron/jobs.json, surviving restarts.
+Each job fires a ChatRequest to agents.systemr.ai in an isolated session.
+Retry with exponential backoff for transient failures.
+
+No bare print() — logging via structlog.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+from neo.config import SYSTEMR_HOME, ensure_systemr_home
+
+logger = structlog.get_logger(module="cron")
+
+CRON_DIR = SYSTEMR_HOME / "cron"
+JOBS_FILE = CRON_DIR / "jobs.json"
+RUNS_DIR = CRON_DIR / "runs"
+
+# Retry settings
+MAX_RETRY_ATTEMPTS: int = 3
+RETRY_BACKOFF_SECONDS: list[float] = [30.0, 60.0, 300.0]
+
+
+class ScheduleKind(Enum):
+    """Type of schedule."""
+
+    AT = "at"  # One-shot ISO 8601 timestamp
+    EVERY = "every"  # Fixed interval in seconds
+    CRON = "cron"  # 5-field cron expression
+
+
+@dataclass
+class Schedule:
+    """Job schedule definition.
+
+    Attributes:
+        kind: Schedule type (at, every, cron).
+        at: ISO 8601 timestamp for one-shot jobs.
+        every_seconds: Interval in seconds for recurring jobs.
+        expr: Cron expression (5-field) for cron jobs.
+        tz: IANA timezone for cron expressions (default: local).
+    """
+
+    kind: ScheduleKind
+    at: str | None = None
+    every_seconds: float | None = None
+    expr: str | None = None
+    tz: str | None = None
+
+
+@dataclass
+class CronJob:
+    """A scheduled job definition.
+
+    Attributes:
+        id: Unique job identifier.
+        name: Human-readable name.
+        schedule: When to run.
+        message: Prompt to send to the backend.
+        model: Optional model override for this job.
+        enabled: Whether the job is active.
+        delete_after_run: Auto-delete one-shot jobs after success.
+        created_at: ISO 8601 creation timestamp.
+        last_run_at: ISO 8601 timestamp of last execution.
+        run_count: Total times executed.
+        error_count: Consecutive error count.
+    """
+
+    id: str = ""
+    name: str = ""
+    schedule: Schedule = field(default_factory=lambda: Schedule(kind=ScheduleKind.AT))
+    message: str = ""
+    model: str | None = None
+    enabled: bool = True
+    delete_after_run: bool = False
+    created_at: str = ""
+    last_run_at: str | None = None
+    run_count: int = 0
+    error_count: int = 0
+
+    def __post_init__(self) -> None:
+        """Set defaults for new jobs."""
+        if not self.id:
+            self.id = f"job_{uuid.uuid4().hex[:8]}"
+        if not self.created_at:
+            self.created_at = datetime.now(timezone.utc).isoformat()
+
+
+@dataclass
+class RunRecord:
+    """Record of a single job execution.
+
+    Attributes:
+        job_id: Which job ran.
+        run_at: ISO 8601 timestamp.
+        status: ok, error, or skipped.
+        message: Error message if failed.
+        duration_seconds: How long the run took.
+    """
+
+    job_id: str
+    run_at: str = ""
+    status: str = "ok"
+    message: str = ""
+    duration_seconds: float = 0.0
+
+    def __post_init__(self) -> None:
+        if not self.run_at:
+            self.run_at = datetime.now(timezone.utc).isoformat()
+
+
+def _ensure_cron_dirs() -> None:
+    """Create cron directories if they don't exist."""
+    ensure_systemr_home()
+    CRON_DIR.mkdir(mode=0o700, parents=True, exist_ok=True)
+    RUNS_DIR.mkdir(mode=0o700, parents=True, exist_ok=True)
+
+
+def _serialize_schedule(s: Schedule) -> dict[str, Any]:
+    """Serialize a Schedule to JSON-safe dict."""
+    return {
+        "kind": s.kind.value,
+        "at": s.at,
+        "every_seconds": s.every_seconds,
+        "expr": s.expr,
+        "tz": s.tz,
+    }
+
+
+def _deserialize_schedule(d: dict[str, Any]) -> Schedule:
+    """Deserialize a Schedule from JSON dict."""
+    return Schedule(
+        kind=ScheduleKind(d.get("kind", "at")),
+        at=d.get("at"),
+        every_seconds=d.get("every_seconds"),
+        expr=d.get("expr"),
+        tz=d.get("tz"),
+    )
+
+
+def load_jobs() -> list[CronJob]:
+    """Load all cron jobs from disk.
+
+    Returns:
+        List of CronJob instances.
+    """
+    if not JOBS_FILE.exists():
+        return []
+
+    try:
+        data = json.loads(JOBS_FILE.read_text())
+        jobs = []
+        for item in data:
+            schedule = _deserialize_schedule(item.pop("schedule", {}))
+            job = CronJob(**item, schedule=schedule)
+            jobs.append(job)
+        return jobs
+    except (json.JSONDecodeError, TypeError, KeyError) as exc:
+        logger.warning("cron_jobs_parse_error", error=str(exc))
+        return []
+
+
+def save_jobs(jobs: list[CronJob]) -> None:
+    """Persist all cron jobs to disk.
+
+    Args:
+        jobs: List of CronJob instances.
+    """
+    _ensure_cron_dirs()
+    data = []
+    for job in jobs:
+        item = {
+            "id": job.id,
+            "name": job.name,
+            "schedule": _serialize_schedule(job.schedule),
+            "message": job.message,
+            "model": job.model,
+            "enabled": job.enabled,
+            "delete_after_run": job.delete_after_run,
+            "created_at": job.created_at,
+            "last_run_at": job.last_run_at,
+            "run_count": job.run_count,
+            "error_count": job.error_count,
+        }
+        data.append(item)
+
+    JOBS_FILE.write_text(json.dumps(data, indent=2))
+    logger.info("cron_jobs_saved", count=len(jobs))
+
+
+def add_job(
+    name: str,
+    message: str,
+    schedule: Schedule,
+    model: str | None = None,
+    delete_after_run: bool = False,
+) -> CronJob:
+    """Create and persist a new cron job.
+
+    Args:
+        name: Human-readable job name.
+        message: Prompt to send when job fires.
+        schedule: When to run.
+        model: Optional model override.
+        delete_after_run: Auto-delete one-shot jobs after success.
+
+    Returns:
+        The created CronJob.
+    """
+    job = CronJob(
+        name=name,
+        message=message,
+        schedule=schedule,
+        model=model,
+        delete_after_run=delete_after_run,
+    )
+    jobs = load_jobs()
+    jobs.append(job)
+    save_jobs(jobs)
+    logger.info("cron_job_added", id=job.id, name=name, kind=schedule.kind.value)
+    return job
+
+
+def remove_job(job_id: str) -> bool:
+    """Remove a job by ID.
+
+    Args:
+        job_id: Job identifier.
+
+    Returns:
+        True if removed, False if not found.
+    """
+    jobs = load_jobs()
+    original_count = len(jobs)
+    jobs = [j for j in jobs if j.id != job_id]
+    if len(jobs) == original_count:
+        return False
+    save_jobs(jobs)
+    logger.info("cron_job_removed", id=job_id)
+    return True
+
+
+def get_job(job_id: str) -> CronJob | None:
+    """Get a job by ID.
+
+    Args:
+        job_id: Job identifier.
+
+    Returns:
+        CronJob if found, None otherwise.
+    """
+    for job in load_jobs():
+        if job.id == job_id:
+            return job
+    return None
+
+
+def record_run(run: RunRecord) -> None:
+    """Append a run record to the job's run history.
+
+    Args:
+        run: The RunRecord to persist.
+    """
+    _ensure_cron_dirs()
+    run_file = RUNS_DIR / f"{run.job_id}.jsonl"
+    line = json.dumps({
+        "run_at": run.run_at,
+        "status": run.status,
+        "message": run.message,
+        "duration_seconds": run.duration_seconds,
+    })
+    with open(run_file, "a") as f:
+        f.write(line + "\n")
+
+
+def get_runs(job_id: str, limit: int = 20) -> list[dict[str, Any]]:
+    """Get recent run history for a job.
+
+    Args:
+        job_id: Job identifier.
+        limit: Maximum records to return.
+
+    Returns:
+        List of run record dicts, newest first.
+    """
+    run_file = RUNS_DIR / f"{job_id}.jsonl"
+    if not run_file.exists():
+        return []
+
+    try:
+        lines = run_file.read_text().strip().splitlines()
+        runs = [json.loads(line) for line in lines[-limit:]]
+        runs.reverse()
+        return runs
+    except (json.JSONDecodeError, TypeError):
+        return []
+
+
+def is_due(job: CronJob) -> bool:
+    """Check if a job is due to run now.
+
+    For 'at' jobs: due if current time >= scheduled time.
+    For 'every' jobs: due if interval elapsed since last run.
+    For 'cron' jobs: simplified check (full cron parsing deferred).
+
+    Args:
+        job: The job to check.
+
+    Returns:
+        True if the job should run now.
+    """
+    if not job.enabled:
+        return False
+
+    now = time.time()
+
+    if job.schedule.kind == ScheduleKind.AT:
+        if not job.schedule.at:
+            return False
+        try:
+            target = datetime.fromisoformat(job.schedule.at).timestamp()
+            return now >= target
+        except ValueError:
+            return False
+
+    if job.schedule.kind == ScheduleKind.EVERY:
+        if not job.schedule.every_seconds:
+            return False
+        if job.last_run_at is None:
+            return True
+        try:
+            last = datetime.fromisoformat(job.last_run_at).timestamp()
+            return now >= last + job.schedule.every_seconds
+        except ValueError:
+            return True
+
+    # CRON expression — requires external library for full parsing.
+    # For now, treat as always due (will be refined with croner equiv).
+    if job.schedule.kind == ScheduleKind.CRON:
+        if job.last_run_at is None:
+            return True
+        try:
+            last = datetime.fromisoformat(job.last_run_at).timestamp()
+            return now >= last + 60  # Minimum 1 minute between cron runs
+        except ValueError:
+            return True
+
+    return False

neo/display/chat_renderer.py

@@ -0,0 +1,127 @@
+"""Chat message renderer — System R streaming conversation display.
+
+All rendering goes through Rich console. No raw sys.stdout writes.
+Text deltas are collected by the chat loop and rendered once as a
+formatted panel when the done event arrives — no double rendering.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Union
+
+from rich.markdown import Markdown
+from rich.panel import Panel
+
+from neo.display.theme import (
+    GREEN,
+    GREEN_DIM,
+    DIM,
+    MUTED,
+    GRAY,
+    RED,
+    AMBER,
+    console,
+)
+
+# Indicators — defined in theme.py, imported for consistency
+ICON_THINKING = "◐"
+ICON_SUCCESS = "✓"
+ICON_ERROR = "✗"
+
+# Low balance threshold — must match credits.SessionCredits if used
+_LOW_BALANCE_THRESHOLD: Decimal = Decimal("50")
+
+
+def render_user_message(text: str) -> None:
+    """Render a user message with the you > prompt.
+
+    Args:
+        text: The user's input text.
+    """
+    console.print(f"\n  [{GREEN_DIM}]you >[/] {text}")
+
+
+def render_assistant_message(text: str) -> None:
+    """Render a complete System R response as a Rich markdown panel.
+
+    Args:
+        text: The full response text (may contain markdown).
+    """
+    if not text.strip():
+        return
+    md = Markdown(text)
+    console.print(
+        Panel(
+            md,
+            title=f"[bold {GREEN}]SYSTEM R[/]",
+            border_style=MUTED,
+            padding=(1, 2),
+        )
+    )
+
+
+def render_thinking(text: str = "thinking...") -> None:
+    """Show a thinking step from the LLM reasoning process.
+
+    Args:
+        text: Description of what the LLM is thinking about.
+    """
+    console.print(f"  [{DIM}]{ICON_THINKING} {text}[/]")
+
+
+def render_action(
+    tool_name: str,
+    status: str = "running",
+    result: str = "",
+) -> None:
+    """Show a tool call being executed with status indicator.
+
+    Args:
+        tool_name: Name of the tool being called.
+        status: One of "running", "complete", "error", "pending".
+        result: Optional result summary (truncated in display).
+    """
+    if status == "complete":
+        suffix = f"  [{GRAY}]{result}[/]" if result else ""
+        console.print(f"  [{GREEN}]{ICON_SUCCESS}[/] [{GRAY}]{tool_name}[/]{suffix}")
+    elif status == "error":
+        suffix = f"  [{RED}]{result}[/]" if result else ""
+        console.print(f"  [{RED}]{ICON_ERROR}[/] [{GRAY}]{tool_name}[/]{suffix}")
+    elif status == "pending":
+        suffix = f"  [{AMBER}]{result}[/]" if result else ""
+        console.print(f"  [{AMBER}]![/] [{GRAY}]{tool_name}[/]{suffix}")
+    else:
+        console.print(f"  [{GREEN_DIM}]{ICON_THINKING}[/] [{GRAY}]{tool_name}...[/]")
+
+
+def render_error(message: str) -> None:
+    """Show an error from the stream or chat loop.
+
+    Args:
+        message: The error message text.
+    """
+    console.print(f"\n  [{RED}]{ICON_ERROR}[/] [{GRAY}]{message}[/]")
+
+
+def render_credits(
+    credits_used: Union[Decimal, float, None] = None,
+    balance: Union[Decimal, float, None] = None,
+) -> None:
+    """Show credit usage after a response.
+
+    Args:
+        credits_used: Credits consumed by this response.
+        balance: Remaining credit balance.
+    """
+    parts: list[str] = []
+    if credits_used is not None:
+        parts.append(f"{float(credits_used):.1f} credits")
+    if balance is not None:
+        bal = Decimal(str(balance)) if not isinstance(balance, Decimal) else balance
+        if bal < _LOW_BALANCE_THRESHOLD:
+            parts.append(f"[{AMBER}]balance: {float(balance):.1f}[/]")
+        else:
+            parts.append(f"balance: {float(balance):.1f}")
+    if parts:
+        console.print(f"  [{DIM}]{' · '.join(parts)}[/]")

neo/display/formatters.py

@@ -0,0 +1,112 @@
+"""Formatting utilities for trading data.
+
+All formatters accept both Decimal and float for backward compatibility.
+New code should pass Decimal values (from neo.types).
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Union
+
+# Accept both Decimal and float — Decimal preferred, float for backward compat
+Numeric = Union[Decimal, float, int]
+
+
+def fmt_price(value: Numeric, decimals: int = 2) -> str:
+    """Format a price with $ prefix.
+
+    Args:
+        value: Price as Decimal, float, or int.
+        decimals: Number of decimal places (default 2).
+
+    Returns:
+        Formatted string like "$1,234.56".
+    """
+    return f"${float(value):,.{decimals}f}"
+
+
+def fmt_qty(value: int | float) -> str:
+    """Format a quantity (shares/contracts).
+
+    Args:
+        value: Quantity as int or float. Floats that are whole numbers
+               are displayed without decimals.
+
+    Returns:
+        Formatted string like "1,200".
+    """
+    if isinstance(value, float) and value == int(value):
+        value = int(value)
+    return f"{value:,}"
+
+
+def fmt_pct(value: Numeric, decimals: int = 1, signed: bool = False) -> str:
+    """Format as percentage.
+
+    Args:
+        value: Percentage as Decimal, float, or int.
+        decimals: Number of decimal places (default 1).
+        signed: If True, prefix with +/- sign (DESIGN.md §4.3).
+
+    Returns:
+        Formatted string like "1.5%" or "+2.34%".
+    """
+    v = float(value)
+    if signed:
+        sign = "+" if v > 0 else ""
+        return f"{sign}{v:.{decimals}f}%"
+    return f"{v:.{decimals}f}%"
+
+
+def fmt_r(value: Numeric) -> str:
+    """Format an R-multiple.
+
+    Args:
+        value: R-multiple as Decimal, float, or int.
+
+    Returns:
+        Formatted string like "+1.50R" or "-1.00R".
+    """
+    v = float(value)
+    sign = "+" if v > 0 else ""
+    return f"{sign}{v:.2f}R"
+
+
+def fmt_risk(value: Numeric) -> str:
+    """Format a risk amount with $ prefix.
+
+    Args:
+        value: Risk amount as Decimal, float, or int.
+
+    Returns:
+        Formatted string like "$1,046.80".
+    """
+    return f"${float(value):,.2f}"
+
+
+def fmt_pnl(value: Numeric) -> str:
+    """Format P&L with sign and Rich color markup.
+
+    Args:
+        value: P&L amount as Decimal, float, or int.
+
+    Returns:
+        Rich-formatted string with green for profit, red for loss.
+    """
+    v = float(value)
+    sign = "+" if v >= 0 else ""
+    color = "#3ECF8E" if v >= 0 else "#EF4444"
+    return f"[{color}]{sign}${v:,.2f}[/]"
+
+
+def direction_style(direction: str) -> str:
+    """Return Rich style string for trade direction.
+
+    Args:
+        direction: "long" or "short".
+
+    Returns:
+        Rich style string with brand colors.
+    """
+    return "bold #3ECF8E" if direction.lower() == "long" else "bold #EF4444"