ramish-explorer 0.2.1

Explore .ramish knowledge graph files — query, validate, predict, and audit geometric truth.

Ramish Explorer

Read, query, and explore .ramish knowledge graph files.

Ramish Explorer is the free, open-source reader for .ramish engine files generated by Ramish.io — a geometric knowledge engine that maps structural integrity in relational databases using quaternion embeddings.

Install

pip install ramish-explorer

Quick Start

# File overview
ramish-explorer stats engine.ramish

# Hybrid geometric + graph query
ramish-explorer query engine.ramish "What relates to AC/DC?"

# Show all connections for an entity
ramish-explorer edges engine.ramish "Iron Maiden"

# Find similar entities (duplicate detection)
ramish-explorer similar engine.ramish "ABC Plumbing"

# Validate a specific relationship
ramish-explorer validate engine.ramish "Led Zeppelin" "genre" "Rock"

# Predict missing links (frozen key rotation)
ramish-explorer predict engine.ramish "Sunset Condo" "serviced_by"

# Recommend based on neighborhood averaging
ramish-explorer recommend engine.ramish "AC/DC" "has_genre"

# Interactive exploration
ramish-explorer explore engine.ramish

Commands

Command	Description
stats	File structure, geometry, and trust weight distribution
query	Hybrid geometric retrieval with graph reranking
validate	Check a specific triple (subject, relation, object)
edges	Show all edges for an entity with trust weights
similar	Find nearest neighbors by embedding distance
predict	Frozen key rotation inference (head + relation → tail)
recommend	Neighborhood averaging — entities similar to known targets
compose	Multi-hop quaternion composition (relation1 ⊗ relation2)
keys	Extract frozen relational keys with stability metrics
audit	Structural integrity report
requantize	Convert between fp32/fp16/int8 quantization
explore	Interactive REPL

What is a .ramish file?

A .ramish file is a portable, binary knowledge graph with truth weights. It contains:

• Entities mapped from your database tables (rows, columns, values)
• Relations connecting entities with typed edges
• Quaternion embeddings encoding geometric structure
• Truth weights measuring confidence in each relationship

Generate .ramish files at ramish.io.

Use Cases

• Data quality auditing — find orphaned records, low-confidence relationships, structural anomalies
• Duplicate detection — similar finds near-duplicates in embedding space
• Relationship exploration — edges shows the full connection web for any entity
• Link prediction — predict finds missing connections using frozen key rotation
• Drift monitoring — compare .ramish files over time to track data quality changes
• Geometric search — query combines embedding-space retrieval with graph structure for discovery

Requirements

• Python 3.8+
• numpy, click, rich (installed automatically)

Changelog

v0.2.1 (2026-03-23)

Geometric mode — New RamishFile.load_geometric() classmethod loads files via memory-mapping with zero RAM overhead. Entities are read for display names; relations, embeddings, and weights are mmap'd. All public methods (query, validate_claim, get_relations, get_top_hubs, audit, get_stats, narrow, autocomplete) transparently select the right code path based on load mode.

RNIX name resolution — Binary search name lookup via RNIX trailer (written at assembly time). Exact resolve in ~3 µs, prefix search for free. Used in both geometric and standard load modes when trailer is detected.

Bidirectional binary search — Sorted relations enable O(log n) edge lookups. Forward search uses head_id sort order; reverse search uses TSIX trailer (pre-computed tail_id argsort). Falls back to computed argsort for files under 50M relations, or outgoing-only for larger files without TSIX.

TSIX trailer — New trailer section storing pre-computed tail sort index. Assembler writes it once; reader mmap's it for zero-RAM reverse lookups at any scale. Format: TSIX magic + relation_count(u64) + dtype_code(u8) + pad(3B) + index data (u32 or u64 per relation).

Sampled audit — audit() in geometric mode uses sampled mmap analysis for orphan detection, weight distribution, and degree imbalance instead of loading all relations into RAM.

Test suite — 126 tests (40 new geometric mode tests covering RNIX, TSIX, binary search, query engine, validate_claim, get_relations, stats, audit, top_hubs, narrow, context manager). Zero regressions on existing 86 tests.

v0.2.0 (2026-03-23)

Geometric query engine — query() now uses hybrid lexical-seed → geometric retrieval → graph rerank, replacing the v0.1 wave-propagation path. Geometry provides recall, graph edges provide precision. Results without graph support are marked with ~similar.

Relation indexes — Pre-built lookup tables (edges_by_rel_type, out_edges, in_edges, compound indexes) replace full linear scans in predict, compose, keys, and REPL commands. Single O(n) build pass during load().

Sign-aligned frozen keys — Frozen key extraction now aligns quaternion signs before averaging, eliminating partial cancellation from sign ambiguity. Keys are cached per session (13,000x speedup on subsequent access). Stability score included.

Canonical quaternion layout — Single embedding_to_quats() helper replaces all inline reshape/transpose patterns. One source of truth for the component-major → (n, dim, 4) conversion.

Predict/recommend split — predict now always uses frozen key rotation (geometric inference). The old neighborhood-averaging behavior moves to a new recommend command.

File safety hardening — Header validation rejects files with entity/relation counts exceeding sanity bounds or file sizes too small for declared contents. Entity name length capped.

Test suite expansion — 90 tests covering indexes, geometric query, sign alignment, quaternion layout, file safety, predict semantics, and name resolution. All 33 original v0.1 regression tests pass unchanged.

v0.1.2 (2026-02-24)

Frozen rotation key infrastructure (.rkey files), spectral coherence scoring fix, Chinook audit time 16+ min → ~20 sec, exact edge hash storage.

v0.1.1 (2026-02-22)

Fix repository URL in package metadata.

v0.1.0 (2026-02-22)

Initial release. Reader, CLI, REPL, quaternion math, trust weight validation, audit.

License

MIT

Links

• Ramish.io — Generate .ramish files
• Documentation
• GitHub