diff --git a/README.md b/README.md index 0431fbe..1201f92 100644 --- a/README.md +++ b/README.md @@ -10,26 +10,8 @@ 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 reasoning as a -knowledge graph that is **used, not just drawn**. **Blue** edges are embedding similarity — -association. **Green** is what an exact evaluator settled — sums and unit conversions, in -fractions, via [mpeqs](https://github.com/punnerud/MPEqs). Everything runs on your machine. - -## The graph is load-bearing - -Every claim below is a measurement pinned in `docs/claims/` and re-checked by CI on every -push — the numbers cannot drift from the code. - -| what the graph does | measured | -|---|---| -| **writes the answer**: the strongest path through the steps is what the final answer is synthesised from | 54.9% → **91.2%** correct on the eval that motivated it | -| **steers exploration**: sub-questions that drift from the parent, or repeat one already asked, are dropped by embedding — decisions the model cannot make about itself | drift and repeats filtered in `explore`/`settle`, tested | -| **gates the answer type**: whether a numeric answer is even on the table is an embedding-relevance decision made by code, not by the model | the model chose a number for "capital of France" 3/3 without it | -| **hands arithmetic to [mpeqs](https://github.com/punnerud/MPEqs)**: expressions and unit conversions settle exactly, off the graph's facts | **+32.5 points** where arithmetic is the task, 95% CI [+15.3, +49.7], replicated | -| **accumulates knowledge**: every run lands in per-session SQL tables and RDF, queryable across time | sessions isolated, hints opt-in, `GET /sessions` | - -Not a general knowledge-graph-builder for documents or RAG: the graph here is built *from -the model's own reasoning* and fed back into it. +A local model reasons step by step, and the reasoning becomes a knowledge graph that is +[**used, not just drawn**](docs/design.md#the-graph-is-load-bearing). Everything runs on your machine. ## Run it @@ -40,16 +22,15 @@ mpe-lkg Open . It talks to a local model through [Ollama](https://ollama.com) and will tell you what is missing and the one command that -fixes it. The model matters more than anything else here — measured, `qwen3:4b-instruct-2507` +fixes it. The model matters more than anything else — measured, `qwen3:4b-instruct-2507` answers 82.5% of the arithmetic battery against `llama3.2:3b`'s 40%: ```bash ollama pull qwen3:4b-instruct-2507-q4_K_M ``` -Ask harder questions with `mode=explore` (each sub-question answered by its own run) or -`mode=settle` (explored twice, finished only when two independent runs agree), and take any -run as RDF: +Harder questions: `mode=explore` answers each sub-question with its own run; `mode=settle` +finishes only when two independent runs agree. Any run can be taken as RDF: ```bash curl -sX POST localhost:5100/jobs -H 'content-type: application/json' \ @@ -61,11 +42,11 @@ curl -s localhost:5100/jobs//rdf | | | |---|---| +| [How it works, and what the graph is for](docs/design.md) | the load-bearing measurements, the modules, the strongest-path search | | [Modes, jobs and RDF](docs/modes.md) | reason / explore / settle, the vote, the probes, the vocabulary | -| [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 | +| [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 | +| [Development](docs/development.md) | tests, the battery, and the gate that checks this documentation against measured data | ## Licence diff --git a/docs/design.md b/docs/design.md index b6768df..c37df53 100644 --- a/docs/design.md +++ b/docs/design.md @@ -1,5 +1,21 @@ # How it works +## The graph is load-bearing + +Every claim below is a measurement pinned in `docs/claims/` and re-checked by CI on every +push — the numbers cannot drift from the code. + +| what the graph does | measured | +|---|---| +| **writes the answer**: the strongest path through the steps is what the final answer is synthesised from | 54.9% → **91.2%** correct on the eval that motivated it | +| **steers exploration**: sub-questions that drift from the parent, or repeat one already asked, are dropped by embedding — decisions the model cannot make about itself | drift and repeats filtered in `explore`/`settle`, tested | +| **gates the answer type**: whether a numeric answer is even on the table is an embedding-relevance decision made by code, not by the model | the model chose a number for "capital of France" 3/3 without it | +| **hands arithmetic to [mpeqs](https://github.com/punnerud/MPEqs)**: expressions and unit conversions settle exactly, off the graph's facts | **+32.5 points** where arithmetic is the task, 95% CI [+15.3, +49.7], replicated | +| **accumulates knowledge**: every run lands in per-session SQL tables and RDF, queryable across time | sessions isolated, hints opt-in, `GET /sessions` | + +Not a general knowledge-graph-builder for documents or RAG: the graph here is built *from +the model's own reasoning* and fed back into it. + | File | Responsibility | |---|---| | `src/mpe_lkg/app.py` | Flask routes and server-sent-event framing |