Metadata-Version: 2.4
Name: shield-regime
Version: 0.1.4
Summary: Detect market manipulation using price kinematics and volume anomaly analysis.
Project-URL: Homepage, https://github.com/VL-mwb/shield-regime
Project-URL: Documentation, https://github.com/VL-mwb/shield-regime#readme
Project-URL: Repository, https://github.com/VL-mwb/shield-regime
Project-URL: Issues, https://github.com/VL-mwb/shield-regime/issues
Author: VL-mwb
License-Expression: MIT
License-File: LICENSE
Keywords: anomaly-detection,finance,market-manipulation,pump-and-dump,quantitative-finance,regtech,wash-trading
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Requires-Dist: numpy>=1.23.0
Requires-Dist: pandas>=1.5.0
Requires-Dist: plotly>=5.10.0
Provides-Extra: data
Requires-Dist: finmind>=1.0.0; extra == 'data'
Requires-Dist: yfinance>=0.2.0; extra == 'data'
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# 🛡️ ShieldRegime: Physics-Inspired Financial Market Anomaly Detection

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://www.python.org/)
[![Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/VL-mwb/shield-regime/blob/main/examples/demo.ipynb)

**ShieldRegime** is an open-source Python library designed to identify market manipulation and suspicious trading activities (such as **Pump-and-Dump schemes** and **Wash Trading**) using **price kinematics**—an innovative, physics-inspired approach to financial time-series analysis.

By modeling price as a physical particle and volume as the underlying force moving it, ShieldRegime computes real-time derivatives (velocity, acceleration, kinetic friction) to flag manipulative trends before they impact market integrity.

> [!TIP]
> **Try it in your browser right now!** Click the **Open In Colab** badge above to launch a fully interactive cloud demo running on real-world GameStop ($GME$) retail-driven mania data.

---

## ⚡ Key Features

*   **📈 Price Kinematics**: Smoothed velocity (1st derivative) and acceleration (2nd derivative) rolling Z-score computations to identify momentum-thrust anomalies.
*   **📊 Volume-Price Profiling**: Advanced indicators (`volume_price_divergence`, `wash_trade_index`) to catch high-volume, narrow-range wash sales.
*   **🚨 Multi-Stage Detectors**: High-fidelity detection models (`PumpDumpDetector`) mapping base, pump, and dump stages.
*   **🎨 Stunning Visualization**: Interactive, presentation-ready Plotly charts highlighting anomaly regions, trigger bounds, and drawdowns.

---

## 🚀 Installation

### 1. Via PyPI (Recommended)
You can install the stable release of ShieldRegime directly from PyPI:
```bash
pip install shield-regime
```

### 2. From Source (For Development)
If you want to contribute, run the tests, or build from source:
```bash
# Clone the official repository
git clone https://github.com/VL-mwb/shield-regime.git
cd shield-regime

# Install in editable mode with development dependencies
pip install -e ".[dev]"
```

---

## 📖 Quick Start & Visualization

The following example downloads historical data for **GameStop (GME)** during the 2021 short-squeeze anomaly, runs the `PumpDumpDetector`, and visualizes the results with Plotly.

```python
import shield_regime as sr
import yfinance as yf

# 1. Download historical market data
df = yf.download("GME", start="2020-09-01", end="2021-04-30")

# Rename columns to match requirements
df_clean = df.copy()
df_clean.index = pd.to_datetime(df.index)
df_clean.columns = [col.lower() for col in df_clean.columns]

# 2. Initialize the detector with custom thresholds
detector = sr.PumpDumpDetector(
    velocity_z_threshold=2.0,      # Trigger on +2.0σ price velocity
    volume_spike_threshold=3.0,    # Require volume > 3x recent average
    dump_drop_threshold=-25.0,     # Flag if price crashes > 25% from peak
    lookback=40,                   # 40-day rolling baseline
)

# 3. Scan the asset
alerts = detector.scan(df_clean, ticker="GME")

for alert in alerts:
    print(f"\n🚨 [DETECTED] {alert}")
    print(f"Details: {alert.details}")
    print(f"Metrics: {alert.metrics}")

# 4. Generate beautiful interactive Plotly chart
fig = sr.plot_alerts(df_clean, alerts, ticker="GME", lookback=40)
if fig:
    # In Jupyter, this displays directly. Or save to HTML:
    fig.write_html("gme_analysis.html")
    print("\n📊 Saved interactive analysis to 'gme_analysis.html'")
```

---

## 🧪 Mathematical Foundation

### Price Velocity ($V$)
The rate of change of price over time, smoothed via Exponential Moving Average (EMA) to filter out high-frequency noise:

$$V_t = \text{EMA}(\Delta P_t, \lambda)$$

### Price Acceleration ($A$)
The second derivative of price, capturing sudden trend thrusts and aggressive manipulation entries:

$$A_t = \text{EMA}(V_t - V_{t-1}, \lambda)$$

### Wash Trade Index ($WTI$)
Under self-dealing conditions, volume explodes while the intraday price range remains narrow. We flag this anomaly using:

$$WTI_t = \frac{\text{Volume Spike Ratio}}{\text{Normalized Intraday Range} + \epsilon}$$

---

## 🛠️ Running Unit Tests

We maintain 100% test coverage for all kinematic formulas, detectors, and visualization routines. Run tests with:

```bash
pytest tests/ -v
```

---

## 🤖 Autonomous AI Agent Integration & Cloud API

ShieldRegime's mathematical engine is designed to be fully compatible with Model Context Protocol (MCP) and modern Agentic AI frameworks (Claude, ChatGPT, AutoGen).

> [!NOTE]
> **Looking for Zero-Config AI Agent Integration?**  
> If you want your AI agents to query ShieldRegime directly without managing local data pipelines, stock scrapers, or Python environments, check out our official **Capafy Managed Agent Skill**.
> 
> The Capafy version provides:
> - **Pre-calibrated parameters** fine-tuned for TWSE (Taiwan Stock Exchange) and US equity market microstructures.
> - **Live market data feeds** integrated automatically.
> - **Plug-and-play MCP / API endpoints** for instant integration into AI trading assistants.

---

## 🗺️ Roadmap & Future Work

ShieldRegime is actively developed to provide regulatory-grade market surveillance.

- [x] **Phase 1: Core Price Kinematics** — Smoothed velocity & acceleration derivatives.
- [x] **Phase 2: Pump-and-Dump Detection** — Dynamic peak-tracking state machines.
- [x] **Phase 3: Wash Trading & Crypto Scans** — Volume-price profiling (`wash_trade_index`) and crypto speculative scans.
- [ ] **Phase 4 (Future HFT Expansion): High-Frequency Spoofing & Layering Detector** — Modeling book pressure imbalances (requires L2/L3 order book tick feeds).

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

