Update README.md

README.md

@@ -1,3 +1,114 @@
----
-license: apache-2.0
----
+---
+language: en
+tags:
+  - multiple-instance-learning
+  - fraud-detection
+  - risk-assessment
+  - anomaly-detection
+  - graph-transformer
+  - interpretability
+license: apache-2.0
+library_name: pytorch
+---
+
+# AC-MIL
+
+AC-MIL (Action-Aware Capsule Multiple Instance Learning for Live-Streaming Room Risk Assessment) is a weakly supervised model for **room-level risk assessment** in live-streaming platforms. It is designed for scenarios where only **binary room-level labels** are available, while risk evidence is often **sparse, localized, and manifested through coordinated behaviors** across users and time.
+
+AC-MIL formulates each live room as a **Multiple Instance Learning (MIL)** bag, where each instance is a **user–timeslot capsule**—a short action subsequence performed by a particular user within a fixed time window. The model produces:
+- a **room-level risk score**, indicating the probability that the room is risky, and
+- **capsule-level attributions**, providing interpretable evidence by highlighting suspicious user–time segments that contribute most to the prediction.
+
+
+---
+
+## Key idea 
+
+Given a room’s action stream, we construct a 2D grid of capsules over **users × timeslots**. Each capsule summarizes localized behavioral patterns within a specific user–time window. AC-MIL then models:
+- **temporal dynamics**: how users’ behaviors evolve over time,
+- **cross-user dependencies**: interactions between viewers and the streamer, as well as coordination patterns among viewers,
+- **multi-level signals**: evidence captured at the action, capsule, user, and timeslot levels,
+and fuses these signals to produce robust room-level risk predictions.
+
+---
+
+## Architecture overview
+
+AC-MIL follows a hierarchical serial–parallel design:
+
+<p align="center">
+    <img src="https://cdn-uploads.huggingface.co/production/uploads/671b2ede3fd1d03dc687c641/Vry7GWMLjGKLsCBqq5B6g.png" width="80%"/>
+<p>
+
+
+1. **Action Field Encoder**
+   - Encodes the full action sequence with a Transformer to produce contextualized action embeddings.
+   - Produces an action-level room representation via a learnable `[CLS]` token.
+
+2. **Capsule Constructor**
+   - Partitions actions into **user–timeslot capsules**.
+   - Encodes each capsule with an LSTM (final hidden state as capsule embedding).
+
+3. **Relational Capsule Reasoner**
+   - Builds an **adaptive relation-aware graph** over capsules using emantic similarity and relation masks.
+   - Runs a **graph-aware Transformer** to refine capsule embeddings.
+   - Provides **capsule-level interpretability** via `[CLS] → capsule` attention.
+
+4. **Dual-View Integrator**
+   - **User-view**: GRU over each user’s capsule sequence and attention pooling across users.
+   - **Timeslot-view**: attention pooling within each timeslot and GRU across timeslots.
+
+5. **Cross-Level Risk Decoder**
+   - Learns gates over multi-level room representations.
+   - Produces the final room embedding and risk score.
+
+
+---
+
+
+## Input / output specification
+
+### Input (conceptual)
+
+Each dataset sample corresponds to a live room `room_id` with a binary room-level label `room_label ∈ {0,1,2,3}` (>0, risky).  
+A room is represented as an **action sequence** `patch_list = {α_i}` ordered by tuple (user, time), where each action follows the paper’s definition:
+`α = (u, t, a, x)` (user, timestamp, action type, and optional textual/multimodal feature).  
+
+In our May/June datasets, each action record is stored with the following fields:
+
+- `u_idx` (int): user index within the room, used to build the `users × timeslots` grid (e.g., 0 = streamer, 1..U = selected viewers).
+- `global_user_idx` (int/str): global user identifier across the whole dataset (before remapping to `u_idx`).
+- `timestamp` (int/float): the action timestamp`t`. In the formulation, timestamps are within a window `[0, T]` after the room starts.  
+- `t` (int): timeslot index derived by discretizing `timestamp` into fixed-length windows. This is the column index when constructing the `users × timeslots` capsule grid.  
+- `l` (int): role indicator (recommended convention: `0 = viewer`, `1 = streamer`).  
+- `action_id` (int): the action type id `a` (e.g., enter, comment, like, gift, share; streamer-side actions may include stream start, ASR text, OCR text, etc.).  
+- `action_desc` (str / null): raw textual content associated with the action (e.g., comment text, ASR transcript, OCR text).
+- `action_vec` (numpy): pre-encoded feature vector for `action_desc`. 
+
+
+Example (JSONL-like):
+```json
+{
+  "room_id": "1",
+  "room_label": "2",
+  "patch_list": [
+    (u_idx, t, l, action_id, action_vec, timestamp, action_desc, user_id),
+    (0, 1, 0, 5, [0.0, 0.3, ...], 4, "主播口播:...", 5415431),
+    ...
+  ]
+}
+```
+
+---
+
+## Intended use
+
+**Primary use cases**
+- Early detection of risky rooms (fraud, collusion, policy-violating coordinated behaviors)
+- Evidence-based moderation: highlight localized suspicious segments (user��time capsules)
+
+**Out of scope**
+- Identifying or tracking specific individuals
+- Any use that violates privacy laws, platform policies, or user consent requirements
+
+---