hypertopos 0.7.2__tar.gz → 0.7.3__tar.gz

{hypertopos-0.7.2 → hypertopos-0.7.3}/CHANGELOG.md

@@ -7,6 +7,28 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.7.3] — 2026-05-27
+
+### Added
+
+- `GDSNavigator.π12_attract_regime_change` (and its cache fast-path) — each detected changepoint now carries a `near_data_boundary: bool` field. Fires `True` when the changepoint timestamp index falls in the first two or last two temporal buckets of the filtered range — agents can suppress these as low-confidence detections sitting on insufficient one-sided context (the buckets at the data range edges have asymmetric neighbours, which inflates the shift magnitude). Applies to both the cache fast-path (`_pi12_from_cache`) and the cold-scan path; no schema change.
+- `Pattern.signed_percentiles` — per-pattern percentile cache (`p1`, `p5`, `p50`, `p95`, `p99`) over the `delta_norm_signed` Lance column, populated at build time when label-aware calibration fires. Drives the new `signed_tail_concentration` dim_quality warning that flags one-sided extreme tails (`|p99| / max(|p50|, 1e-9) > 50`) on the Fisher LDA-projected delta distribution; suppressed when `Pattern.label_aware_n_pos < 30` to avoid noise from undersampled positive classes.
+- `GDSEngine.decompose_displacement(delta, label_direction)` — pure-math helper that splits a polygon delta vector along (`intrinsic`) and orthogonal to (`extrinsic`) any label-discriminating axis, satisfying `intrinsic^2 + extrinsic^2 == ||delta||^2`. Pattern-level means `intrinsic_displacement_mean` / `extrinsic_displacement_mean` are persisted on `Pattern` at build time when label-aware calibration fires.
+- `Pattern.label_aware_n_pos` / `Pattern.label_aware_n_neg` — positive / negative labelled sample counts captured at build time, co-populated with `label_aware_calibration`.
+- `GDSNavigator.chain_signed_confidence_rollup(chain_id, chain_pattern=..., anchor_pattern=...)` — chain-level reliability rollup derived from per-member `signed_confidence` ranking on the anchor pattern. Returns `chain_mean_signed_confidence`, `chain_n_low_confidence_members`, `chain_n_single_dim_driven_members`, and `chain_confidence_verdict` ∈ {high, medium, low, label-aware-unavailable}. Falls back cleanly with verdict `"label-aware-unavailable"` and null numeric fields when the anchor pattern lacks `label_aware_calibration`.
+- `GDSNavigator.aggregate` per-entity result rows gain `anomaly_rate: float | null` — fraction of an entity's events flagged anomalous (`delta_norm >= theta_diag`). `null` when entity has zero events or pattern lacks anomaly threshold.
+- `GDSNavigator.sphere_overview` gains `cross_pattern_discrepancy: dict | null` — pairwise Jaccard overlap of anomalous primary_keys across cover-overlapping patterns. Lists pairs with `pattern_a`, `pattern_b`, `shared_line`, the four anomaly-bucket counts, and `jaccard_anomaly_overlap`. `null` on spheres with fewer than two cover-overlapping patterns.
+- `GDSNavigator.find_anomalies(..., sample_size: int | None = None, boundary_aware: bool = False)` — opt-in sampling for the in-process scan path. `sample_size` caps geometry rows scored; `boundary_aware=True` allocates half the budget to entities within the `[0.8 * theta_norm, 1.2 * theta_norm]` band around the decision threshold, the other half drawn from the rest of the population. Defaults preserve the existing full-scan behaviour. `boundary_aware=True` requires `sample_size` to be set.
+- `engine.topology.classify_trajectory(solid_table, *, sample_size=10000)` — wraps `trajectory_continuous_score` with a deterministic 4-category classifier (`outlier` / `lagging` / `leading` / `typical`). Combines DTW distance against the population-median trajectory with a first-derivative slope comparison via `scipy.stats.linregress`. Returns a list of `{primary_key, dtw_distance, category, category_evidence}` per entity, with `category_evidence` carrying the signed deviation that drove the classification.
+- `GDSNavigator.classify_trajectory(primary_key, pattern_id, sample_size=10000)` — per-entity navigator wrapper that streams temporal `shape_snapshot` rows, projects to `delta_snapshot` via the pattern's `(mu, sigma_diag)`, and returns the classification for the requested entity.
+- `sphere.yaml` `graph_features.features:` accepts a new token — `community_id` — Louvain modularity-optimizing community detection on the anchor-pattern graph. `igraph.Graph.community_multilevel` when igraph is installed; `networkx.algorithms.community.louvain_communities` otherwise; gracefully emits an empty mapping (caller fills nulls) when neither backend is available. Community IDs are renumbered so the largest community is `0`.
+- `graph_features.features:` `pagerank` and `connected_component` now route through pure-numpy helpers (damped PageRank with damping `0.85`, max `100` iterations, L2 convergence threshold `1e-6`; Union-Find connected components with path compression and union-by-rank). No external graph library is required for these two; igraph remains optional and is used only for the other features in the block.
+- `engine.graph.compute_pagerank`, `compute_louvain_community`, `compute_connected_components`, `compute_from_adjacency` — pure helpers exposed for direct use on an `AdjacencyIndex`. PageRank parameters (`damping`, `max_iter`, `tol`) are configurable per call.
+- `GDSNavigator.find_calibration_influencers(..., auto_discover: bool = False, auto_k: int = 10)` — auto-discovery mode runs k-means on the pattern's geometry, surfaces top-K candidate influencers from cluster centroids, then ranks each by existing μ-impact algorithm. Returns the existing shape extended with per-candidate `cluster_size` and `cluster_centroid_distance`. Default `auto_discover=False` preserves manual mode requiring caller-supplied candidate_keys.
+- `GDSNavigator.calibration_influencer_history(primary_key, *, pattern_id)` — per-epoch μ-impact history for a known influencer. Lazily populated write-through cache at `_gds_meta/calibration_history/<pattern>/influencer_<primary_key>.json`. Returns chronological list of `{epoch, calibrated_at, mu_impact, delta_norm_impact}` entries. Empty list + warning when cache absent.
+- `engine.topology.local_trajectory_shape(delta_norms)` — pure-function classifier that categorises an entity's own `delta_norm` time-series as `arch` / `V` / `linear` / `flat` without requiring a population reference. Returns `None` when fewer than three samples are available. Used by `dive_solid` to surface trajectory shape on the entity's temporal slices.
+- `Navigator.find_similar_entities(..., with_neighbor_anomaly=False)` — opt-in flag triggers a single point lookup over the returned top-N neighbour keys and populates the `SimilarityResult.is_anomaly_map` sidecar with stored anomaly flags. Existing 2-tuple iteration is preserved.
+
 ## [0.7.2] — 2026-05-21
 
 ### Added

{hypertopos-0.7.2 → hypertopos-0.7.3}/LICENSE.md

@@ -26,7 +26,7 @@ For purposes of this License:
 - **Internal use** within an organization is not a competitive offering. Your
   organization includes entities under common control.
 
-**Change Date:** 2029-05-21
+**Change Date:** 2029-05-27
 
 **Change License:** Apache License, Version 2.0
 

{hypertopos-0.7.2 → hypertopos-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypertopos
-Version: 0.7.2
+Version: 0.7.3
 Summary: Understand the structure of your data — without training machine learning models
 Project-URL: Homepage, https://github.com/hypertopos/hypertopos-py
 Project-URL: Documentation, https://github.com/hypertopos/hypertopos-py/tree/main/docs

{hypertopos-0.7.2 → hypertopos-0.7.3}/README.md

@@ -9,7 +9,7 @@
 [![PyArrow](https://img.shields.io/badge/format-PyArrow-red.svg)](https://arrow.apache.org/docs/python/)
 [![Lance](https://img.shields.io/badge/storage-Lance-blueviolet.svg)](https://github.com/lance-format/lance)
 [![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)
-[![Version](https://img.shields.io/badge/version-0.7.2-%235500FF.svg)](pyproject.toml)
+[![Version](https://img.shields.io/badge/version-0.7.3-%235500FF.svg)](pyproject.toml)
 
 hypertopos is not a database, and not a machine learning model. It is a layer that turns relational data into a coordinate system where every entity gets a position derived from its relationships and the population around it.
 

{hypertopos-0.7.2 → hypertopos-0.7.3}/ROADMAP.md

@@ -7,6 +7,9 @@
 Detector composition and counterfactual primitives on native Lance MVCC — multi-detector consensus, per-edge / joint / per-counterparty influence math, topological cycle persistence, multi-resolution FDR, and the entity-side investigation orchestrator land on a modernized Lance 6.0 storage substrate with sphere format 3.0.
 
 - **0.7.0** — Lance 4.0 → 6.0 bump; sphere format 2.4 → 3.0 (breaking — single Lance dataset per pattern, calibration epochs tagged `epoch_<N>`, no migration tool); Wilson HMP combiner + `combine_anomaly_pvalues` + `classify_detector_consensus` over five orthogonal anomaly axes; counterfactual family (`simulate_edge_removal`, `select_minimal_joint_edge_removal`, `simulate_counterparty_removal`); `find_topological_anomalies` H_1 cycle persistence + `find_topological_trajectory_anomalies`; `find_graph_geometry_tension` 2×2 behavioural-vs-graph cross-tab; multi-resolution FDR with `Pattern.fdr_hierarchy` + `fdr_temporal_hierarchy`; per-dim FDR axis + `rank_by="min_q_per_dim"`; `investigate_entity` orchestrator; `edge_curvature_frc` Forman-Ricci edge dimension; `reliability_flags` triage on five primitive outputs; `composite_risk` switches Fisher → HMP.
+- **0.7.1** — label-aware calibration foundation: `label_audit:` YAML block, per-class μ/σ + Cohen's d + Fisher LDA direction on `Pattern`, `delta_norm_signed` Lance column, `audit_pattern_dims` full per-class field path, Levene's test homoscedasticity diagnostic in `dim_quality_warnings`.
+- **0.7.2** — composition orchestrators on the 0.7.1 foundation: `find_anomalies(rank_by="signed_confidence")`, `chain_full_loop_summary` chain-side mirror of `investigate_entity`, `audit_label_alignment` Fisher LDA AUROC sibling to `audit_pattern_dims`, `kind_mismatch` warning + `recommended_action="kind_mismatch_review"`, `dive_solid(counterfactual_frozen_population=True)`, `Chain.to_dict() edge_potentials`, `changelog.d/` per-PR fragments convention.
+- **0.7.3** — detector-composition continuation + investigation-orchestrator surface: per-dim AUROC + intrinsic / extrinsic decomposition on `audit_pattern_dims`, `signed_tail_concentration` warning, chain reliability rollup on `chain_full_loop_summary`, `find_anomalies(sample_size, boundary_aware)`, `classify_trajectory` + `local_trajectory_shape`, `sphere_overview.cross_pattern_discrepancy` + per-row `anomaly_rate`, `community_id` graph feature + pure-NumPy `pagerank` / `connected_component`, `find_calibration_influencers(auto_discover=True)` + `calibration_influencer_history`, `π12_attract_regime_change.near_data_boundary` flag, `find_similar_entities(with_neighbor_anomaly=True)`, `passive_scan` interpretation hint, `dive_solid.trajectory_shape`.
 
 See [CHANGELOG](CHANGELOG.md) for the full feature list.
 

{hypertopos-0.7.2 → hypertopos-0.7.3}/SECURITY.md

@@ -1,6 +1,6 @@
 # Security
 
-## Current version: 0.7.2
+## Current version: 0.7.3
 
 hypertopos runs locally. No network services, no auth layer, no multi-tenancy.
 

{hypertopos-0.7.2 → hypertopos-0.7.3}/hypertopos/__init__.py

@@ -44,4 +44,4 @@ __all__ = [
     "IntrinsicExtrinsicReport",
     "LeadLagReport",
 ]
-__version__ = "0.7.2"
+__version__ = "0.7.3"

{hypertopos-0.7.2 → hypertopos-0.7.3}/hypertopos/builder/builder.py

@@ -624,6 +624,15 @@ class PatternBuildResult:
     # into sphere.json as ``label_aware_calibration`` and hydrated back
     # into ``Pattern.label_aware_calibration`` by the storage reader.
     label_aware_calibration: dict[str, Any] | None = None
+    # Co-populated with ``label_aware_calibration`` — positive / negative
+    # labelled sample counts and the percentiles + intrinsic / extrinsic
+    # displacement means computed from the signed delta projection. ``None``
+    # on patterns without label-aware calibration.
+    label_aware_n_pos: int | None = None
+    label_aware_n_neg: int | None = None
+    signed_percentiles: dict[str, float] | None = None
+    intrinsic_displacement_mean: float | None = None
+    extrinsic_displacement_mean: float | None = None
 
 
 @dataclass
@@ -822,7 +831,8 @@ class GDSBuilder:
     ) -> dict[str, Any] | None:
         """Fit label-aware per-dim calibration when the pattern opts in.
 
-        Returns the per-dim mapping ``{dim_label: DimCalibration}`` and
+        Returns a bundle ``{"per_dim": {dim_label: DimCalibration},
+        "n_pos": int, "n_neg": int, "direction": np.ndarray}`` and
         registers the global Fisher LDA direction in
         ``self._label_aware_directions[pat.pattern_id]`` so the downstream
         geometry pass can populate ``delta_norm_signed``. Returns ``None``
@@ -924,10 +934,16 @@ class GDSBuilder:
             )
             return None
 
-        self._label_aware_directions[pat.pattern_id] = np.asarray(
+        direction_vec = np.asarray(
             result.signed_direction_vector, dtype=np.float32,
         )
-        return dict(result.per_dim)
+        self._label_aware_directions[pat.pattern_id] = direction_vec
+        return {
+            "per_dim": dict(result.per_dim),
+            "n_pos": int(result.n_pos),
+            "n_neg": int(result.n_neg),
+            "direction": direction_vec,
+        }
 
     def add_line(
         self,
@@ -2916,6 +2932,105 @@ class GDSBuilder:
 
         return result
 
+    @staticmethod
+    def _unpack_lac_bundle(
+        lac_bundle: dict[str, Any] | None,
+        deltas: np.ndarray | None,
+    ) -> dict[str, Any]:
+        """Translate the ``_run_label_aware_calibration`` bundle into
+        PBR kwargs.
+
+        Returns a dict with keys ``label_aware_calibration``,
+        ``label_aware_n_pos``, ``label_aware_n_neg``,
+        ``signed_percentiles``, ``intrinsic_displacement_mean``,
+        ``extrinsic_displacement_mean`` — every value ``None`` when the
+        bundle is missing or the delta matrix is unavailable, ready to
+        splat into PatternBuildResult.
+        """
+        if lac_bundle is None or deltas is None or deltas.ndim != 2:
+            return {
+                "label_aware_calibration": None,
+                "label_aware_n_pos": None,
+                "label_aware_n_neg": None,
+                "signed_percentiles": None,
+                "intrinsic_displacement_mean": None,
+                "extrinsic_displacement_mean": None,
+            }
+        direction = lac_bundle.get("direction")
+        if direction is None or direction.shape[0] != deltas.shape[1]:
+            return {
+                "label_aware_calibration": lac_bundle.get("per_dim"),
+                "label_aware_n_pos": lac_bundle.get("n_pos"),
+                "label_aware_n_neg": lac_bundle.get("n_neg"),
+                "signed_percentiles": None,
+                "intrinsic_displacement_mean": None,
+                "extrinsic_displacement_mean": None,
+            }
+        signed_p, intr_mean, extr_mean = (
+            GDSBuilder._compute_signed_artefacts(deltas, direction)
+        )
+        return {
+            "label_aware_calibration": lac_bundle.get("per_dim"),
+            "label_aware_n_pos": lac_bundle.get("n_pos"),
+            "label_aware_n_neg": lac_bundle.get("n_neg"),
+            "signed_percentiles": signed_p or None,
+            "intrinsic_displacement_mean": intr_mean,
+            "extrinsic_displacement_mean": extr_mean,
+        }
+
+    @staticmethod
+    def _compute_signed_artefacts(
+        deltas: np.ndarray,
+        direction: np.ndarray,
+    ) -> tuple[dict[str, float], float, float]:
+        """Derive signed-projection artefacts from deltas + Fisher direction.
+
+        Computes:
+
+        - ``signed_percentiles``: dict with keys ``p1``, ``p5``, ``p50``,
+          ``p95``, ``p99`` of the signed projection
+          ``deltas @ direction_unit``. The LDA fit returns a unit-norm
+          direction so today's caller passes the same vector the
+          geometry pass uses to populate ``delta_norm_signed``; we still
+          normalise defensively so any future non-unit caller gets the
+          contract everyone else assumes.
+        - ``intrinsic_displacement_mean``: mean of
+          ``|delta . direction_unit|`` across rows. Magnitude of motion
+          along the label axis.
+        - ``extrinsic_displacement_mean``: mean of
+          ``sqrt(||delta||^2 - intrinsic^2)`` across rows. Magnitude of
+          motion orthogonal to the label axis.
+
+        Returns empty percentiles dict + (0.0, 0.0) when the delta matrix
+        is empty or the direction is the zero vector.
+        """
+        if deltas.ndim != 2 or deltas.shape[0] == 0:
+            return {}, 0.0, 0.0
+        d = deltas.astype(np.float64, copy=False)
+        v = direction.astype(np.float64, copy=False)
+        v_norm = float(np.linalg.norm(v))
+        if v_norm <= 0.0:
+            return {}, 0.0, 0.0
+        v = v / v_norm
+        projected = d @ v
+        percs = np.percentile(projected, [1, 5, 50, 95, 99])
+        signed_percentiles = {
+            "p1": round(float(percs[0]), 4),
+            "p5": round(float(percs[1]), 4),
+            "p50": round(float(percs[2]), 4),
+            "p95": round(float(percs[3]), 4),
+            "p99": round(float(percs[4]), 4),
+        }
+        intrinsic = np.abs(projected)
+        row_norms_sq = np.einsum("ij,ij->i", d, d)
+        residual_sq = np.maximum(row_norms_sq - intrinsic * intrinsic, 0.0)
+        extrinsic = np.sqrt(residual_sq)
+        return (
+            signed_percentiles,
+            float(intrinsic.mean()),
+            float(extrinsic.mean()),
+        )
+
     def _compute_dim_percentiles(
         self,
         entity_line_id: str,
@@ -3221,6 +3336,20 @@ class GDSBuilder:
                     }
                     for label, dc in pbr.label_aware_calibration.items()
                 }
+                if pbr.label_aware_n_pos is not None:
+                    pat_dict["label_aware_n_pos"] = int(pbr.label_aware_n_pos)
+                if pbr.label_aware_n_neg is not None:
+                    pat_dict["label_aware_n_neg"] = int(pbr.label_aware_n_neg)
+                if pbr.signed_percentiles:
+                    pat_dict["signed_percentiles"] = pbr.signed_percentiles
+                if pbr.intrinsic_displacement_mean is not None:
+                    pat_dict["intrinsic_displacement_mean"] = float(
+                        pbr.intrinsic_displacement_mean,
+                    )
+                if pbr.extrinsic_displacement_mean is not None:
+                    pat_dict["extrinsic_displacement_mean"] = float(
+                        pbr.extrinsic_displacement_mean,
+                    )
             if pat.description:
                 pat_dict["description"] = pat.description
             if pat.fdr_hierarchy:
@@ -3767,7 +3896,7 @@ class GDSBuilder:
                     edge_dim_agg_labels=ps.edge_dim_agg_labels,
                 ),
                 edge_dim_names=ps.edge_dim_names,
-                label_aware_calibration=lac,
+                **self._unpack_lac_bundle(lac, ps.deltas),
             )
             self._write_calibration_epoch_for_pattern(pat, pbr)
             return pat_id, pbr
@@ -4671,7 +4800,7 @@ class GDSBuilder:
                 edge_dim_agg_labels=ps.edge_dim_agg_labels,
             ),
             edge_dim_names=ps.edge_dim_names,
-            label_aware_calibration=lac,
+            **self._unpack_lac_bundle(lac, ps.deltas),
         )
 
     def _build_shape_chunk(

{hypertopos-0.7.2 → hypertopos-0.7.3}/hypertopos/builder/derived.py

@@ -833,15 +833,39 @@ def compute_graph_features(
     # --- Graph algorithm features (computed on AdjacencyIndex) ---
     _ALGO_FEATURES = {
         "pagerank", "connected_component", "clustering_coefficient",
-        "community", "betweenness",
+        "community", "community_id", "betweenness",
     }
     needed_algos = _ALGO_FEATURES & set(features)
     if needed_algos:
-        from hypertopos.engine.graph_algorithms import compute_all_from_lists
-
         f_list = edges["_f"].to_pylist()
         t_list = edges["_t"].to_pylist()
-        algo_results = compute_all_from_lists(f_list, t_list, needed_algos)
+
+        # pagerank / community_id / connected_component go through engine.graph
+        # (pure-numpy / igraph→NetworkX fallback chain). Remaining algos
+        # (clustering_coefficient, betweenness, label-prop "community") stay
+        # on the igraph fast path in graph_algorithms.
+        algo_results: dict[str, dict] = {}
+        _GRAPH_HELPERS = {"pagerank", "community_id", "connected_component"}
+        helper_algos = _GRAPH_HELPERS & needed_algos
+        if helper_algos:
+            from hypertopos.engine.adjacency import AdjacencyIndex
+            from hypertopos.engine.graph import compute_from_adjacency
+            n_edges_lance = len(f_list)
+            adj_for_helpers = AdjacencyIndex.from_edge_lists(
+                f_list, t_list,
+                [0.0] * n_edges_lance, [0.0] * n_edges_lance,
+                [f"_e{i}" for i in range(n_edges_lance)],
+            )
+            algo_results.update(
+                compute_from_adjacency(adj_for_helpers, helper_algos),
+            )
+
+        remaining_algos = needed_algos - _GRAPH_HELPERS
+        if remaining_algos:
+            from hypertopos.engine.graph_algorithms import compute_all_from_lists
+            algo_results.update(
+                compute_all_from_lists(f_list, t_list, remaining_algos),
+            )
 
         _EDGE_MAX_OVERRIDES = {
             "clustering_coefficient": 1,
@@ -853,7 +877,7 @@ def compute_graph_features(
                 idx = key_to_idx.get(k)
                 if idx is not None:
                     vals[idx] = float(v)
-            if feat_name in ("connected_component", "community"):
+            if feat_name in ("connected_component", "community", "community_id"):
                 n_unique = len(set(scores.values())) if scores else 1
                 edge_max = max(n_unique - 1, 1)
             elif feat_name in _EDGE_MAX_OVERRIDES:
@@ -898,7 +922,7 @@ def compute_graph_features_temporal(
     # PageRank/betweenness is meaningless and extremely expensive)
     STATIC_ONLY_FEATURES = {
         "pagerank", "connected_component", "clustering_coefficient",
-        "community", "betweenness",
+        "community", "community_id", "betweenness",
     }
     fast_indices = [i for i, f in enumerate(features) if f in FAST_FEATURES]
     need_recip = "reciprocity" in features

{hypertopos-0.7.2 → hypertopos-0.7.3}/hypertopos/engine/aggregation.py

@@ -638,6 +638,18 @@ def aggregate(
                             f"with a '{group_by_line}' edge. "
                             f"Use anomaly_summary for population-wide totals."
                         )
+                # Per-group anomaly_rate enrichment also runs on the reversed-scan
+                # fast path so the field is uniformly present regardless of which
+                # execution branch produced the counts.
+                if _should_emit_per_group_anomaly_rate(
+                    False, metric, group_by_property, pivot_event_field,
+                    group_by_line_2, distinct, result,
+                ):
+                    _enrich_per_group_anomaly_rate(
+                        reader, event_pattern_id, pattern, group_by_line,
+                        edge_col="entity_keys",
+                        result=result,
+                    )
                 return result
             except Exception:
                 pass  # Fall through to read_geometry path
@@ -2185,4 +2197,105 @@ def aggregate(
                 row["total_events"] = total
                 row["anomaly_rate"] = round(row["count"] / total, 4) if total > 0 else 0.0
 
+    # --- Per-group anomaly_rate enrichment (inverse of _anomaly_rate_requested) ---
+    # When metric='count' without an is_anomaly filter, each row['count'] is the
+    # total event count for the group. Surface the share of anomalous events by
+    # doing a second read filtered to is_anomaly=True and dividing.
+    # Skipped when the existing block already wrote anomaly_rate (above), when
+    # the metric is not 'count' (rate is undefined for sum/avg/median), when
+    # composite keys are used (group_by_property / pivot_event_field /
+    # group_by_line_2 — the row key is not a single group_by_line edge target),
+    # and when no rows were returned.
+    if _should_emit_per_group_anomaly_rate(
+        _anomaly_rate_requested, metric, group_by_property, pivot_event_field,
+        group_by_line_2, distinct, result,
+    ):
+        _enrich_per_group_anomaly_rate(
+            reader, event_pattern_id, pattern, group_by_line,
+            edge_col=("entity_keys" if "entity_keys" in geo.schema.names else "edges"),
+            result=result,
+        )
+
     return result
+
+
+def _should_emit_per_group_anomaly_rate(
+    anomaly_rate_requested: bool,
+    metric: str,
+    group_by_property: str | None,
+    pivot_event_field: str | None,
+    group_by_line_2: str | None,
+    distinct: bool,
+    result: dict,
+) -> bool:
+    """Predicate for the inverse anomaly_rate enrichment.
+
+    Triggers when the row's ``count`` is the total event count for the group
+    (per-row composite keys excluded) and the existing "filter-by-is_anomaly"
+    block has not already attached ``anomaly_rate`` to each row.
+    """
+    return (
+        not anomaly_rate_requested
+        and metric == "count"
+        and not group_by_property
+        and not pivot_event_field
+        and not group_by_line_2
+        and not distinct
+        and bool(result.get("results"))
+    )
+
+
+def _enrich_per_group_anomaly_rate(
+    reader: Any,
+    event_pattern_id: str,
+    pattern: Any,
+    group_by_line: str,
+    *,
+    edge_col: str,
+    result: dict,
+) -> None:
+    """Attach ``anomaly_rate = n_anomalous_in_group / total_in_group`` per row.
+
+    Performs one extra geometry read scoped to two columns (``is_anomaly`` +
+    edge column) with a Lance ``is_anomaly = true`` filter pushed down via
+    the bitmap index so only anomalous rows materialise. Counts anomalous
+    edges per group and divides into the row's existing ``count``.
+    ``anomaly_rate`` is ``None`` when the group's total count is zero.
+    The field is omitted when the geometry on disk has no ``is_anomaly``
+    column (degraded / pre-schema spheres) — no zero-div crash, no
+    spurious value.
+    """
+    try:
+        raw = reader.read_geometry(
+            event_pattern_id, pattern.version,
+            columns=["is_anomaly", edge_col],
+            filter="is_anomaly = true",
+        )
+    except Exception:
+        # Reader rejected the filter syntax (mock / pre-Lance reader) — fall
+        # back to a no-filter read; the in-process predicate below still
+        # narrows to anomalous rows.
+        raw = reader.read_geometry(
+            event_pattern_id, pattern.version,
+            columns=["is_anomaly", edge_col],
+        )
+    if "is_anomaly" not in raw.schema.names:
+        # Column was projected out (degraded / pre-schema sphere) —
+        # cannot compute the rate. Leave rows unannotated.
+        return
+    import pyarrow.compute as pc
+    # Apply the predicate in-process too — Lance may or may not honour the
+    # pushed-down filter (mock readers silently ignore it). This guarantees
+    # ``anom_only`` is strictly the anomalous subset regardless.
+    anom_only = raw.filter(pc.equal(raw["is_anomaly"], True))
+    anom_per_group, _ = _vectorized_count_with_warning(
+        anom_only, group_by_line, geometry_filters=None, relations=pattern.relations,
+    )
+    for row in result.get("results", []):
+        key = row.get("key")
+        total = row.get("count")
+        if key is None or total is None or total == 0:
+            row["anomaly_rate"] = None
+            continue
+        n_anom = anom_per_group.get(key, 0)
+        row["anomaly_rate"] = round(n_anom / total, 4)

{hypertopos-0.7.2 → hypertopos-0.7.3}/hypertopos/engine/geometry.py

@@ -178,6 +178,62 @@ class GDSEngine:
             delta = delta * pattern.dimension_weights
         return delta
 
+    @staticmethod
+    def decompose_displacement(
+        delta: np.ndarray,
+        label_direction: np.ndarray,
+    ) -> dict[str, float]:
+        """Decompose a single delta vector along the label-discriminating axis.
+
+        Splits ``delta`` into two scalar magnitudes:
+
+        - ``intrinsic`` = ``|delta . label_direction_unit|`` — magnitude of
+          the projection onto the unit-norm label direction. Captures how
+          far the entity moved along the axis that separates labelled
+          classes.
+        - ``extrinsic`` = ``sqrt(||delta||^2 - intrinsic^2)`` — magnitude of
+          the residual component orthogonal to the label axis.
+
+        Identity: ``intrinsic^2 + extrinsic^2 == ||delta||^2`` to floating
+        precision. ``label_direction`` is normalised internally — callers
+        may pass any non-zero vector.
+
+        This is the label-axis decomposition of a single polygon's delta
+        vector. It is NOT the calibration-drift intrinsic/extrinsic
+        decomposition (see ``_compute_intrinsic_extrinsic_decomposition``)
+        which splits drift between two calibration epochs into a
+        within-entity-shape component vs a coordinate-system component —
+        same vocabulary, different math.
+
+        Args:
+            delta: 1-D delta vector for one polygon.
+            label_direction: 1-D vector of the same length, must be
+                non-zero. Direction sense is irrelevant (``intrinsic``
+                is absolute-valued).
+
+        Returns:
+            ``{"intrinsic": float, "extrinsic": float}``. Both
+            non-negative. When ``label_direction`` is the zero vector
+            both values are 0.0 (no axis to project onto, no decomposition
+            defined).
+        """
+        d = np.asarray(delta, dtype=np.float64).ravel()
+        ld = np.asarray(label_direction, dtype=np.float64).ravel()
+        if d.shape != ld.shape:
+            raise ValueError(
+                f"delta and label_direction shape mismatch: "
+                f"{d.shape} vs {ld.shape}",
+            )
+        ld_norm = float(np.linalg.norm(ld))
+        if ld_norm <= 0.0:
+            return {"intrinsic": 0.0, "extrinsic": 0.0}
+        ld_unit = ld / ld_norm
+        intrinsic = float(abs(np.dot(d, ld_unit)))
+        d_sq = float(np.dot(d, d))
+        residual_sq = max(d_sq - intrinsic * intrinsic, 0.0)
+        extrinsic = float(np.sqrt(residual_sq))
+        return {"intrinsic": intrinsic, "extrinsic": extrinsic}
+
     def _polygon_to_shape_vector(
         self, polygon: Polygon, pattern: Pattern
     ) -> np.ndarray: