hypertopos 0.2.0__tar.gz

hypertopos-0.2.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Type checking
+.mypy_cache/
+
+# Linting
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+.cursor/
+*.iml
+
+# Claude Code
+.claude/
+.worktrees/
+.agents/
+
+# Generated test fixtures
+tests/fixtures/gds/
+
+# Built spheres (output of hypertopos build)
+**/sphere/gds_*/
+
+# Build CLI cache (source parquet + chain pickle)
+.cache/

hypertopos-0.2.0/CHANGELOG.md

@@ -0,0 +1,156 @@
+# Changelog
+
+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).
+
+## [0.2.0] — 2026-04-10
+
+### Added
+
+**Edge Table**
+- Lance-based edge table per event pattern — auto-emitted at build time from FK data
+- BTREE indexes on `from_key`/`to_key` — O(log n) lookups at any scale
+- `GDSWriter.write_edges()`, `append_edges()`, `create_edge_indexes()`
+- `GDSReader.read_edges()`, `has_edge_table()`, `edge_table_stats()`
+- MVCC session pinning for edge tables
+- YAML `edge_table` config (optional, auto-detected from graph_features/relations)
+- `--no-edges` CLI flag
+
+**Navigation**
+- `find_geometric_path()` — beam search with geometric/anomaly/shortest/amount scoring
+- `discover_chains()` — runtime temporal BFS on edge table (no build-time extraction needed)
+- `find_counterparties()` — edge table fast path with BTREE lookup and amount aggregates
+- `entity_flow()` — net flow per counterparty via edge table
+- `contagion_score()` / `contagion_score_batch()` — anomaly neighborhood scoring via edge table
+- `degree_velocity()` — temporal connection velocity (degree change over time buckets)
+- `investigation_coverage()` — agent guidance: explored vs unexplored counterparty coverage
+- `propagate_influence()` — BFS influence propagation with geometric decay and tx_count weighting
+- `cluster_bridges()` — geometry+graph fusion: find entities bridging geometric clusters
+- `anomalous_edges()` — event-level scoring between entity pairs (uses event geometry, not anchor)
+- Amount-weighted scoring mode for `find_geometric_path` — `scoring="amount"`
+- Lazy adjacency expansion — never loads full edge table into memory
+- Anchor pattern resolution for geometric scoring (event pattern edge table → anchor pattern deltas)
+- Score interpretation hint in `find_geometric_path` summary
+
+**PassiveScanner**
+- `"graph"` source type — contagion scoring via edge table + geometry anomaly check
+- `add_graph_source()` — register graph contagion source with configurable threshold
+- `auto_discover()` — auto-detects graph sources for event patterns with edge tables
+
+**MCP Tools**
+- `find_geometric_path` — path finding with geometric coherence scoring (+ amount mode)
+- `discover_chains` — runtime chain discovery without pre-built chain lines
+- `edge_stats` — edge table statistics (row count, degree, timestamp/amount range)
+- `entity_flow` — net flow analysis per counterparty
+- `contagion_score` / `contagion_score_batch` — anomaly neighborhood scoring
+- `degree_velocity` — temporal connection velocity
+- `investigation_coverage` — agent guidance for investigation coverage
+- `propagate_influence` — BFS influence propagation with geometric decay and tx_count weighting
+- `cluster_bridges` — geometry+graph fusion cluster bridge analysis
+- `anomalous_edges` — event-level edge scoring between entity pairs
+- Output cap (top 20 paths / top 100 influenced) with warning when truncated
+
+**Builder**
+- Edge table emission in all build paths (standard, streaming, chunked)
+- Adjacency deduplication — one entry per unique neighbor
+- Self-loop filtering in graph traversal and temporal chain BFS
+- Edge stats cached at build time (`_gds_meta/edge_stats/`) for instant reads
+- Timestamp string parsing with sample-based format detection (6 formats supported)
+- Windows timezone database fallback in timestamp parsing
+- Edge table auto-detect infers `timestamp_col` and `amount_col` from common column names (`timestamp`/`ts`/`event_time`/`created_at`/`tx_date`/`date` and `amount_received`/`amount`/`amount_paid`/`value`/`total`/`amt`) when not explicitly configured
+- `sphere.json` edge_table metadata persists full config (`from_col`, `to_col`, plus `timestamp_col`/`amount_col` when set)
+
+---
+
+## [0.1.0] — 2026-04-07
+
+First public release. Core GDS stack.
+
+### Added
+
+**Sphere Builder**
+- Declarative YAML config (`sphere.yaml`) with CLI: `hypertopos build`, `validate`, `info`
+- Three source tiers: single file (CSV/Parquet), multi-file join, Python script
+- Derived dimensions (count, sum, avg, windowed metrics, IET)
+- Precomputed dimensions with `edge_max` continuous mode
+- Graph features: `in_degree`, `out_degree`, `reciprocity`, `counterpart_overlap`
+- Composite lines (multi-key entities)
+- Chain lines (temporal BFS extraction with parallel processing)
+- Aliases with cutting-plane sub-populations
+- Temporal snapshot builder
+- `dimension_weights: kurtosis` automatic weighting
+- Incremental update (`GDSBuilder.incremental_update()`)
+
+**Navigation (π1–π12)**
+- π1 `walk_line` — step along a line
+- π2 `jump_polygon` — cross to related line via edge
+- π3 `dive_solid` — enter temporal history
+- π4 `emerge` — return to surface
+- π5 `attract_anomaly` — find outliers in population
+- π6 `attract_boundary` — find entities near alias boundary
+- π7 `attract_hub` — find most connected entities
+- π8 `attract_cluster` — discover geometric archetypes (k-means++)
+- π9 `attract_drift` — find entities with highest temporal drift
+- π10 `attract_trajectory` — find entities with similar trajectory (ANN)
+- π11 `attract_population_compare` — compare geometry across time windows
+- π12 `attract_regime_change` — detect structural shifts in population
+
+**Analysis & Investigation**
+- `explain_anomaly` — structured explanation with witness set, repair set, severity, reputation
+- `contrast_populations` — dimension-by-dimension comparison (Cohen's d)
+- `find_similar_entities` — ANN search in delta-space
+- `centroid_map` — group centroids for sub-population positioning
+- `composite_risk` — cross-pattern risk scoring (Fisher's method)
+- `cross_pattern_profile` — multi-pattern risk view for one entity
+- Full-text search (`search_entities_fts`) and hybrid search (semantic + FTS with RRF)
+- 10 detection recipes: cross-pattern discrepancy, neighbor contamination, trajectory anomaly, segment shift, event rate anomaly, hub concentration, subgroup inflation, collective drift, temporal burst, data quality
+
+**Forecasting**
+- Trajectory extrapolation (exponentially-weighted linear regression)
+- `forecast_anomaly_status` — predict future anomaly state
+- `forecast_segment_crossing` — predict boundary crossings
+- Pluggable `ForecastProvider` protocol for external backends
+
+**Model**
+- Point, Edge, Polygon, Solid, SolidSlice
+- Line, Pattern, Alias, Manifest, Contract
+- CalibrationTracker (online Welford drift detection)
+- MVCC sessions (version-pinned reads per agent)
+
+**Engine**
+- Delta vector computation with z-score normalization
+- Anomaly detection: theta threshold + conformal p-values
+- Mahalanobis variant (ellipsoidal boundary via Cholesky decomposition)
+- K-means++ clustering with automatic k selection (silhouette)
+- DTW trajectory comparison
+- Reputation scoring (Beta distribution posterior)
+- Investigation engine (witness set, anti-witness, severity classification)
+- Composition: Fisher's method for p-value combination, co-dispersion (Spearman)
+
+**Storage**
+- Arrow IPC format with Lance vector index (IVF-PQ)
+- BTREE, BITMAP, FTS indices on points
+- Append-only writes, LRU polygon cache
+- Geometry stats cache, temporal centroid cache, trajectory ANN index
+- Optional DataFusion SQL aggregation (~30x speedup on 5M+ events)
+
+**PassiveScanner**
+- Multi-source batch screening: geometry, borderline, points, compound sources
+- `auto_discover` — automatic source registration from sphere structure
+- Density boost, weighted scoring mode
+- 4 operating stages
+
+**Validation**
+- Berka banking benchmark (skill calibration, 6 runs)
+- NYC Yellow Taxi benchmark (domain generalization, 3 runs)
+- IBM AML benchmark (3-layer pipeline with cross-validation)
+
+**Documentation**
+- Quick Start guide
+- Core Concepts with mathematical foundation
+- API Reference with navigation primitive families
+- Configuration YAML reference with aliases
+- Physical data format reference
+- Architecture overview

hypertopos-0.2.0/LICENSE.md

@@ -0,0 +1,83 @@
+# Business Source License 1.1
+
+**Licensor:** Karol Kędzia
+
+**Licensed Work:** hypertopos
+Copyright (c) 2026 Karol Kędzia.
+
+**Additional Use Grant:** You may make production use of the Licensed Work,
+provided that you do not offer the Licensed Work to third parties on a hosted
+or embedded basis as a competitive offering.
+
+For purposes of this License:
+
+- **Competitive offering** means a Product offered to third parties on a paid
+  basis, including through paid support arrangements, that significantly
+  overlaps with the capabilities of the Licensor's paid version(s) of the
+  Licensed Work. If your Product is not a competitive offering when first made
+  generally available, it does not become a competitive offering later merely
+  because the Licensor releases new versions with additional capabilities.
+- **Product** means software offered to end users to run in their own
+  environments or offered as a service on a hosted basis.
+- **Embedded** means including source code or executable code from the Licensed
+  Work in a competitive offering, or packaging a competitive offering in a way
+  that requires the Licensed Work to be accessed or downloaded for the offering
+  to operate.
+- **Internal use** within an organization is not a competitive offering. Your
+  organization includes entities under common control.
+
+**Change Date:** 2029-04-09
+
+**Change License:** Apache License, Version 2.0
+
+Commercial licensing inquiries: contact@hypertopos.com
+
+---
+
+## Terms
+
+The Licensor grants you the right to copy, modify, create derivative works,
+redistribute, and make non-production use of the Licensed Work. The Licensor
+may make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the third anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the rights granted above terminate and the
+Change License applies instead.
+
+If your use of the Licensed Work does not comply with the requirements in
+effect under this License, you must obtain a commercial license from the
+Licensor, its affiliates, or authorized resellers, or stop using the Licensed
+Work.
+
+All copies of the original and modified Licensed Work, and derivative works of
+the Licensed Work, remain subject to this License. This License applies
+separately to each version of the Licensed Work, and the Change Date may vary
+by version.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive a copy of the Licensed Work under a
+different license, the terms of that license do not override this License.
+
+Any use of the Licensed Work in violation of this License terminates the rights
+granted under this License for the current and all other versions of the
+Licensed Work.
+
+This License does not grant you any right in any trademark or logo of the
+Licensor or its affiliates, except where this License expressly requires it.
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN
+"AS IS" BASIS. THE LICENSOR DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS OR
+IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE, NON-INFRINGEMENT, AND TITLE.
+
+This License text may be used to license your own works, and may be referred to
+as "Business Source License" provided you follow the public guidance published
+by MariaDB. Copying this License without modification is permitted as long as
+you keep the original text intact. Modifications to this License are not
+permitted.
+
+---
+
+License text copyright (c) 2024 MariaDB plc, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB plc.
+

hypertopos-0.2.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: hypertopos
+Version: 0.2.0
+Summary: Navigate your data like space.
+Project-URL: Homepage, https://github.com/hypertopos/hypertopos-py
+Project-URL: Documentation, https://github.com/hypertopos/hypertopos-py/tree/main/docs
+Project-URL: Repository, https://github.com/hypertopos/hypertopos-py
+Project-URL: Issues, https://github.com/hypertopos/hypertopos-py/issues
+Author: Karol Kędzia
+License: BSL-1.1
+License-File: LICENSE.md
+Requires-Python: >=3.12
+Requires-Dist: numpy>=1.26
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: pylance>=0.20
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: datafusion
+Requires-Dist: datafusion>=40.0; extra == 'datafusion'
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp[cli]>=1.20; extra == 'mcp'
+Requires-Dist: tzdata>=2024.1; extra == 'mcp'

hypertopos-0.2.0/README.md

@@ -0,0 +1,120 @@
+# hypertopos
+
+> **Navigate your data like space.**
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: BSL 1.1](https://img.shields.io/badge/license-BSL%201.1-orange.svg)](LICENSE.md)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19482069.svg)](https://doi.org/10.5281/zenodo.19482069)
+[![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/lancedb/lancedb)
+[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)
+[![Version](https://img.shields.io/badge/version-0.2.0-blue.svg)](pyproject.toml)
+
+**hypertopos** transforms relational data into navigable geometric space.
+
+Every entity — customer, vendor, transaction — accumulates a **polygon** built from its typed relationships: who it connects to, through which channels, how often, and with what properties filled or missing. The shape of that polygon is the entity's geometric identity.
+
+A **pattern** calibrates what "typical" looks like for a population: the mean shape (μ), the spread per dimension (σ), and a threshold (θ) derived from the empirical distribution. The resulting coordinate space supports clustering, population comparison, similarity search, hub analysis, boundary exploration, drift tracking, and anomaly detection — no model training, no labeled data, no tuning.
+
+Over time, polygons deform into **solids** — temporal stacks that capture how an entity's geometry evolves. Drift, trajectory similarity, and regime shifts become measurable geometric quantities.
+
+Twelve **navigation primitives** (π1–π12) let AI agents walk lines, jump across relationships, discover clusters, compare populations, find hubs, and track temporal change — all as stateful, composable geometric operations.
+
+```bash
+pip install hypertopos
+```
+
+![hypertopos overview](docs/images/hypertopos-overview.svg)
+
+## Under the Hood
+
+At its core, the system builds a population-calibrated coordinate space from typed relationships and entity properties — and enables agents to navigate it.
+
+Each entity occupies a position derived from statistical normalization (μ and σ per dimension), producing a shared coordinate system in ℝ^D.
+
+Navigation primitives turn this space into a stateful, step-by-step workspace, where clustering, anomaly detection, drift tracking, and temporal analysis are performed as geometric operations — without model training or learned embeddings.
+
+## What Makes It Different
+
+- **Geometry, not queries** — entities live in a population-calibrated coordinate space (μ, σ, θ). Position tells you what's typical. Distance reveals what's unusual, what's similar, and where clusters form.
+- **Navigate, don't search** — twelve primitives (π1–π12) let agents walk lines, jump across relationships, cluster populations, compare groups, find hubs, and track drift. Stateful, composable, geometric.
+- **Graph meets geometry** — edge tables give runtime graph traversal with geometric path scoring. Find paths scored by witness overlap and anomaly propagation — not just hop count. Lazy chain discovery without build-time extraction.
+- **Time is built in** — polygons accumulate into solids. Trajectory similarity, regime change detection, and drift analysis are first-class — not bolted on.
+- **Agents first** — designed for MCP tool-calling. Smart detection recipes, investigation workflows. The sphere is the agent's workspace.
+- **Zero training** — no ML models, no labels, no training pipeline. Population statistics and empirical thresholds. Deploy in minutes.
+
+> **Full power via MCP.** The core library provides the Python API. For the complete experience — guided investigation, smart detection, 66 tools exposed to AI agents — use **[hypertopos-mcp](https://github.com/hypertopos/hypertopos-mcp)** (`pip install hypertopos-mcp`). The MCP server turns navigation primitives into agent-callable tools with automatic context management, tool visibility phases, and detection recipes that chain multiple primitives into end-to-end investigative workflows.
+
+## How It Compares
+
+| | hypertopos | Neo4j GDS | Vector DBs | PyGOD |
+|---|---|---|---|---|
+| **Geometry from** | Entity's own relationships | Graph algorithms | External embeddings (ML) | Graph neural networks |
+| **Training required** | No | No | Embedding model needed | Yes |
+| **Population-relative** | Yes (μ, σ, θ per population) | No | No | No |
+| **Temporal** | Built-in (solids, drift, regimes) | Snapshot-based | No | No |
+| **Navigation** | 12 stateful primitives | Query-based | KNN search | N/A |
+| **Multi-hop** | Edge table (runtime graph + lazy chains) + pre-computed chain geometry | Native (Cypher, ad-hoc) | No | No |
+| **Anomaly propagation** | Contagion scoring + influence BFS in delta-space | No | No | Local neighborhood only |
+| **Agent-native (MCP)** | Yes | No | No | No |
+| **Explains why** | Witness sets, dimension ranking | Centrality scores | Nearest neighbors | Anomaly scores |
+
+hypertopos is not a graph database, a vector store, or an ML framework. It is a **geometric coordinate system** built from relational structure — designed for AI agents to navigate, not for humans to query.
+
+## Why This Matters
+
+Most systems either:
+
+- operate on raw relationships (queries, traversals), or
+- rely on trained models (embeddings, ML pipelines)
+
+This approach provides a third option:
+
+- a persistent, interpretable coordinate system
+- consistent across time
+- usable for multiple analytical tasks without retraining
+
+This enables simpler, more transparent analysis of complex relational systems.
+
+## Documentation
+
+| | |
+|---|---|
+| **[Quick Start](docs/quickstart.md)** | Install, build a sphere, navigate — in one page |
+| **[Core Concepts](docs/concepts.md)** | GDS mental model, objects, mathematical foundation |
+| **[API Reference](docs/api-reference.md)** | Python API — classes, methods, navigation primitives, errors |
+| **[Configuration](docs/configuration.md)** | Sphere builder YAML reference |
+| **[Data Format](docs/data-format.md)** | Physical storage — directory layout, Arrow schemas |
+| **[Architecture](docs/architecture.md)** | Package structure, layers, runtime flow |
+| **[Benchmarks](docs/benchmarks.md)** | Validation results — banking, AML, transportation |
+
+## Tech Stack
+
+| Technology | Role |
+|------------|------|
+| Python 3.12+ | Core language |
+| PyArrow | Arrow IPC format, in-memory transport |
+| NumPy | Vector operations, delta computation, DTW |
+| Lance | Vector index (IVF-PQ), scalar indices, predicate pushdown |
+| PyYAML | Sphere builder YAML config |
+
+## License
+
+Licensed under the [Business Source License 1.1](LICENSE.md).
+
+| Question | Answer |
+|----------|--------|
+| Can I use it internally? | Yes |
+| Development, testing, research? | Yes |
+| Host as a service for third parties? | Not if it competes with the Licensor's paid offering |
+| Embed in a commercial product? | Not if competitive |
+| When does it become Apache 2.0? | On the Change Date or third anniversary, whichever comes first |
+
+For commercial licensing: [contact@hypertopos.com](mailto:contact@hypertopos.com)
+
+## Contributing
+
+**Core library** — requires a Contributor License Agreement (CLA).
+**MCP server & docs** — DCO sign-off only (`Signed-off-by: Name <email>`).
+
+Bug reports, feature requests, and discussion via [GitHub Issues](https://github.com/hypertopos/hypertopos-py/issues).

hypertopos-0.2.0/ROADMAP.md

@@ -0,0 +1,73 @@
+# hypertopos — Roadmap
+
+> Planned direction. Priorities may change based on feedback. 
+
+## Current: 0.2.0
+
+**Graph meets geometry.** The main theme is the unified **edge table** — a Lance-based adjacency index per event pattern with BTREE lookups, auto-emitted at build time, giving runtime graph traversal at O(log n) scale.
+
+- **Edge table** — one Lance dataset per event pattern, BTREE indexes on `from_key`/`to_key`, MVCC session pinning, YAML `edge_table` config (auto-detected from `graph_features`/relations), `--no-edges` CLI flag
+- **11 new navigation functions** — `find_geometric_path` (beam search with geometric/anomaly/shortest/amount scoring), `discover_chains` (runtime temporal BFS, no build-time extraction), `entity_flow` (net flow per counterparty), `contagion_score` / `contagion_score_batch` (anomaly neighborhood scoring), `degree_velocity`, `investigation_coverage`, `propagate_influence` (BFS with geometric decay), `cluster_bridges` (geometry+graph fusion), `anomalous_edges` (event-level scoring)
+- **`find_counterparties` fast path** — edge table BTREE lookup with amount aggregates when `pattern_id` given
+- **PassiveScanner graph source** — `"graph"` source type for contagion scoring, `add_graph_source()`, `auto_discover()` auto-detects edge tables
+- **11 new MCP tools** — edge table tools available in Phase 2 (immediately after `open_sphere`), no `sphere_overview` needed. Total: 66 MCP tools (55 → 66)
+- **7 fraud investigation recipes** added to `gds-fraud-investigator` skill — Mirror Transaction, Pass-Through, Burst Detection, Weighted Reciprocity, Financial Profile, Concentration Risk, Benford's Law
+- **All 8 skills updated** — edge table tools integrated across `gds-analyst`, `gds-detective`, `gds-explorer`, `gds-fraud-investigator`, `gds-investigator`, `gds-monitor`, `gds-scanner`, `gds-sphere-designer`
+- **Builder improvements** — adjacency deduplication, self-loop filtering, edge stats cached at build time (`_gds_meta/edge_stats/`), timestamp string parsing with 6-format sample-based detection, Windows timezone database fallback
+- **Performance** — `passive_scan` 84s → <10s, `detect_pattern` 86s → <15s, `cluster_bridges` 31s → <5s
+- **Fixes** — `find_anomalies` Lance duplicate row deduplication, zero-variance `tracked_properties` cleanup in AML benchmark spheres
+
+---
+
+## 0.1.0
+
+Core GDS stack — sphere build, geometry, navigation, MCP server, storage/performance, and maintainability.
+
+- Sphere builder — declarative YAML config, CLI (`build`, `validate`, `info`), Tier 1-3 sources, derived/precomputed/graph dimensions, composite lines, chain lines
+- Navigation primitives π1–π12 — walk, jump, dive, emerge, attract (anomaly, boundary, hub, cluster), drift, trajectory, population compare, regime change
+- Aliases — cutting-plane sub-populations with derived geometry (W vector, bias, direction)
+- Temporal snapshots — deformation history, solid construction, temporal centroids
+- Investigation — `explain_anomaly`, witness set, anti-witness, reputation scoring
+- Forecasting — trajectory extrapolation, anomaly forecast, segment crossing prediction, pluggable `ForecastProvider` protocol
+- Full-text search — FTS index on points, `search_entities_fts`, hybrid search (semantic + FTS with reciprocal rank fusion)
+- CalibrationTracker — online Welford drift detection with soft/hard thresholds
+- MVCC sessions — Manifest/Contract version pinning, isolated reads per agent
+- PassiveScanner — multi-source batch screening (geometry, borderline, points, compound), auto-discover, density boost
+- Incremental update — `GDSBuilder.incremental_update()` for appending without full rebuild
+- MCP server (55 tools, smart detection mode, 3-phase tool visibility)
+- Validation suite — Berka (skill calibration), NYC Taxi (domain generalization), IBM AML (3-layer benchmark)
+- Storage — Lance vector index, Arrow IPC, LRU cache, append-only writes
+- Docs — quickstart, concepts, architecture, configuration, API reference, data format
+
+---
+
+## Plan: 0.3.0
+
+**Storage / performance:**
+- Upgrade `pylance 2.0.1 → 3.0.1` — format 2.2, ~300% faster scans, LZ4/zstd compression
+- Replace `shutil.copytree` with `lance.dataset.clone()` in test fixtures (O(1) metadata clone)
+- Builder: incremental rebuild (geometry-only without `--force` wipe)
+
+**Code refactoring:**
+- Break up oversized modules into smaller, domain-focused components
+- Reduce coupling between core layers by replacing private cross-layer access with explicit interfaces where practical
+- Tighten error handling in hot paths so failures are surfaced more consistently
+- Consolidate repeated orchestration logic into shared helpers instead of duplicating it across modules
+- Make the refactor pass incremental: preserve behavior, improve structure, then revisit deeper architectural boundaries
+
+**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. Core loop: enumerate patterns → single-source anomaly scans → greedy multi-source combination → ranked composition report. No labeled GT needed; optional GT file unlocks supervised calibration.
+
+**Anomaly detection quality:**
+- Confidence scoring, robust estimators, multi-scale resolution — improve anomaly precision and reduce false positives on heavy-tail and multi-modal populations
+
+---
+
+## Future
+
+- Cross-sphere comparison — dimensionless metrics across independently calibrated coordinate spaces
+- What-if analysis — hypothetical edge changes producing modified coordinate vectors
+- Dimension access control — per-agent visibility constraints on delta dimensions
+- Runtime latency benchmarks in package docs

hypertopos-0.2.0/SECURITY.md

@@ -0,0 +1,15 @@
+# Security
+
+## Current version: 0.2.x
+
+hypertopos runs locally. No network services, no auth layer, no multi-tenancy.
+
+## What to watch for
+
+- **Pickle files** — chain cache (`.cache/chains_*.pkl`) uses pickle. Don't load cache files from untrusted sources.
+- **Sphere paths** — `HyperSphere.open(path)` reads from the local filesystem. Don't point it at user-controlled paths without validation.
+- **MCP server** — communicates over stdio. Not designed for network exposure.
+
+## Reporting
+
+If you find a security issue: [GitHub private vulnerability reporting](https://github.com/hypertopos/hypertopos-py/security/advisories/new) or email [contact@hypertopos.com](mailto:contact@hypertopos.com).

hypertopos-0.2.0/docs/README.md

@@ -0,0 +1,38 @@
+# hypertopos Documentation
+
+> Package documentation for hypertopos — the AI-first geometric data sphere.
+
+## Reading Paths
+
+**New to hypertopos?** Start here:
+
+1. [Quick Start](quickstart.md) — install, build, navigate
+2. [Core Concepts](concepts.md) — the GDS mental model
+3. [Configuration](configuration.md) — sphere.yaml reference
+
+**Building a sphere?**
+→ [Configuration](configuration.md) — full YAML reference with examples
+
+**Writing Python code?**
+→ [API Reference](api-reference.md) — classes, methods, error types
+
+**Understanding the format?**
+→ [Data Format](data-format.md) — directory layout, Arrow schemas, sphere.json
+
+**Understanding the design?**
+→ [Architecture](architecture.md) — package structure, runtime flow
+
+**Checking the evidence?**
+→ [Benchmarks](benchmarks.md) — validation results across three domains
+
+## All Documents
+
+| Document | Description |
+|----------|-------------|
+| [quickstart.md](quickstart.md) | From zero to navigating a sphere |
+| [concepts.md](concepts.md) | Core GDS mental model and vocabulary |
+| [architecture.md](architecture.md) | Package structure, layers, design principles |
+| [configuration.md](configuration.md) | Sphere builder YAML reference |
+| [api-reference.md](api-reference.md) | Python API — classes, methods, errors |
+| [data-format.md](data-format.md) | Physical storage format on disk |
+| [benchmarks.md](benchmarks.md) | Validation results — Berka, IBM AML, NYC Taxi |