Metadata-Version: 2.4
Name: vllm-hust-clm-lifecycle
Version: 0.1.0
Summary: CLM: context-lifecycle management perception plugin for vLLM-HUST (request-lifecycle event sink)
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: ruff>=0.12; extra == "test"
Dynamic: license-file

# vllm-hust-clm-lifecycle

CLM: Context Lifecycle Management perception plugin for vLLM-HUST.

Consumes the scheduler-level request lifecycle events exposed by the host
(`RequestFinished` / `RequestPreempted`, contract `vllm.request-lifecycle.v1`)
and reports session-level KV growth to an out-of-tree CLM controller, which
decides when to compact a long conversation.

Bundle ID: `org.vllm-hust.clm-lifecycle` (Extension Bundle v1, schema 1.0)

## What it does

- **Lifecycle-sink component** (contract `vllm.request-lifecycle.v1`,
  execution plane `scheduler`): registers a sink on the engine's default-off
  typed `EventBus`. When a request finishes or is preempted, the sink
  attributes the KV footprint to a session (engine-side `session_id`, or a
  `__default__` bucket) and reports growth to a controller endpoint.
- **Default-off, zero-overhead when absent**: the events only exist on hosts
  that carry the request-lifecycle hook; without them `register()` skips
  gracefully. Reports never block serving (failures are swallowed).

## Install

```bash
pip install vllm-hust-clm-lifecycle
```

## Enable

Requires a host that exposes `vllm.v1.events` (vllm-hust with the
request-lifecycle hook). Enable via plugin loading:

```bash
# runtime registration (vllm.general_plugins)
export VLLM_PLUGINS=ascend,clm_lifecycle
# observation / static discovery (vllm.extension_bundles)
vllm-hust-ext extension inspect org.vllm-hust.clm-lifecycle
```

### Environment

| Variable | Default | Meaning |
|---|---|---|
| `VLLM_CLM_CONTROLLER` | *(empty)* | HTTP endpoint receiving JSON reports (`{"session_id","event","kv_blocks","total_tokens"}`). Empty = observation-only (no reports sent). |
| `VLLM_CLM_REPORT_BLOCKS` | `128` | KV-block accumulation threshold per session before a report fires. |
| `VLLM_CLM_REPORT_INTERVAL` | `5.0` | Minimum seconds between two reports of the same session. |

Parse failures on these variables fall back to defaults (empty values are
tolerated).

## Disable

```bash
unset VLLM_CLM_CONTROLLER VLLM_CLM_REPORT_BLOCKS VLLM_CLM_REPORT_INTERVAL
# or simply do not list clm_lifecycle in VLLM_PLUGINS
pip uninstall vllm-hust-clm-lifecycle
```

## Development

```bash
pip install -e ".[test]"
python -m pytest tests/
ruff check .
```

`tests/conftest.py` stubs `vllm.v1.events` before the plugin is imported, so
the test suite runs without a vLLM install.

## License

Apache-2.0
