Hillock API Reference: HTTP Endpoints and Python SDK

Hillock exposes two interfaces: an OpenAI-compatible HTTP API served by FastAPI, and a Python library you can import directly into any agent framework or script. Both interfaces share the same underlying IntegratedHillock engine instance — the FastAPI server is a thin HTTP wrapper around the same reasoning pipeline you call directly in Python. This page covers both in full.

FastAPI Server

The HTTP server (api.py) starts a FastAPI application on port 8000 and exposes a chat completions endpoint that any OpenAI-compatible client can point to without modification. Base URL: http://localhost:8000 Start the server:

python api.py

🚀 Starting Hillock OpenAI-Compatible API Server on http://0.0.0.0:8000

The server binds to 0.0.0.0:8000 — it accepts connections on all interfaces. On a shared machine, firewall port 8000 if you don’t want it accessible on your local network.

`GET /`

Health check. Returns a status object confirming the server is online. Response

{
  "status": "online",
  "message": "Hillock API is running! Point your AI client to /v1/chat/completions",
  "version": "0.6.1"
}

string

Always "online" when the server is running.

string

A human-readable prompt pointing you to the chat completions endpoint.

string

The running Hillock API version string.

`POST /v1/chat/completions`

OpenAI-compatible chat completions. Extracts the last user message from the messages array, routes it through IntegratedHillock.execute_chat_turn(), and returns an OpenAI-format response. Drop-in compatible with any client that supports the OpenAI Chat Completions API. Request body

string

required

Model identifier string. Hillock ignores this value and uses whichever Ollama model is currently configured on the server. Pass any string — "hillock" works fine.

array

required

Array of message objects, each with role ("user" or "assistant") and content (string). Only the last message with role: "user" is processed; earlier messages are not used for context retrieval.

boolean

If true, returns a Server-Sent Events (SSE) streaming response in OpenAI delta format. Defaults to false.

number

Accepted in the request body but not forwarded to the LLM — Hillock always runs at temperature: 0.0 for deterministic fact rendering. Defaults to 0.0.

Request example

{
  "model": "hillock",
  "messages": [
    {"role": "user", "content": "What did Marie Curie discover?"}
  ],
  "stream": false
}

Response (non-streaming)

string

Unique completion ID in the format chatcmpl-{uuid}.

string

Always "chat.completion".

integer

Unix timestamp of when the response was generated.

string

Echoes back the model string from the request.

array

Array containing a single completion choice object.

integer

Always 0.

string

Always "assistant".

string

The rendered response from Hillock. CLI prefixes (e.g. Hillock (Renderer) >) are automatically stripped before this field is populated.

string

Always "stop".

object

Token usage object. All fields (prompt_tokens, completion_tokens, total_tokens) return 0 — Hillock does not track token counts.

{
  "id": "chatcmpl-3f7a2b1e9d4c6a0f8b5e2d1c7a4f9b3e",
  "object": "chat.completion",
  "created": 1720000000,
  "model": "hillock",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Marie Curie discovered Radioactivity."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

Streaming response When stream: true, the server returns Content-Type: text/event-stream. The full response text is sent as a single content delta, followed by a stop chunk and [DONE].

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1720000000,"model":"hillock","choices":[{"index":0,"delta":{"content":"Marie Curie discovered Radioactivity."},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1720000000,"model":"hillock","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Hillock’s streaming implementation yields the complete reply text in a single delta chunk rather than token-by-token. Clients that expect incremental token streaming will receive the full response at once before the stop chunk arrives.

Error responses

Status	Cause
`422 Unprocessable Entity`	Request body failed Pydantic validation (missing required fields, wrong types).
`500 Internal Server Error`	Ollama is unreachable, the configured model is not pulled, or an unhandled exception occurred in the engine.

Example: OpenAI Python client pointed at Hillock

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed",  # Hillock doesn't require authentication
)

response = client.chat.completions.create(
    model="hillock",
    messages=[{"role": "user", "content": "What did Marie Curie discover?"}],
)

print(response.choices[0].message.content)
# Marie Curie discovered Radioactivity.

Python Library

Import IntegratedHillock directly to embed Hillock into any Python application, agent loop, or evaluation harness.

from engine import IntegratedHillock
from ingestor import ingest_document_parallel
from config import DB_FILE

hillock = IntegratedHillock(DB_FILE)

`IntegratedHillock(db_path, ollama_model)`

Constructor. Initializes all Hillock subsystems in sequence: SQLiteKnowledgeGraph, HebbianPlasticityEngine, HyperdimensionalReservoir, and GloVe encoder. Seeds the HDC codebook with every entity currently in the knowledge graph.

string

Path to the SQLite database file. Created automatically if it doesn’t exist. Defaults to DB_FILE from config.py ("hillock_kg.db").

string

Name of the Ollama model to use for LLM rendering. Defaults to "llama3.2".

from engine import IntegratedHillock

# Default configuration
hillock = IntegratedHillock("hillock_kg.db")

# Custom model and database path
hillock = IntegratedHillock(
    db_path="/data/my_project.db",
    ollama_model="mistral",
)

Instance attributes you can read and set at runtime:

Attribute	Type	Default	Description
`ollama_model`	`str`	`"llama3.2"`	Active Ollama model. Assignable at any time.
`verbosity_mode`	`str`	`"BALANCED"`	Response personality: `"STRICT"`, `"BALANCED"`, or `"CONVERSATIONAL"`.
`debug_level`	`str`	`"OFF"`	Trace verbosity: `"OFF"`, `"LOW"`, or `"FULL"`.
`kg`	`SQLiteKnowledgeGraph`	—	Direct handle to the knowledge graph.
`plasticity`	`HebbianPlasticityEngine`	—	Direct handle to the Hebbian plasticity engine.
`hdc`	`HyperdimensionalReservoir`	—	Direct handle to the HDC reservoir.

`execute_chat_turn(query)`

Main reasoning pipeline. Runs the full neuro-symbolic inference chain: entity linking → HDC reservoir step → knowledge graph fact retrieval → HDC gate scoring → LLM rendering. This is the method the FastAPI server calls on every request.

reply, primed, fingerprint, mode = hillock.execute_chat_turn(
    "What did Marie Curie discover?"
)
print(reply)
# Hillock (Renderer) > Marie Curie discovered Radioactivity.

string

required

The user’s natural-language question or statement.

Returns: Tuple[str, List[Tuple[str, float]], List[Tuple[str, float]], str]

string

The full response string from Hillock, prefixed with "Hillock (Renderer) > " on LLM-rendered responses or "Hillock > " on deterministic fallbacks.

list[tuple[str, float]]

Top Hebbian priming activations from the plasticity engine: list of (entity_id, synaptic_strength) tuples, ordered by strength descending. Empty list if no facts matched.

list[tuple[str, float]]

Top HDC context fingerprint entries: list of (entity_id, cosine_similarity) tuples from the reservoir’s fading memory state. Empty list if no HDC context is active.

string

Execution mode tag indicating how the response was generated. One of: "RENDER_SUCCESS", "RENDER_FALLBACK", "GREETING", "DETERMINISTIC_GATED_FALLBACK", "CONVERSATIONAL_REFUSAL".

When verbosity_mode is "STRICT" and no matching facts are found, the method returns immediately with "I do not have verified information about that." — no LLM call is made, making it the fastest and most deterministic mode.

`get_ambiguous_facts()`

Scans the knowledge graph for stored SPO triples where the subject or object is a bare pronoun (he, she, it, they, this, that, who, whom, which, his, her). Call this after ingestion to identify facts that need human disambiguation.

ambiguous = hillock.get_ambiguous_facts()
for subject, predicate, obj, source_doc in ambiguous:
    print(f"[{subject}] -[{predicate}]-> [{obj}]  (source: {source_doc})")
# [she] -[discovered]-> [Radioactivity]  (source: curie_biography.pdf)

Returns: List[Tuple[str, str, str, str]] Each tuple contains (subject, predicate, object, source_doc). The ambiguous term is whichever of subject or object is a pronoun.

`resolve_ambiguous_fact(old_s, p, old_o, new_s, new_o)`

Resolves a pronoun ambiguity by deleting the ambiguous triple and replacing it with a human-confirmed triple at confidence = 1.0. Also allocates HDC hypervectors for any new entities introduced by the resolution.

# Resolve [she] -[discovered]-> [Radioactivity]
hillock.resolve_ambiguous_fact(
    old_s="she",
    p="discovered",
    old_o="Radioactivity",
    new_s="Marie_Curie",
    new_o="Radioactivity",
)

string

required

Subject of the ambiguous fact to delete (as returned by get_ambiguous_facts()).

string

required

Predicate of the ambiguous fact to delete.

string

required

Object of the ambiguous fact to delete.

string

required

Resolved subject for the replacement fact. Will be normalized via resolve_entity_identity() before insertion.

string

required

Resolved object for the replacement fact. Will be normalized via resolve_entity_identity() before insertion.

Returns: None

Resolved facts are stored with source_doc = "human_disambiguation" and confidence = 1.0. They are never overwritten by subsequent ingestion of the same document.

`link_entities(query)`

Performs token-level entity linking against the knowledge graph. Tokenizes the query, then checks each token against every entity ID in the graph, matching on individual word parts (split by _). Tokens shorter than three characters are skipped.

entities = hillock.link_entities("What did Marie Curie discover?")
print(entities)
# {'Marie_Curie'}

string

required

Natural-language query string to link.

Returns: Set[str] Set of matched entity IDs from the knowledge graph. Empty set if no tokens match any registered entity.

`resolve_entity_identity(entity_str)`

Normalizes an entity name for consistent knowledge graph lookup. Strips trailing possessives ('s, _s), converts spaces to underscores, lowercases, then attempts exact match → word-part match → fallback to the normalized input string.

print(hillock.resolve_entity_identity("Marie Curie's"))
# Marie_Curie

print(hillock.resolve_entity_identity("curie"))
# Marie_Curie  (matched via word-part "curie")

print(hillock.resolve_entity_identity("unknown_entity"))
# unknown_entity  (fallback: returned as-is)

string

required

Raw entity string from extraction output or user input.

Returns: str The canonical entity ID from the knowledge graph if a match is found, otherwise the normalized version of the input string.

`ingest_document_parallel(file_path, hillock)`

Top-level ingestion function. Reads a .txt or .pdf document, runs the full TALON extraction pipeline (coreference resolution → predicate normalization → relation extraction), commits all extracted triples to the knowledge graph, updates Hebbian weights for co-occurring entities, generates and binds multi-hop hypergraph paths into the HDC reservoir, and persists a compact reservoir BLOB to SQLite.

from ingestor import ingest_document_parallel
from engine import IntegratedHillock
from config import DB_FILE

hillock = IntegratedHillock(DB_FILE)

summary, stats = ingest_document_parallel(
    "./research_papers/curie_biography.pdf",
    hillock,
)

print(summary)
print(f"Extracted {stats['extracted_triples']} triples in {stats['total_time']:.2f}s")

string

required

Absolute or relative path to a .txt or .pdf file. Relative paths are resolved from the working directory.

IntegratedHillock

required

An initialized IntegratedHillock instance. The function writes directly to hillock.kg, hillock.plasticity, and hillock.hdc.

Returns: Tuple[str, Dict[str, float]]

string

Human-readable ingestion report (multi-line string) including file name, sentence count, extracted triple count, multi-hop path count, timing breakdown, and CPU/RAM utilization.

dict

Machine-readable timing and count data. Keys:

Key	Type	Description
`load_and_first_extraction_time`	`float`	Seconds from function entry to first extracted triple (model cold-start cost).
`pure_extraction_time`	`float`	Seconds from first to last extracted triple (pure TALON throughput window).
`pure_rate`	`float`	Sentences per second during the pure extraction window.
`total_time`	`float`	Total wall-clock seconds for the entire ingestion call.
`total_sentences`	`int`	Number of sentences detected in the source document.
`extracted_triples`	`int`	Number of 1-hop SPO triples extracted and stored.

ingest_document_parallel requires the full TALON dependency stack: glirel, fastcoref, spacy (en_core_web_sm), and torch. If any are missing, the function prints a warning and returns an empty stats dict without modifying the knowledge graph. Run pip install -r requirements.txt && python -m spacy download en_core_web_sm to install everything.

The TALON engine instance is lazy-loaded and cached as a module-level singleton on first call. Subsequent calls within the same process skip the cold-start cost. The models are unloaded and the singleton is cleared after each ingestion call to free GPU VRAM.

Getting Started

Architecture

Integrations & Guides

Reference

Commercial & Community

Hillock API Reference: HTTP Endpoints and Python SDK

FastAPI Server

`GET /`

`POST /v1/chat/completions`

Python Library

`IntegratedHillock(db_path, ollama_model)`

`execute_chat_turn(query)`

`get_ambiguous_facts()`

`resolve_ambiguous_fact(old_s, p, old_o, new_s, new_o)`

`link_entities(query)`

`resolve_entity_identity(entity_str)`

`ingest_document_parallel(file_path, hillock)`

​FastAPI Server

​GET /

​POST /v1/chat/completions

​Python Library

​IntegratedHillock(db_path, ollama_model)

​execute_chat_turn(query)

​get_ambiguous_facts()

​resolve_ambiguous_fact(old_s, p, old_o, new_s, new_o)

​link_entities(query)

​resolve_entity_identity(entity_str)

​ingest_document_parallel(file_path, hillock)

FastAPI Server

`GET /`

`POST /v1/chat/completions`

Python Library

`IntegratedHillock(db_path, ollama_model)`

`execute_chat_turn(query)`

`get_ambiguous_facts()`

`resolve_ambiguous_fact(old_s, p, old_o, new_s, new_o)`

`link_entities(query)`

`resolve_entity_identity(entity_str)`

`ingest_document_parallel(file_path, hillock)`