How eleutherai/delphi works
Main Architectural Layers
a. Entry Points (CLI & Programmatic API)
• delphi/__main__.py (CLI invocation)
• Any user code that imports delphi.pipeline, delphi.latents, etc.
b. Orchestration & Pipeline
• delphi/pipeline.py (Pipeline class, process_wrapper, async runner)
c. Core Modules
• Clients (delphi/clients) – adapters to LLM backends:
• Offline (local VLLM)
• OpenRouter (API)
• Latent Handling (delphi/latents) – caching, loading, constructing contexts:
• LatentCache, LatentDataset, ConstructorConfig, SamplerConfig
• Explainers (delphi/explainers) – build prompts + call model:
• DefaultExplainer, ContrastiveExplainer, NoOp, SingleToken, etc.
• Scorers (delphi/scorers) – evaluate explanations:
• ClassifierScorers (detection, fuzzing, intruder)
• EmbeddingScorer
• SimulatorScorer (OpenAI auto‐interp fork)
• SurprisalScorer
• Sparse Coders (delphi/sparse_coders) – AE model wrappers and loading
• Configuration & Utilities
• delphi/config.py
• delphi/utils.py, logging (delphi/log)
d. Data Stores & File Artifacts
• Activation caches (.safetensors shards)
• Embedding caches (FAISS index)
• Generated explanations & scores (JSON/text files)
• Logs, histograms, confusion matrices
e. External Dependencies & Services
• HuggingFace Datasets & Models
• FAISS (semantic search)
• OpenRouter / OpenAI API
• VLLM local model server
Component Relationships & Data Flows
• Data Flow:
1. Dataset Load → tokens
2. LatentCache (model + tokens) → activation shards on disk
3. LatentDataset (constructor + sampler) → context windows
4. Pipeline orchestrates steps:
a. ExplainerPipe: contexts → Explainer → explanations
b. ScorerPipe: (contexts + explanations) → Scorers → scores
5. ResultAnalysis: collate metrics, generate plots
• Control Flow: CLI or user script triggers Pipeline → async tasks
• Dependencies:
• Explainers & Scorers depend on a Client
• LatentDataset depends on caches + config
• FAISS index built by Constructor if enabled
Architectural Patterns & Principles
• Modular Pipeline – each stage is a pluggable “pipe”
• Adapter Pattern for LLM clients (Offline vs. OpenRouter)
• Separation of Concerns: caching vs. constructing vs. explaining vs. scoring
• Asynchronous Processing with asyncio for parallel API/model calls
• Configuration-driven (dataclasses in config.py)
• Extensibility Points: add new Explainer, Scorer, or Client by subclassing