Metadata-Version: 2.5
Name: mpe-lkg
Version: 0.6.0
Summary: Local Knowledge Graph: a local LLM reasons step by step, and the steps become a graph.
Project-URL: Homepage, https://github.com/punnerud/Local_Knowledge_Graph
Project-URL: Issues, https://github.com/punnerud/Local_Knowledge_Graph/issues
Author: Morten Punnerud-Engelstad
License: The mpedb License 1.0
        
        Copyright (c) 2026 Morten Punnerud-Engelstad
        
        ## Acceptance
        
        By using, copying, modifying, or distributing the software, you agree to all of the terms of this license. If you do not or cannot agree, you may not use the software.
        
        ## Grant
        
        The licensor grants you a non-exclusive, worldwide, non-transferable, non-sublicensable license to use, copy, modify, and distribute the software and derivative works of it, for any purpose, subject to the conditions below.
        
        Use is FREE OF CHARGE for every person and every organization, except as the Large Enterprise Device Fee below provides.
        
        ## Large Enterprise Device Fee
        
        1. **Who pays.** A "Large Enterprise" is any organization whose Group's consolidated annual revenue OR total valuation (public market capitalization, or the most recent fair valuation for private entities) exceeds USD 5,000,000,000, measured in 2026 United States dollars (adjusted for inflation by the US CPI-U from calendar year 2026), taking whichever of the two metrics is HIGHER.
        
        2. **Group.** "Group" means the organization together with every entity that directly or indirectly controls it, is controlled by it, or is under common control or ownership with it, through any chain and in any direction — expressly including a non-profit entity that owns or controls a for-profit entity and a for-profit entity that owns or controls a non-profit entity. The revenue and valuation tests apply to the Group's combined totals.
        
        3. **The fee.** A Large Enterprise owes the licensor a ONE-TIME fee of USD 0.07 (seven US cents), measured in 2026 United States dollars (adjusted for inflation by the US CPI-U from calendar year 2026), per physical device on which the software runs. Where the software runs on one or more servers, the fee is instead counted per physical device that connects, directly or indirectly, to those servers or to services backed by them. For any deployment, the applicable device count is the HIGHER of (a) the number of physical devices running the software and (b) the number of physical devices so connected. Each physical device is counted once; the fee for a device already paid for is not owed again.
        
        4. **Five-year tail.** A Group that meets the Large Enterprise threshold at any point in a calendar year is a Large Enterprise for that year and for the five following calendar years, regardless of its revenue or valuation in those years.
        
        5. **Payment.** Fees are payable to the licensor upon first deployment or, for devices added later, within 90 days of the device first running or connecting. Contact: morten@punnerud.net. A Large Enterprise must keep records sufficient to support its device count and provide a summary on reasonable request.
        
        ## Distribution and Notices
        
        You must include a copy of this license, and keep this copyright notice, in all copies or substantial portions of the software, including modified copies and derivative works. You may not remove or obscure the license or the fee terms when distributing the software.
        
        ## Scope
        
        This license applies to every version, commit, and artifact of the software published by the licensor, including versions published before this license text was added, to the fullest extent the licensor can so provide.
        
        ## No Other Rights
        
        This license does not grant any trademark rights or any patent rights beyond those necessarily exercised by using the software as licensed.
        
        ## Termination
        
        Your license ends immediately if you materially breach this license and do not cure the breach within 30 days of becoming aware of it. Unpaid fees survive termination.
        
        ## Interpretation
        
        Any doubt or ambiguity in the interpretation of this license shall be resolved in favor of the licensor and this project.
        
        ## Disclaimer
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
License-File: LICENSE
Keywords: embeddings,knowledge-graph,llm,ollama,reasoning,visualization
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Flask
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Requires-Dist: flask>=3.0
Requires-Dist: mpeqs>=0.3.0
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=1.24
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: playwright>=1.48; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: rdflib>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: layers
Requires-Dist: torch>=2.1; extra == 'layers'
Requires-Dist: transformers>=4.44; extra == 'layers'
Description-Content-Type: text/markdown

# Local Knowledge Graph

[![Linux](https://github.com/punnerud/Local_Knowledge_Graph/actions/workflows/linux.yml/badge.svg?branch=main)](https://github.com/punnerud/Local_Knowledge_Graph/actions/workflows/linux.yml)
[![macOS](https://github.com/punnerud/Local_Knowledge_Graph/actions/workflows/macos.yml/badge.svg?branch=main)](https://github.com/punnerud/Local_Knowledge_Graph/actions/workflows/macos.yml)
[![Windows](https://github.com/punnerud/Local_Knowledge_Graph/actions/workflows/windows.yml/badge.svg?branch=main)](https://github.com/punnerud/Local_Knowledge_Graph/actions/workflows/windows.yml)
[![PyPI](https://img.shields.io/pypi/v/mpe-lkg.svg)](https://pypi.org/project/mpe-lkg/)
[![Python](https://img.shields.io/pypi/pyversions/mpe-lkg.svg)](https://pypi.org/project/mpe-lkg/)

<!-- Absolute, not docs/example.png: PyPI renders this README standalone on
     pypi.org, where a relative path resolves against pypi.org and 404s. -->
![Example](https://raw.githubusercontent.com/punnerud/Local_Knowledge_Graph/main/docs/example.png)

Ask a local model a question, watch it reason step by step, and see the steps drawn as a graph
where the edges are how similar the steps are to each other.

The run starts by breaking the question into angles worth checking, then works through them —
about eight steps, each with a named job rather than a quota to fill. Any arithmetic a step
relies on is handed over as an expression and evaluated exactly, in fractions, by
[mpeqs](https://github.com/punnerud/MPEqs). Those sums are shown above the graph: they are the
one part of a run the model did not decide, and you can check `20-13.5 = 6.5` at a glance in a
way you cannot check a paragraph of reasoning.

The graph draws in two colours, because it holds two kinds of claim. **Blue** links steps by
how similar their embeddings are — an association, with no truth value, and the thing that
makes indirect knowledge visible. **Green** is what an exact evaluator settled: a sum, or a
conversion between two units, derived from exact ratios. A reader should never have to guess
which is which.

Everything runs on your machine. Nothing is uploaded anywhere.

## Headless, and as RDF

A run can be started without a browser, polled, and taken as RDF — the graph as text, for
anything that would rather query it than look at it.

```bash
ID=$(curl -sX POST localhost:5100/jobs -H 'content-type: application/json' \
       -d '{"query":"How many seconds are there in 23 weeks?"}' | jq -r .id)

curl -s localhost:5100/jobs/$ID              # {"state":"running","steps":3,...}
curl -s localhost:5100/jobs/$ID/stream       # N-Triples, live, one triple per line
curl -s localhost:5100/jobs/$ID/rdf          # Turtle, once it has finished
curl -sX DELETE localhost:5100/jobs/$ID      # stop it
```

Two formats for two purposes. **N-Triples** streams: each line is a complete document, so a
consumer can parse what has arrived without waiting for the end. **Turtle** is prefixed and
readable, and needs the whole document, so it is what a finished run serialises to.

The `lkg:basis` predicate carries the same distinction as the colours, so a consumer can take
only the part it can rely on:

```turtle
<run/a1b2/link/Step1-Step2>  lkg:similarity "0.8371"^^xsd:decimal ;
                             lkg:basis      lkg:Embedding .     # measured association

<run/a1b2/conversion/1>      lkg:statement  "23 week = 13910400 second" ;
                             lkg:from       <unit/week> ;
                             lkg:to         <unit/second> ;
                             lkg:basis      lkg:Exact .         # derived, reproducible
```

## Run it

```bash
pip install mpe-lkg
mpe-lkg
```

Then open <http://localhost:5100>.

It needs a local model, which it reaches through [Ollama](https://ollama.com). **You do not
need to work that out from here** — start it and it will tell you what it found, what is
missing, and the one command that fixes it. `mpe-lkg doctor` reports the same thing without
starting the server, and exits non-zero, so it works in a script.

Python 3.10 or newer. The wheel is `py3-none-any`, so nothing is compiled and the same
artefact serves Linux, macOS and Windows — all three tested on every push.

<details>
<summary>From a clone, or from Python</summary>

```bash
git clone https://github.com/punnerud/Local_Knowledge_Graph
cd Local_Knowledge_Graph
python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/mpe-lkg
```

`python app.py` still works from a clone as it always has.

```python
from mpe_lkg import create_app, health

print(health())
create_app().run(port=5100)
```

</details>

## More

| | |
|---|---|
| [Models and configuration](docs/models.md) | Choosing models, every environment variable, troubleshooting |
| [Embeddings from inside a model](docs/internal-layers.md) | Reading a chosen layer instead of an embedding endpoint |
| [How it works](docs/design.md) | The modules, the strongest-path search, why there is no ANN index |
| [Development](docs/development.md) | Tests, and the gate that checks this documentation against measured data |

## Licence

[The mpedb License 1.0](LICENSE) — the same licence as
[mpedb](https://github.com/punnerud/mpedb) and [MPEqs](https://github.com/punnerud/MPEqs),
byte for byte.

Free of charge for every person and every organization, with one exception: a group whose
revenue or valuation exceeds five billion dollars owes a one-time fee of seven US cents per
device. Not an OSI-approved licence.

---

<sub>Published to PyPI as `mpe-lkg` — **M**orten **P**unnerud-**E**ngelstad **L**ocal
**K**nowledge **G**raph.</sub>
