Local Knowledge Graph

The Problem

Most local LLM tools are black boxes: you ask a question and get an answer with no visibility into how the model got there. This project makes the reasoning process inspectable by streaming each step and rendering it as a knowledge graph where edge weights are semantic similarities between steps. It works entirely against a local Ollama instance, so nothing leaves the machine.

What This Does

Local_Knowledge_Graph is a Flask app that asks a local Llama chat model to reason through a question step by step, embeds each step using an Ollama embedding model, and draws the steps as a graph with cosine-similarity edges. The core logic lives in src/mpe_lkg/: app.py wires the HTTP routes and streaming, backends.py abstracts Ollama chat and embedding calls, store.py persists vectors in a database, and reasoning.py orchestrates the question-answering loop.

The front end is a single page (src/mpe_lkg/templates/index.html) with vendor JavaScript for Markdown rendering and graph visualization. A CLI (src/mpe_lkg/cli.py) provides mpe-lkg doctor for environment checks. The package is published on PyPI as mpe-lkg.

How It Is Wired

Execution starts at main in src/mpe_lkg/cli.py:43, which reaches 39 functions. The Flask app entry is run at src/mpe_lkg/app.py:269, which calls health and list_models — the shortest path to a network call is run -> health -> list_models -> session.get. The reasoning worker path is worker -> embed, which reaches the filesystem via out.parent.mkdir and hashes text with hashlib.sha256.

The most-connected modules form a cycle: src/mpe_lkg/app.py, __init__.py, and cli.py import each other, so changing any one of them risks breaking the others. backends.py is the hub — 32 functions, called from 11 files, and it owns the network calls, database access, and hashing. The top-called functions (normal_script at 43 call sites, flask_client at 31, embed at 25) are where changes have the widest blast radius.

How To Use It

pip install mpe-lkg
mpe-lkg
# open http://localhost:5100

You need Ollama running locally with a chat model (ollama pull llama3.2:3b) and optionally an embedding model (ollama pull nomic-embed-text). Configuration is via environment variables: OLLAMA_URL (default http://localhost:11434), LKG_CHAT_MODEL, LKG_EMBED_MODEL, LKG_HOST/LKG_PORT (default 127.0.0.1:5100). For source installs, the repo's Makefile and pyproject.toml support pip install -e . in a venv; python app.py also works as a shim.

Real-World Use

A support engineer debugging why a model misidentified a code bug runs mpe-lkg, asks "why did this function fail on empty input?", and sees the reasoning graph: each step is a node, edges show which steps the model considered similar, and weak edges reveal where the reasoning jumped tracks. The mpe-lkg doctor command automates the same environment check in CI scripts.

Code Health & Issues

Static analysis found 9 findings (4 high, 5 medium). High severity: an import cycle among src/mpe_lkg/__init__.py, app.py, and cli.py, and deep nesting (depth 6) in app.py, reasoning.py, and tests/test_stream.py. Medium: duplicated 6-line blocks across scripts/layer_sweep.py, scripts/measure.py, backends.py, and layers.py, plus high branching density in tests/test_stream.py (64 branches over 163 lines).

SDLC observations: no LICENSE file (default all-rights-reserved), no dependency lockfile, and GitHub Actions pinned to moving tags like pypa/gh-action-pypi-publish@release/v1 instead of commit SHAs. CI workflows lack least-privilege token permissions and timeout limits. Tests and CI are present across Linux, macOS, and Windows.

The Bottom Line

A well-structured tool for anyone who wants to see how a local LLM reasons, with a clean separation between app, backends, and storage. The import cycle and missing license are the main blockers for serious reuse. Best suited for developers debugging prompt chains or building local-first AI tooling.

What the analyser found

Deployment readiness

4/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

41 files

Python25
YAML4
JSON3
JavaScript3
Markdown1
TOML1

Flask

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["src<br/>9 modules"] g1["tests<br/>9 modules"] g2["scripts<br/>6 modules"] g1 -->|1| g2

Module dependencies

The 10 most depended-upon modules of 25, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_mpe_lkg_app["app"] n1_src_mpe_lkg___init__["__init__"] n2_src_mpe_lkg_cli["cli"] n3_src_mpe_lkg_reasoning["reasoning"] n4_scripts_layer_sweep["layer_sweep"] n5_scripts_measure["measure"] n6_src_mpe_lkg_backends["backends"] n7_src_mpe_lkg_graph["graph"] n8_src_mpe_lkg_layers["layers"] n9_src_mpe_lkg_store["store"] n4_scripts_layer_sweep --> n5_scripts_measure n1_src_mpe_lkg___init__ --> n0_src_mpe_lkg_app n1_src_mpe_lkg___init__ --> n2_src_mpe_lkg_cli n0_src_mpe_lkg_app --> n1_src_mpe_lkg___init__ n0_src_mpe_lkg_app --> n3_src_mpe_lkg_reasoning n0_src_mpe_lkg_app --> n9_src_mpe_lkg_store n0_src_mpe_lkg_app --> n8_src_mpe_lkg_layers n2_src_mpe_lkg_cli --> n1_src_mpe_lkg___init__ n2_src_mpe_lkg_cli --> n0_src_mpe_lkg_app n3_src_mpe_lkg_reasoning --> n6_src_mpe_lkg_backends n3_src_mpe_lkg_reasoning --> n7_src_mpe_lkg_graph classDef cyc stroke:#ef4444,stroke-width:2px; class n0_src_mpe_lkg_app,n1_src_mpe_lkg___init__,n2_src_mpe_lkg_cli cyc;

Findings

MediumNo LICENSE file - unclear usage/redistribution rights root
LowDependencies declared without a lockfile - non-reproducible builds pyproject.toml

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium4

low1

Pin third-party GitHub Actions to a commit SHAhigh

.github/workflows

pypa/gh-action-pypi-publish@release/v1

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Add a LICENSE; redistribution rights are undefinedhigh

no licence file at the repository root

Fix: Add MIT or Apache-2.0 at the repository root.

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Declare least-privilege permissions for GITHUB_TOKENmedium3 occurrences

.github/workflows/linux.yml

3 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/linux.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/linux.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.