> ## Documentation Index
> Fetch the complete documentation index at: https://hillock.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart: Run Hillock Locally in Under 5 Minutes

> Install Hillock via pip, connect to a local Ollama model, ingest your first document, and query the interactive CLI with the HDC hallucination gate active.

By the end of this guide you'll have Hillock running locally, a document ingested into the Knowledge Graph, and the interactive CLI answering questions from your document's extracted facts — with the HDC hallucination gate active from the first query. The entire setup runs on your machine with no cloud dependencies.

<Note>
  **Prerequisites before you begin:**

  * **Python 3.10 or later** — check with `python --version`
  * **Ollama installed and running** — download from [ollama.com](https://ollama.com)
  * **A local Ollama model pulled** — Hillock defaults to `llama3.2`. Run `ollama pull llama3.2` if you haven't already. Any Ollama-compatible model works; smaller models like `phi3:mini` also run well.
</Note>

<Steps>
  <Step title="Install Hillock">
    The fastest way to install is via pip:

    ```bash theme={null}
    pip install hillock
    ```

    Alternatively, use the **one-click launcher** to clone the repo, create a virtual environment, install all dependencies, and start the console automatically:

    <Tabs>
      <Tab title="Linux / macOS">
        ```bash theme={null}
        git clone https://github.com/roandejager/Hillock.git
        cd Hillock
        chmod +x run.sh
        ./run.sh
        ```
      </Tab>

      <Tab title="Windows">
        ```bat theme={null}
        git clone https://github.com/roandejager/Hillock.git
        cd Hillock
        run.bat
        ```
      </Tab>
    </Tabs>

    If you cloned manually and want to install in editable mode:

    ```bash theme={null}
    pip install -e .
    python -m spacy download en_core_web_sm
    ```
  </Step>

  <Step title="Start Ollama">
    Pull the default model and make sure the Ollama server is running:

    ```bash theme={null}
    ollama pull llama3.2
    ollama serve
    ```

    Ollama listens on `http://localhost:11434` by default. Hillock connects to this endpoint automatically — no additional configuration needed unless you change the port.

    <Tip>
      You can swap to any model at any time from inside the Hillock CLI using `/model phi3:mini`. Smaller models run faster and use less VRAM alongside Hillock's pipeline.
    </Tip>
  </Step>

  <Step title="Launch the CLI">
    If you installed via pip:

    ```bash theme={null}
    hillock
    ```

    If you're running from source:

    ```bash theme={null}
    python main.py
    ```

    You'll see Hillock's banner, a list of available local Ollama models, and the interactive prompt. The Knowledge Graph is created automatically at `hillock_kg.db` in your working directory on first launch.
  </Step>

  <Step title="Ingest a document">
    Feed a document into Hillock's memory using the `/ingest` command. Both plain text (`.txt`) and PDF (`.pdf`) files are supported:

    ```
    You > /ingest path/to/your/document.pdf
    ```

    TALON processes the document in parallel blocks (5 sentences per block, 2 sentences of overlap), extracts Subject-Predicate-Object triples using spaCy and GLiREL, resolves coreferences, and writes the resulting facts into the SQLite Knowledge Graph. For a typical 30-sentence document, this takes roughly 5 seconds.

    After ingestion, Hillock may launch the **Active Disambiguation Quiz** — see the tip below.

    <Tip>
      **Active Disambiguation Quiz:** After ingesting, Hillock scans the Knowledge Graph for unresolved pronoun references (e.g., facts where the subject is stored as "he" or "she"). It presents these ambiguous facts one-by-one and asks you to clarify the referent. Resolving these improves retrieval precision significantly — take a few seconds to answer each prompt.
    </Tip>
  </Step>

  <Step title="Ask a question">
    Type any question about the content you just ingested:

    ```
    You > What did Alan Turing crack?

    Hillock (Renderer) > According to the ingested document, Alan Turing cracked the
    Enigma cipher during World War II. (Source: document.pdf)
    ```

    If you ask something Hillock doesn't have verified facts for, the HDC gate blocks the query and returns an honest refusal instead of a fabricated answer:

    ```
    You > What is Alan Turing's favourite colour?

    Hillock > I do not have verified information about that.
    ```

    You can also use these CLI commands to explore and tune Hillock's behaviour:

    | Command | Description |
    | - | - |
    | `/ingest <file>` | Ingest a `.txt` or `.pdf` document into the Knowledge Graph |
    | `/model <name>` | Switch the active Ollama model on the fly, or list available models |
    | `/mode strict \| balanced \| conversational` | Change the answering verbosity mode |
    | `/inspect <entity>` | Display all stored SPO facts and Hebbian weights for an entity |
    | `/status` | Show live hardware profile and Knowledge Graph statistics |
    | `/debug off \| low \| full` | Set background log verbosity (off hides traces; full shows HDC scores) |
    | `/reset` | Clear and re-seed the Knowledge Graph and HDC hypervector space |
    | `/help` | Display the full command reference |
  </Step>
</Steps>

## Configuration

Hillock's key settings live in `config.py`. The defaults work for most setups, but you can edit them directly for your hardware and workflow:

```python theme={null}
# config.py

# The local Ollama model Hillock uses for rendering answers
OLLAMA_MODEL = "llama3.2"        # or "phi3:mini", "mistral", etc.

# HDC gate threshold — queries must score ≥ this value to reach the LLM
HDC_THRESHOLD = 0.55             # Raise to be more restrictive, lower for more permissive retrieval

# SQLite Knowledge Graph file path (relative to your working directory)
DB_FILE = "hillock_kg.db"

# Hyperdimensional Computing vector size — larger = more expressive, more RAM
HDC_DIMENSION = 10000

# Parallel ingestion block settings
BLOCK_SIZE = 5                   # Sentences per extraction block
BLOCK_OVERLAP = 2                # Overlap between adjacent blocks
```

<Note>
  Raising `HDC_THRESHOLD` above 0.55 makes the gate stricter — fewer facts pass, but false positives decrease. Lowering it below 0.55 lets more candidate facts through but increases the risk of the LLM receiving weakly matched context. The default of 0.55 was calibrated to eliminate hallucination leaks on the test suite.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Architecture Deep Dive" icon="layer-group" href="/architecture/three-tier-system">
    Understand how the SQLite Knowledge Graph, Hebbian plasticity engine, and HDC reservoir interact at query time.
  </Card>

  <Card title="Python Library" icon="python" href="/guides/python-library">
    Embed `IntegratedHillock` directly in your Python application for programmatic ingestion and querying.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.