hypertopos 0.6.0__tar.gz → 0.6.2__tar.gz

{hypertopos-0.6.0 → hypertopos-0.6.2}/CHANGELOG.md

@@ -7,6 +7,194 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.6.2] — 2026-05-05
+
+### Added
+- Chain-anchor `edge_dim_aggregations:` regime — third `anchor_kind`
+  alongside `single` (account-style) and `pair` (k=2 composite). Chain
+  anchor patterns auto-emitted from `chain_lines:` config can declare
+  `edge_dim_aggregations: { from: <event_pid>, dims: [...] }` directly
+  in the `chain_lines.<id>:` block; the builder forwards it to the
+  auto-emitted `<id>_pattern`. Aggregation reads the source event
+  pattern's edge_features sidecar and bakes per-chain `<source_dim>_mean`
+  and `<source_dim>_max` columns into the chain anchor polygon's
+  `shape_snapshot`. New `_chain_lines: set[str]` registry on `GDSBuilder`
+  for regime detection. `aggregate_edge_dims_for_anchor` gains a
+  `chain_events: list[str] | None` keyword for the chain regime
+  (comma-joined event_keys per anchor; engine performs explosion + join
+  + groupby). Cross-block parse-time validation enforces
+  `chain_lines.<id>.event_line == src_pat.edge_table.event_line`;
+  zero-extracted-chains with declared aggregations raise loudly at
+  build dispatch. Sphere format stays at 2.4 — `chain_events` property
+  column on the chain anchor line is the existing membership source.
+  Aggregated dims surface automatically in every existing anchor-pattern
+  primitive (`find_anomalies`, `explain_anomaly`, `find_clusters`,
+  `find_calibration_influencers`, `decompose_drift`) via
+  `dimension_kinds` source-of-truth — no new tools, no MCP API change.
+
+### Added
+- `AdjacencyIndex.neighbors_out_window` and
+  `AdjacencyIndex.neighbors_in_window` — column-selective neighbor
+  accessors. Return a per-column dict (`{col: list[Any]}`) for any subset
+  of `("to_key" / "from_key", "timestamp", "amount", "event_key")` with
+  an optional `ts_min` window predicate applied at the pyarrow C++ layer
+  before materialization. Useful for callers that need only key + timestamp
+  without paying the cost of materializing `amount` / `event_key`.
+- `AdjacencyIndex.distinct_neighbors_out`,
+  `AdjacencyIndex.distinct_neighbors_in`, and
+  `AdjacencyIndex.max_amount_out_excl_self` — O(1) public accessors over
+  precomputed per-`from_key` aggregates (distinct-out-neighbor count,
+  distinct-in-neighbor count, max-amount-excluding-self). Self-loop
+  semantics preserved; null amounts skipped.
+
+### Fixed
+- Cold-call latency on motif enumeration tools (`find_high_potential_motifs`,
+  `score_motif`, `find_motif_by_hops`) reduced across `bipartite_burst`,
+  `fan_out`, `fan_in`, and `cycle_2` motif types. No public API change.
+- `AdjacencyIndex.pair_counts()` first-call cost on hub-graph workloads
+  reduced. The aggregate is now precomputed at adjacency build time and
+  surfaced in O(1) on first call. Self-loop semantics preserved
+  (`pair_counts` includes self-pairs; distinct counts skip them).
+
+### Changed
+- `AdjacencyIndex` cold load path is faster on edge-table-backed
+  patterns; motif tools' first-call latency drops materially. No format
+  bump, no persisted artifact, no public API change — every public method
+  (`neighbors_out`, `neighbors_in`, `degree_out`, `degree_in`, `all_nodes`,
+  `all_edges`, `node_count`, `edge_count`, `pair_counts`) preserves its
+  signature and observable behavior.
+
+## [0.6.1] — 2026-05-01
+
+### Fixed
+- `find_motif_by_hops` `score=True` now functional on event patterns. The
+  scoring branch was previously dead code (gated on
+  `pattern_type != "event"`, but the function rejects non-event patterns
+  upstream), so passing `score=True` had no observable effect since the
+  declarative motif API shipped. Scoring now resolves the event pattern's
+  anchor companion via `_resolve_anchor_pattern_for_scoring` and uses the
+  anchor pattern's per-entity geometry (entity-level deltas) rather than
+  the event pattern's per-transaction polygons. Each scored motif carries
+  a new `anchor_pattern_id` provenance field. Raises `GDSNavigationError`
+  when no anchor companion is configured for the event pattern; per-motif
+  scoring failures (endpoint missing in anchor geometry) leave the motif
+  unscored without breaking the call. Output ordering: descending on
+  score, unscored motifs at tail.
+- Motif scoring kernel (`_score_motif_from_edges`, `_lean_score_motif`)
+  now event-aware via opt-in `event_keys` + `event_pattern_id` arguments.
+  Previously `edge_potential = delta_distance × (1/effective_pair_count)`
+  depended only on the node pair, so multiple distinct transactions
+  between the same `(from, to)` accounts produced identical motif scores
+  — turning ranked `find_motif_by_hops(score=True)` output into "5–10
+  distinct ranks with the rest as ties" whenever motifs shared a node
+  sequence. With the new arguments the kernel batch-reads the event
+  pattern's per-event polygons and multiplies each edge's potential by
+  `(1 + ||event_polygon[event_key]||)`; events sitting at the population
+  centroid (norm 0) keep the legacy score, anomalous events boost above.
+  Per-edge `score_breakdown` carries a new `event_factor` field when
+  event-aware. Backward compatible: legacy callers (`score_motif`,
+  `find_high_potential_motifs`, any external caller of
+  `_score_motif_from_edges` without event_keys) see unchanged scores.
+  `find_motif_by_hops` passes both arguments automatically and hoists
+  both anchor and event delta reads out of the per-motif loop (one
+  batched scan per pattern across the union of all motifs, vs.
+  per-motif reads pre-hoist) so the per-call I/O cost stays O(1) in
+  motif count.
+- `Pattern.dim_labels` and `Pattern.delta_dim()` now include aggregated
+  edge-dim names from `edge_dim_aggregations` so callers don't see a
+  stale 33-element view of a 37-element delta. Previously the property
+  returned only `relations + event_dimensions + prop_columns` — but the
+  builder appends `(source_dim)_mean` and `(source_dim)_max` columns to
+  the polygon delta when an anchor pattern declares
+  `edge_dim_aggregations: { from: <event>, dims: [...] }`. The mismatch
+  produced two visible failure classes on patterns with aggregations
+  declared:
+    - `anomaly_summary` raised `operands could not be broadcast together
+      with shapes (33,) (37,) (33,)` because `dim_sq_totals` was sized
+      from `len(pattern.dim_labels)` (33) but cluster delta vectors had
+      length 37 (33 base + 4 aggregated).
+    - `find_clusters.dim_profile`, `find_anomalies.anomaly_dimensions`,
+      `explain_anomaly` top-dim labels, `contrast_populations`
+      effect-size labels and other label-resolving paths returned
+      `dim_35` / `dim_36` placeholders for the aggregated dims instead
+      of the build-time names (`find_motif_structuring_mean`,
+      `pair_edge_count_max`, etc.).
+  Both classes are resolved by the model property fix; the aggregated
+  name convention follows `f"{source_dim}_{agg}"` for each
+  `agg ∈ AGGREGATE_NAMES = ("mean", "max")` in
+  `engine/edge_features.py`. `parse_edge_dim_aggregations` now requires
+  `dims` to be a non-empty list — the previous `dims=None` shorthand
+  ("aggregate every applicable dim") was a latent build-vs-runtime
+  inconsistency: builder appended columns from the source event
+  pattern, but the runtime model had no record of which columns. Users
+  must now declare dims explicitly. Backward compatible for spheres
+  with explicit `dims:` on disk (AML HI-small etc.); spheres that
+  somehow built with `dims=None` fail loudly at re-load and need a
+  rebuild with explicit declaration. Closes the F1.d follow-up
+  (human-readable aggregated-dim labels) and the F6 stress-test
+  wildcard for the broadcast regression.
+
+### Changed
+- `find_motif_by_hops` engine: replaced the recursive DFS walk with an
+  iterative BFS-by-level enumerator. Lifts the per-call hop count cap
+  from 6 to 8 (matches the `chain_k` motif vocabulary). Adds an optional
+  `time_window_hours: float | None` top-level parameter for total-
+  chain-span cap (independent semantic from per-hop
+  `time_delta_max_hours`; both apply when both are set). API surface
+  preserved: same enumeration output shape, all existing tests pass.
+  Cites the Paranjape-Benson-Leskovec delta-temporal motif algorithm as
+  prior art for sliding-window enumeration; the implementation is a
+  pragmatic level-synchronous BFS (PBL counts fixed-template motifs
+  without per-edge predicates, which does not fit the enumerate-with-
+  arbitrary-predicates use case).
+
+### Added
+- `HopPredicate.require_anomalous_entity: bool` — new per-hop predicate
+  field for the declarative motif API (closes the X1 predicate set
+  alongside `amount_ratio_to_prev`). When `True` on hop `i`, the
+  destination entity (`nodes[i+1]` of the resulting motif) must satisfy
+  `is_anomaly=True` in the resolved anchor companion pattern's geometry.
+  Multiple hops can set this independently; constraints AND across hops.
+  Filter runs at the navigator layer after BFS enumeration but before
+  scoring (saves scoring work on motifs that get dropped). The seed
+  (`nodes[0]`) is never checked — pre-filter `seed_keys` upfront if seed
+  coverage is needed. `max_results` applies AFTER the filter, so a
+  restrictive filter can return fewer than `max_results` motifs. Raises
+  `GDSNavigationError` when no anchor companion is configured for the
+  queried event pattern, or when the anchor pattern has no `is_anomaly`
+  column (calibration must run first). Default `False` is a no-op,
+  preserving prior behavior. Reuses the same anchor-companion lookup
+  wired by F5; no sphere format change, no rebuild required.
+- `HopPredicate.amount_ratio_to_prev: float | None` — new per-hop predicate
+  field for the declarative motif API. When set on hop `i ≥ 1`, the engine
+  rejects a candidate edge unless `current_amount / prev_hop_amount ≤
+  ratio`. Bounds `0 < ratio ≤ 1.0` enforced at validation; `hops[0]` must
+  leave the field None (no previous amount). Edges where either amount is
+  ≤ 0 are silently skipped, matching the existing `find_motif_structuring`
+  convention. Use case: declarative structuring / layering chain detection
+  without baking absolute amount thresholds (`amount_min` / `amount_max`).
+- Anchor-pattern aggregation of edge-derived dimensions (S1 extension).
+  An anchor pattern can declare `edge_dim_aggregations: { from: <event_pid>, dims: [...] }`
+  in its YAML stanza; the builder reads the event pattern's edge_features
+  sidecar and bakes per-anchor-entity `_mean` and `_max` aggregates of
+  the named source dims into the anchor polygon's `shape_snapshot`.
+  Aggregation handles two anchor regimes — `single` (anchor PK matches
+  edge `from_key` OR `to_key`, account-style) and `pair` (anchor PK
+  encoded as `<from>__<to>`, composite-pair-style); chain anchors
+  raise `NotImplementedError` and ship in 0.6.2. New
+  `EdgeDimAggregationsConfig` builder dataclass, `EdgeDimAggregationsRef`
+  runtime dataclass on `Pattern`, and
+  `engine.edge_features.aggregate_edge_dims_for_anchor` engine entry
+  point. Builder switches to a two-phase build (event patterns first,
+  anchor patterns second) when any pattern declares
+  `edge_dim_aggregations` so the sidecar dependency holds without a
+  topo sort. New aggregated dims surface automatically in every
+  existing anchor-pattern primitive (`find_anomalies`,
+  `explain_anomaly`, `find_clusters`, `find_calibration_influencers`,
+  `decompose_drift`) via the `dimension_kinds` source-of-truth — no
+  new tools, no MCP API change. Sphere format stays at 2.4; spheres
+  without the new YAML block are byte-identical.
+
 ## [0.6.0] — 2026-04-30
 
 ### Theme

{hypertopos-0.6.0 → hypertopos-0.6.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-30
+**Change Date:** 2029-05-05
 
 **Change License:** Apache License, Version 2.0
 

{hypertopos-0.6.0 → hypertopos-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypertopos
-Version: 0.6.0
+Version: 0.6.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.6.0 → hypertopos-0.6.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.6.0-%235500FF.svg)](pyproject.toml)
+[![Version](https://img.shields.io/badge/version-0.6.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.
 
@@ -59,6 +59,16 @@ Each capability below emerges from treating entities as points in a shared, popu
 | 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` |
+| Multi-epoch calibration audit | `compare_calibrations(v_from, v_to)` — per-dim μ/σ/θ drift between two retained calibration epochs of one pattern | Drift detectors compare model predictions; nothing compares the underlying coordinate system itself | `0.6.0` |
+| Intrinsic vs extrinsic drift decomposition | `decompose_drift` splits an entity's geometric drift into its own movement vs population recalibration; `intrinsic_fraction ∈ [0, 1]` | Drift magnitude alone — population shift and entity behaviour change confound | `0.6.0` |
+| Hidden-influencer matrix | `find_calibration_influencers` — 4-cell classification (`hidden` / `distorter` / `standard_anomaly` / `normal`) via exact leave-one-out impact on calibration | SHAP / counterfactual: explain a prediction, not the coordinate system itself | `0.6.0` |
+| Cross-pattern temporal lead-lag | `find_lead_lag(pattern_a, pattern_b)` — cross-correlates differenced population-centroid drift; peak lag, Bonferroni-adjusted significance, per-dim FDR matrix | Granger causality on raw metrics — not on population-relative geometry | `0.6.0` |
+| Anomaly by absence | `find_density_gaps` — joint-density gaps under independence null with BH-corrected q-values; surfaces under-populated cells in named delta-space ranges | Outlier detection finds extremes; gap detection finds *missing* combinations | `0.6.0` |
+| Declarative motif API | `find_motif_by_hops(pattern_id, hops, *, seed_keys)` — caller passes per-hop `HopPredicate`s (amount / time-delta / direction / edge-dim filters); navigator walks chains of length 1..8 with optional total-span cap (`time_window_hours`) | Closed-vocab motif registry — no escape hatch for ad-hoc structural shapes | `0.6.0` |
+| Anchor-pattern aggregation of edge-derived dims | Anchor patterns declare `edge_dim_aggregations:` to bake per-edge sidecar signals (`pair_edge_count`, `find_motif_structuring`, …) into per-anchor `_mean` / `_max` columns; surfaces in every anchor primitive (`find_anomalies`, `explain_anomaly`, `find_clusters`) | Hand-rolled SQL roll-up + manual feature engineering | `0.6.1` |
+| Richer hop predicates | `HopPredicate.amount_ratio_to_prev` (decreasing-chain ratio) and `require_anomalous_entity` (filter chains routing through calibrated-anomalous nodes) extend the declarative motif API | Closed-vocab motif library has fixed amount thresholds and no anomaly-routing filter | `0.6.1` |
+| Event-aware motif scoring | `find_motif_by_hops(score=True)` ranks motifs by the product of event-aware `edge_potential` across edges (uses both the anchor companion's per-entity geometry and the event pattern's per-transaction polygons); distinct transactions between the same accounts produce distinct scores | Pure node-pair scoring collapses ranks when motifs share a node sequence | `0.6.1` |
+| Chain-anchor aggregation | Chain anchor patterns auto-emitted from `chain_lines:` declare `edge_dim_aggregations:` to bake per-event sidecar signals into per-chain `_mean` / `_max` columns; closes the third `anchor_kind` after `single` and `pair` | Per-chain manual aggregation outside the geometry, or no chain-level edge-dim summary at all | `0.6.2` |
 
 ### What changes in practice
 
@@ -77,6 +87,8 @@ The same problems look different when graph, time, and statistics are unified:
 | Root-cause an anomaly | Manual chain: explain → counterparties → contagion → hub check, 4+ tool calls | `trace_root_cause(entity)` — single call returns bounded DAG of evidence |
 | Detect relationship layering | Custom rule engine or manual rare-pair SQL queries | `edge_potential(A, B)` — per-edge score combining endpoint distance and pair rarity |
 | Match AML typology patterns | Graph DB subgraph queries + separate risk scoring | `find_motif(type="structuring", …)` — structural pattern + geometric rarity product |
+| Match ad-hoc structural chains | Custom subgraph queries per shape, no built-in scoring | `find_motif_by_hops(hops=[HopPredicate(...)])` — declarative per-hop predicates (amount, time, direction, edge-dim, ratio-to-prev, anomaly filter) with event-aware geometric scoring on the same call |
+| Account-level transaction layering recall | Hand-rolled SQL roll-ups of per-edge signals into account features | `edge_dim_aggregations:` on the anchor pattern bakes per-edge structuring / pair-recurrence / chain-depth signals into anchor geometry — read off `find_anomalies` like any other dim |
 | Direction of behavioural drift | Drift magnitude alone — no toward/away-from-centre signal | `attract_drift` returns `drift_direction ∈ {normalizing, deteriorating, neutral}` |
 
 ## Benchmarks

hypertopos-0.6.2/ROADMAP.md

@@ -0,0 +1,89 @@
+# hypertopos — Roadmap
+
+> Planned direction. Priorities may change based on feedback.
+
+## 0.6.0
+
+Architecture-emergent analytics, properly enabled — calibration is now versioned, and patent-aligned analytics ride on that versioning.
+
+- **0.6.0** — multi-epoch calibration retention, `compare_calibrations`, intrinsic / extrinsic drift decomposition, hidden-influencer matrix (`find_calibration_influencers`), cross-pattern temporal lead-lag (`find_lead_lag`), edge-derived event-pattern dimensions, joint density gap detection (`find_density_gaps`), declarative motif API (`find_motif_by_hops`, bounded MVP). Sphere format 2.4.
+- **0.6.1** — anchor-pattern aggregation of edge-derived dimensions (`edge_dim_aggregations:`); BFS-by-level enumerator on `find_motif_by_hops` with hop count cap raised 6→8 and global `time_window_hours`; declarative motif API completion via `HopPredicate.amount_ratio_to_prev` and `require_anomalous_entity`; functional anchor-companion + event-aware scoring on `find_motif_by_hops(score=True)`; broadcast-safe `Pattern.dim_labels` on patterns with aggregated edge-dim names. Additive only — no sphere format bump, no new tools.
+- **0.6.2** — chain-anchor `edge_dim_aggregations:` regime closes the third `anchor_kind` after single (account-style) and pair (k=2 composite); vectorized `AdjacencyIndex` load path (pyarrow `group_by` + lazy per-key materialization) for cold-start latency cleanup; column-selective `neighbors_*_window` accessors with motif enumerator migration for `bipartite_burst`, `fan_out`, `fan_in`, `cycle_2`; new project skill `profile-before-plan` gating hot-path refactors on real-data cProfile. Additive only — sphere format stays at 2.4 (the originally proposed persisted-artifact path was empirically refuted; vectorized loader ships without any on-disk change).
+
+See [CHANGELOG](CHANGELOG.md) for the full feature list.
+
+---
+
+## 0.5.0
+
+Detection-quality and investigation-workflow push.
+
+- **0.5.0** — Storey adaptive π₀ FDR; drift direction on `π9_attract_drift`; multi-hop root-cause tracing (`trace_root_cause` DAG); geometric edge potential; structural motif scoring (`fan_out`, `cycle_2`, `cycle_3`, `structuring`).
+- **0.5.1** — `fan_in` and `chain_k` motifs.
+- **0.5.2** — `split_recombine` and `bipartite_burst` motifs; perf-hardening pass on the catalog.
+
+---
+
+## 0.4.0
+
+Distribution-aware geometry, calibration fidelity, and graph acceleration.
+
+- **0.4.0** — Distribution-aware Bregman divergence with per-dim kind tags; per-dimension anomaly threshold; in-memory adjacency index.
+- **0.4.1** — Native graph algorithms as build-time dimensions (PageRank, betweenness, community, clustering, components); bidirectional BFS rewrite of `find_geometric_path`.
+
+---
+
+## 0.3.0
+
+Lance perf upgrade, FDR control, builder intelligence.
+
+- **0.3.0** — Aggregate engine rewrite on Lance SQL; precomputed contagion stats; format 2.2.
+- **0.3.1** — Benjamini-Hochberg FDR control; submodular facility location; vectorized build with adaptive memory chunking.
+- **0.3.2** — NumPy graph features; chunked pre-computation; geometric heredity (`find_novel_entities`).
+- **0.3.3** — Agent navigation policy; dimension-selective similarity.
+
+---
+
+## 0.2.0
+
+Graph meets geometry — edge table, runtime traversal, contagion/influence.
+
+- **0.2.0** — Edge table; +11 navigator functions; contagion/influence primitives.
+- **0.2.1** — Witness cohort discovery; investigative peer ranking.
+- **0.2.2** — As-of graph reconstruction; `detect_cross_pattern_discrepancy` latency fix.
+
+---
+
+## 0.1.0
+
+First public release — full GDS stack, π1–π12, builder, MCP server, validation suite.
+
+---
+
+## Future
+
+**Detection quality**
+- Robust estimators, multi-scale resolution — trimmed means / MAD-based σ, hierarchical build at daily/weekly/full granularity.
+- Chains as first-class geometric entities — external chains declared as anchor lines with a membership table, plus chain-aware geometric primitives (anomaly propagation inside a chain, coherent-anomaly filter, chain drift trajectory).
+
+**Builder evolution**
+- Incremental rebuild — geometry-only without `--force` wipe.
+
+**PassiveScanner evolution**
+- Native temporal source support for direct temporal inputs, without requiring manual dataset plumbing in benchmark scripts.
+- Optional weighted scoring mode that uses continuous intensity instead of binary counts.
+- **SphereProfiler** — autonomous sphere scanner that profiles all patterns, runs calibration sweeps across source combinations, proposes optimal PassiveScanner composition for Layer 1 surveillance.
+
+**Code refactoring**
+- Break up oversized modules into smaller, domain-focused components (post-0.5.0 `navigator.py` is over 11k lines and is the obvious first target; per-pattern parallelism and AdjacencyIndex reuse in 0.4.0/0.5.0 reduced some coupling but the module itself did not shrink).
+- Consolidate repeated orchestration logic into shared helpers.
+
+**Cross-sphere capabilities**
+- Cross-sphere comparison — dimensionless metrics across independently calibrated coordinate spaces.
+- What-if analysis — hypothetical edge changes producing modified coordinate vectors.
+
+**Enterprise / governance**
+- Dimension access control — per-agent visibility constraints on delta dimensions.
+
+**Tooling**
+- Runtime latency benchmarks in package docs.

{hypertopos-0.6.0 → hypertopos-0.6.2}/SECURITY.md

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

{hypertopos-0.6.0 → hypertopos-0.6.2}/docs/api-reference.md

@@ -270,15 +270,16 @@ nav.find_motif_by_hops(
     *,
     seed_keys: list[str] | None = None,
     max_results: int = 100,
-    score: bool = True,
+    score: bool = False,
+    time_window_hours: float | None = None,
 ) -> dict
 ```
 
-Declarative motif API — power-user escape hatch from the closed-vocab `find_motif` registry. Caller passes a list of `HopPredicate`s describing per-hop constraints (`amount_min`, `amount_max`, `time_delta_max_hours`, `direction` (`"forward"` / `"reverse"` / `"any"`), `edge_dim_predicates: dict[str, tuple[op, value]]`); the navigator walks the in-memory `AdjacencyIndex` for matching chains. `seed_keys=None` enumerates from all `from_key` nodes (capped at `max_results`). Returns `{pattern_id, n_results, motifs}` with each motif carrying `nodes`, `edges` (event_keys), `timestamps`, `amounts`, `dim_values_per_hop` (only when `edge_dim_predicates` were used), optional `score` (anchor patterns only) and `score_breakdown`. Raises on anchor pattern (event-only), unknown pattern, empty hops, k>6, `max_results<1`. Bounded MVP — `amount_ratio_to_prev` and `require_anomalous_entity` predicates plus k>6 land in a follow-up.
+Declarative motif API — power-user escape hatch from the closed-vocab `find_motif` registry. Caller passes a list of `HopPredicate`s describing per-hop constraints (`amount_min`, `amount_max`, `time_delta_max_hours`, `amount_ratio_to_prev`, `direction` (`"forward"` / `"reverse"` / `"any"`), `edge_dim_predicates: dict[str, tuple[op, value]]`); the navigator walks the in-memory `AdjacencyIndex` for matching chains via level-synchronous BFS. `seed_keys=None` enumerates from all `from_key` nodes (capped at `max_results`). `time_window_hours` (optional, default `None`) caps the total chain span: when set, every hop after the first must satisfy `abs(current_edge_ts - first_edge_ts) <= time_window_hours`; independent of per-hop `time_delta_max_hours`, both apply when both are set. When `score=True`, the navigator resolves the event pattern's anchor companion via `_resolve_anchor_pattern_for_scoring` and scores each motif as the product of event-aware `edge_potential` (`delta_distance × (1/effective_pair_count) × (1 + event_norm)`) across its edges. The `event_norm` factor (norm of the event pattern's per-transaction polygon for each edge's `event_key`) breaks ties between motifs that share a node sequence but use different transactions. Scored motifs gain `score`, `score_breakdown` (per-edge entries carry `edge_potential`, `delta_distance`, `pair_tx_count`, `effective_weight`, `event_factor`), and `anchor_pattern_id` fields together (sorted descending on score, unscored motifs at tail). Returns `{pattern_id, n_results, motifs}` with each motif carrying `nodes`, `edges` (event_keys), `timestamps`, `amounts`, `dim_values_per_hop` (only when `edge_dim_predicates` were used), and the score triple when `score=True` succeeds. Raises on anchor pattern (event-only), unknown pattern, empty hops, hop count outside `1..8`, non-positive `time_window_hours`, `max_results<1`, or `score=True` with no anchor companion configured for the pattern.
 
 ### `HopPredicate` (dataclass, frozen)
 
-Fields: `amount_min`, `amount_max`, `time_delta_max_hours`, `direction` (Literal["forward", "reverse", "any"], default `"forward"`), `edge_dim_predicates` (`dict[str, tuple[str, float]]`, e.g. `{"pair_edge_count": (">=", 20.0)}`). Operators: `<`, `<=`, `>`, `>=`, `==`.
+Fields: `amount_min`, `amount_max`, `time_delta_max_hours`, `amount_ratio_to_prev` (`float | None`, decreasing-chain ratio in `(0, 1.0]`; rejects edge unless `current_amount / prev_hop_amount ≤ ratio`; must be `None` on `hops[0]`; edges with non-positive amounts are silently skipped), `direction` (Literal["forward", "reverse", "any"], default `"forward"`), `edge_dim_predicates` (`dict[str, tuple[str, float]]`, e.g. `{"pair_edge_count": (">=", 20.0)}`). Operators: `<`, `<=`, `>`, `>=`, `==`. `require_anomalous_entity` (`bool`, default `False`) — when `True` on hop `i`, the destination entity (`nodes[i+1]`) must satisfy `is_anomaly=True` in the resolved anchor companion pattern's geometry; constraints AND across hops; filter runs at the navigator post-BFS, pre-scoring; `max_results` applies AFTER the filter; raises `GDSNavigationError` when no anchor companion is configured.
 
 ### Density Gaps Engine (`hypertopos.engine.density_gaps`)
 
@@ -337,6 +338,9 @@ names in user-supplied `dim_pairs`.
 |--------|-------------|
 | `EdgeDimensionsConfig(dims: dict[str, dict])` | Parsed `edge_dimensions:` block — frozen dataclass attached to `PatternMapping.edge_dimensions` |
 | `parse_edge_dimensions(raw_list, *, pattern_type)` | Parse + validate the YAML list of dim entries (bare strings or single-key dicts). Raises `ValueError` on anchor pattern, `min_position < 3`, `cv_threshold` outside `(0, 1]`, `min_count < 2`, non-positive `amt1_min` / `amt2_max` / `time_window_hours`, negative `burst_seconds`, duplicate or unknown dim names, malformed entries |
+| `EdgeDimAggregationsConfig(from_event_pattern: str, dims: tuple[str, ...])` | Parsed `edge_dim_aggregations:` block on an anchor pattern — frozen dataclass attached to `PatternMapping.edge_dim_aggregations`. `dims` is a non-empty tuple of source dim names |
+| `parse_edge_dim_aggregations(raw_dict, *, pattern_type)` | Parse + validate the YAML mapping. Raises `ValueError` on event pattern, missing `from`, missing or empty `dims` (non-empty list required), non-list `dims`, or unknown dim name |
+| `aggregate_edge_dims_for_anchor(*, anchor_keys, edges, sidecar, dims, anchor_kind, pair_separator, chain_events)` | Aggregate per-edge sidecar dim values up to per-anchor `_mean` / `_max` columns. `anchor_kind` ∈ `{single, pair, chain}`. For chain regime, pass `chain_events: list[str]` of comma-joined event_keys per anchor (one per `anchor_keys` entry); `edges` arg is ignored. Returns a `pa.Table` keyed by `primary_key` |
 
 ### Calibration History (GDSReader)
 

{hypertopos-0.6.0 → hypertopos-0.6.2}/docs/architecture.md

@@ -30,7 +30,7 @@ The core package is split into a few layers:
 - **Builder**: transforms source data into a complete sphere
 - **CLI**: builds and inspects spheres from the command line
 
-The `hypertopos-mcp` package sits on top of this core library and exposes the same capabilities to agents via 67 MCP tools.
+The `hypertopos-mcp` package sits on top of this core library and exposes the same capabilities to agents via 80 MCP tools.
 
 The split is deliberate:
 
@@ -175,7 +175,7 @@ graph LR
     ST --> E["Engine\ngeometry, delta,\nclustering, DTW"]
     E --> N["Navigator\nπ1–π12, detect_*"]
     N --> PS["PassiveScanner\nmulti-source\nbatch screening"]
-    N --> MCP["MCP Server\n72 tools\nstdio transport"]
+    N --> MCP["MCP Server\n80 tools\nstdio transport"]
     MCP --> Agent["AI Agent"]
     CT["CalibrationTracker\nonline drift\nWelford stats"] -.-> E
     M["Manifest\nMVCC version pin"] -.-> ST

{hypertopos-0.6.0 → hypertopos-0.6.2}/docs/concepts.md

@@ -238,7 +238,7 @@ Event patterns can declare an `edge_dimensions:` block in YAML to add up to five
 | `pair_amount_zscore` (LOW_VAR pairs only) | gaussian | signed z-score of amount within `(from_key, to_key)` pairs whose CV(amount) < `cv_threshold`; HIGH_VAR pairs and pairs below `min_count` write 0.0 — direction-agnostic outlier signal on locked-amount pairs |
 | `find_motif_structuring` | bernoulli | 1.0 if the edge participates in any A→B→C→D structuring motif within `time_window_hours` with hop1 ≥ `amt1_min` and hops 2/3 ≤ `amt2_max` |
 
-These dims are computed at edge-table emission time, written to the `_gds_meta/edge_features/{pid}/data.lance` sidecar keyed by `event_key`, AND merged into the event polygon `shape_snapshot` (one extra dim per declared entry). Downstream primitives (`find_anomalies`, `find_similar_entities`, `find_clusters`) automatically include them in `delta` / `delta_norm` / classification — no new query API. Reject `min_position < 3` at YAML parse time. Anchor patterns reject the block — the per-edge → per-entity aggregation that would let anchor patterns use these dims is a deferred follow-up.
+These dims are computed at edge-table emission time, written to the `_gds_meta/edge_features/{pid}/data.lance` sidecar keyed by `event_key`, AND merged into the event polygon `shape_snapshot` (one extra dim per declared entry). Downstream primitives (`find_anomalies`, `find_similar_entities`, `find_clusters`) automatically include them in `delta` / `delta_norm` / classification — no new query API. Reject `min_position < 3` at YAML parse time. Anchor patterns reject the `edge_dimensions:` block directly; to expose these per-edge signals on anchor entities, declare `edge_dim_aggregations:` on the anchor pattern instead — see `configuration.md` for the YAML stanza and supported aggregates (`_mean` / `_max`). For chain anchor patterns auto-emitted from `chain_lines:` config, declare `edge_dim_aggregations:` directly inside the `chain_lines.<id>:` block — same `from: <event_pid>` and `dims: [...]` schema as on regular anchor patterns; the builder forwards it to the auto-emitted `<id>_pattern`.
 
 ## Chain Interpretation
 

{hypertopos-0.6.0 → hypertopos-0.6.2}/docs/configuration.md

@@ -373,6 +373,7 @@ patterns:
 | `description` | string | `null` | Human-readable description. Stored in sphere.json — visible to agents via `get_sphere_info`. |
 | `edge_table` | dict | `null` | Explicit edge table config (see below). Auto-emitted for event patterns with 2+ FK relations to same anchor line. |
 | `edge_dimensions` | list | `null` | Build-time per-edge dims for event patterns. Each item is either a bare dim name or a single-key dict with overrides. Five dims available: `pair_edge_count`, `position_in_chain` (`min_position` ≥ 3, default 5), `time_since_pair_last_edge`, `pair_amount_zscore` (LOW_VAR pairs only), `find_motif_structuring`. |
+| `edge_dim_aggregations` | dict | `null` | **Anchor patterns only.** Aggregate per-edge sidecar dims of an event pattern up to per-anchor `_mean` / `_max` columns baked into the anchor polygon. `from: <event_pid>` is required and must reference an event pattern that declares `edge_dimensions:`. `dims: [...]` is required — must be a non-empty list of source dim names from the referenced sidecar (the previous "omit `dims` to aggregate everything" shorthand was removed; explicit declaration prevents build-vs-runtime label drift). Anchor regimes: `single` (account-style, anchor PK matches edge `from_key` OR `to_key`) and `pair` (composite-key, anchor PK = `<from>__<to>`); `chain` raises `NotImplementedError`. Builder switches to a two-phase build (events first, anchors second) when this block is present. |
 | `bootstrap_iterations` | int | `200` | Number of bootstrap resamples used to compute `anomaly_confidence` per entity. Skipped automatically for N > 50K, `group_by_property`, or `use_mahalanobis`. |
 
 ### Edge Table
@@ -733,6 +734,25 @@ Automatically creates an anchor line + pattern (`{line_id}_pattern`).
 | `bidirectional` | bool | `true` | Follow edges in both directions. |
 | `anomaly_percentile` | float | `95.0` | Theta for the auto-created chain pattern. |
 | `description` | string | `null` | Description for chain line + pattern. |
+| `edge_dim_aggregations` | dict | `null` | Aggregate per-edge sidecar dims of an event pattern up to per-chain `_mean` / `_max` columns baked into the chain anchor polygon. `from: <event_pid>` is required and must reference an event pattern that declares `edge_dimensions:` and whose `edge_table.event_line` matches this `chain_lines.<id>.event_line` (validated at parse time). `dims: [...]` is required — non-empty list of source dim names from the referenced sidecar. The chain anchor pattern's polygon shape grows by `2 * len(dims)` columns; downstream primitives (`find_anomalies`, `explain_anomaly`, `find_clusters`) surface the new dims transparently. |
+
+**Example with edge-dim aggregation on chain anchor:**
+
+```yaml
+chain_lines:
+  tx_chains:
+    event_line: transactions
+    from_col: from_account
+    to_col: to_account
+    features: [hop_count, is_cyclic, time_span_hours]
+    edge_dim_aggregations:
+      from: tx_pattern                    # event pattern declaring edge_dimensions
+      dims: [find_motif_structuring, position_in_chain]
+```
+
+The chain anchor `tx_chains_pattern` then exposes `find_motif_structuring_mean`,
+`find_motif_structuring_max`, `position_in_chain_mean`, `position_in_chain_max`
+in `find_anomalies` response and `Pattern.dim_labels`.
 
 ---