# 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](https://ramish.io) — a geometric knowledge engine that maps structural integrity in relational databases using quaternion embeddings.

## Install

```bash
pip install ramish-explorer
```

## Quick Start

```bash
# File overview
ramish-explorer stats engine.ramish

# Natural language search
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
ramish-explorer predict engine.ramish "Sunset Condo" "serviced_by"

# Interactive exploration
ramish-explorer explore engine.ramish
```

## Commands

| Command | Description |
|---------|-------------|
| `stats` | File structure, geometry, and trust weight distribution |
| `query` | Natural language search with wave propagation |
| `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) |
| `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](https://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

## Requirements

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

## License

MIT

## Links

- [Ramish.io](https://ramish.io) — Generate .ramish files
- [Documentation](https://ramish.io/docs)
