IntegratedHillock directly, feed it documents, resolve ambiguous facts programmatically, and drive the full neuro-symbolic reasoning pipeline from your own code. This page walks through installation, the core ingestion and query loop, streaming output, and the complete public API surface.
Installation
IntegratedHillock requires Ollama running locally at http://localhost:11434 to execute execute_chat_turn(). Document ingestion and HDC gating work fully offline without Ollama — you only need it for the final LLM rendering step.Basic Usage
1
Import and initialize
Instantiate By default, Hillock uses the database file path and Ollama model defined in
IntegratedHillock to boot all subsystems: the SQLite knowledge graph, the Hebbian plasticity engine, and the hyperdimensional computing reservoir. The constructor seeds the KG with built-in knowledge and allocates HDC hypervectors for every registered entity.config.py. You can override both at construction time:2
Ingest a document
Pass any local The
.txt or .pdf file through the TALON extraction pipeline. TALON extracts subject-predicate-object triples, resolves coreferences, binds multi-hop relational paths into the HDC reservoir, and persists everything to SQLite. The function returns a human-readable summary string and a dict of timing statistics.timing dict keys are:3
Handle disambiguation (recommended)
TALON’s coreference resolver occasionally extracts facts where a subject or object is an unresolved pronoun (e.g., Resolved facts are written back to SQLite with
he, she, it). Call get_ambiguous_facts() after ingestion to surface these, then resolve them with resolve_ambiguous_fact().confidence = 1.0 and tagged source_doc = "human_disambiguation", so they are treated as high-trust anchors during HDC gating.4
Ask a question
Call The return tuple carries:
execute_chat_turn() with any natural-language question. Hillock links the query tokens to KG entities, gates candidate facts through the HDC similarity threshold, primes associated concepts via Hebbian weights, and streams the grounded answer through Ollama to sys.stdout. The full concatenated response is also returned as the first element of the tuple.Streaming Responses
execute_chat_turn() drives query_ollama_stream() internally, which writes tokens directly to sys.stdout as they arrive from Ollama’s SSE stream. The full concatenated response is returned as the first element of the tuple once streaming completes.
If you need to capture tokens as they stream (e.g., to pipe them to a websocket), patch sys.stdout:
API Reference
IntegratedHillock(db_path, ollama_model)
Initializes all Hillock subsystems. Safe to call multiple times with different db_path values to maintain separate knowledge bases.
Path to the SQLite database file. Created automatically if it does not exist.
Name of the Ollama model to use for LLM rendering. Must be pulled locally via
ollama pull <model>.execute_chat_turn(query)
The main entry point for the full reasoning pipeline. Links query tokens to KG entities, gates facts through the HDC threshold, primes Hebbian associations, and streams a grounded response to sys.stdout.
Natural-language question or statement. Greetings and single-word inputs are handled gracefully without triggering the KG lookup.
Tuple[str, List[Tuple[str, float]], List[Tuple[str, float]], str]
get_ambiguous_facts()
Scans the knowledge graph for stored triples where the subject or object is a pronoun (he, she, it, they, this, that, who, whom, which, his, her).
Returns: List[Tuple[str, str, str, str]] — list of (subject, predicate, object, source_doc) tuples.
resolve_ambiguous_fact(old_s, p, old_o, new_s, new_o)
Deletes the ambiguous triple and replaces it with a human-clarified version tagged as confidence = 1.0.
ingest_document_parallel(file_path, hillock)
Routes a .txt or .pdf document through the TALON extraction pipeline, commits triples to the knowledge graph, and binds multi-hop paths into the HDC reservoir.
An initialized
IntegratedHillock instance. The function writes extracted entities and triples directly into this instance’s knowledge graph and HDC reservoir.Tuple[str, Dict[str, float]] — a human-readable summary string and a timing statistics dictionary.
link_entities(query)
Tokenizes query and matches tokens against all entity IDs in the knowledge graph. Used internally by execute_chat_turn() to build the candidate fact set.
Returns: Set[str] — set of matched entity IDs.
resolve_entity_identity(entity_str)
Normalizes raw entity strings: strips possessive suffixes ('s, _s), lower-cases, and resolves partial matches against registered KG entity IDs. Use this before storing or looking up entities manually.
Returns: str — canonical entity ID (underscore-delimited, lowercase).
Configuration
Hillock’s runtime behavior is controlled by constants inconfig.py. Edit them before initializing IntegratedHillock to change defaults across your application.
You can also override model and database at the instance level without touching
config.py: