llmintent 0.9.1__py3-none-any.whl

llmintent/__init__.py

@@ -0,0 +1,95 @@
+"""LLMIntent — semantic extraction and intent analysis for transformer LLMs."""
+
+from llmintent.activation import activation_summary, identify_activation_layers
+from llmintent.analyzer import AnalysisReport, LLMIntentAnalyzer
+from llmintent.compaction import CompactionAnalyzer
+from llmintent.cognitive import CognitiveModuleProfile, build_cognitive_module_profile
+from llmintent.heighten import (
+    FocusMetrics,
+    HeightenedReasoningFramework,
+    HeightenedReasoningResult,
+    RetraceMode,
+    heighten_reasoning,
+)
+from llmintent.jspace import (
+    IntentTrace,
+    TransportMaps,
+    build_intent_trace,
+    classify_layer_regimes,
+    fit_transport_maps,
+)
+from llmintent.kernels import minimize_twin_barlow, per_layer_kl_profile
+from llmintent.layers import build_layer_correspondence_map, summarize_layer_bands
+from llmintent.metrics import calculate_sso_score, kl_divergence, shannon_entropy
+from llmintent.query import ConceptQueryResult, query_concept_in_trajectory, query_concepts_batch
+from llmintent.trajectory import TrajectoryMapping, build_trajectory_mapping
+from llmintent.viz import VisualizationSuite
+from llmintent.benchmark import (
+    AblationCondition,
+    BenchmarkRunConfig,
+    HellaSwagBenchmarkRunner,
+    RetraceStore,
+    list_slms,
+    parse_conditions,
+    prepare_slm_comparison,
+)
+from llmintent.live import (
+    LiveIntentPipeline,
+    LiveSessionConfig,
+    list_live_models,
+)
+from llmintent.retracement import (
+    RetracementConfig,
+    RetracementMode,
+    RetracementTransformer,
+    run_retracement_ablation,
+)
+
+__all__ = [
+    "AnalysisReport",
+    "CognitiveModuleProfile",
+    "AblationCondition",
+    "BenchmarkRunConfig",
+    "CompactionAnalyzer",
+    "ConceptQueryResult",
+    "FocusMetrics",
+    "HellaSwagBenchmarkRunner",
+    "HeightenedReasoningFramework",
+    "HeightenedReasoningResult",
+    "IntentTrace",
+    "LLMIntentAnalyzer",
+    "LiveIntentPipeline",
+    "LiveSessionConfig",
+    "RetraceStore",
+    "RetraceMode",
+    "RetracementConfig",
+    "RetracementMode",
+    "RetracementTransformer",
+    "TrajectoryMapping",
+    "TransportMaps",
+    "VisualizationSuite",
+    "activation_summary",
+    "build_cognitive_module_profile",
+    "build_intent_trace",
+    "build_layer_correspondence_map",
+    "build_trajectory_mapping",
+    "calculate_sso_score",
+    "classify_layer_regimes",
+    "fit_transport_maps",
+    "heighten_reasoning",
+    "identify_activation_layers",
+    "kl_divergence",
+    "minimize_twin_barlow",
+    "list_live_models",
+    "list_slms",
+    "parse_conditions",
+    "prepare_slm_comparison",
+    "per_layer_kl_profile",
+    "query_concept_in_trajectory",
+    "query_concepts_batch",
+    "run_retracement_ablation",
+    "shannon_entropy",
+    "summarize_layer_bands",
+]
+
+__version__ = "0.9.1"

llmintent/activation.py

@@ -0,0 +1,108 @@
+"""Identify layers of peak activation and inference pivots."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import torch
+
+from llmintent.forward import forward_hidden_states
+from llmintent.metrics import cosine_intensity
+from llmintent.models import ModelBundle
+from llmintent.poles import build_numerical_pole
+
+
+def identify_activation_layers(
+    bundle: ModelBundle,
+    prompt: str,
+    *,
+    layer_stats: pd.DataFrame | None = None,
+    entropy: list[float] | None = None,
+    occupancy: list[float] | None = None,
+    position: int = -1,
+) -> dict[str, int]:
+    """
+    Detect key activation layers for a prompt.
+
+    Returns layer indices for:
+    - inference_pivot: largest entropy drop (maturation point)
+    - workspace_peak: max J-space occupancy in workspace band
+    - motor_onset: where decode aligns with final layer output
+    - intensity_peak: max numerical-pole cosine similarity (notebook metric)
+    """
+    _, states = forward_hidden_states(bundle, prompt)
+    num_layers = len(states)
+
+    if entropy is None:
+        from llmintent.steering import get_entropy_trajectory
+
+        ent_df = get_entropy_trajectory(bundle, prompt)
+        entropy = ent_df["entropy"].tolist()
+
+    ent = np.array(entropy, dtype=float)
+    ent_diff = np.diff(ent)
+    inference_pivot = int(np.argmin(ent_diff) + 1) if len(ent_diff) else 0
+
+    if occupancy is None:
+        from llmintent.jspace.decompose import jspace_occupancy
+
+        occupancy = [
+            float(jspace_occupancy(bundle, states[i][0, position, :]))
+            for i in range(num_layers)
+        ]
+    occ = np.array(occupancy, dtype=float)
+
+    # Workspace band ~ middle third
+    ws_start = num_layers // 3
+    ws_end = (2 * num_layers) // 3
+    ws_slice = occ[ws_start : ws_end + 1]
+    workspace_peak = ws_start + int(np.argmax(ws_slice)) if len(ws_slice) else ws_start
+
+    if layer_stats is not None and "motor_alignment" in layer_stats.columns:
+        motor_onset = int(layer_stats["motor_alignment"].idxmax())
+    else:
+        motor_onset = max(0, num_layers - 2)
+
+    pole = build_numerical_pole(bundle)
+    intensities = [
+        cosine_intensity(states[i][0, position, :], pole.to(bundle.device))
+        for i in range(num_layers)
+    ]
+    intensity_peak = int(np.argmax(intensities))
+
+    return {
+        "inference_pivot": inference_pivot,
+        "workspace_peak": workspace_peak,
+        "motor_onset": motor_onset,
+        "intensity_peak": intensity_peak,
+    }
+
+
+def activation_summary(
+    bundle: ModelBundle,
+    prompt: str,
+    *,
+    position: int = -1,
+) -> pd.DataFrame:
+    """Per-layer activation metrics for layer correspondence mapping."""
+    from llmintent.jspace.decompose import jspace_occupancy
+    from llmintent.steering import get_entropy_trajectory
+
+    _, states = forward_hidden_states(bundle, prompt)
+    ent_df = get_entropy_trajectory(bundle, prompt)
+    pole = build_numerical_pole(bundle)
+
+    rows: list[dict] = []
+    for i, state in enumerate(states):
+        hidden = state[0, position, :]
+        rows.append(
+            {
+                "layer": i,
+                "entropy": float(ent_df.loc[i, "entropy"]),
+                "occupancy": float(jspace_occupancy(bundle, hidden)),
+                "intensity": cosine_intensity(hidden, pole.to(bundle.device)),
+            }
+        )
+    df = pd.DataFrame(rows)
+    df["entropy_drop"] = -df["entropy"].diff().fillna(0)
+    return df

llmintent/analyzer.py

@@ -0,0 +1,427 @@
+"""High-level facade combining notebook extraction workflows."""
+
+from __future__ import annotations
+
+import gc
+from collections import Counter
+from dataclasses import dataclass, field
+
+import pandas as pd
+import torch
+
+from llmintent.activation import activation_summary, identify_activation_layers
+from llmintent.compaction import CompactionAnalyzer
+from llmintent.embeddings import EmbeddingSpace, load_glove_gensim
+from llmintent.cognitive import CognitiveModuleProfile, build_cognitive_module_profile
+from llmintent.jspace.trace import IntentTrace, build_intent_trace
+from llmintent.jspace.transport import TransportMaps, fit_transport_maps
+from llmintent.layers import build_layer_correspondence_map, summarize_layer_bands
+from llmintent.models import ModelBundle, get_transformer_layers, load_model_bundle
+from llmintent.morphemes import MorphemeExtractor
+from llmintent.poles import build_glove_poles, build_numerical_pole
+from llmintent.query import ConceptQueryResult, query_concept_in_trajectory, query_concepts_batch
+from llmintent.trajectory import TrajectoryMapping, build_trajectory_mapping
+from llmintent.steering import (
+    analyze_steering_intensity,
+    calculate_pivot_entropy,
+    compare_cot_intensity,
+    get_entropy_trajectory,
+    run_intensity_sweep,
+    run_stress_test,
+)
+from llmintent.weight_semantics import get_block_expertise, get_block_semantics
+
+
+@dataclass
+class AnalysisReport:
+    prompt: str
+    model_name: str
+    intensity_sweep: pd.DataFrame = field(default_factory=pd.DataFrame)
+    entropy_trajectory: pd.DataFrame = field(default_factory=pd.DataFrame)
+    pivot_entropy: dict[str, float] = field(default_factory=dict)
+    cot_comparison: dict[str, float] = field(default_factory=dict)
+    block_semantics: dict[int, dict[str, list[str]]] = field(default_factory=dict)
+    compaction: pd.DataFrame = field(default_factory=pd.DataFrame)
+    inference_pivot: int | None = None
+    activation_layers: dict[str, int] = field(default_factory=dict)
+    layer_map: pd.DataFrame = field(default_factory=pd.DataFrame)
+    intent_trace: IntentTrace | None = None
+    cognitive_profile: CognitiveModuleProfile | None = None
+
+
+class LLMIntentAnalyzer:
+    """
+    Unified semantic extraction analyzer.
+
+    Combines notebook metrics (steering, compaction, morpheme wells) with
+    Anthropic J-space layer thoughts (logit/J-lens decode, activation pivots).
+    """
+
+    def __init__(
+        self,
+        model_name: str,
+        *,
+        device: str | None = None,
+        morpheme_backend: str = "lemma",
+        embedding_name: str = "glove-wiki-gigaword-100",
+        load_glove: bool = True,
+        pivot_layer: int | None = None,
+        fit_jspace_transport: bool = False,
+        transport_prompts: list[str] | None = None,
+    ) -> None:
+        self.model_name = model_name
+        self.pivot_layer = pivot_layer
+        self.bundle = load_model_bundle(model_name, device=device)
+        self.extractor = MorphemeExtractor(morpheme_backend)  # type: ignore[arg-type]
+        self.embedding_space: EmbeddingSpace | None = None
+        self.morpheme_freq: Counter[str] = Counter()
+        self.transport: TransportMaps | None = None
+
+        if load_glove:
+            self.embedding_space = load_glove_gensim(embedding_name)
+            sample_words = self.embedding_space.vocab[:5000]
+            self.morpheme_freq = Counter(self.extractor.extract(sample_words))
+
+        self._numerical_pole: torch.Tensor | None = None
+        self._glove_poles = build_glove_poles(self.embedding_space) if self.embedding_space else None
+
+        if fit_jspace_transport:
+            prompts = transport_prompts or [
+                "The quick brown fox jumps over the lazy dog.",
+                "Two plus two equals four.",
+                "Question: What is 12 times 2? Answer:",
+            ]
+            self.transport = fit_transport_maps(self.bundle, prompts)
+
+    @property
+    def numerical_pole(self) -> torch.Tensor:
+        if self._numerical_pole is None:
+            self._numerical_pole = build_numerical_pole(self.bundle)
+        return self._numerical_pole
+
+    def analyze_prompt(
+        self,
+        prompt: str,
+        *,
+        cot_prompt: str | None = None,
+        include_compaction: bool = False,
+        include_block_semantics: bool = False,
+        include_jspace: bool = True,
+        track_tokens: list[str] | None = None,
+        twin_b: str | None = None,
+    ) -> AnalysisReport:
+        report = AnalysisReport(prompt=prompt, model_name=self.model_name)
+        pole = self.numerical_pole
+
+        report.intensity_sweep = analyze_steering_intensity(self.bundle, prompt, pole)
+        report.entropy_trajectory = get_entropy_trajectory(self.bundle, prompt)
+
+        pivot = self.pivot_layer or self._default_pivot()
+        if cot_prompt:
+            report.cot_comparison = compare_cot_intensity(
+                self.bundle,
+                prompt,
+                cot_prompt,
+                pole,
+                pivot_layer=pivot,
+            )
+            report.pivot_entropy = calculate_pivot_entropy(
+                self.bundle,
+                prompt,
+                cot_prompt,
+                pivot_layer=pivot,
+            )
+
+        if include_jspace:
+            report.intent_trace = build_intent_trace(
+                self.bundle,
+                prompt,
+                transport=self.transport,
+                track_tokens=track_tokens,
+            )
+            report.activation_layers = report.intent_trace.activation_layers
+            if twin_b:
+                report.cognitive_profile = build_cognitive_module_profile(
+                    self.bundle,
+                    prompt,
+                    twin_b,
+                    transport=self.transport,
+                )
+                report.layer_map = build_layer_correspondence_map(
+                    self.bundle,
+                    prompt,
+                    transport=self.transport,
+                    cognitive_profile=report.cognitive_profile,
+                )
+            else:
+                report.layer_map = build_layer_correspondence_map(
+                    self.bundle,
+                    prompt,
+                    transport=self.transport,
+                )
+            report.inference_pivot = report.activation_layers.get("inference_pivot")
+
+        if include_block_semantics and self.embedding_space:
+            report.block_semantics = self.extract_block_semantics()
+
+        if include_compaction and self.embedding_space:
+            comp = CompactionAnalyzer(self.model_name, self.embedding_space)
+            report.compaction = comp.analyze_compaction()
+            if report.inference_pivot is None:
+                report.inference_pivot = comp.find_inference_pivot(report.compaction)
+            comp.cleanup()
+
+        return report
+
+    def identify_activation(self, prompt: str) -> dict[str, int]:
+        """Return layer indices for inference pivot, workspace peak, motor onset."""
+        return identify_activation_layers(self.bundle, prompt)
+
+    def cognitive_modules(
+        self,
+        twin_a: str,
+        twin_b: str,
+    ) -> CognitiveModuleProfile:
+        """Identify identity, reasoning, meta-reasoning, ideation kernels."""
+        from llmintent.heighten.cot_delta import compute_cot_delta
+
+        cot_delta = compute_cot_delta(self.bundle, twin_a, twin_b)
+        return build_cognitive_module_profile(
+            self.bundle,
+            twin_a,
+            twin_b,
+            transport=self.transport,
+            cot_delta=cot_delta,
+        )
+
+    def layer_correspondence(
+        self,
+        prompt: str,
+        *,
+        twin_b: str | None = None,
+    ) -> pd.DataFrame:
+        """Map each transformer layer to regime, role, and top verbal intent."""
+        return build_layer_correspondence_map(
+            self.bundle,
+            prompt,
+            transport=self.transport,
+            twin_b=twin_b,
+        )
+
+    def intent_trace(
+        self,
+        prompt: str,
+        *,
+        track_tokens: list[str] | None = None,
+    ) -> IntentTrace:
+        """Build full J-space intent trace (layer thoughts)."""
+        return build_intent_trace(
+            self.bundle,
+            prompt,
+            transport=self.transport,
+            track_tokens=track_tokens,
+        )
+
+    def layer_band_summary(self, prompt: str) -> dict:
+        return summarize_layer_bands(self.bundle, prompt, transport=self.transport)
+
+    def fit_transport(self, prompts: list[str]) -> TransportMaps:
+        self.transport = fit_transport_maps(self.bundle, prompts)
+        return self.transport
+
+    def query_concept(
+        self,
+        concept: str,
+        prompt: str,
+        *,
+        twin_b: str | None = None,
+        top_k_layers: int = 5,
+    ) -> ConceptQueryResult:
+        """
+        Query a semantic concept against the activation trajectory.
+
+        Uses KL + twin Barlow feature space with KNN retrieval to identify
+        which layers activate for the given concept text.
+        """
+        cognitive = None
+        if twin_b:
+            cognitive = build_cognitive_module_profile(
+                self.bundle,
+                prompt,
+                twin_b,
+                transport=self.transport,
+            )
+        return query_concept_in_trajectory(
+            self.bundle,
+            concept,
+            prompt,
+            twin_b=twin_b,
+            top_k_layers=top_k_layers,
+            cognitive_profile=cognitive,
+        )
+
+    def query_concepts(
+        self,
+        concepts: list[str],
+        prompt: str,
+        *,
+        twin_b: str | None = None,
+    ) -> dict[str, ConceptQueryResult]:
+        return query_concepts_batch(
+            self.bundle,
+            concepts,
+            prompt,
+            twin_b=twin_b,
+        )
+
+    def trajectory_map(
+        self,
+        prompt: str,
+        *,
+        twin_b: str | None = None,
+        concepts: list[str] | None = None,
+    ) -> TrajectoryMapping:
+        """Build unified activation trajectory mapping across all layers."""
+        return build_trajectory_mapping(
+            self.bundle,
+            prompt,
+            twin_b=twin_b,
+            transport=self.transport,
+            concepts=concepts,
+        )
+
+    def visualizer(self, output_dir: str = "llmintent_viz"):
+        """Return a VisualizationSuite for maps, correlations, and animations."""
+        from llmintent.viz import VisualizationSuite
+
+        return VisualizationSuite(self.bundle, output_dir=output_dir)
+
+    def visualize_report(
+        self,
+        prompt: str,
+        *,
+        twin_b: str | None = None,
+        concepts: list[str] | None = None,
+        output_dir: str = "llmintent_viz",
+        include_morphemes: bool = False,
+    ) -> dict[str, str]:
+        """Generate full visualization report (maps, correlations, animations)."""
+        viz = self.visualizer(output_dir=output_dir)
+        block_semantics = self.extract_block_semantics() if include_morphemes else None
+        return viz.render_full_report(
+            prompt,
+            twin_b=twin_b,
+            concepts=concepts,
+            block_semantics=block_semantics,
+        )
+
+    def heighten_framework(self, focus_threshold: float = 0.45):
+        """Return HeightenedReasoningFramework for retrace-based focus sharpening."""
+        from llmintent.heighten import HeightenedReasoningFramework
+
+        return HeightenedReasoningFramework(
+            self.bundle,
+            transport=self.transport,
+            focus_threshold=focus_threshold,
+        )
+
+    def diagnose_focus(
+        self,
+        prompt: str,
+        *,
+        anchor_prompt: str | None = None,
+        concepts: list[str] | None = None,
+    ):
+        """Measure how focused reasoning is for a prompt trajectory."""
+        return self.heighten_framework().diagnose_focus(
+            prompt,
+            anchor_prompt=anchor_prompt,
+            concepts=concepts,
+        )
+
+    def heighten_reasoning(
+        self,
+        prompt: str,
+        *,
+        anchor_prompt: str | None = None,
+        concepts: list[str] | None = None,
+        mode: str = "explicit_retrace",
+        apply_steering: bool = False,
+    ):
+        """
+        Heighten reasoning by forcing a self-retrace and measuring focus gain.
+
+        Uses retrace prompt scaffolding + optional activation steering at
+        reasoning layers to sharpen concept-peaked, layer-concentrated computation.
+        """
+        from llmintent.heighten import RetraceMode, heighten_reasoning
+
+        retrace_mode = RetraceMode(mode) if isinstance(mode, str) else mode
+        return heighten_reasoning(
+            self.bundle,
+            prompt,
+            anchor_prompt=anchor_prompt,
+            concepts=concepts,
+            mode=retrace_mode,
+            transport=self.transport,
+            apply_steering=apply_steering,
+        )
+
+    def compare_prompts(
+        self,
+        prompts: dict[str, str],
+    ) -> pd.DataFrame:
+        """Multi-prompt intensity sweep (Direct vs CoT, ablation levels, etc.)."""
+        return run_intensity_sweep(self.bundle, prompts, self.numerical_pole)
+
+    def stress_test(self, simple: str, complex: str) -> pd.DataFrame:
+        return run_stress_test(self.bundle, simple, complex)
+
+    def activation_profile(self, prompt: str) -> pd.DataFrame:
+        return activation_summary(self.bundle, prompt)
+
+    def extract_block_semantics(self, max_layers: int | None = None) -> dict[int, dict[str, list[str]]]:
+        if not self.embedding_space:
+            raise RuntimeError("GloVe embeddings required for block semantics")
+        layers = get_transformer_layers(self.bundle.model)
+        limit = max_layers or len(layers)
+        out: dict[int, dict[str, list[str]]] = {}
+        for idx, layer in enumerate(layers[:limit]):
+            try:
+                out[idx] = get_block_semantics(
+                    layer,
+                    self.embedding_space,
+                    self.morpheme_freq,
+                    extractor=self.extractor,
+                )
+            except AttributeError:
+                continue
+        return out
+
+    def block_expertise_report(self, max_layers: int | None = None) -> pd.DataFrame:
+        semantics = self.extract_block_semantics(max_layers=max_layers)
+        rows: list[dict[str, str | int]] = []
+        for layer_idx, block in semantics.items():
+            expertise = get_block_expertise(block)
+            for component, units in block.items():
+                rows.append(
+                    {
+                        "layer": layer_idx,
+                        "expertise": expertise,
+                        "component": component,
+                        "top_units": ", ".join(units[:5]),
+                    }
+                )
+        return pd.DataFrame(rows)
+
+    def _default_pivot(self) -> int:
+        canonical = 18
+        canonical_depth = 48
+        scaled = int(round(canonical / canonical_depth * self.bundle.num_layers))
+        return max(1, min(scaled, self.bundle.num_layers - 1))
+
+    def cleanup(self) -> None:
+        del self.bundle
+        gc.collect()
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()

llmintent/benchmark/__init__.py

@@ -0,0 +1,43 @@
+"""Benchmark suite: HellaSwag validation with retrace ablations on SLMs."""
+
+from llmintent.benchmark.ablation import (
+    AblationCondition,
+    DEFAULT_ABLATION_SUITE,
+    FAST_ABLATION_SUITE,
+    parse_conditions,
+)
+from llmintent.benchmark.hellaswag import (
+    HellaSwagExample,
+    hellaswag_accuracy,
+    load_hellaswag,
+    load_hellaswag_fallback,
+    score_hellaswag_example,
+)
+from llmintent.benchmark.retrace_store import RetraceStore, StoredRetracement
+from llmintent.benchmark.runner import (
+    BenchmarkRunConfig,
+    ConditionResult,
+    HellaSwagBenchmarkRunner,
+    prepare_slm_comparison,
+)
+from llmintent.benchmark.slm_registry import DEFAULT_SLMS, get_slm, list_slms
+
+__all__ = [
+    "AblationCondition",
+    "BenchmarkRunConfig",
+    "ConditionResult",
+    "DEFAULT_ABLATION_SUITE",
+    "FAST_ABLATION_SUITE",
+    "HellaSwagBenchmarkRunner",
+    "HellaSwagExample",
+    "RetraceStore",
+    "StoredRetracement",
+    "get_slm",
+    "hellaswag_accuracy",
+    "list_slms",
+    "load_hellaswag",
+    "load_hellaswag_fallback",
+    "parse_conditions",
+    "prepare_slm_comparison",
+    "score_hellaswag_example",
+]