update readme

Author: nekw

README.md

@@ -2,43 +2,72 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Python 3.11](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
 
-# AI-Driven Trade Surveillance Orchestrator
+# AI-Driven Trade Surveillance Orchestrator 🚦
 
-A small demo is designed to illustrate **AI orchestration** and **governance patterns** in **trade surveillance**.
+**TL;DR:** A compact example demonstrating AI orchestration, governance, and anomaly detection for trade surveillance. Use the CLI or the Streamlit UI to run workflows that parse trades, detect anomalies (rule-based or ML), produce compliance-style summaries, and capture an audit trail.
 
-This project simulates a **trade surveillance workflow**:
+Keywords: **trade surveillance**, **anomaly detection**, **AI orchestration**, **governance**, **IsolationForest**, **Streamlit**
 
-1. Parse a set of trades
-2. Run simple anomaly detection rules
-3. Generate a compliance-style summary
-4. Capture an audit trail with risk levels
+**Docs:** Additional documentation is available in the `docs/` folder — see [AI governance](docs/ai_governance.md), [Model card (ML detector)](docs/model_card_ml_anomaly_detector.md), [Roadmap](docs/roadmap.md), and screenshots in [docs/images](docs/images/).
 
-The code is intentionally compact but structured like a real enterprise component.
+<table>
+  <tr>
+    <td align="center" valign="top">
+      <img src="docs/images/ui_ml.gif" alt="ML workflow demo" width="420" />
+      <br>
+      <strong>ML workflow</strong>
+    </td>
+    <td align="center" valign="top">
+      <img src="docs/images/ui_rule_based.gif" alt="Rule-based workflow demo" width="420" />
+      <br>
+      <strong>Rule-based workflow</strong>
+    </td>
+  </tr>
+</table>
+
+> **Note:** Individual screenshots (PNG) are available in `docs/images/` for full-resolution stills and reference.
+
+---
+
+## Table of contents 📚
 
-## Features
+- [Why this project](#why-this-project-%EF%B8%8F)
+- [Features](#features)
+- [Quick start](#quick-start-rocket)
+  - [Install](#install)
+  - [Run example (CLI)](#run-example-cli)
+  - [Run UI (Streamlit)](#run-ui-streamlit)
+- [Quick demo — expected output](#quick-demo--expected-output)
+- [Files of interest](#files-of-interest)
+- [Testing & CI](#testing--ci)
+- [Contributing & Support](#contributing--support)
+- [License](#license)
 
-- **Workflow as config**
-  - Define surveillance workflows in YAML (`workflows/trade_surveillance.yml`).
+---
 
-- **Tool registry**
-  - Pluggable tools in `orchestrator/tools.py`:
-    - `parse_trades`: parses JSON list of trades
-    - `anomaly_detector`: rule-based checks (large trades, rapid flips, wash-like patterns)
-    - `ml_anomaly_detector`: ML-based detector (IsolationForest) — optional
-    - `summarizer`: produces a compliance-style narrative
+## Why this project ⚖️
 
-- **Task routing & orchestration**
-  - `orchestrator/workflow_runner.py` runs configured steps and tracks an audit log.
+This repository is a focused demo for engineers and researchers who want to explore how AI components can be orchestrated and governed in a trade surveillance setting. It balances realistic structure (tool registry, workflow config, audit logs) with lightweight code that’s easy to extend.
 
-- **Governance & audit**
-  - `AuditLog` and `AuditEntry` in `orchestrator/governance.py` capture step inputs/outputs and risk levels.
+---
 
-- **UI**
-  - Streamlit app (`ui/app.py`) to paste/edit trade JSON, choose detection method (rule-based or ML), run the workflow, and inspect results.
+## Features ✨
 
-## Getting started
+- Workflow-as-config: define surveillance flows in YAML (`workflows/trade_surveillance.yml`).
+- Tool registry: modular tools in `orchestrator/tools.py`:
+  - `parse_trades` — parse JSON trade lists
+  - `anomaly_detector` — rule-based heuristics (large trades, flips, wash-like patterns)
+  - `ml_anomaly_detector` — optional IsolationForest-based detector
+  - `summarizer` — compliance-style narrative
+- Orchestration: `orchestrator/workflow_runner.py` executes steps and builds an audit log.
+- Governance & audit: `AuditLog` and `AuditEntry` capture inputs/outputs and risk levels (`orchestrator/governance.py`).
+- UI: Streamlit app (`ui/app.py`) for interactive exploration and parameter tuning.
 
-### 1. Setup environment
+---
+
+## Quick start 🚀
+
+### Install
 
 ```bash
 python -m venv .venv
@@ -50,114 +79,78 @@ source .venv/bin/activate
 pip install -r requirements.txt
 ```
 
-### 2. Run CLI example
+Tip: use `python -m pip install -e .` if you add packaging later and want editable installs.
+
+### Run example (CLI)
 
 ```bash
 python -m examples.run_workflow
 ```
 
-Expected output:
-- A final textual summary
-- A list of detected anomalies
-- Compact audit log lines
-
-### 3. Run Streamlit UI
+### Run UI (Streamlit)
 
 ```bash
 python -m streamlit run ui/app.py
 ```
 
-Then open the URL printed in the terminal (usually http://localhost:8501). In the UI you can:
-- Inspect and modify `examples/sample_trades.json`
-- Choose detection method (`Rule-based` or `ML (IsolationForest)`) and tune parameters (`threshold` or `contamination`)
-- Set summary max length and view the audit log
+Open the URL printed in the terminal (usually http://localhost:8501).
 
-Screenshots of the UI (real captures):
+---
 
-<table>
-  <thead>
-    <tr>
-      <th align="center" valign="top"><strong>ML</strong></th>
-      <th align="center" valign="top"><strong>Rule-based</strong></th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td align="center" valign="top">
-        <em>Initial</em>
-        <br>
-        <img src="docs/images/ui_ml_1_initial.png" alt="ML initial" width="420"/>
-      </td>
-      <td align="center" valign="top">
-        <em>Initial</em>
-        <br>
-        <img src="docs/images/ui_rule_based_1_initial.png" alt="Rule-based initial" width="420"/>
-      </td>
-    </tr>
-    <tr>
-      <td align="center" valign="top">
-        <em>Summary</em>
-        <br>
-        <img src="docs/images/ui_ml_2_summary.png" alt="ML summary" width="420"/>
-      </td>
-      <td align="center" valign="top">
-        <em>Summary</em>
-        <br>
-        <img src="docs/images/ui_rule_based_2_summary.png" alt="Rule-based summary" width="420"/>
-      </td>
-    </tr>
-    <tr>
-      <td align="center" valign="top">
-        <em>Anomaly (expanded)</em>
-        <br>
-        <img src="docs/images/ui_ml_3_anomaly_expanded.png" alt="ML anomaly expanded" width="420"/>
-      </td>
-      <td align="center" valign="top">
-        <em>Anomaly (expanded)</em>
-        <br>
-        <img src="docs/images/ui_rule_based_3_anomaly_expanded.png" alt="Rule-based anomaly expanded" width="420">
-      </td>
-    </tr>
-    <tr>
-      <td align="center" valign="top">
-        <em>Audit</em>
-        <br>
-        <img src="docs/images/ui_ml_4_audit.png" alt="ML audit" width="420"/>
-      </td>
-      <td align="center" valign="top">
-        <em>Audit</em>
-        <br>
-        <img src="docs/images/ui_rule_based_4_audit.png" alt="Rule-based audit" width="420"/>
-      </td>
-    </tr>
-  </tbody>
-</table>
+## Quick demo — expected output 🧾
+
+CLI output shows a short summary, detected anomalies, and a compact audit log. Example snippet:
+
+```text
+Summary: 2 potential anomalies detected, highest risk: high
+Anomalies:
+  - trade_id: 12345 — large size (>$1m)
+  - trade_id: 12348 — rapid flip pattern
+AuditLog:
+  [01:23:45] parse_trades -> 100 trades
+  [01:23:45] anomaly_detector -> 2 anomalies (risk=high)
+  [01:23:46] summarizer -> 1 summary
+```
+
+Use `examples/sample_trades.json` as a starting dataset.
 
-## Files of interest
+---
 
-- `orchestrator/tools.py` — parsing, rule-based anomaly detection, ML detector, summarizer, tool registry
-- `orchestrator/workflow_runner.py` — runs steps and builds the audit log
-- `orchestrator/governance.py` — audit models and risk classification
-- `workflows/trade_surveillance.yml` — example workflow configuration
-- `ui/app.py` — Streamlit UI
+## Files of interest 📂
+
+- `orchestrator/tools.py` — parsing, rule-based and ML detectors, summarizer
+- `orchestrator/workflow_runner.py` — workflow execution and audit log
+- `orchestrator/governance.py` — audit models, risk classification
+- `workflows/trade_surveillance.yml` — an example workflow configuration
+- `ui/app.py` — Streamlit UI for interactive runs
 - `docs/model_card_ml_anomaly_detector.md` — model card for the ML detector
-- `examples/evaluate_ml_detector.py` — quick runner for the ML detector
+- `examples/` — quick scripts (`run_workflow`, `evaluate_ml_detector`)
 - `tests/` — unit and integration tests
 
-## Testing & CI
+---
+
+## Testing & CI ✅
 
-Run tests locally with:
+Run tests locally:
 
 ```bash
 python -m pytest -q
 ```
 
-A CI workflow is included at `.github/workflows/ci.yml` to run tests on push/PR.
+CI runs automatically at `.github/workflows/ci.yml` on push and PRs.
+
+---
+
+## Contributing & Support 🤝
+
+- See `CONTRIBUTING.md` for contribution guidelines and how to run tests.
+- File issues or feature requests at the repo Issues page.
+- For quick questions, open an issue and tag maintainers.
 
-## Contributing
+---
 
-See `CONTRIBUTING.md` for guidelines on contributing, testing, and submitting PRs.
+## License 📜
 
-## License
+MIT — see `LICENSE` for details.
 
-This project is licensed under the MIT License — see `LICENSE` for details.
+---