Metadata-Version: 2.4
Name: lm-monitor
Version: 0.1.2
Summary: Callable algorithm primitives for cyberspace security risk monitoring.
Author: LM Monitor contributors
License-Expression: MIT
Project-URL: Repository, https://github.com/Ferry-Li/lm_monitor
Project-URL: Issues, https://github.com/Ferry-Li/lm_monitor/issues
Keywords: cybersecurity,model-monitoring,knowledge-distillation,open-set
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0
Provides-Extra: examples
Requires-Dist: transformers>=4.40; extra == "examples"
Requires-Dist: torchvision>=0.15; extra == "examples"
Requires-Dist: pillow>=9.0; extra == "examples"
Dynamic: license-file

# LM Monitor

<p align="center">
  <img src="https://raw.githubusercontent.com/Ferry-Li/lm_monitor/main/ict.png" alt="Institute of Computing Technology, Chinese Academy of Sciences (ICT, CAS)" height="48">
  &nbsp;&nbsp;&nbsp;
  <img src="https://raw.githubusercontent.com/Ferry-Li/lm_monitor/main/baai.png" alt="Beijing Academy of Artificial Intelligence (BAAI)" height="48">
</p>

<p align="center">
  <strong>Jointly released by the Institute of Computing Technology, Chinese Academy of Sciences (ICT, CAS), and the Beijing Academy of Artificial Intelligence (BAAI).</strong>
</p>

LM Monitor is a lightweight, composable Python package for **cyberspace
security content monitoring**. It provides training losses, optimizers, and
inference signals that can be inserted into an existing classifier,
vision-language monitor, or safety evaluation service. It does not make an
allow/block decision by itself.

## Security-monitoring motivation

The effective domain of a monitor is the range of content and distributions it
can identify, score, and route reliably. Deployment changes it in three ways:

- **Knowledge gaps:** terminology and visual evidence differ between fraud,
  abuse, malware, privacy, and emerging-event verticals. ABKD, TuckA, and
  Focal-SAM transfer or consolidate domain knowledge at training time.
- **Distribution shift:** rare incidents are long-tailed and new traffic can
  contain unknown classes. DirMixE provides a multi-expert long-tail objective;
  OpenworldAUC separates known-risk recognition from unknown-risk discovery.
- **Domain collapse and attacks:** coverage can silently degrade, or a
  generative service can contain a black-box backdoor. InterNeg exposes a
  cross-modal drift signal; BlackMirror exposes trigger and
  instruction-response signals for investigation.

The operational loop is:

```text
domain data → knowledge fusion → adaptive evaluation → drift/backdoor signal
           → alert + human review → retraining or compensation
```

## Installation and dependencies

The core package depends only on PyTorch:

```bash
pip install lm-monitor
```

The package never downloads models, datasets, checkpoints, or credentials.
Examples that load official HuggingFace/torchvision models require:

```bash
pip install -r requirements-examples.txt
# or: pip install lm-monitor[examples]
```

For a source checkout:

```bash
pip install -e .
```

## QuickStart

```python
import torch
from lm_monitor import abkd_loss

# Both tensors are float logits [batch, sequence, vocabulary].
student = torch.randn(2, 16, 128, requires_grad=True)
teacher = torch.randn(2, 16, 128)
loss = abkd_loss(student, teacher)
loss.backward()
print(float(loss))
```

## Public API

All functions are re-exported from `lm_monitor` and `lm_monitor.algorithms`.
Callers load models and control device, precision, batching, and data policy.

### `abkd_loss`

Alpha-beta divergence knowledge-distillation loss for transferring broad risk
domain knowledge into a smaller monitor.

```python
loss = abkd_loss(student_logits, teacher_logits, labels=None,
                 temperature=1.0, alpha=0.5, beta=0.5, kd_ratio=1.0)
```

`student_logits` and `teacher_logits` are float `[B,L,V]` or `[B,V]` tensors
with identical shapes. Optional long `labels` match the leading dimensions;
`-100` is ignored. The return value is a differentiable scalar. Compatible
models are decoder-only HuggingFace causal LMs with aligned vocabularies;
validated models include Qwen2.5-1.5B-Instruct, Qwen2.5-0.5B, and
Qwen2.5-0.5B-Instruct.

### `FocalSAM` and `focal_sam_step`

`FocalSAM` is a sharpness-aware optimizer and `focal_sam_step` performs one
classifier update.

```python
optimizer = FocalSAM(model.parameters(), lr=1e-5, rho=0.05)
result = focal_sam_step(model, optimizer, images, labels)
```

`images` are model-specific float inputs (usually `[B,3,H,W]`) and `labels`
are long `[B]`. The result contains scalar `loss` and `[B,C]` `logits`.
Validated models include native ResNet32, torchvision ResNet18, and ViT-B/16.

### `dirmixe_loss`

Aggregate and per-expert cross-entropy for long-tail recognition.

```python
loss = dirmixe_loss(expert_logits, labels, class_counts=None)
```

`expert_logits` is float `[E,B,C]` or `[B,E,C]`; `labels` is long `[B]`;
optional `class_counts` is `[C]`. Returns a scalar. Validated with ResNet-50
and ViT-B/16 outputs.

### `tucka_loss`

Supervised loss for a TuckA adapter/classification head:

```python
loss = tucka_loss(logits, labels)
```

`logits` is float `[B,C]`, `labels` is long `[B]`, and the return is scalar.
The validated checkpoint shape is ViT-B/16-compatible.

### `openworldauc_loss`

Pairwise surrogate for known-versus-unknown/open-world scores:

```python
loss = openworldauc_loss(scores, known_mask)
```

`scores` is float `[K]`; `known_mask` is bool/0-1 `[K]` and must contain both
classes. Returns a differentiable scalar. Validated with CLIP ViT-B/16 and
ViT-L/14 features.

### `interneg_score`

Cross-modal distance-consistency OOD signal:

```python
score = interneg_score(image_features, id_text_features,
                       negative_text_features, temperature=1.0)
```

`image_features` is `[D]` or `[B,D]`; each text tensor is `[N,D]`; all are
float and share `D`. Returns a scalar or `[B]`; higher means negative text is
more competitive. Validated with CLIP ViT-B/16 and ViT-L/14.

### `keyword_attack_score` and `check_prompt_trigger`

Model-independent text-side signals for a BlackMirror investigation:

```python
signal = keyword_attack_score(prompt, trigger, target=None)
flag = check_prompt_trigger(prompt, trigger)
```

Both inputs are strings. The first returns `triggered`, `target`, `prompt`, and
numeric `score`; the second returns `bool`. Full detection additionally loads
Stable Diffusion, a Qwen vision-language model, and a Qwen language model.

## Package layout

```text
lm_monitor/                 # installable public package
  __init__.py               # stable exports and version
  algorithms/               # one lightweight module per algorithm
  assets/                   # packaged organization logos
examples/                   # complete two-step/mini-batch examples
tests/                      # dependency-light API tests
requirements-examples.txt   # optional model/example dependencies
```

Research repositories, benchmark datasets, checkpoints, and full lifecycle
scripts remain outside this PyPI distribution. Use the source repository for
paper-scale experiments; use this package inside an existing safety monitor.
