Metadata-Version: 2.1
Name: lm-monitor
Version: 0.1.0
Summary: Callable algorithm primitives for cyberspace security risk monitoring.
Author: LM Monitor contributors
License: MIT License
        
        Copyright (c) 2026 LM Monitor contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
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'

# LM Monitor

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
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.
