Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/kernelshreyak/knowledge_engine-problemsolver

A general knowledge representation and querying system that helps understand relationships between concepts, simulate scenarios and find solutions to problems
https://github.com/kernelshreyak/knowledge_engine-problemsolver

falkordb graphiti graphrag knowledge-discovery knowledge-graph knowledge-management ontology-engineering owl-ontology rdf

Last synced: 24 days ago
JSON representation

A general knowledge representation and querying system that helps understand relationships between concepts, simulate scenarios and find solutions to problems

Awesome Lists containing this project

README 

          
# Knowledge Engine  

*A validated, ontology-driven knowledge backend for planning, simulation, and reasoning*



📄 **White Paper (Design & Rationale)**  

➡️ https://docs.google.com/document/d/1tEWRXAXDzJdT1Z1Z5D-zaWnx8w7es_qKYlQLpvO-fn4/edit?usp=sharing  



> **Recommended starting point**  

> The white paper explains *why* this system exists, the architectural choices behind it, and how it differs from naïve RAG, agentic systems, and auto-generated knowledge graphs.  

>  

> This repository is the **reference implementation** of that design.



---



## Overview



**Knowledge Engine** is a modular backend component for building, validating, and querying a **governed knowledge graph**.



It is designed to plug into existing systems that need:

- Accurate and auditable knowledge representation

- Explicit lineage of changes

- Deterministic graph-based retrieval (GraphRAG)

- Ontology-driven structure without coupling the rest of the stack to a specific graph database



The system treats knowledge as a **managed asset**, not as an unverified byproduct of LLM generation.



---



## Why This Project Exists



Most LLM-based systems today suffer from one or more of the following:



- Hallucinations becoming persistent “knowledge”

- No separation between extraction, inference, and authority

- No audit trail for how facts entered the system

- Tight coupling between prompts, storage, and retrieval

- Poor suitability for high-trust domains (planning, simulation, analysis)



**Knowledge Engine addresses these issues by design.**



### Key Characteristics



- **Validation-first workflow**  

  New knowledge is always staged as a *validation object* before it can affect the KG.



- **Versioned approvals**  

  Regenerations create linked versions; validating one invalidates the rest.



- **Ontology-driven extraction**  

  LLMs must align proposed nodes and relationships to the active ontology.



- **Relationship-aware retrieval (GraphRAG)**  

  Queries are post-filtered by relation type  

  (e.g. `DISCOVERED` for “What did X discover?”).



- **Backend-friendly APIs**  

  Exposed as clean REST endpoints callable from any service.



- **Switchable storage backends**  

  - SQLite for metadata  

  - FalkorDB + Graphiti for the KG  

  - Extensible to other graph databases



This makes the system suitable for **planning, wargaming, simulation, and decision-support workflows**.



---



## Relationship to the White Paper



The white paper describes:

- The **problem statement** this system addresses

- The **architecture and design principles**

- The **knowledge lifecycle** (proposal → validation → persistence → retrieval)

- How ontology definition enables reuse across domains

- Why this approach differs from RAG and agentic pipelines



This repository implements those ideas concretely.



If you are evaluating or extending the system, **read the white paper first**.



---

## Run



```bash

python -m venv .venv

source .venv/bin/activate

pip install -r requirements.txt

uvicorn app.main:app --reload

```



## FalkorDB + Graphiti



Start FalkorDB with persistence:



```bash

docker-compose up -d

```



The compose file mounts a named volume to persist the graph data directory and enables append-only persistence.



Set env vars (see `.env.example`) and enable Graphiti:



```bash

export KG_BACKEND=graphiti

export GRAPHITI_URI=falkor://localhost:6379

export GRAPHITI_GRAPH_NAME=knowledge_engine

```



The API also loads `.env` automatically via `python-dotenv`.



Graphiti requires an embeddings/LLM provider (for example `OPENAI_API_KEY`) depending on your setup.



The API loads `.env` from the project root automatically.



Ontology switching (via env):



```bash

export ONTOLOGY_PATH=./ontologies_and_facts/ontology.md

# or use the wargaming ontology

export ONTOLOGY_PATH=./ontologies_and_facts/wargaming_ontology.md

```



## Endpoints



- POST `/knowledge-engine/ingest/text`

- POST `/knowledge-engine/expand`

- POST `/knowledge-engine/query/expand`

- POST `/knowledge-engine/query/retrieve`

- POST `/knowledge-engine/validation/{validation_id}/validate`

- POST `/knowledge-engine/validation/{validation_id}/regenerate`

- GET `/knowledge-engine/validation/{validation_id}`

- GET `/knowledge-engine/validation/{validation_id}/image`

- GET `/knowledge-engine/ontology`



## Docs



- `docs/overview.md`

- `docs/ontology.md`

- `docs/validation-workflow.md`

- `docs/graphiti-falkordb.md`

- `docs/api.md`

- `docs/changes-retrieval-filtering.md`

- `docs/ontology.md` (explains ontology switching)



## API Usage



Ingest free text (creates a validation object):



```bash

curl -X POST http://localhost:8000/knowledge-engine/ingest/text \

  -H "Content-Type: application/json" \

  -d '{"text":"Marie Curie discovered radium."}'

```



Expand with LLM (creates a validation object placeholder):



```bash

curl -X POST http://localhost:8000/knowledge-engine/expand \

  -H "Content-Type: application/json" \

  -d '{"text":"Expand this knowledge about Marie Curie."}'

```



Query to expand the KG (creates a validation object + query record):



```bash

curl -X POST http://localhost:8000/knowledge-engine/query/expand \

  -H "Content-Type: application/json" \

  -d '{"query":"Find related discoveries to radium."}'

```



Retrieve via GraphRAG (returns query record with results):



```bash

curl -X POST http://localhost:8000/knowledge-engine/query/retrieve \

  -H "Content-Type: application/json" \

  -d '{"query":"What did Marie Curie discover?"}'

```



Validate a validation object (writes to KG when Graphiti is enabled):



```bash

curl -X POST http://localhost:8000/knowledge-engine/validation/1/validate

```



Regenerate a validation object (creates a new version linked to the root):



```bash

curl -X POST http://localhost:8000/knowledge-engine/validation/1/regenerate

```



Fetch a validation object:



```bash

curl http://localhost:8000/knowledge-engine/validation/1

```



Fetch a validation object as PNG:



```bash

curl http://localhost:8000/knowledge-engine/validation/1/image --output validation.png

```



Fetch the ontology definition:



```bash

curl http://localhost:8000/knowledge-engine/ontology

```



## Typical Flow



1) Ingest or expand to create a validation object.

2) Review the validation object (and optionally the image).

3) Validate the version you want committed to the KG.

4) Query the KG for retrieval (GraphRAG) or request expansions.



Example flow:



1) Ingest text



```bash

curl -X POST \

  http://localhost:8000/knowledge-engine/ingest/text \

  -H 'Content-Type: application/json' \

  -d '{"text":"Marie Curie discovered radium."}'

```



2) View validation



```bash

curl http://localhost:8000/knowledge-engine/validation/1

```



```bash

curl http://localhost:8000/knowledge-engine/validation/1/image --output validation.png

```



3) Validate (writes to KG when Graphiti is enabled)



```bash

curl -X POST http://localhost:8000/knowledge-engine/validation/1/validate

```



4) Retrieve



```bash

curl -X POST \

  http://localhost:8000/knowledge-engine/query/retrieve \

  -H 'Content-Type: application/json' \

  -d '{"query":"What did Marie Curie discover?"}'

```



## Visualize the Graph (FalkorDB Browser)



You can use the FalkorDB Browser UI to explore the graph visually.



Option A: Run FalkorDB + Browser together (quickest):



```bash

docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest

```



Open http://localhost:3000 in your browser.



Option B: Run Browser separately and connect to your FalkorDB server:



```bash

docker run -p 3000:3000 -e FALKORDB_URL=redis://localhost:6379 falkordb/falkordb-browser:latest

```



You can also try the hosted browser at https://browser.falkordb.com.



## Ontology + LLM Extraction



The ontology is stored in `ontology.md` and loaded at runtime. To change it, edit the file directly.



The validation object is created by an LLM using LangGraph. Set an LLM provider env var, for example:



```bash

export LLM_MODEL=gpt-4o-mini

export OPENAI_API_KEY=your_key_here

```



## Graphiti Data Notes



Graphiti stores data as `Entity`, `Fact`, and `Episode` nodes inside the FalkorDB graph. Use the Browser to query those labels directly:



```cypher

MATCH (e:Entity) RETURN e LIMIT 25

```



```cypher

MATCH (f:Fact) RETURN f LIMIT 25

```