juuri
Juuri (pronounced "JooRi", Finnish for root): Knowledge Graphs for RAG. Nothing else.
pip install juuri
Status
v0.1: the minimum knowledge-graph RAG loop works end to end. The API is early and may change.
| Step | What you get |
|---|---|
| Store | Typed (subject, predicate, object) triples, integer-interned strings, S/P/O indexes |
| Schema | Allowed classes, relations with domain/range, subclasses, declared rules |
| Extract | LLM triple extraction through Ollama |
| Provenance | Source, chunk ID, confidence and timestamp on every fact |
| Retrieve | Vector search for seed entities, then k-hop expansion |
| Context | Token-budgeted prompt text with citations |
Quick start
Needs a running Ollama server with a chat model and an embedding model, for example:
ollama pull qwen2.5:7b-instruct
ollama pull nomic-embed-text
import juuri as jr
schema = jr.Schema(
classes=["Player", "Team"],
relations={
"PLAYED_FOR": ("Player", "Team"),
"CAPTAINED": ("Player", "Team"),
},
)
store = jr.TripleStore(schema=schema)
# text -> triples (each fact keeps its source, chunk, confidence, timestamp)
llm = jr.OllamaLLM("qwen2.5:7b-instruct")
store.ingest({"cricket.txt": "MS Dhoni captained Chennai Super Kings."}, llm=llm)
# embed entities, then retrieve
embedder = jr.OllamaEmbedder("nomic-embed-text")
store.embed(embedder)
hits = store.retrieve("Who led CSK?", embedder, seeds=1, hops=1)
# cited prompt text for your LLM
print(hits.to_context(tokens=2000))
FACTS:
- MS Dhoni CAPTAINED Chennai Super Kings [cricket.txt#0]
SOURCES:
[cricket.txt#0] MS Dhoni captained Chennai Super Kings.
Using the pieces
Triples and lookups
store = jr.TripleStore()
store.add("Dhoni", "PLAYED_FOR", "CSK", source="stats.csv", confidence=0.9)
list(store.find(obj="CSK")) # None is a wildcard
store.provenance("Dhoni", "PLAYED_FOR", "CSK")
Adding the same fact again from another source keeps one triple and adds a second provenance record.
Schema guard
With a schema, add() rejects undeclared relations and wrong subject or object types by raising jr.SchemaError. Pass types the first time an entity appears: store.add("Dhoni", "PLAYED_FOR", "CSK", "Player", "Team"). The type is remembered afterwards. Subclasses count as their parent class (subclasses={"Batsman": "Player"}).
Rules (transitive, symmetric, implies:REL, inverse:REL) are validated and stored, but nothing applies them yet.
Ingest
store.ingest(docs, llm, max_chars=2000, min_confidence=0.0, source=None) accepts a string, a list of strings, or a dict {source_name: text}. Triples that break the schema are dropped. Output that is not valid JSON raises jr.ExtractionError. A failed Ollama call raises jr.LLMError. Any object with complete(prompt) -> str works as an LLM backend.
Retrieve
store.retrieve(query, embedder, seeds=3, hops=1, expand=None, direction="both", min_score=0.0)
expand=["CAUSED_BY"]follows only those relations.directionis"out","in"or"both".- Call
store.embed(embedder)first, and again after adding facts about new entities. - Any object with
embed(list_of_texts) -> list_of_vectorsworks as an embedder.
Context
hits.to_context(tokens=2000, passages=True, count_tokens=None) adds facts in rank order until the budget is used, then source passages with what is left. The default token count is a rough estimate of 1 token per 4 characters. Pass count_tokens with a real tokenizer for exact budgets.
Limitations
- Everything is in memory. Nothing is saved to disk yet.
- Vector search compares the query with every entity. There is no ANN index.
- Only entities are embedded, not edges.
- No entity resolution: "MS Dhoni" and "Dhoni" are separate nodes.
- Ollama is the only built-in backend.
Roadmap
See juuri-base.md for the design notes and the v0.1 to v0.3 roadmap.
Metadata
Release files for juuri 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| juuri-0.1.0.tar.gz | 13.2 kB | Without provenance | Details for juuri-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| juuri-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for juuri-0.1.0-py3-none-any.whl |
Total release size: 26.8 kB
Release files / juuri-0.1.0.tar.gz
| Download URL | juuri-0.1.0.tar.gz |
|---|---|
| Size | 13.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
93c6ebc755863288de25b1fd4c8b64ffa566f5b0dfd6b59ea094469d8d42fac2
|
|
BLAKE2b-256 checksum How to use checksums |
f5bbbf5d7aa25e8c85fddfe2e550716d22531ea15cccb0e40f69cc848515709f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.12
|
Release files / juuri-0.1.0-py3-none-any.whl
| Download URL | juuri-0.1.0-py3-none-any.whl |
|---|---|
| Size | 13.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
567a993522b5009f891d24fa5b49e057dd097b5d1088a13fa7f1ed84f4731fcb
|
|
BLAKE2b-256 checksum How to use checksums |
01c59819c28c6db791dac513c18daf69bd4d1999c6589fa466f8e6f3d07ce794
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.12
|
Security for juuri 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.