Metadata-Version: 2.4
Name: hypabase
Version: 0.1.0
Summary: A Python library for storing and querying n-ary relationships with provenance tracking. SQLite-backed, zero configuration.
Project-URL: Homepage, https://hypabase.app
Project-URL: Repository, https://github.com/hypabase/hypabase
Project-URL: Documentation, https://hypabase.app/docs
Author: Hypabase
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,context-graph,database,graphrag,hypergraph,hyperrag,knowledge-graph,mcp,n-ary,rag
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.0
Provides-Extra: cli
Requires-Dist: click>=8.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mike>=2.0; extra == 'docs'
Requires-Dist: mkdocs-llmstxt>=0.2; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Provides-Extra: mcp
Requires-Dist: click>=8.0; extra == 'mcp'
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# Hypabase

[![CI](https://github.com/hypabase/hypabase/actions/workflows/ci.yml/badge.svg)](https://github.com/hypabase/hypabase/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/hypabase)](https://pypi.org/project/hypabase/)
[![Python](https://img.shields.io/pypi/pyversions/hypabase)](https://pypi.org/project/hypabase/)
[![License](https://img.shields.io/github/license/hypabase/hypabase)](LICENSE)

Hypabase is a Python library for storing and querying relationships between entities. A single edge connects two or more nodes, every edge tracks where it came from (`source` and `confidence`), and the whole graph lives in a local SQLite file with no server or configuration.

Use it to build knowledge graphs, retrieval-augmented generation pipelines, and structured agent memory. Recent research explores hypergraph representations for these tasks:

- [HyperGraphRAG](https://arxiv.org/abs/2503.21322) — n-ary knowledge retrieval across medicine, agriculture, CS, and law
- [Cog-RAG](https://arxiv.org/abs/2511.13201) — dual-hypergraph retrieval with theme-level and entity-level recall
- [Hypergraph Memory for Multi-step RAG](https://arxiv.org/abs/2512.23959) — hypergraph-based memory for long-context relational modeling

## Install

```bash
uv add hypabase
```

## Quick example

```python
from hypabase import Hypabase

hb = Hypabase("my.db")  # local SQLite, zero config

# One edge connecting five entities
hb.edge(
    ["dr_smith", "patient_123", "aspirin", "headache", "mercy_hospital"],
    type="treatment",
    source="clinical_records",
    confidence=0.95,
)

# Query edges involving a node
hb.edges(containing=["patient_123"])

# Find paths between entities
hb.paths("dr_smith", "mercy_hospital")
```

## Provenance

Every edge carries `source` and `confidence`:

```python
hb.edge(
    ["patient_123", "aspirin", "ibuprofen"],
    type="drug_interaction",
    source="clinical_decision_support_v3",
    confidence=0.92,
)

# Bulk provenance
with hb.context(source="schema_analysis", confidence=0.9):
    hb.edge(["a", "b"], type="fk")
    hb.edge(["b", "c"], type="fk")

# Query by provenance
hb.edges(source="clinical_decision_support_v3")
hb.edges(min_confidence=0.9)

# Overview of all sources
hb.sources()
```

## Namespace isolation

Isolate data into separate namespaces within a single database file:

```python
hb = Hypabase("knowledge.db")

drugs = hb.database("drugs")
sessions = hb.database("sessions")

drugs.node("aspirin", type="drug")
sessions.node("s1", type="session")

drugs.nodes()     # → [aspirin]
sessions.nodes()  # → [s1]
```

## Features

- **N-ary hyperedges** — an edge connects 2+ nodes in a single relationship
- **O(1) vertex-set lookup** — find edges by their exact node set
- **Provenance** — every edge carries `source` and `confidence`
- **Provenance queries** — filter by `source` and `min_confidence`, summarize with `sources()`
- **SQLite persistence** — local-first, zero-config
- **Namespace isolation** — `.database("name")` for scoped views in a single file
- **MCP server** — 14 tools + 2 resources for AI agent integration
- **CLI** — `hypabase init`, `hypabase node`, `hypabase edge`, `hypabase query`

## Documentation

[hypabase.app/docs](https://hypabase.app/docs)

## License

Apache 2.0
