ARGUS

Overview

ARGUS is a Python research library exploring control-theoretic approaches to market data, regime detection, risk monitoring, and execution-aware analysis. The project treats markets as noisy, partially observed systems where state estimation, stability monitoring, and feedback control can make risk more observable. The public release includes deterministic sample data, a scalar state-estimation module, rolling risk diagnostics, a tested CLI report path, examples, and documentation. Private data, broker credentials, and live execution workflows are intentionally excluded.

Why It Matters

Quantitative trading systems fail when uncertainty is hidden: stale data, regime shifts, crowding, execution cost, and unmanaged drawdown risk. ARGUS frames those problems using cyber-physical systems ideas such as sensor fusion, state estimation, fault detection, and feedback. The goal is not to promise returns, but to make market-risk infrastructure easier to inspect, test, and reason about.

Key Concepts

• Regime detection over price and volatility windows
• Kalman and extended Kalman filtering research patterns
• Lyapunov-style portfolio stability monitoring
• Risk surfaces, drawdown windows, and stress diagnostics
• Model-predictive execution research
• Feedback loops between market state, risk state, and reporting

Core Features

Area	Description
Market data	Lightweight interfaces for loading and validating price series
Indicators	Moving averages, returns, volatility, and regime features
Statistics	Drawdown, z-score, correlation, and windowed summaries
State estimation	Scalar Kalman-style smoothing over noisy price observations
Risk	Rolling diagnostics, drawdown/volatility stress, and stability-margin scoring
CLI	argus diagnose report builder for sample or user-supplied price series
Research docs	CPS mapping, methodology notes, and architecture diagrams

Architecture

graph TD
  A[Data Ingestion] --> B[Feature Engineering]
  B --> C[Regime Detection]
  C --> D[State Estimation]
  D --> E[Risk Engine]
  E --> F[Reporting]
  F --> C

Loading

argus/
  src/argus/
    market_data.py   # price-series interfaces and validation helpers
    filters.py       # scalar state-estimation helpers
    indicators.py    # moving averages, returns, and volatility features
    stats.py         # drawdown and statistical summaries
    risk.py          # stability-margin and risk diagnostic helpers
    cli.py           # command-line report builder
    greeks.py        # option-risk roadmap module
    calendar.py      # market-calendar research module
    cache.py         # small local cache helper
    config.py        # typed configuration helpers
    utils.py         # shared utilities
  examples/
    demo_regime_risk.py
    sample_config.yaml
  docs/
    architecture.md
    research_notes.md
    methodology.md
  tests/
    test_imports.py

Module Notes

Module	Role
market_data.py	Normalize sample price series and validate input shape
filters.py	Run scalar Kalman-style smoothing for state-estimation demos
indicators.py	Compute returns, moving averages, volatility, and simple regime signals
stats.py	Provide drawdown and summary statistics used by the risk layer
risk.py	Score drawdown/volatility stress, rolling windows, and stability margin
cli.py	Render deterministic diagnostic reports from the terminal
greeks.py	Defines the option-risk roadmap interface without claiming production coverage
cache.py	Stores safe, local research artifacts outside private data folders
calendar.py	Keeps exchange-calendar assumptions explicit
config.py	Loads safe YAML-style configuration where available
utils.py	Shared type and validation helpers

Review Docs

• Technical case study
• Validation matrix
• Research notes
• Recruiter brief

Tech Stack

• Python 3.10+
• pandas, NumPy, PyYAML
• pytest
• Mermaid documentation diagrams

Quickstart

git clone https://github.com/shawsignaldev/argus.git
cd argus
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .
python examples/demo_regime_risk.py
argus diagnose --window 5
argus diagnose --prices 100,101,99,102,103 --json

Windows:

git clone https://github.com/shawsignaldev/argus.git
cd argus
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
pip install -e .
python examples\demo_regime_risk.py
argus diagnose --window 5
argus diagnose --prices 100,101,99,102,103 --json

Example Output

Metric	Example
Current regime	stable
Realized volatility	0.0158
Max drawdown	-0.0333
Stability margin	0.7403
Risk state	watch
Rolling windows	5
Last filtered price	100.890885

Research Notes

ARGUS connects cyber-physical systems and quantitative finance through a control-loop framing: data feeds act as sensors, regime estimators act as observers, risk policies act as controllers, execution models act as actuators, and reports close the loop. The current public release includes a scalar state-estimation path and rolling risk diagnostics. More advanced items such as extended Kalman filtering, robust control, and MPC execution remain documented research directions unless implemented and tested.

Project Status

Version 0.1 public research release with implemented sample-data diagnostics, state-estimation utilities, rolling risk windows, CLI reports, examples, tests, and roadmap items.

Roadmap

• Add reproducible notebooks for regime and drawdown case studies
• Expand risk-surface diagnostics with tested examples
• Add optional market-data provider adapters with strict credential hygiene
• Build a small Streamlit demo for stability monitoring

Disclaimer

This repository is for educational and research purposes only. It is not financial advice, investment advice, or a recommendation to buy or sell any security. Trading involves risk, including possible loss of capital.