F.R.I.D.A.Y.

Frontier Research in Interpretable Discovery and Analysis of Yielded Intelligence

Chrome DevTools for AI Brains.

Upload any LLM. Get a complete circuit risk report in minutes. Discover hidden risks, bias circuits, deception patterns, and hallucination sources — with evidence.

Powered by automated circuit discovery in transformer models (mechanistic interpretability research).

🚀 The Product

from product.scanner import ModelScanner

scanner = ModelScanner.from_pretrained("gpt2")
report = scanner.scan_sync(depth="standard")

print(report.risk_summary())
# ⚠️ This model (gpt2, 124M) contains 2 high/critical risk circuits:
# Bias Circuit, Deception Circuit. Review before deployment.

print(f"Safe to deploy: {report.safe_to_deploy()}")
# Safe to deploy: False

# Full markdown audit report
with open("safety_report.md", "w") as f:
    f.write(report.to_markdown())

🧠 What this does

Large language models are powerful but opaque. We know that GPT-2 can identify indirect objects in sentences, but we don't know how — which attention heads route the information, which MLP layers transform it, and which internal features represent the relevant concepts. Manual analysis is slow, subjective, and doesn't scale.

FRIDAY automates this process. Given a model and a behavioral task, the system extracts activations across all layers, trains sparse autoencoders to decompose superposed representations into interpretable features, and runs an iterative edge-pruning algorithm (ACDC) to identify the minimal subgraph — the circuit — that implements the behavior. The result is a directed graph of attention heads, MLP layers, and SAE features, validated with faithfulness and completeness metrics, and visualized in an interactive dashboard.

Input: a model + a task (e.g., "indirect object identification")
Output: a circuit graph + ablation proof + interactive visualization
┌─────────┐      ┌───────────┐      ┌─────────┐      ┌───────────┐
│  Model  │─────►│ Activate  │─────►│  Train  │─────►│ Discover  │
│  + Task │      │ & Cache   │      │   SAE   │      │  Circuit  │
└─────────┘      └───────────┘      └─────────┘      └─────┬─────┘
                      M2                 M3                 │
                                                            ▼
                                                     ┌───────────┐
                                                     │ Evaluate  │
                                                     │ & Display │
                                                     └───────────┘
                                                       M1 + M4

🏗️ Architecture

╔══════════════════════════════════════════════════════════════════╗
║                          F.R.I.D.A.Y.                            ║
║                Mechanistic Interpretability Engine               ║
╠══════════════════════════════════════════════════════════════════╣
║                                                                  ║
║   ┌──────────┐   AblationSpec    ┌───────────────┐               ║
║   │          │ ───────────────►  │               │               ║
║   │    M1    │                   │      M2       │               ║
║   │ Research │   AblationResult  │  Extraction   │               ║
║   │          │ ◄───────────────  │               │               ║
║   └──────────┘                   └───────┬───────┘               ║
║        │                                 │                       ║
║        │ CircuitHypothesis    ActivationBatch (HDF5)             ║
║        │                                 │                       ║
║        ▼                                 ▼                       ║
║   ┌──────────┐                   ┌───────────────┐               ║
║   │          │                   │               │               ║
║   │   M1+M6  │   CircuitGraph    │      M3       │               ║
║   │ Circuits │ ◄────────────     │     SAE       │               ║
║   │          │                   │               │               ║
║   └────┬─────┘                   └───────┬───────┘               ║
║        │                                 │                       ║
║        │ CircuitGraphContract    FeatureDictionary (JSON)        ║
║        │                                 │                       ║
║        ▼                                 ▼                       ║
║   ┌──────────────────────────────────────────────┐  ┌──────────┐ ║
║   │                    M4                        │  │          │ ║
║   │              Dashboard                       │  │    M5    │ ║
║   │   circuit_explorer │ feature_browser         │  │   Docs   │ ║
║   │   attention_heatmap│ ablation_diff           │  │ & Exper. │ ║
║   └──────────────────────────────────────────────┘  └──────────┘ ║
║                                                                  ║
╠══════════════════════════════════════════════════════════════════╣
║                   M6 · Pipeline · Integration                    ║
║         PipelineRunner → contracts.py → config.yaml              ║
╚══════════════════════════════════════════════════════════════════╝

Data contracts

Every piece of data that crosses a module boundary has a typed Pydantic contract. If the contract validates, the data is safe to consume.

⚡ Quickstart

# 1. Clone
git clone https://github.com/friday/friday.git
cd friday

# 2. Install
python -m venv .venv && source .venv/bin/activate
pip install -e ".[all]"

# 3. Scan a model (product)
python -c '
from product.scanner import ModelScanner
scanner = ModelScanner.from_pretrained("gpt2")
print(scanner.scan_sync().risk_summary())
'

# 4. Run the research pipeline
make run

# 5. Launch the ecosystem
make product     # FRIDAY UI at http://localhost:8501
make api         # REST API at http://localhost:8000/docs
make landing     # Landing page at http://localhost:3000

👥 Team & ownership

📂 Project structure

friday/
├── README.md                    ← You are here
├── config.yaml                  ← All configurable parameters (model, SAE, thresholds)
├── pyproject.toml               ← Dependencies and build config
├── Makefile                     ← run, test, lint, api, product, landing, clean
├── product/                     ← FRIDAY product layer
│   ├── scanner.py               ← ModelScanner: the core product class
│   ├── report.py                ← ScanReport: structured output for customers
│   ├── risk_engine.py           ← RiskEngine: circuits → risk scores (core IP)
│   └── pricing.py               ← Free/Pro/Enterprise tier management
├── api/                         ← REST API (FastAPI)
│   ├── main.py                  ← FastAPI app with CORS, error handlers, timing
│   ├── routes/
│   │   ├── scan.py              ← POST /v1/scan, GET /v1/scan/{id}
│   │   ├── reports.py           ← GET /v1/reports, GET /v1/reports/{id}
│   │   └── health.py            ← GET /v1/health, GET /v1/version
│   ├── schemas/
│   │   ├── scan_request.py      ← Pydantic request validation
│   │   └── scan_response.py     ← Pydantic response models
│   └── middleware/
│       ├── auth.py              ← Bearer token authentication
│       └── rate_limit.py        ← Tier-based rate limiting
├── landing/                     ← Product landing page
│   ├── index.html               ← Hero, demo, pricing, personas
│   ├── styles.css               ← Dark theme, responsive
│   └── demo.js                  ← Interactive scan demo
├── src/                         ← Research engine (M1-M5)
│   ├── research/
│   │   ├── hypotheses.py        ← CircuitHypothesis + IOI/induction examples
│   │   ├── ablation_spec.py     ← AblationSpec: what to ablate and how
│   │   └── literature.md        ← Annotated reading list (11 key papers)
│   ├── extraction/
│   │   ├── cache.py             ← ActivationCache: HDF5-backed tensor storage
│   │   ├── hooks.py             ← TransformerLens hook builders
│   │   ├── patching.py          ← Zero/mean/causal ablation methods
│   │   └── api.py               ← get_activation(), run_ablation()
│   ├── sae/
│   │   ├── model.py             ← SparseAutoencoder nn.Module
│   │   ├── train.py             ← SAETrainer with L1 sweep
│   │   ├── labeling.py          ← FeatureLabeler (Claude API)
│   │   └── feature_dict.py      ← FeatureDictionary: M3 → M4 contract
│   ├── circuits/
│   │   ├── graph.py             ← CircuitGraph (nodes + edges + serialization)
│   │   ├── discovery.py         ← AutoCircuitDiscovery (ACDC algorithm)
│   │   └── evaluate.py          ← faithfulness(), completeness()
│   └── pipeline/
│       ├── runner.py            ← PipelineRunner: end-to-end orchestration
│       ├── config.py            ← PipelineConfig: typed YAML loader
│       └── contracts.py         ← Pydantic contracts for all module boundaries
├── dashboard/
│   ├── app.py                   ← FRIDAY dashboard (product + research views)
│   └── views/
│       ├── scanner_upload.py    ← Model upload + scan trigger
│       └── risk_report.py       ← Scan results + downloadable report
├── docs/
│   ├── architecture.md          ← System diagram, data contracts, decision log
│   ├── api_reference.md         ← REST API endpoint documentation
│   ├── product_vision.md        ← Product vision, market, revenue model
│   ├── customer_personas.md     ← Buyer profiles (lab, enterprise, government)
│   ├── pricing_model.md         ← Tier structure, justification, projections
│   ├── pitch_outline.md         ← 10-slide investor/partner pitch outline
│   ├── onboarding.md            ← New member setup guide
│   └── reproduce.md             ← Seeds, checksums, and split strategy
└── tests/
    ├── conftest.py              ← Shared fixtures (tiny model, sample data)
    ├── test_extraction.py       ← Cache, hooks, and patching tests
    ├── test_sae.py              ← SAE forward pass, metrics, serialization
    ├── test_pipeline.py         ← Config loading, hashing, env overrides
    ├── test_contracts.py        ← Contract validation for all boundaries
    ├── test_scanner.py          ← ModelScanner scan execution tests
    ├── test_report.py           ← ScanReport serialization + markdown
    ├── test_risk_engine.py      ← Risk scoring and recommendation tests
    ├── test_pricing.py          ← Tier limits and enforcement tests
    └── test_api.py              ← API endpoint integration tests

🔬 Core concepts

🧪 Experiments

Running an experiment

1. State a hypothesis — Define a CircuitHypothesis in src/research/hypotheses.py with the predicted components.
2. Create an ablation spec — Build an AblationSpec targeting those components.
3. Run the pipeline — Execute make run (or call run_ablation() directly).
4. Evaluate — Check faithfulness and completeness against thresholds.
5. Log the result — Update experiments/log.md and commit the notebook.

Creating a new experiment

# 1. Create an issue using the Experiment template
# 2. Create a notebook
cp experiments/exp_001_ioi_baseline.ipynb experiments/exp_003_your_experiment.ipynb

# 3. Add to the log
echo "| 003 | $(date +%Y-%m-%d) | Your hypothesis | config.yaml | — | PROPOSED | exp_003 |" >> experiments/log.md

See the full experiment log: experiments/log.md

⚙️ Configuration

All parameters live in config.yaml. No magic numbers in code.

🌊 Data flow

When you run make run, here's exactly what happens:

1. PipelineRunner loads config.yaml
   └── Computes config_hash (SHA-256) for artifact tagging

2. Stage 1: Extraction (M2)
   ├── Loads model via TransformerLens
   ├── Runs forward pass on task dataset
   ├── Captures activations via hook functions
   └── Saves to data/activations/gpt2_{hash}.h5

3. Stage 2: SAE Training (M3)
   ├── Loads activations from HDF5 cache
   ├── Trains SparseAutoencoder (768 → 4096 features)
   ├── Saves checkpoint to checkpoints/sae_epoch_0009.pt
   └── Saves feature dictionary to data/feature_dicts/latest.json

4. Stage 3: Circuit Discovery (M1 + M6)
   ├── Builds full computational graph (all heads + MLPs)
   ├── Runs ACDC: iterative edge pruning via activation patching
   └── Saves minimal circuit to data/ablation_results/ioi_circuit.json

5. Stage 4: Evaluation
   ├── Computes faithfulness and completeness
   └── Logs results to data/ablation_results/evaluation.json

🛠️ Development guide

Branch naming

m{N}/{short-description}

Examples:
  m2/add-residual-caching
  m3/l1-sweep-experiment
  m6/fix-contract-validation

PR checklist

• make test passes
• make lint passes
• New tests added for new code
• Updates experiments/log.md if results changed
• No breaking changes to data contracts (or contracts.py is updated)

Running tests

make test                      # All tests
pytest tests/test_sae.py -v    # Just SAE tests
pytest -k "test_cache" -v      # Tests matching a pattern
pytest -m "not slow"           # Skip slow tests

🗺️ Roadmap

What we're building toward

Research goal: A publishable circuit (IOI in GPT-2 small), fully traced from input to output, with faithfulness ≥ 0.95 and completeness ≥ 0.90.

Product goal: A live product at aisafetyscanner.com where anyone can upload a model and get a circuit risk report in minutes. Free tier for researchers, Pro for ML teams, Enterprise for companies.

📚 Research background

Full annotated reading list: src/research/literature.md

📝 Citation

@software{friday_2026,
  title   = {FRIDAY: Automated Circuit Discovery in Transformer Models},
  author  = {FRIDAY Team},
  year    = {2026},
  url     = {https://github.com/friday/friday},
  version = {0.1.0}
}

⚖️ License

MIT — see LICENSE for details.