Skip to main content

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.
  • direction is "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_vectors works 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)

Source distribution for juuri 0.1.0
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)

Table of built distributions (wheels) for juuri 0.1.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page