Metadata-Version: 2.4
Name: character-lens
Version: 0.2.0.dev0
Summary: Compute, inspect, and steer with persona/emotion vectors in language models
Author: Zafir Stojanovski
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: accelerate>=1.13.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: torch<=2.6.0
Requires-Dist: tqdm
Requires-Dist: transformers<5,>=4.51.0
Description-Content-Type: text/markdown

# Character Lens

A Python library for computing, inspecting, and steering with persona/emotion vectors in language models.

## Install

```bash
pip install character-lens
```

Or for development:

```bash
uv sync --all-extras
```

## Overview

Character Lens extracts emotion/persona vectors from language model activations using a single-pole methodology: each trait's vector is the mean activation for that trait minus the global mean across all traits. These vectors can then be used for:

- **Inspection**: Project token-level activations onto persona vectors to see which concepts are active at each position
- **Steering**: Add persona vectors to residual stream activations during generation to influence model behavior

First-class model support: **OLMo 3 7B**

## Quick Start

```python
from character_lens import ActivationSteerer, extract_hidden_states
```

See [docs/ROADMAP.md](docs/ROADMAP.md) for the full development plan.

## Development

```bash
# Install dependencies
uv sync --all-extras

# Run tests
uv run pytest tests/ -v --tb=short

# Run linter
uv run pre-commit run --all-files
```

## Prior Work

The multilingual persona vectors research (v0.1.0) is archived under the `v0.1.0` tag.
