Peripheral Attention Engineering (PAE)

Structured peripheral context for LLMs — proven across 4 domains, 8 conditions, 3 model families.

What is PAE?

LLMs answer queries using directly relevant material. But a competent human silently consults peripheral context — who is asking, what's their situation, what's anomalous about them — before answering. PAE is the deliberate structuring of that context to measurably improve LLM responses.

Results: Structured peripheral context improves response quality by 2.5–3.1× (Cohen's d=2.02–3.10) across customer service, medical triage, legal advisory, and financial advisory domains. The improvement comes from entity-focused context (not prompt length or additional domain knowledge). A fine-tuned model achieves 100% contextual reach. Read the paper.

Quick Install

pip install pae

Zero dependencies. Core library is pure Python.

For the full toolkit (LLM inference, API server, experiments):

pip install pae[all]

Quick Start

from pae.context import EntityProfile, AnomalyFlag, wrap, detect_anomalies

profile = EntityProfile(
    entity_id="cust_42",
    direct_context={"Return Policy": "30 days with receipt."},
    asker_context={"tier": "VIP", "lifetime_spend": "$84,000"},
    situational_context={"date": "Dec 28", "warehouse": "93% full"},
    anomaly_flags=[
        detect_anomalies("return_rate", 0.47, 0.08, description="6x baseline"),
        AnomalyFlag("avg_order", 12000, 350, description="Recent $12k order"),
    ],
)

prompt = wrap("What's your return policy?", profile)
# Ready to send to any LLM

Full CRM Integration (Import from CSV)

from pae import SubstrateEngine

engine = SubstrateEngine()
engine.import_csv(
    customers="customers.csv",   # id, name, tier, account_age
    orders="orders.csv",         # id, customer_id, amount, date
    returns="returns.csv",       # id, customer_id, order_id, amount, date
    tickets="tickets.csv",       # id, customer_id, category, resolution
)

response = engine.generate("What's your return policy?", "cust_42", situation="customer_service")

Install Options

Group	Command	Includes
Core	pip install pae	context.py, substrate (zero deps)
Inference	pip install pae[inference]	OpenAI, Anthropic, Google API clients
API Server	pip install pae[api]	FastAPI REST server
Experiments	pip install pae[experiments]	Full experiment runner
Phase 2	pip install pae[phase2]	Local fine-tuning tools
Everything	pip install pae[all]	All of the above

Architecture

The library has three layers:

Layer	Module	Purpose
Prompt Builder	pae.context	wrap(), EntityProfile, detect_anomalies()
Knowledge Graph	pae.substrate	SubstrateEngine, CSV import, ancestry lenses
Inference	pae.inference	generate() — send to any LLM

Prompt Builder

wrap() takes a query and an EntityProfile and returns a slotted, anomaly-flagged prompt. The output is plain text — no API calls, no dependencies. Slot labels and PAY ATTENTION markers guide the LLM to use peripheral context appropriately.

Knowledge Graph

The SubstrateEngine ingests CSV data (customers, orders, returns, tickets) into an in-memory property graph. It applies situation-conditioned lenses (buyer, risk, relationship) that ask: "viewing this customer as a buyer, what's relevant?" It computes population baselines and auto-flags anomalies.

Inference

The generate() function wraps wrap() plus an LLM API call into a single step. Supported providers: OpenAI, Anthropic, Google, OpenRouter, local models.

Project Structure

pae/
├── __init__.py       # Top-level API
├── context.py        # EntityProfile, AnomalyFlag, wrap(), detect_anomalies()
├── config.py         # Experiment models and config
├── inference.py      # LLM inference
├── cli.py            # CLI entry point
├── conditions/       # 8 experimental conditions (C1–C8)
├── evaluation/       # LLM judge
├── experiment/       # Parallel experiment runner
├── models/           # LLM API clients
├── scenarios/        # Scenario schema and generation
├── statistics/       # Analysis, bootstrapping, surprisal
├── storage/          # SQLite + JSON persistence
├── substrate/        # Knowledge graph, lenses, CSV import
└── utils/            # Noise generation, logging

experiments/          # Experiment runner scripts
scripts/              # User-facing tools
  ├── human_eval.py   # Human evaluation CLI
  └── attention_analysis.py  # Attention heatmap extraction

Running the Experiment

pip install pae[experiments]

cp .env.example .env  # Add your OPENROUTER_API_KEY
python experiments/run_experiment.py

Fine-Tuned Model

A Gemma 4 12B model fine-tuned for contextual reach is available at: anthonylee991/gemma-4-12b-pae-contextual-reach

Metric	Base	Fine-tuned
Requests context when missing	65%	100%
Uses context when provided	90%	100%

References

• Paper: Peripheral Attention Engineering (2026)
• Preregistration: 10.17605/OSF.IO/W3XYV
• Dataset: 10.5281/zenodo.20599000
• Model: anthonylee991/gemma-4-12b-pae-contextual-reach

License

MIT — see LICENSE