Paquete · Librería
jw-interp
Interpretabilidad mecanicista tri-modelo
Paquete F80 que cierra el loop F77-F79 con una pregunta operativa: ¿el modelo internalizó los principios o aprendió un shortcut estilístico? Arquitectura tri-modelo: producción Qwen3.5-0.8B nunca se toca, lab Qwen3.5-2B-Base con Qwen-Scope público (TopK k=50 residual, 24 capas, 32k features) y lab Gemma-2-2B-PT con Gemma Scope (JumpReLU SOTA residual+MLP+attention todas las capas, 16k-262k features). Cross-family validation: una feature moral que emerge en ambas familias arquitectónicamente distintas es evidencia mucho más robusta. Tier 4 en fidelity_wrap es deliberadamente observacional — un probe miss NUNCA veta un Finding solo, solo anota probe_scores + probe_coherence (clear|confirms|conflicts|silent). El tipo ProbeEvaluatorCallable vive en jw-agents para coupling cero.
Funcionalidades
Lo que hace, en detalle.
Probing lineal por principio (F80.1)
ContrastiveSpec declarativos por principio (5 builtin seed PF001/002/003/010/012), PrincipleContrastiveBuilder + ProbingDataset con validación de shape. MockActivationCapturer determinístico (offset por principio × capa × hook) que produce datos linealmente separables — contrato matemático: si la probe no separa eso, el pipeline está roto. TorchActivationCapturer con AutoModelForCausalLM + forward hooks sobre model.model.layers, auto-device cuda > mps > cpu, last-token o mean pooling. LinearProbe sklearn LogisticRegression con stratified split, accuracy + AUC, coef + bias persistibles para steering. Accuracy ≥0.80 alguna capa = principio internalizado; <0.65 todas las capas = shortcut detectado.
Steering vectors + activation patching (F80.2)
SteeringVector frozen dataclass. compute_steering_vector diferencia de medias positivas vs negativas, unit-norm por defecto. apply_steering_to_residual con broadcasting (residual 1D o 2D batch). project_out remueve la componente para ablación (dot post-proyección ~0). evaluate_steering_effect mide monotonicidad bajo alpha contra el probe: +alpha sube probe score, -alpha lo baja → causal; ninguna dirección cambia → spurious. patching.PatchedActivation + patch_one / patch_batch / evaluate_patching_effect pure-numpy.
Qwen-Scope adapter (F80.3)
QwenScopeSAE frozen con W_enc / b_enc / W_dec / b_dec + d_model + d_sae + k. encode TopK puro numpy con np.argpartition (O(n·d_sae) sin sort completo). decode reconstruye residual, reconstruction_error como MSE. load_qwen_scope_sae(path, layer, k) con torch.load(weights_only=True) — sin pickle execution. Verifica file exists ANTES de importar torch (FileNotFoundError fast-path). summarize_feature_activations mapea principios a features candidatas por differential activation rate.
Gemma Scope wrapper (F80.4)
GemmaScopeSAE frozen con layer + site (resid_post|mlp_out|attn_out) + d_model + d_sae + _inner SAELens object. encode/decode atraviesan sae_lens.SAE pero la interfaz pública es numpy in/numpy out — idéntica a QwenScopeSAE para que F80.3 y F80.4 sean intercambiables aguas abajo. _RELEASE_MAP declarativo para gemma-2-2b/-9b × resid/mlp/attn → SAELens release id. summarize_gemma_features reusa el summarizer de QwenScopeSAE (mismo contrato).
Runtime probe store + fidelity_wrap Tier 4 (F80.5)
save_probe / load_probe con np.savez_compressed + JSON sidecar (forward-compat across sklearn versions, sin pickle). save_probe_set / load_probe_set con manifest.json (model_name + hidden_size + n_layers). RuntimeProbe.predict_proba con sigmoid numéricamente estable (matchea sklearn predict_proba a 1e-5). ProbeEvaluator con __call__ eager (un forward por finding) y score_cached (activaciones pre-capturadas). build_probe_evaluator auto-construye capturer del manifest si torch está. mock_evaluator(returns) para tests deterministas sin GPU. fidelity_wrap acepta probe_evaluator: Callable[[str], dict[str, float]] + probe_min_score. Tier 4 errors swallowed → probe_error en metadata.
En la práctica
Cuatro líneas.
Resultado verificable.
Entrenar probes sobre el modelo fine-tuneado y enchufar Tier 4 en producción.
from jw_interp import (
PrincipleContrastiveBuilder, TorchActivationCapturer,
build_default_contrastive_specs, train_probes_for_principle,
save_probe_set, ProbeStoreManifest,
)
from jw_interp.runtime import build_probe_evaluator
from jw_agents.fidelity_wrap import fidelity_wrap
from jw_eval.principles import load_principles
# 1. Capturar activaciones y entrenar probes
cap = TorchActivationCapturer("Qwen/Qwen3.5-0.8B")
builder = PrincipleContrastiveBuilder(build_default_contrastive_specs())
results = []
for pid in builder.principle_ids:
batches = cap.capture(builder.build(pid), layers=list(range(0, 24, 4)))
results.extend(train_probes_for_principle(batches, pid))
save_probe_set(results, "~/jw-probes/v1", ProbeStoreManifest(
model_name="Qwen/Qwen3.5-0.8B",
hidden_size=cap.hidden_size, n_layers=cap.n_layers,
))
# 2. Tier 4 observacional en producción (NUNCA veta un Finding solo)
evaluator = build_probe_evaluator(probes_dir="~/jw-probes/v1")
@fidelity_wrap(
on_fail="warn",
principles=load_principles(),
probe_evaluator=evaluator,
probe_min_score=0.5,
)
async def apologetics(query: str): ...API pública
Qué exporta el módulo.
Resumen de los símbolos principales. La referencia exhaustiva cubre cada uno con signature, parámetros y ejemplos.
- ContrastivePair · ContrastiveSpec · PrincipleContrastiveBuilder · ProbingDataset
- build_default_contrastive_specs (5 specs seed PF001/002/003/010/012)
- MockActivationCapturer · TorchActivationCapturer (auto-device)
- LinearProbe · train_probe · train_probes_for_principle
- SteeringVector · compute_steering_vector · apply_steering_to_residual · project_out
- patching.{PatchedActivation, patch_one, patch_batch, evaluate_patching_effect}
- QwenScopeSAE · load_qwen_scope_sae · summarize_feature_activations
- GemmaScopeSAE · load_gemma_scope_sae · summarize_gemma_features
- save_probe / load_probe · save_probe_set / load_probe_set · ProbeStoreManifest
- RuntimeProbe · ProbeEvaluator · build_probe_evaluator · mock_evaluator
Otros paquetes
Explora el resto del monorepo.
jw-core
El núcleo determinístico
jw-cli
Terminal para mortales
jw-mcp
Puente con tu agente
jw-rag
Recuperación híbrida
jw-agents
Orquestación multipaso + agéntica verificable
jw-finetune
Tu modelo, tus datos
jw-eval
Red de seguridad doctrinal
jw-gen
Generación con difusión, uso personal
jw-brain
Second-brain + Bible Knowledge Graph
jw-meeting-media
Reunión-en-vivo · clean-room
jw-meeting-scheduler
Solver de asignaciones + importer organized-app
jw-legal
BrainDomain plugin: casos legales TJ vs Estado