neuronlens 0.2.4

NeuronLens Python Package - Interpretability analysis functions

NeuronLens Python Package

A Python package for accessing NeuronLens interpretability analysis functions.

Server Deployment (New Machine)

Setup: Clone sae_app_v5, set API_KEY in environment, run ./start_frontend_backend.sh. Override API URL: NEURONLENS_API_URL env var or pip/config.json. See Developer Guide.

Installation

pip install neuronlens

For development (editable install):

cd sae_app_v5/pip
pip install -e .

Publishing to PyPI

To publish a new version to PyPI:

1. Update version in setup.py and __init__.py

2. Build package:

   cd sae_app_v5/pip
   python -m build
   

3. Publish to PyPI (using token from .env file):

   # Load PyPI credentials from .env (not committed to git)
   export $(cat .env | xargs)
   python -m twine upload dist/*
   

Note: PyPI API token is stored in sae_app_v5/pip/.env (excluded from git via .gitignore).

Quick Start

With API Key (Required)

Note: API key is required for all functions. You must provide it either via parameter or environment variable.

import neuronlens

# Initialize with API key
NEURONLENS_API_KEY = "nlive_your_api_key_here"
engine = neuronlens.Engine(api_key=NEURONLENS_API_KEY)

# Optionally specify frontend API URL (defaults to https://api.neuronlens.com)
# engine = neuronlens.Engine(api_key=NEURONLENS_API_KEY, api_url="https://api.neuronlens.com")

# Use functions directly
result = engine.analyze_agent("Get Tesla stock price")
print(f"Alignment: {result['alignment_status']}")

Environment Variables

You can also set the API key via environment variables:

export NEURONLENS_API_KEY="nlive_your_api_key_here"
export NEURONLENS_API_URL="https://api.neuronlens.com"  # Optional

Then initialize:

import neuronlens
engine = neuronlens.Engine()  # Automatically picks up from environment

Architecture

The package works in two modes:

• Direct mode: When sae_app_v5 is available, imports and calls functions directly
• HTTP mode: When sae_app_v5 is not available (pip install), makes HTTP requests to frontend server (port 8001)

Server Requirements:

• Backend server must be running on http://localhost:8000 (GPU operations)
• Frontend server must be running on http://localhost:8001 (High-level API)
• Frontend server is exposed at api.neuronlens.com for remote access

Function Reference

High-Level Analysis Functions

engine.analyze_agent(query, response=None, model_path=None, sae_path=None, layer=19, api_url=None, **kwargs) Analyze agent tool intent and alignment. Returns alignment_status, tool_called, intent_scores, top_features.

engine.check_tool(tool_name, prompt="", session_id=None, sae_features=None) Gate-check a single tool call via the v5 agent lens endpoint. Returns action (allow | review | block), tool_risk_tier (low | medium | high), tool_needed (bool), and action_reason. Use inside your agent's tool invocation logic to decide whether to proceed, flag for review, or block the call before it executes. Optional sae_features (length 786432) enables probe-backed scores instead of heuristics.

engine.analyze_sentiment(text, top_n=10, model_path=None, sae_path=None, layer=10, api_url=None, **kwargs) Analyze sentiment with SAE feature attribution. Returns sentiment (predicted_label, confidence, probabilities) and top_features. Note: top_n only applies in HTTP mode; direct mode uses hardcoded top_n=10.

engine.analyze_trading(text, ticker=None, model_path=None, sae_path=None, layer=19, api_url=None, **kwargs) Extract trading signals from news text. Returns trading signals and direction.

engine.analyze_reasoning(prompt, model_path=None, sae_path=None, layer=28, expected_buckets=None, api_url=None, **kwargs) Analyze CoT reasoning faithfulness. Returns reasoning analysis with bucket alignment, chain metrics (RS/AF/TB), and per-sentence importance scores.

engine.analyze_hallucination(prompt, max_tokens=256, temperature=0.7, api_url=None, **kwargs) Token-level hallucination detection. Returns token_details with risk scores per token.

engine.search_features(query, k=10, layer=16, model_id="gemma-2-9b-it", api_url=None, **kwargs) Search Neuronpedia features by keyword/semantic query. Returns list of feature explanation dicts.

engine.steer_features(prompt, features, model="gemma-2-9b-it", api_url=None, **kwargs) Steer via Neuronpedia API. Features: list of dicts with modelId, layer, index, strength (positive steers towards, negative steers away). Returns original_text, steered_text, has_steering, metrics.

engine.get_searchsteer_models() Return available Neuronpedia models for Search & Steer.

engine.get_searchsteer_presets() Return finance-themed feature presets for Search & Steer.

Common Backend Wrapper Functions

engine.extract_top_features(text, model_path, sae_path, layer, top_n=10, use_hf_model=False, use_hf_sae=False, sae_config_path=None, api_url=None, **kwargs) Extract top SAE features from text. Returns dictionary with features array and top_features list.

engine.unload_model(model_path, device=None, **kwargs) Unload specific model from cache. Returns success status.

engine.unload_all_models(**kwargs) Unload all models from cache. Returns success status.

engine.model_cache_status(**kwargs) Get model cache status. Returns dictionary with loaded_models list and cache information.

Complete Examples

Agent Lens Analysis

import neuronlens

engine = neuronlens.Engine(api_key="nlive_your_key")

result = engine.analyze_agent("What's the latest news about Apple?")

print(f"Query: {result['query']}")
print(f"Alignment Status: {result['alignment_status']}")  # GREEN, AMBER, or RED
print(f"Expected Tools: {result['expected_tools']}")
print(f"Tool Called: {result['tool_called']}")
print(f"Intent Scores: {result['intent_scores']}")

# Top activated features
for feature in result['top_features'][:5]:
    print(f"Feature #{feature['feature_id']}: {feature['activation']:.4f}")

Tool Gate (check_tool)

import neuronlens

engine = neuronlens.Engine(api_key="nlive_your_key")

# Gate a tool call before it executes
out = engine.check_tool("execute_trade", prompt="Buy 100 NVDA shares at market price")

print(f"Action: {out['action']}")          # allow | review | block
print(f"Risk Tier: {out['tool_risk_tier']}")  # low | medium | high
print(f"Tool Needed: {out['tool_needed']}")
print(f"Reason: {out['action_reason']}")

# Use in your agent loop
if out["action"] == "block":
    raise RuntimeError(f"Tool blocked: {out['action_reason']}")
elif out["action"] == "review":
    # send to human review queue
    pass

Sentiment Analysis

import neuronlens

engine = neuronlens.Engine(api_key="nlive_your_key")

result = engine.analyze_sentiment(
    text="Strong quarterly earnings exceeded expectations",
    top_n=10
)

sentiment = result['sentiment']
print(f"Predicted Label: {sentiment['predicted_label']}")
print(f"Confidence: {sentiment['confidence']:.3f}")

# Top contributing features
for feature in result['top_features']:
    print(f"Feature #{feature['feature_id']}: {feature['activation']:.4f}")

Trading Lens

import neuronlens

engine = neuronlens.Engine(api_key="nlive_your_key")

signals = engine.analyze_trading(
    text="Apple earnings beat expectations by 15%",
    ticker="AAPL"
)

print(f"Signals: {signals}")

Reasoning Lens

import neuronlens

engine = neuronlens.Engine(api_key="nlive_your_key")

result = engine.analyze_reasoning(
    prompt="What is 2+2? Show your reasoning step by step.",
    layer=28
)

print(f"Reasoning Analysis: {result}")
# result contains chain metrics: RS (total_mass), AF (lift_k), TB (late_lift)
# and per-sentence importance scores with verdict (allow/flag/block)

Hallucination Detection

import neuronlens

engine = neuronlens.Engine(api_key="nlive_your_key")

result = engine.analyze_hallucination(
    prompt="Write a summary about Apple",
    max_tokens=256,
    temperature=0.7
)

print(f"Token Details: {len(result.get('token_details', []))} tokens analyzed")

Search & Steer

import neuronlens

engine = neuronlens.Engine(api_key="nlive_your_key")

# Search for features
features = engine.search_features(
    query="market volatility and uncertainty",
    k=10,
    model_id="gemma-2-9b-it"
)

# Steer using found features
steered = engine.steer_features(
    prompt="What is the market outlook for tech stocks?",
    features=[
        {
            "modelId": "gemma-2-9b-it",
            "layer": "9-gemmascope-res-131k",
            "index": features[0]["index"],
            "strength": 150,   # positive → steer towards
        },
    ],
    model="gemma-2-9b-it",
)

print(f"Original: {steered['original_text']}")
print(f"Steered:  {steered['steered_text']}")
print(f"Metrics:  {steered['metrics']}")

Common Functions

import neuronlens

engine = neuronlens.Engine(api_key="nlive_your_key")

# Extract features directly
features = engine.extract_top_features(
    text="Strong earnings report",
    model_path="ProsusAI/finbert",
    sae_path="/path/to/sae",
    layer=10,
    top_n=10
)

# Check cache status
status = engine.model_cache_status()
print(f"Models loaded: {status.get('loaded_models', [])}")

# Unload all models
engine.unload_all_models()

How It Works

Direct Mode (when sae_app_v5 is available)

• Imports functions directly from sae_app_v5.api_functions
• Uses APIClient.patch_requests() to inject API key into HTTP requests
• Calls backend functions directly for common operations
• No HTTP overhead for function calls

HTTP Mode (when sae_app_v5 not available, pip install)

• Makes HTTP requests to frontend server on port 8001
• All requests include X-API-Key header
• Works standalone without sae_app_v5 codebase

The Engine class automatically:

1. Detects if sae_app_v5 is available
2. Uses direct mode if available, HTTP mode otherwise
3. Injects X-API-Key header in all HTTP requests
4. Handles async functions automatically

Error Handling

import neuronlens
import requests

try:
    engine = neuronlens.Engine(api_key="invalid_key")
    result = engine.analyze_agent("Get Tesla price")
except ValueError as e:
    if "API key is required" in str(e):
        print("Error: API key is required")
    else:
        print(f"Configuration error: {e}")
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 401:
        print("Authentication failed: Invalid API key")
    else:
        print(f"API error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Requirements

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

For full functionality, you need:

• Backend server running on port 8000
• Frontend server running on port 8001
• See root README.md in sae_app_v5 for server setup instructions

Developer Guide

Updating API URL

When the backend API URL changes, update it using one of these methods (priority order):

1. Config File (sae_app_v5/pip/config.json):

   { "api_url": "https://api.neuronlens.com", "timeout": 30 }
   

2. Environment Variable:

   export NEURONLENS_API_URL="https://api.neuronlens.com"
   

3. Engine Constructor:

   engine = neuronlens.Engine(api_key="key", api_url="https://api.neuronlens.com")
   

API Key Configuration

Where to put the API key:

• Environment Variable: export NEURONLENS_API_KEY="nlive_your_key" or export API_KEY="nlive_your_key"
• .env File (sae_app_v5/.env): API_KEY=nlive_your_key (load with python-dotenv)
• Engine Constructor: engine = neuronlens.Engine(api_key="nlive_your_key")

Note: API key is required for all functions. Engine raises ValueError if missing.

HTTP Mode (Standalone)

When sae_app_v5 is not available (pip install), package works completely via HTTP:

• All calls make HTTP requests to the cloud API (api.neuronlens.com)
• No local code dependencies - works from any machine
• API key automatically injected in X-API-Key header

engine = neuronlens.Engine(api_key="key", api_url="https://api.neuronlens.com")
result = engine.analyze_sentiment("text")  # POST to /frontend/analyze_sentiment

Direct Mode (Local Development)

When sae_app_v5 is available, package uses direct function calls:

• High-level: Imports from sae_app_v5.api_functions, calls directly, injects API key via patched requests.post
• Common: Imports from sae_app_v5.services.model_loader, calls directly
• API key still required (validated in constructor)

engine = neuronlens.Engine(api_key="key")
status = engine.model_cache_status()  # Direct call, no HTTP
result = engine.analyze_sentiment("text")  # Direct call, API key injected for internal backend calls

Configuration Files

• sae_app_v5/pip/config.json - Default API URL (edit this file)
• sae_app_v5/.env - API key and URL (requires python-dotenv)
• sae_app_v5/pip/.env - PyPI API token for publishing (not committed to git)
• sae_app_v5/pip/config.py - URL detection logic (modify if needed)

License

MIT License