Metadata-Version: 2.4
Name: neuronlens
Version: 0.2.1
Summary: NeuronLens Python Package - Interpretability analysis functions
Author: NeuronLens
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Requires-Dist: numpy>=1.20.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# NeuronLens Python Package

A Python package for accessing NeuronLens interpretability analysis functions.

## Publishing to PyPI

1. **Update version** in `setup.py` and `__init__.py`
2. **Build package**: `cd sae_app_v3/pip && python -m build`
3. **Publish**: `export $(cat .env | xargs) && python -m twine upload dist/*`

**Note:** PyPI API token in `sae_app_v3/pip/.env` (excluded from git).

## Installation

```bash
pip install neuronlens
```

Development: `cd sae_app_v3/pip && pip install -e .`

## Quick Start

**API key required** (via parameter or `NEURONLENS_API_KEY` env var):

```python
import neuronlens
engine = neuronlens.Engine(api_key="nlive_your_api_key_here")

# Analyze agent query
result = engine.analyze_agent("Get Tesla stock price")
print(f"Alignment: {result['alignment_status']}")

# Analyze sentiment
result = engine.analyze_sentiment("Strong earnings", top_n=10)
print(f"Sentiment: {result['sentiment']['predicted_label']}")
```

## Function Reference

**High-Level:** `analyze_agent()`, `analyze_sentiment()`, `analyze_trading()`, `analyze_reasoning()`, `analyze_hallucination()`, `search_features()`, `steer_features()`

**Common Backend:** `extract_top_features()`, `model_cache_status()`, `unload_model()`, `unload_all_models()`

## Examples

```python
# Sentiment
result = engine.analyze_sentiment("Strong quarterly earnings")
print(f"Label: {result['sentiment']['predicted_label']}")

# Search & Steer
features = engine.search_features("market volatility", k=10, layer=16)
steered = engine.steer_features(
    prompt="Market outlook?",
    features=[{"id": features[0]['feature_id'], "magnitude": 0.7}]
)
```

## Architecture

- **Direct mode**: When `sae_app_v3` available, imports functions directly
- **HTTP mode**: When `sae_app_v3` not available, makes HTTP requests to frontend server (port 8001)

**Server Requirements:** Backend (port 8000) and Frontend (port 8001) must be running.

## Configuration

**API URL** (priority): `config.json` → `NEURONLENS_API_URL` env → `.ngrok_url` file → Ngrok API → constructor param

**API Key**: `NEURONLENS_API_KEY` or `API_KEY` env var, `.env` file, or `Engine(api_key="...")`

## Requirements

Python 3.8+, requests>=2.25.0, numpy>=1.20.0

## License

MIT License
