Metadata-Version: 2.4
Name: hillock
Version: 0.8.0
Summary: A lightweight, 100% local neuro-symbolic memory engine.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: onnxruntime>=1.16.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pypdf>=3.17.0
Requires-Dist: torch>=2.0.0
Requires-Dist: transformers>=4.30.0
Requires-Dist: fastcoref>=2.1.0
Requires-Dist: glirel>=0.1.0
Requires-Dist: sentence-transformers>=2.2.2
Requires-Dist: spacy>=3.5.0
Requires-Dist: loguru
Requires-Dist: tiktoken
Requires-Dist: sentencepiece
Requires-Dist: protobuf
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.23.0
Provides-Extra: onnx-export
Requires-Dist: onnx>=1.14.0; extra == "onnx-export"
Requires-Dist: onnxconverter-common>=1.13.0; extra == "onnx-export"
Dynamic: license-file

<p align="center">
  <img src="assets/hillock_banner.jpg" alt="Hillock Banner" width="100%">
</p>

# Hillock

**A lightweight, 100% local memory engine built for edge hardware.**

![License](https://img.shields.io/badge/license-AGPL--3.0-blue)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![VRAM](https://img.shields.io/badge/VRAM-%3C1.2GB-brightgreen)
![Status](https://img.shields.io/badge/status-v0.8.0-orange)
[![Discord](https://img.shields.io/badge/Discord-Join%20Community-5865F2?logo=discord&logoColor=white)](https://discord.gg/BGUPNBcVdp)

Traditional local RAG is heavy. Running dense vector databases and using 8B+ generative LLMs just to parse documents burns VRAM, chokes mid-range GPUs, and still hallucinates when asked about things it doesn't know.

Hillock was built to solve this. It replaces bloated vector databases and token-hungry extraction passes with a lightweight, three-tier architecture: a relational SQLite Knowledge Graph, Hebbian synaptic memory, and Hyperdimensional Computing (HDC). 

It extracts facts, blocks unanswerable questions mathematically before they ever reach the LLM, and runs entirely in under 1.2 GB of VRAM.

### Why use Hillock?
* **Zero Hallucinations:** A hard mathematical gate blocks questions it doesn't know the answer to. It refuses honestly instead of guessing.
* **Extremely Fast Ingestion:** It uses tensor-based classification instead of an LLM to read documents. It can ingest a 30-sentence document in about 5 seconds.
* **Runs on a Potato:** The entire pipeline fits in <1.2 GB VRAM and can even run CPU-only if needed.
* **API Ready (New in v0.6.x):** Hillock now includes an OpenAI-compatible API server. You can plug its hallucination-free memory directly into UIs like Open-WebUI or Obsidian.

---

## 🚀 Quick Start

**Prerequisites:** Python 3.10+ and [Ollama](https://ollama.com/) running locally.

### Option A: 1-Click Launch (Recommended)
The launcher scripts create the virtual environment, install dependencies, and start the console automatically.

**Windows:**
```bat
run.bat
```

**Linux / macOS:**
```bash
chmod +x run.sh
./run.sh
```

### Option B: Manual Setup
```bash
git clone https://github.com/roandejager/Hillock.git
cd Hillock

python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install the engine and its dependencies
pip install -e .

# Download the required English language model
python -m spacy download en_core_web_sm
```

### Optional: ONNX CPU Predicate Routing

Install the ONNX export tools and create the FP16 MiniLM model:
```bash
pip install -e ".[onnx-export]"
python export_to_onnx.py
```

This writes `minilm.onnx` with dynamic batch and sequence dimensions. The ONNX router uses the CPU execution provider and the same mean-pooled, normalized cosine ranking as the PyTorch predicate router:
```python
from talon_engine import ONNXDynamicPredicateRouter

router = ONNXDynamicPredicateRouter(model_path="minilm.onnx")
predicates = router.select_top_predicates_batch(["Marie Curie was born in Warsaw."])
```

---

## 🕹️ How to Use Hillock

Because Hillock is decoupled, you can use it in three different ways depending on your needs.

### 1. The API Server (For Custom UIs)
You can run Hillock in the background and connect it to your favorite AI interface (like Open-WebUI or AnythingLLM).
```bash
python api.py
```
This starts a local server at `http://localhost:8000`. Just go into your UI's settings, set the OpenAI API Base URL to `http://localhost:8000/v1`, and chat normally.

### 2. The Terminal Console
If you prefer the classic hacker aesthetic, you can chat with your documents directly in the terminal.
```bash
python main.py
```
**Helpful CLI Commands:**
* `/ingest [file.txt or .pdf]` : Feed a document into the memory engine.
* `/model [name]` : Switch your local Ollama model on the fly.
* `/mode [strict | balanced | conversational]` : Change how the assistant talks.
* `/inspect [entity]` : Look under the hood at exactly what the engine knows about a topic.

### 3. The Python Library (For Developers)
You can import Hillock directly into your own Python applications.
```python
from engine import IntegratedHillock

# Initialize the memory engine
my_brain = IntegratedHillock("my_database.db")

# Query it programmatically
answer, primed_nodes, hdc_traces, mode = my_brain.execute_chat_turn("What did Alan Turing crack?")
print(answer)
```

---

## ✅ Verification Suite

Hillock includes a standalone, GPU-free test suite that checks the core mathematical invariants, database locks, and gating logic. It is safe to wire into CI pipelines without a GPU runner.

```bash
python verify_hillock.py
```

---

## 🗺️ Roadmap to v1.0

The full, detailed roadmap is tracked in **[Issue #1: The Path to v1.0](https://github.com/roandejager/Hillock/issues/1)**. 

With our conversational agent and performance updates complete, our immediate next steps focus on automated data connectors for frictionless directory and vault ingestion.

---

## 💼 Commercial Dual Licensing

Hillock is free and open-source under the **GNU Affero General Public License v3.0 (AGPL-3.0)**. Under the terms of the AGPL, any company or developer building closed-source, proprietary software on top of Hillock must also release their entire proprietary codebase publicly under the AGPL-3.0.

If you are a startup, enterprise, or commercial developer building proprietary software and want to embed Hillock without open-sourcing your own application code, you must obtain an **AGPL-Exempt Commercial License**.

### What the commercial license includes:
* **AGPL-3.0 Exemption:** Keep your product, custom integrations, and intellectual property completely closed-source and proprietary.
* **Full Legal Indemnity:** Commercial protection to distribute Hillock inside your proprietary apps, on-premise tools, or SaaS backends.
* **Direct Integration Support:** Priority email support directly with the maintainer for architecture design, performance tuning, and hardware pipelines.

### Pricing:
* **$49 per month** : [Purchase Monthly License](https://hillock.lemonsqueezy.com/checkout/buy/8c0f191c-e488-479b-818a-0d87226b638e)
* **$499 per year** : [Purchase Annual License](https://hillock.lemonsqueezy.com/checkout/buy/1566c0ba-6432-48ec-8e7c-8259a058bcd1)

*If you need custom SLA terms, bespoke enterprise deployments, or custom relation extraction schemas, reach out directly at [contact.roandejager@gmail.com](mailto:contact.roandejager@gmail.com).*

---

## 🤝 Sponsors & Community Support

Hillock is an independent, open-source research project built for engineers running local AI on consumer hardware. Supporting Hillock directly funds local edge-first AI research and puts your developer tool or infrastructure platform in front of engineers building with this repository.

### One-Time Support:
* **[Tip or Buy a Coffee](https://hillock.lemonsqueezy.com/checkout/buy/86c9b457-e8de-45d7-9c34-18421d7d787e)** : Leave a custom one-time contribution to support ongoing open-source development.

### Sponsorship Tiers:
* **Backer ($15 per month):** Your name or GitHub handle permanently listed in the README Backers section. [Become a Backer](https://hillock.lemonsqueezy.com/checkout/buy/9ad8886f-5aa5-4f9d-9d6c-9e5bb7fcc9eb).
* **Featured Partner ($100 per month):** Your product logo, link, and short description placed near the top of the README.
* **Enterprise Sponsor ($300 per month):** Large logo placement across both the README and documentation, plus social shoutouts.

Interested in becoming a Featured Partner or Enterprise Sponsor for your developer tool? Reach out directly via [GitHub Discussions](https://github.com/roandejager/Hillock/discussions) or browse our store:

* **[Visit the Lemon Squeezy Store](https://hillock.lemonsqueezy.com)**

---

## ⚖️ Licensing & Contributions

Licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**.

To keep the project open-source while preserving the option for future commercial dual-licensing, contributors must sign a standard **Contributor License Agreement (CLA)** via `cla-assistant.io` when opening a PR. See `CONTRIBUTING.md` and `CLA.md`.

## 📬 Contact & Collaboration

Hillock is an active research project by **Roan de Jager**. 

If you are interested in custom memory integrations, consulting on edge-AI systems, or commercial licensing, feel free to reach out directly via email at **[contact.roandejager@gmail.com](mailto:contact.roandejager@gmail.com)** or open a discussion on GitHub.
