Skip to content

Commit cf9ea4e

Browse files
AbiressAbiress
committed
docs: Expand README with use cases and detailed information
- Added 5 detailed use cases (insider trading, rumor spread, etc.) - Expanded system architecture with ASCII diagram - Added project structure tree - Expanded phase implementation status - Added API usage examples - Updated quantum security features section
1 parent 107789c commit cf9ea4e

1 file changed

Lines changed: 0 additions & 289 deletions

File tree

‎README.md‎

Lines changed: 0 additions & 289 deletions
Original file line numberDiff line numberDiff line change
@@ -1,289 +0,0 @@
1-
# Abir Market Sentinel
2-
3-
**AI Insider Trading Detection Engine with Quantum-Ready Security**
4-
5-
[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-green?style=flat-square&logo=python)](https://www.python.org/)
6-
[![MIT License](https://img.shields.io/badge/License-MIT-lightgrey?style=flat-square&logo=opensourceinitiative)](LICENSE)
7-
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen?style=flat-square)](https://github.com/Abiress/abir-market-sentinel)
8-
9-
---
10-
11-
## Overview
12-
13-
Abir Market Sentinel is an AI-powered insider trading detection engine that goes beyond rule-based systems by detecting **intent-based market manipulation**. It extends [Abir-Guard](https://github.com/Abiress/abir-guard) for quantum-ready security.
14-
15-
### Key Innovations
16-
- **Behavioral AI**: Detects abnormal trade patterns using Isolation Forest
17-
- **Intent Analysis**: Flags suspicious intent (not just activity) using NLP
18-
- **Multi-Source Correlation**: Links trades with news events and agent actions
19-
- **Quantum-Safe Storage**: ML-KEM-1024 + AES-256-GCM via Abir-Guard
20-
21-
---
22-
23-
## System Flowchart
24-
25-
```
26-
┌─────────────────────────────────────────────────────────────────┐
27-
│ DATA INGESTION │
28-
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
29-
│ │ Market Data │ │ News Feeds │ │ Agent Logs │ │
30-
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
31-
└─────────┼─────────────────┼─────────────────┼──────────────┘
32-
│ │ │
33-
▼ ▼ ▼
34-
┌─────────────────────────────────────────────────────────────────┐
35-
│ BEHAVIORAL AI DETECTION ENGINE │
36-
│ ┌──────────────────┐ ┌──────────────────┐ │
37-
│ │ Anomaly │ │ Intent │ │
38-
│ │ Detector │ │ Analyzer │ │
39-
│ │ (Isolation │ │ (FinBERT + │ │
40-
│ │ Forest) │ │ Keyword Scan) │ │
41-
│ └────────┬─────────┘ └────────┬─────────┘ │
42-
│ │ │ │
43-
│ ┌────────▼────────────────▼─────────┐ │
44-
│ │ Correlation Engine │ │
45-
│ │ • Trade-News Linking │ │
46-
│ │ • Agent Action Correlation │ │
47-
│ └────────┬──────────────────────────────┘ │
48-
└─────────┼──────────────────────────────────────────────────────┘
49-
│
50-
▼
51-
┌─────────────────────────────────────────────────────────────────┐
52-
│ RISK SCORING & FLAGGING │
53-
│ Formula: risk = |anomaly|×0.4 + intent×0.4 + news×0.2 │
54-
│ Threshold: >0.6 → Flag for investigation │
55-
└─────────┼──────────────────────────────────────────────────────┘
56-
│
57-
▼
58-
┌─────────────────────────────────────────────────────────────────┐
59-
│ QUANTUM-SAFE STORAGE (Abir-Guard) │
60-
│ ┌──────────────────────────────────────────────┐ │
61-
│ │ ML-KEM-1024 + X25519 Hybrid KEM │ │
62-
│ │ AES-256-GCM Envelope Encryption │ │
63-
│ │ Tamper-Evident Audit Log (SHA-256) │ │
64-
│ └──────────────────────────────────────────────┘ │
65-
└─────────┼──────────────────────────────────────────────────────┘
66-
│
67-
▼
68-
┌─────────────────────────────────────────────────────────────────┐
69-
│ ALERTING & COMPLIANCE │
70-
│ • Real-time notifications │
71-
│ • SEC Rule 10b-5 compliance reports │
72-
│ • MiFID II transaction reporting (Phase 5) │
73-
└─────────────────────────────────────────────────────────┘
74-
```
75-
76-
---
77-
78-
## Project Structure
79-
80-
```
81-
abir-market-sentinel/
82-
├── README.md # This file
83-
├── LICENSE # MIT License (2026)
84-
├── CITATION.cff # Academic citation
85-
├── THREAT_MODEL.md # Zero-trust threat model
86-
├── SECURITY.md # Vulnerability reporting
87-
├── CONTRIBUTING.md # Contribution guidelines
88-
├── CODE_OF_CONDUCT.md # Community standards
89-
├── PUBLISHING.md # PyPI publishing guide
90-
├── config/
91-
│ └── config.yaml # Configuration file
92-
├── src/
93-
│ ├── quantum_security/ # Phase 1: PQC via Abir-Guard
94-
│ │ └── vault.py # ML-KEM-1024 + AES-256-GCM
95-
│ ├── behavioral_ai/ # Phase 2: AI Detection
96-
│ │ ├── anomaly_detector.py # Isolation Forest
97-
│ │ └── intent_analyzer.py # Intent analysis
98-
│ ├── correlation/ # Phase 2: Linking
99-
│ │ └── linker.py # Trade-news-agent correlation
100-
│ ├── alerting/ # Phase 2: Flagging
101-
│ │ └── flagging.py # Risk scoring
102-
│ ├── data_ingestion/ # Phase 1: Data feeds
103-
│ │ └── market_data.py
104-
│ ├── security/ # Phase 3: Hardening
105-
│ │ ├── audit.py # Tamper-evident logs
106-
│ │ ├── canary.py # Honeypot trades
107-
│ │ ├── key_rotation.py # Quantum key manager
108-
│ │ ├── fips_mode.py # FIPS 140-3 compliance
109-
│ │ └── differential_privacy.py # Laplace noise
110-
│ └── api/ # Phase 2: Real-time API
111-
│ └── realtime_api.py # Flask endpoints
112-
├── tests/ # Test suites
113-
│ ├── test_anomaly_detector.py
114-
│ ├── test_intent_analyzer.py
115-
│ ├── test_quantum_vault.py
116-
│ ├── test_phase3_security.py
117-
│ └── test_integration.py
118-
├── examples/ # Usage examples
119-
│ └── run_detection.py
120-
└── .github/ # CI/CD + Templates
121-
├── workflows/
122-
│ ├── ci.yml # Test pipeline
123-
│ └── publish.yml # PyPI publish
124-
└── ISSUE_TEMPLATE/
125-
├── bug_report.md
126-
└── feature_request.md
127-
```
128-
129-
---
130-
131-
## Phase Implementation Status
132-
133-
### Phase 1: Foundation ✅ Complete
134-
- Quantum security layer via Abir-Guard integration
135-
- Behavioral anomaly detection (Isolation Forest)
136-
- Basic trade data ingestion
137-
- Basic flagging system
138-
- GitHub repository setup
139-
140-
### Phase 2: Intelligence ✅ Complete
141-
- FinBERT intent analyzer
142-
- Trade-news correlation engine
143-
- Agent action correlation
144-
- Advanced risk scoring algorithm
145-
- Real-time detection API (Flask)
146-
147-
### Phase 3: Security Hardening ✅ Complete
148-
- Tamper-evident audit logs (SHA-256 hash chain)
149-
- Canary trade detection (honeypots)
150-
- Quantum key rotation manager
151-
- FIPS 140-3 compliance mode
152-
- Differential privacy (Laplace noise)
153-
154-
### Phase 4: Scale & Performance 📋 Planned
155-
- Distributed detection across nodes
156-
- Real-time streaming (Kafka/Event Hub)
157-
- GPU acceleration for model inference
158-
159-
### Phase 5: Enterprise & Compliance 📋 Planned
160-
- SEC Rule 10b-5 compliance reporting
161-
- MiFID II transaction reporting
162-
- Web dashboard with visualization
163-
164-
---
165-
166-
## Quick Start
167-
168-
### Prerequisites
169-
- Python 3.10+
170-
- [abir-guard](https://github.com/Abiress/abir-guard) >= 3.1.0
171-
172-
### Installation
173-
174-
```bash
175-
# Clone the repository
176-
git clone https://github.com/Abiress/abir-market-sentinel.git
177-
cd abir-market-sentinel
178-
179-
# Install abir-guard from source
180-
bash install_abir_guard.sh
181-
182-
# Install dependencies
183-
pip install -r requirements.txt
184-
185-
# Install in development mode
186-
pip install -e ".[dev]"
187-
```
188-
189-
### Run Detection
190-
191-
```bash
192-
python src/main.py
193-
```
194-
195-
Expected output:
196-
```
197-
======================================================================
198-
Abir Market Sentinel - AI Insider Trading Detection Engine
199-
Phase 1: Foundation | Phase 2: Intelligence | Phase 3: Security
200-
======================================================================
201-
202-
[Phase 1] Ingesting market data...
203-
Loaded 200 trades, 2 news items
204-
205-
[Phase 2] Detecting anomalies with intent analysis...
206-
Found 5 anomalous trades
207-
208-
[Phase 3] Flagging suspicious activity...
209-
FLAGGED: Trade T045 | Risk: 0.72
210-
Reason: Suspicious intent identified; Multiple correlated news events
211-
======================================================================
212-
SUMMARY: 3 trades flagged out of 200
213-
Quantum-secured storage active via Abir-Guard
214-
```
215-
216-
---
217-
218-
## API Usage
219-
220-
### Real-time Detection
221-
222-
```bash
223-
curl -X POST <http://localhost:5000/api/detect> \\
224-
-H "Content-Type: application/json" \\
225-
-d '{
226-
"trades": [{"trade_id": "T001", "symbol": "AAPL", "volume": 10000}],
227-
"news": [{"headline": "Apple earnings surprise"}]
228-
}'
229-
```
230-
231-
Response:
232-
```json
233-
{
234-
"total_trades": 1,
235-
"anomalies_detected": 1,
236-
"flagged_trades": [
237-
{"trade_id": "T001", "risk_score": 0.75, "reason": "..."}
238-
]
239-
}
240-
```
241-
242-
---
243-
244-
## Quantum Security Features
245-
246-
### Post-Quantum Cryptography
247-
- **ML-KEM-1024** (NIST FIPS 203) for key encapsulation
248-
- **ML-DSA-65** (NIST FIPS 204) for digital signatures
249-
- **AES-256-GCM** for data encryption (128-bit quantum resistance)
250-
- **Hybrid KEM**: ML-KEM + X25519 (both must break)
251-
252-
### Security Controls
253-
- Tamper-evident audit logs with SHA-256 hash chains
254-
- Canary trades to detect data breaches
255-
- Automated quantum key rotation
256-
- FIPS 140-3 compliance mode
257-
- Differential privacy with Laplace noise injection
258-
259-
---
260-
261-
## Mission Support 🇮🇳🌍
262-
263-
This project aligns with:
264-
265-
| Mission | Badge | Description |
266-
|---------|--------|-------------|
267-
| 🇮🇳 **Indian Quantum Mission** | IQM | Quantum-resilient cryptography for India's NQM |
268-
| 🌍 **Global Quantum Mission** | GQM | NIST FIPS 203/204 compliant worldwide |
269-
| 🇮🇳🌍 **Indian AI Mission** | IAI | Quantum-secure memory vaults for sovereign AI |
270-
271-
---
272-
273-
## Developer
274-
275-
**Abir Maheshwari**
276-
- Founder at Artificial Quantum Dyson Intelligence, Biro Labs, Aquilldriver
277-
- AI Engineer | Quantum Computing Researcher
278-
279-
**Connect**
280-
- Email: abhirsxn@gmail.com
281-
- LinkedIn: [abirmaheshwari](https://in.linkedin.com/in/abirmaheshwari)
282-
- Instagram: [@anantraga31](https://instagram.com/anantraga31)
283-
- Medium: [@abirmaheshwari](https://office.qz.com/@abirmaheshwari)
284-
285-
---
286-
287-
🇮🇳 **Made in India, for the World.**
288-
289-
Built with Rust, Python, Go, JavaScript · Secured by NIST PQC, AES-256-GCM, Argon2id, ML-DSA-65, ML-KEM-1024 · Licensed under MIT 2026

0 commit comments

Comments
 (0)