hypertopos 0.5.0__tar.gz → 0.5.2__tar.gz

{hypertopos-0.5.0 → hypertopos-0.5.2}/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to hypertopos will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.5.2] — 2026-04-28
+
+### Added
+- Two new closed-vocabulary motifs extending the 0.5.1 catalog:
+  - `split_recombine` — diamond scatter-gather: source S → k distinct intermediaries M = {m₁,…,mₖ} → single sink D, with stacked-bipartite temporal order (all split-hops precede all recombine-hops within the window). Seed picks whether to enumerate forward from the source (`direction="forward"`) or backward from the sink (`direction="backward"`). Default window 24h, `min_k` default 3. Covers AML scatter-gather smurfing, parallel layering, and concentrator/sink atoms (forward from source vs backward from sink) without amount gating — for amount-gated chains use `structuring`. Canonical definition follows Starnini et al. 2021 and the IBM AMLSim stacked-bipartite spec.
+  - `bipartite_burst` — complete K_{k,m} bipartite subgraph within a tight time window: k distinct sources each send to every one of m distinct sinks. Greedy single-core enumeration (not maximal): enumerate seed-as-source first, fall back to seed-as-sink. Parameters `min_k` (sources, default 3), `min_m` (sinks, default 3), default window 24h. Covers coordinated-burst and parallel-collusion atoms; complements `fan_out` + `fan_in` by requiring completeness on both sides rather than single-anchor density.
+- `score_motif` and `find_high_potential_motifs` accept `direction` (`split_recombine`) and `min_m` (`bipartite_burst`) parameters. `min_k` override now applies to `split_recombine` and `bipartite_burst` in addition to `fan_out` / `fan_in`. Registry size grows from 6 to 8.
+
+### Changed
+- chain_k motif enumerator now uses per-k adaptive frontier cap (k=3,4: 1000; k=5: 500; k=6: 250; k=7: 125; k=8: 100) instead of a static 1000-cap. Bounds worst-case FHPM cold latency at higher k while preserving the generous cap for k=3,4 where measurements show no fragility. Public API unchanged (k=3..8 still accepted); `frontier_truncated=true` may surface more often at higher k as a result.
+- Single-seed motif enumeration (fan_out, fan_in, cycle_2, cycle_3, structuring, chain_k) now delegates to the in-memory adjacency-path enumerator instead of issuing per-call Lance read_edges scans. Single source of truth per motif type — single-seed dispatch follows the same hot path as find_high_potential_motifs ranking.
+- `_score_motif_from_edges` batches endpoint delta reads into a single filtered Lance scan and reuses the warm AdjacencyIndex pair_counts cache, mirroring the fast-path used by find_high_potential_motifs. Cuts found=true scoring tail latency from O(num_edges × per-endpoint Lance read) to O(1) batched scan. trace_root_cause's motif_potential auto-attach branch benefits transitively.
+- bipartite_burst K-set intersection now starts from the smallest neighbour-set (size-ascending sink/source ordering) instead of alphabetic order, bounding the running intersection by the smallest set. Result identical (set intersection is commutative); protects against worst-case dense graphs where one sink dominates.
+- `_enumerate_structuring` no longer raises `GDSNavigationError` when the underlying edge table lacks an amount column. The post-refactor adjacency path always carries amounts (defaulting to 1.0 when unspecified), so the predicate `amt >= amt1_min` returns an empty result cleanly. Now consistent with how the other 7 motifs handle no-match.
+- cycle_3 motif enumerator now pre-filters intermediary candidates via 2-step adjacency traversal before the inner pair loop, skipping intermediaries that have no return-edge to the seed within the time window. Result equivalence preserved (semantic no-op on the candidate space).
+- bipartite_burst K_{k,m} dispatcher now pre-checks seed in/out degree before invoking the per-side enumerator. Correctness-preserving; skips fruitless fail-fast work for seeds that don't qualify on either side.
+
+## [0.5.1] — 2026-04-21
+
+### Added
+- Two new closed-vocabulary motifs extending the 0.5.0 structural catalog:
+  - `fan_in` — k distinct sources → one sink within a sliding time window, mirror of `fan_out`. Seed = sink. Surfaces concentrator/sink accounts (T13) and destination-side parallel layering (T12) as a single-call atomic query, so the agent no longer has to invert the graph by hand.
+  - `chain_k` — open directed chain A→B→…→Z of length `k` (3 ≤ k ≤ 8, k-1 edges), no cycle closure, no node revisit, strict monotone timestamps, total span ≤ window. Covers multi-stage layering typologies (T5 Long-Cycle Multi-Stage, T18 Multi-Jurisdiction Latency) that `cycle_3` and `structuring` could not express — `cycle_3` requires closure back to the seed and `structuring` is amount-gated with a 1h window; `chain_k` is the open-chain, amount-free variant that matches layering-over-days semantics. Each `chain_k` instance carries a `frontier_truncated: bool` flag — truthy when `_CHAIN_K_MAX_FRONTIER = 1000` was hit while expanding partial paths on at least one hop, signalling that the returned chains are real but the ranking may miss longer chains (recommended agent response: retry with a tighter `time_window_hours` or a lower `k`). Surfaces on both `score_motif` and `find_high_potential_motifs` result dicts.
+- `score_motif` and `find_high_potential_motifs` gain a `k` parameter (default 4, validated 3–8 for `chain_k`, ignored for other types). `k` participates in the ranking cache key so different chain lengths are cached separately. `score_motif` additionally gains a `min_k: int | None = None` override on the single-seed path — when provided (must be ≥ 1), it plumbs through to the `fan_out` / `fan_in` enumerators, so callers can check e.g. "is this sink fed by ≥ 10 distinct sources?" without falling back on `find_high_potential_motifs` and triggering a pattern-wide cold cache. When None (default), enumerators fall back to their built-in `min_k = 3`, preserving the original behaviour exactly. Ignored for motif types that don't accept it (`cycle_2`, `cycle_3`, `structuring`, `chain_k`).
+- `find_high_potential_motifs`'s `min_k` parameter now applies to `fan_in` in addition to `fan_out` (default 3).
+- Numeric stability for the motif catalog: every motif scorer returns `log_score` (sum of `log(edge_potential)` over non-zero edges, `-inf` when any edge is zero) and `score_clamped: bool` alongside `score`. The raw `score` is clamped at `_MOTIF_SCORE_MAX = 1e300` when the edge-potential product would overflow (mirror of the existing `_MOTIF_SCORE_EPSILON = 1e-30` underflow clamp), and the ranking sort key in `_rank_motifs` switched from `-score` to `-log_score` so large-`k` motifs rank correctly regardless of clamp. Observed on AML HI-small: `fan_out` / `fan_in` hubs with k in the low thousands produced `score = +inf` that survived JSON serialisation, tied `score_rank_pct` to `100.0` across every affected result, and destroyed ordering at the top of the ranking.
+
+### Fixed
+- `passive_scan` chain and composite sources report entity-specific `related_count` instead of the total pattern population count.
+- `detect_trajectory_anomaly` navigator method accepts `sample_size` to cap entity streaming on large patterns.
+- Builder writes `null` (not `0.0`) for `anomaly_confidence` when bootstrap is skipped, preventing agents from misinterpreting zero as a computed confidence score.
+- Single-seed motif enumerators for `fan_out`, `cycle_2`, and `cycle_3` computed their time-window threshold in microseconds against float-seconds timestamps (`EDGE_TABLE_SCHEMA` declares `timestamp: float64` = epoch seconds, as produced by `builder._to_epoch_seconds`). The µs-scaled threshold could never be exceeded by seconds-scale deltas, silently disabling the window filter in production — `score_motif(entity, motif_type, pattern_id, time_window_hours=H)` returned results as if no window was set. Flipped all three enumerators to seconds arithmetic, matching `_enumerate_structuring`, every `_enum_*_via_adj` adjacency path, and the new `_enumerate_fan_in` / `_enumerate_chain_k`. **Observable behaviour change on `score_motif`** for these three motif types: users who relied on the broken "all-time" behaviour may see fewer results on narrow windows. `find_high_potential_motifs` is unaffected (its adjacency ranking path was already correct). Test helper `_hour_us` retired in favour of `_hour_sec` so fixture semantics align with the production edge table; five tight-window parity regression guards (one per migrated enumerator plus the two shipping with the new motifs) prevent future unit reversion.
+
 ## [0.5.0] — 2026-04-19
 
 ### Added

{hypertopos-0.5.0 → hypertopos-0.5.2}/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-04-19
+**Change Date:** 2029-04-28
 
 **Change License:** Apache License, Version 2.0
 

{hypertopos-0.5.0 → hypertopos-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypertopos
-Version: 0.5.0
+Version: 0.5.2
 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.5.0 → hypertopos-0.5.2}/README.md

@@ -8,7 +8,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.5.0-%235500FF.svg)](pyproject.toml)
+[![Version](https://img.shields.io/badge/version-0.5.2-%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.
 
@@ -57,6 +57,8 @@ Each capability below emerges from treating entities as points in a shared, popu
 | One-call root cause | `trace_root_cause` returns bounded evidence DAG — witness, edge-counterparty, contamination, hub | Manual chain of `explain_anomaly → find_counterparties → contagion_score → π7 hub` | `0.5.0` |
 | Geometric edge potential | `\|\|delta_from − delta_to\|\| × (1/pair_tx_count)` — per-edge layering signature | Node-level `delta_norm` misses one-off transactions between divergent accounts | `0.5.0` |
 | Structural motif scoring | Product of `edge_potential` across closed-vocab motifs (fan_out, cycle_2, cycle_3, structuring) | Graph DB motif matching has no geometric rarity score | `0.5.0` |
+| Extended motif catalog | `fan_in` (sink-centric concentrator) and `chain_k` (open directed chain, 3 ≤ k ≤ 8) extend the motif vocabulary; window-filter correctness fix on fan_out/cycle_2/cycle_3 | Prior motifs silently ignored declared `time_window_hours` in production | `0.5.1` |
+| Bipartite motif catalog | `split_recombine` (diamond scatter-gather S → k intermediaries → D, forward/backward seed anchoring) and `bipartite_burst` (complete K_{k,m} bipartite subgraph in tight window) cover scatter-gather smurfing, parallel layering, and coordinated-burst atoms | Closed-vocabulary atomic queries — no manual graph inversion or per-side enumeration glue | `0.5.2` |
 
 ### What changes in practice
 

{hypertopos-0.5.0 → hypertopos-0.5.2}/ROADMAP.md

@@ -17,9 +17,13 @@ Any item may slip to 0.7.0 if scope pressure requires. The multi-epoch retention
 
 ---
 
-## Plan: 0.5.0
+## 0.5.0
 
-Theme: **detection-quality and investigation-workflow push.** Shipped: Storey adaptive π₀ FDR + chi² p-values, drift direction, multi-hop root-cause tracing (`trace_root_cause` DAG), geometric edge potential, find_motif with four motif types (fan_out / cycle_2 / cycle_3 / structuring) including the 0.5.0 AdjacencyIndex reuse refactor. The "architecture-emergent analytics" side of the original plan was re-scoped to 0.6.0 because the prerequisite infrastructure (multi-epoch calibration retention in the builder) was larger than the advertised features — scope stayed on detection quality and agent workflow instead.
+Detection-quality and investigation-workflow push.
+
+- **0.5.0** — Storey adaptive π₀ FDR + chi² p-values (power recovery in moderate-super-anomaly regimes without chasing the Storey estimator off a rank-based null). Drift direction on `π9_attract_drift` — `gradient_alignment` and `drift_direction ∈ {normalizing, deteriorating, neutral}` on every entity. Multi-hop root-cause tracing (`trace_root_cause` DAG) replacing `explain_anomaly_chain`. Geometric edge potential — per-edge anomaly score via `||δ_from − δ_to|| × (1/pair_tx_count)` sourced from the shared `AdjacencyIndex.pair_counts()` cache. Structural motif scoring — `score_motif` and `find_high_potential_motifs` over four closed-vocabulary atoms (`fan_out`, `cycle_2`, `cycle_3`, `structuring`) composing `edge_potential` via product, with 0.5.0 AdjacencyIndex-reuse refactor consolidating motif ranking / edge_potential / eight graph primitives onto one shared adjacency build per session. The "architecture-emergent analytics" side of the original plan was re-scoped to 0.6.0 because the prerequisite infrastructure (multi-epoch calibration retention in the builder) was larger than the advertised features.
+- **0.5.1** — Two new closed-vocabulary motifs extending the 0.5.0 catalog: `fan_in` (mirror of `fan_out`, sink-centric, covers T12 destination-side parallel layering and T13 concentrator/sink) and `chain_k` (open directed chain of parametric length 3 ≤ k ≤ 8, no cycle closure, no node revisit, covers T5 multi-stage layering and T18 multi-jurisdiction latency). Reuses the 0.5.0 `MotifSpec` / `_score_motif_from_edges` / AdjacencyIndex machinery without touching the format. `score_motif` and `find_high_potential_motifs` grow a `k` parameter (default 4, validated 3–8 for `chain_k`, ignored otherwise); `min_k` now applies to `fan_in` in addition to `fan_out`. `split_recombine` and `bipartite_burst` remain under consideration for 0.5.2.
+- **0.5.2** — Closes the structural motif catalog with two bipartite atoms — `split_recombine` (diamond scatter-gather S → k intermediaries → D, stacked-bipartite temporal order, `direction ∈ {"forward","backward"}` for source vs sink seed anchoring) and `bipartite_burst` (complete K_{k,m} bipartite subgraph in a tight window, asymmetric `min_k` / `min_m` cardinality controls) — covering T1 / T12 / T13 / T16 atoms unreachable by the 0.5.0 / 0.5.1 vocabulary. Registry grows from six to eight types. Same release ships a perf-hardening pass on the existing catalog: single-seed enumeration unified onto the in-memory adjacency path, `_score_motif_from_edges` batched, `cycle_3` two-step pre-filter on hub seeds, `chain_k` per-k adaptive frontier cap, `bipartite_burst` size-ascending K-set intersection, and `_enumerate_structuring` consistency fix. No format change.
 
 ---
 

{hypertopos-0.5.0 → hypertopos-0.5.2}/SECURITY.md

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