neuronlens 0.2.3

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_v3, set NGROK_AUTH_TOKEN and API_KEY in environment (or cloud_config.json), run ./start_frontend_backend.sh && ./api_key_util/start_ngrok.sh. Override API URL: NEURONLENS_API_URL env var or pip/config.json (1-2 places control everything). See Developer Guide.

Installation

pip install neuronlens

For development (editable install):

cd sae_app_v3/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_v3/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_v3/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 http://localhost:8001)
# engine = neuronlens.Engine(api_key=NEURONLENS_API_KEY, api_url="https://your-ngrok-url.ngrok-free.dev")

# 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://your-ngrok-url.ngrok-free.dev"  # 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_v3 is available, imports and calls functions directly
• HTTP mode: When sae_app_v3 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 can be exposed via ngrok 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.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.

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, api_url=None, **kwargs) Search features using semantic similarity. Returns list of features with feature_id, score, and label.

engine.steer_features(prompt, features, model="meta-llama/Llama-2-7b-hf", api_url=None, **kwargs) Apply feature steering. Features: list of dicts with "id" and "magnitude" (-1.0 to +1.0). Returns original_text and steered_text.

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}")

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")

# Extract signals
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.",
    max_new_tokens=2048
)

print(f"Reasoning Analysis: {result}")

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,
    layer=16
)

# Steer using found features
steered = engine.steer_features(
    prompt="What is the market outlook for tech stocks?",
    features=[
        {"id": features[0]['feature_id'], "magnitude": 0.7},  # Steer towards
        {"id": features[1]['feature_id'], "magnitude": -0.5}  # Steer away
    ],
    model="meta-llama/Llama-2-7b-hf"
)

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

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_v3 is available)

• Imports functions directly from sae_app_v3.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_v3 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_v3 codebase

The Engine class automatically:

1. Detects if sae_app_v3 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

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 FUNCTION_LIST.md in sae_app_v3 for server setup instructions

Developer Guide

Updating API URL When Ngrok Changes

When the backend API URL changes (e.g., new ngrok URL), update it using one of these methods (priority order):

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

   {"api_url": "https://new-ngrok-url.ngrok-free.dev", "timeout": 30}
   

2. Environment Variable:

   export NEURONLENS_API_URL="https://new-ngrok-url.ngrok-free.dev"
   

3. .ngrok_url File (Auto-detected):

   echo "https://new-ngrok-url.ngrok-free.dev" > sae_app_v3/.ngrok_url
   

4. Ngrok API (Auto-detected from http://127.0.0.1:4040/api/tunnels)

5. Engine Constructor:

   engine = neuronlens.Engine(api_key="key", api_url="https://new-url.ngrok-free.dev")
   

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_v3/.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_v3 is not available (pip install), package works completely via HTTP:

• All calls make HTTP requests to frontend server (port 8001) via ngrok
• 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://ngrok-url.ngrok-free.dev")
result = engine.analyze_sentiment("text")  # POST to /frontend/analyze_sentiment

Direct Mode (Local Development)

When sae_app_v3 is available, package uses direct function calls:

• High-level: Imports from sae_app_v3.api_functions, calls directly, injects API key via patched requests.post
• Common: Imports from sae_app_v3.backend.common and sae_app_v3.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_v3/pip/config.json - Default API URL (edit this file)
• sae_app_v3/.ngrok_url - Auto-detected ngrok URL
• sae_app_v3/.env - API key and URL (requires python-dotenv)
• sae_app_v3/pip/.env - PyPI API token for publishing (not committed to git)
• sae_app_v3/pip/config.py - URL detection logic (modify if needed)

License

MIT License