juuri 0.0.2__tar.gz → 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- juuri-0.2.0/PKG-INFO +162 -0
- juuri-0.2.0/README.md +155 -0
- juuri-0.2.0/juuri/__init__.py +16 -0
- juuri-0.2.0/juuri/extract.py +100 -0
- juuri-0.2.0/juuri/llm.py +72 -0
- juuri-0.2.0/juuri/paths.py +49 -0
- juuri-0.2.0/juuri/prompts/claims.txt +16 -0
- juuri-0.2.0/juuri/prompts/extract.txt +18 -0
- juuri-0.2.0/juuri/provenance.py +20 -0
- juuri-0.2.0/juuri/resolve.py +42 -0
- juuri-0.2.0/juuri/retrieve.py +121 -0
- juuri-0.2.0/juuri/schema.py +84 -0
- juuri-0.2.0/juuri/store.py +616 -0
- juuri-0.2.0/juuri/verify.py +141 -0
- juuri-0.2.0/juuri.egg-info/PKG-INFO +162 -0
- juuri-0.2.0/juuri.egg-info/SOURCES.txt +18 -0
- {juuri-0.0.2 → juuri-0.2.0}/pyproject.toml +4 -1
- juuri-0.0.2/PKG-INFO +0 -39
- juuri-0.0.2/README.md +0 -32
- juuri-0.0.2/juuri/__init__.py +0 -5
- juuri-0.0.2/juuri/store.py +0 -117
- juuri-0.0.2/juuri.egg-info/PKG-INFO +0 -39
- juuri-0.0.2/juuri.egg-info/SOURCES.txt +0 -8
- {juuri-0.0.2 → juuri-0.2.0}/juuri.egg-info/dependency_links.txt +0 -0
- {juuri-0.0.2 → juuri-0.2.0}/juuri.egg-info/top_level.txt +0 -0
- {juuri-0.0.2 → juuri-0.2.0}/setup.cfg +0 -0
juuri-0.2.0/PKG-INFO
ADDED
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: juuri
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: juuri placeholder package
|
|
5
|
+
Requires-Python: >=3.8
|
|
6
|
+
Description-Content-Type: text/markdown
|
|
7
|
+
|
|
8
|
+
# juuri
|
|
9
|
+
|
|
10
|
+
**Juuri** (pronounced "JooRi", Finnish for *root*): Knowledge Graphs for RAG. Nothing else.
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
pip install juuri
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Status
|
|
17
|
+
|
|
18
|
+
v0.2: the knowledge-graph RAG loop works end to end, with root-cause tracing, grounding checks and entity resolution. The API is early and may change.
|
|
19
|
+
|
|
20
|
+
| Step | What you get |
|
|
21
|
+
|---|---|
|
|
22
|
+
| Store | Typed (subject, predicate, object) triples, integer-interned strings, S/P/O indexes |
|
|
23
|
+
| Schema | Allowed classes, relations with domain/range, subclasses, declared rules |
|
|
24
|
+
| Extract | LLM triple extraction through Ollama |
|
|
25
|
+
| Provenance | Source, chunk ID, confidence and timestamp on every fact |
|
|
26
|
+
| Re-ingest | Re-ingesting a named source replaces only that source's facts |
|
|
27
|
+
| Resolve | Merge names for the same entity (`sameAs`), with suggestions |
|
|
28
|
+
| Retrieve | Vector search for seed entities, then k-hop expansion |
|
|
29
|
+
| Traverse | Paths between entities, root-cause and blast-radius chains |
|
|
30
|
+
| Context | Token-budgeted prompt text with citations |
|
|
31
|
+
| Verify | Grounding check of an LLM answer against retrieved facts |
|
|
32
|
+
|
|
33
|
+
## Quick start
|
|
34
|
+
|
|
35
|
+
Needs a running [Ollama](https://ollama.com) server with a chat model and an embedding model, for example:
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
ollama pull qwen2.5:7b-instruct
|
|
39
|
+
ollama pull nomic-embed-text
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
```python
|
|
43
|
+
import juuri as jr
|
|
44
|
+
|
|
45
|
+
schema = jr.Schema(
|
|
46
|
+
classes=["Player", "Team"],
|
|
47
|
+
relations={
|
|
48
|
+
"PLAYED_FOR": ("Player", "Team"),
|
|
49
|
+
"CAPTAINED": ("Player", "Team"),
|
|
50
|
+
},
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
store = jr.TripleStore(schema=schema)
|
|
54
|
+
|
|
55
|
+
# text -> triples (each fact keeps its source, chunk, confidence, timestamp)
|
|
56
|
+
llm = jr.OllamaLLM("qwen2.5:7b-instruct")
|
|
57
|
+
store.ingest({"cricket.txt": "MS Dhoni captained Chennai Super Kings."}, llm=llm)
|
|
58
|
+
|
|
59
|
+
# embed entities, then retrieve
|
|
60
|
+
embedder = jr.OllamaEmbedder("nomic-embed-text")
|
|
61
|
+
store.embed(embedder)
|
|
62
|
+
hits = store.retrieve("Who led CSK?", embedder, seeds=1, hops=1)
|
|
63
|
+
|
|
64
|
+
# cited prompt text for your LLM
|
|
65
|
+
print(hits.to_context(tokens=2000))
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
FACTS:
|
|
70
|
+
- MS Dhoni CAPTAINED Chennai Super Kings [cricket.txt#0]
|
|
71
|
+
|
|
72
|
+
SOURCES:
|
|
73
|
+
[cricket.txt#0] MS Dhoni captained Chennai Super Kings.
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Using the pieces
|
|
77
|
+
|
|
78
|
+
**Triples and lookups**
|
|
79
|
+
|
|
80
|
+
```python
|
|
81
|
+
store = jr.TripleStore()
|
|
82
|
+
store.add("Dhoni", "PLAYED_FOR", "CSK", source="stats.csv", confidence=0.9)
|
|
83
|
+
list(store.find(obj="CSK")) # None is a wildcard
|
|
84
|
+
store.provenance("Dhoni", "PLAYED_FOR", "CSK")
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Adding the same fact again from another source keeps one triple and adds a second provenance record.
|
|
88
|
+
|
|
89
|
+
**Schema guard**
|
|
90
|
+
|
|
91
|
+
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"}`).
|
|
92
|
+
|
|
93
|
+
Rules (`transitive`, `symmetric`, `implies:REL`, `inverse:REL`) are validated and stored, but nothing applies them yet.
|
|
94
|
+
|
|
95
|
+
**Ingest**
|
|
96
|
+
|
|
97
|
+
`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.
|
|
98
|
+
|
|
99
|
+
**Retrieve**
|
|
100
|
+
|
|
101
|
+
`store.retrieve(query, embedder, seeds=3, hops=1, expand=None, direction="both", min_score=0.0)`
|
|
102
|
+
|
|
103
|
+
- `expand=["CAUSED_BY"]` follows only those relations.
|
|
104
|
+
- `direction` is `"out"`, `"in"` or `"both"`.
|
|
105
|
+
- Call `store.embed(embedder)` first, and again after adding facts about new entities.
|
|
106
|
+
- Any object with `embed(list_of_texts) -> list_of_vectors` works as an embedder.
|
|
107
|
+
|
|
108
|
+
**Context**
|
|
109
|
+
|
|
110
|
+
`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.
|
|
111
|
+
|
|
112
|
+
**Re-ingest**
|
|
113
|
+
|
|
114
|
+
`ingest` with a source name replaces that source's earlier facts (`replace=True` is the default), so an edited document leaves no stale facts. A fact that another source also backs stays. All documents are extracted before anything is replaced, so a failed LLM call changes nothing. `store.sources()` lists sources and `store.remove_source(name)` deletes one. Facts added without a source are never removed, and a document ingested without a source name cannot be replaced.
|
|
115
|
+
|
|
116
|
+
**Traverse**
|
|
117
|
+
|
|
118
|
+
```python
|
|
119
|
+
store.root_cause("A") # follow CAUSED_BY to the end of each branch
|
|
120
|
+
store.blast_radius("D") # follow it backwards: what D led to
|
|
121
|
+
store.paths("A", "D", max_hops=4, predicates=["CAUSED_BY"])
|
|
122
|
+
|
|
123
|
+
for chain in store.root_cause("A"):
|
|
124
|
+
print(chain.to_context("ROOT CAUSE CHAIN")) # numbered, cited lines
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Direction follows how triples are stored: `A CAUSED_BY B` means B is a cause of A, so `root_cause` walks subject to object. Each `Chain` has `.start`, `.end`, `.triples`, `.provenance`, `.cyclic` and `.truncated`. A cycle stops the walk with `cyclic=True` and means there is no single root cause.
|
|
128
|
+
|
|
129
|
+
**Verify**
|
|
130
|
+
|
|
131
|
+
```python
|
|
132
|
+
v = store.verify(answer, hits, llm) # needs a schema
|
|
133
|
+
v.grounded # True only if every claim is supported
|
|
134
|
+
v.score # share of supported claims, or None if no claims
|
|
135
|
+
v.supported, v.unsupported, v.unchecked
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
The LLM lists the answer's claims and each one is matched against the retrieved facts, using the schema's `symmetric`, `inverse` and `implies` rules. `unchecked` means the claim uses a relation the schema does not declare. Invalid LLM output raises `jr.ExtractionError`. A true claim that retrieval did not return counts as unsupported.
|
|
139
|
+
|
|
140
|
+
**Entity resolution**
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
store.suggest_merges() # candidates only, nothing is merged
|
|
144
|
+
store.merge("Dhoni", "MS Dhoni") # alias -> canonical
|
|
145
|
+
store.resolve_entities() # merges names identical after normalising
|
|
146
|
+
store.aliases("MS Dhoni")
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
After a merge, the alias name works in `add`, `find`, `paths`, `root_cause`, `blast_radius` and `verify`. Merging entities of different types raises `SchemaError`. `resolve_entities()` defaults to `min_score=1.0` on purpose: "Dhoni" and "MS Dhoni" score 0.9, and short names can match several different entities, so review those with `suggest_merges()` first. Pass `min_embedding` to `suggest_merges` to add suggestions from stored vectors.
|
|
150
|
+
|
|
151
|
+
## Limitations
|
|
152
|
+
|
|
153
|
+
- Everything is in memory. Nothing is saved to disk yet, including aliases.
|
|
154
|
+
- Vector search compares the query with every entity. There is no ANN index.
|
|
155
|
+
- Only entities are embedded, not edges.
|
|
156
|
+
- Merges and source removals rebuild the store, and `suggest_merges` compares every pair within a type, so they are slow on large graphs.
|
|
157
|
+
- Rules are applied one step at a time in `verify`. There is no rule chaining and `transitive` is not used.
|
|
158
|
+
- Ollama is the only built-in backend.
|
|
159
|
+
|
|
160
|
+
## Roadmap
|
|
161
|
+
|
|
162
|
+
See `juuri-base.md` for the design notes and the v0.1 to v0.3 roadmap.
|
juuri-0.2.0/README.md
ADDED
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# juuri
|
|
2
|
+
|
|
3
|
+
**Juuri** (pronounced "JooRi", Finnish for *root*): Knowledge Graphs for RAG. Nothing else.
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
pip install juuri
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
## Status
|
|
10
|
+
|
|
11
|
+
v0.2: the knowledge-graph RAG loop works end to end, with root-cause tracing, grounding checks and entity resolution. The API is early and may change.
|
|
12
|
+
|
|
13
|
+
| Step | What you get |
|
|
14
|
+
|---|---|
|
|
15
|
+
| Store | Typed (subject, predicate, object) triples, integer-interned strings, S/P/O indexes |
|
|
16
|
+
| Schema | Allowed classes, relations with domain/range, subclasses, declared rules |
|
|
17
|
+
| Extract | LLM triple extraction through Ollama |
|
|
18
|
+
| Provenance | Source, chunk ID, confidence and timestamp on every fact |
|
|
19
|
+
| Re-ingest | Re-ingesting a named source replaces only that source's facts |
|
|
20
|
+
| Resolve | Merge names for the same entity (`sameAs`), with suggestions |
|
|
21
|
+
| Retrieve | Vector search for seed entities, then k-hop expansion |
|
|
22
|
+
| Traverse | Paths between entities, root-cause and blast-radius chains |
|
|
23
|
+
| Context | Token-budgeted prompt text with citations |
|
|
24
|
+
| Verify | Grounding check of an LLM answer against retrieved facts |
|
|
25
|
+
|
|
26
|
+
## Quick start
|
|
27
|
+
|
|
28
|
+
Needs a running [Ollama](https://ollama.com) server with a chat model and an embedding model, for example:
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
ollama pull qwen2.5:7b-instruct
|
|
32
|
+
ollama pull nomic-embed-text
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
```python
|
|
36
|
+
import juuri as jr
|
|
37
|
+
|
|
38
|
+
schema = jr.Schema(
|
|
39
|
+
classes=["Player", "Team"],
|
|
40
|
+
relations={
|
|
41
|
+
"PLAYED_FOR": ("Player", "Team"),
|
|
42
|
+
"CAPTAINED": ("Player", "Team"),
|
|
43
|
+
},
|
|
44
|
+
)
|
|
45
|
+
|
|
46
|
+
store = jr.TripleStore(schema=schema)
|
|
47
|
+
|
|
48
|
+
# text -> triples (each fact keeps its source, chunk, confidence, timestamp)
|
|
49
|
+
llm = jr.OllamaLLM("qwen2.5:7b-instruct")
|
|
50
|
+
store.ingest({"cricket.txt": "MS Dhoni captained Chennai Super Kings."}, llm=llm)
|
|
51
|
+
|
|
52
|
+
# embed entities, then retrieve
|
|
53
|
+
embedder = jr.OllamaEmbedder("nomic-embed-text")
|
|
54
|
+
store.embed(embedder)
|
|
55
|
+
hits = store.retrieve("Who led CSK?", embedder, seeds=1, hops=1)
|
|
56
|
+
|
|
57
|
+
# cited prompt text for your LLM
|
|
58
|
+
print(hits.to_context(tokens=2000))
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
FACTS:
|
|
63
|
+
- MS Dhoni CAPTAINED Chennai Super Kings [cricket.txt#0]
|
|
64
|
+
|
|
65
|
+
SOURCES:
|
|
66
|
+
[cricket.txt#0] MS Dhoni captained Chennai Super Kings.
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Using the pieces
|
|
70
|
+
|
|
71
|
+
**Triples and lookups**
|
|
72
|
+
|
|
73
|
+
```python
|
|
74
|
+
store = jr.TripleStore()
|
|
75
|
+
store.add("Dhoni", "PLAYED_FOR", "CSK", source="stats.csv", confidence=0.9)
|
|
76
|
+
list(store.find(obj="CSK")) # None is a wildcard
|
|
77
|
+
store.provenance("Dhoni", "PLAYED_FOR", "CSK")
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Adding the same fact again from another source keeps one triple and adds a second provenance record.
|
|
81
|
+
|
|
82
|
+
**Schema guard**
|
|
83
|
+
|
|
84
|
+
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"}`).
|
|
85
|
+
|
|
86
|
+
Rules (`transitive`, `symmetric`, `implies:REL`, `inverse:REL`) are validated and stored, but nothing applies them yet.
|
|
87
|
+
|
|
88
|
+
**Ingest**
|
|
89
|
+
|
|
90
|
+
`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.
|
|
91
|
+
|
|
92
|
+
**Retrieve**
|
|
93
|
+
|
|
94
|
+
`store.retrieve(query, embedder, seeds=3, hops=1, expand=None, direction="both", min_score=0.0)`
|
|
95
|
+
|
|
96
|
+
- `expand=["CAUSED_BY"]` follows only those relations.
|
|
97
|
+
- `direction` is `"out"`, `"in"` or `"both"`.
|
|
98
|
+
- Call `store.embed(embedder)` first, and again after adding facts about new entities.
|
|
99
|
+
- Any object with `embed(list_of_texts) -> list_of_vectors` works as an embedder.
|
|
100
|
+
|
|
101
|
+
**Context**
|
|
102
|
+
|
|
103
|
+
`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.
|
|
104
|
+
|
|
105
|
+
**Re-ingest**
|
|
106
|
+
|
|
107
|
+
`ingest` with a source name replaces that source's earlier facts (`replace=True` is the default), so an edited document leaves no stale facts. A fact that another source also backs stays. All documents are extracted before anything is replaced, so a failed LLM call changes nothing. `store.sources()` lists sources and `store.remove_source(name)` deletes one. Facts added without a source are never removed, and a document ingested without a source name cannot be replaced.
|
|
108
|
+
|
|
109
|
+
**Traverse**
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
store.root_cause("A") # follow CAUSED_BY to the end of each branch
|
|
113
|
+
store.blast_radius("D") # follow it backwards: what D led to
|
|
114
|
+
store.paths("A", "D", max_hops=4, predicates=["CAUSED_BY"])
|
|
115
|
+
|
|
116
|
+
for chain in store.root_cause("A"):
|
|
117
|
+
print(chain.to_context("ROOT CAUSE CHAIN")) # numbered, cited lines
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Direction follows how triples are stored: `A CAUSED_BY B` means B is a cause of A, so `root_cause` walks subject to object. Each `Chain` has `.start`, `.end`, `.triples`, `.provenance`, `.cyclic` and `.truncated`. A cycle stops the walk with `cyclic=True` and means there is no single root cause.
|
|
121
|
+
|
|
122
|
+
**Verify**
|
|
123
|
+
|
|
124
|
+
```python
|
|
125
|
+
v = store.verify(answer, hits, llm) # needs a schema
|
|
126
|
+
v.grounded # True only if every claim is supported
|
|
127
|
+
v.score # share of supported claims, or None if no claims
|
|
128
|
+
v.supported, v.unsupported, v.unchecked
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
The LLM lists the answer's claims and each one is matched against the retrieved facts, using the schema's `symmetric`, `inverse` and `implies` rules. `unchecked` means the claim uses a relation the schema does not declare. Invalid LLM output raises `jr.ExtractionError`. A true claim that retrieval did not return counts as unsupported.
|
|
132
|
+
|
|
133
|
+
**Entity resolution**
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
store.suggest_merges() # candidates only, nothing is merged
|
|
137
|
+
store.merge("Dhoni", "MS Dhoni") # alias -> canonical
|
|
138
|
+
store.resolve_entities() # merges names identical after normalising
|
|
139
|
+
store.aliases("MS Dhoni")
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
After a merge, the alias name works in `add`, `find`, `paths`, `root_cause`, `blast_radius` and `verify`. Merging entities of different types raises `SchemaError`. `resolve_entities()` defaults to `min_score=1.0` on purpose: "Dhoni" and "MS Dhoni" score 0.9, and short names can match several different entities, so review those with `suggest_merges()` first. Pass `min_embedding` to `suggest_merges` to add suggestions from stored vectors.
|
|
143
|
+
|
|
144
|
+
## Limitations
|
|
145
|
+
|
|
146
|
+
- Everything is in memory. Nothing is saved to disk yet, including aliases.
|
|
147
|
+
- Vector search compares the query with every entity. There is no ANN index.
|
|
148
|
+
- Only entities are embedded, not edges.
|
|
149
|
+
- Merges and source removals rebuild the store, and `suggest_merges` compares every pair within a type, so they are slow on large graphs.
|
|
150
|
+
- Rules are applied one step at a time in `verify`. There is no rule chaining and `transitive` is not used.
|
|
151
|
+
- Ollama is the only built-in backend.
|
|
152
|
+
|
|
153
|
+
## Roadmap
|
|
154
|
+
|
|
155
|
+
See `juuri-base.md` for the design notes and the v0.1 to v0.3 roadmap.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
from .extract import ExtractionError
|
|
2
|
+
from .llm import LLMError, OllamaEmbedder, OllamaLLM
|
|
3
|
+
from .paths import Chain
|
|
4
|
+
from .provenance import Provenance
|
|
5
|
+
from .resolve import MergeCandidate
|
|
6
|
+
from .retrieve import Hit, Hits
|
|
7
|
+
from .schema import Schema, SchemaError
|
|
8
|
+
from .store import TripleStore
|
|
9
|
+
from .verify import Claim, Verification
|
|
10
|
+
|
|
11
|
+
__version__ = "0.2.0"
|
|
12
|
+
|
|
13
|
+
__all__ = [
|
|
14
|
+
"Chain", "Claim", "ExtractionError", "Hit", "Hits", "LLMError", "MergeCandidate", "OllamaEmbedder", "OllamaLLM",
|
|
15
|
+
"Provenance", "Schema", "SchemaError", "TripleStore", "Verification",
|
|
16
|
+
]
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
"""Chunking and LLM triple extraction."""
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
from importlib import resources
|
|
5
|
+
from typing import Any, Dict, Iterator, List
|
|
6
|
+
|
|
7
|
+
from .schema import Schema
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class ExtractionError(ValueError):
|
|
11
|
+
"""Raised when the LLM output cannot be parsed into triples."""
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
_REQUIRED = ("subject", "subject_type", "predicate", "object", "object_type")
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def load_prompt(name: str) -> str:
|
|
18
|
+
return resources.files("juuri").joinpath("prompts", f"{name}.txt").read_text(encoding="utf-8")
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def chunk_text(text: str, max_chars: int = 2000) -> Iterator[str]:
|
|
22
|
+
"""Split text on blank lines into chunks of at most max_chars where possible."""
|
|
23
|
+
if max_chars < 1:
|
|
24
|
+
raise ValueError("max_chars must be positive")
|
|
25
|
+
current = ""
|
|
26
|
+
for para in text.split("\n\n"):
|
|
27
|
+
para = para.strip()
|
|
28
|
+
if not para:
|
|
29
|
+
continue
|
|
30
|
+
while len(para) > max_chars:
|
|
31
|
+
if current:
|
|
32
|
+
yield current
|
|
33
|
+
current = ""
|
|
34
|
+
yield para[:max_chars]
|
|
35
|
+
para = para[max_chars:]
|
|
36
|
+
if current and len(current) + len(para) + 2 > max_chars:
|
|
37
|
+
yield current
|
|
38
|
+
current = ""
|
|
39
|
+
current = f"{current}\n\n{para}" if current else para
|
|
40
|
+
if current:
|
|
41
|
+
yield current
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def build_prompt(text: str, schema: Schema) -> str:
|
|
45
|
+
relations = "\n".join(
|
|
46
|
+
f"- {name}: {dom} -> {rng}" for name, (dom, rng) in sorted(schema.relations.items())
|
|
47
|
+
)
|
|
48
|
+
return load_prompt("extract").format(
|
|
49
|
+
classes=", ".join(sorted(schema.classes)), relations=relations, text=text
|
|
50
|
+
)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def parse_triples(raw: str, schema: Schema) -> List[Dict[str, Any]]:
|
|
54
|
+
"""Parse LLM output. Triples that violate the schema are dropped.
|
|
55
|
+
|
|
56
|
+
Raises ExtractionError if the output is not valid JSON of the expected shape.
|
|
57
|
+
"""
|
|
58
|
+
try:
|
|
59
|
+
data = json.loads(raw)
|
|
60
|
+
except json.JSONDecodeError as exc:
|
|
61
|
+
raise ExtractionError(f"LLM output is not valid JSON: {exc}") from exc
|
|
62
|
+
if isinstance(data, dict):
|
|
63
|
+
if all(k in data for k in _REQUIRED):
|
|
64
|
+
data = [data] # a single bare triple
|
|
65
|
+
else:
|
|
66
|
+
# Wrapped list, e.g. {"triples": [...]}.
|
|
67
|
+
lists = [v for v in data.values() if isinstance(v, list)]
|
|
68
|
+
if len(lists) != 1:
|
|
69
|
+
raise ExtractionError("LLM output is an object without a single list of triples")
|
|
70
|
+
data = lists[0]
|
|
71
|
+
if not isinstance(data, list):
|
|
72
|
+
raise ExtractionError("LLM output is not a list")
|
|
73
|
+
triples = []
|
|
74
|
+
for item in data:
|
|
75
|
+
if not isinstance(item, dict) or any(not isinstance(item.get(k), str) or not item[k].strip() for k in _REQUIRED):
|
|
76
|
+
continue
|
|
77
|
+
triple = {k: item[k].strip() for k in _REQUIRED}
|
|
78
|
+
try:
|
|
79
|
+
conf = float(item.get("confidence", 1.0))
|
|
80
|
+
except (TypeError, ValueError):
|
|
81
|
+
continue
|
|
82
|
+
triple["confidence"] = min(max(conf, 0.0), 1.0)
|
|
83
|
+
try:
|
|
84
|
+
schema.check(triple["subject_type"], triple["predicate"], triple["object_type"])
|
|
85
|
+
except ValueError:
|
|
86
|
+
continue
|
|
87
|
+
triples.append(triple)
|
|
88
|
+
return triples
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def extract_triples(text: str, schema: Schema, llm, max_chars: int = 2000) -> List[Dict[str, Any]]:
|
|
92
|
+
"""Run LLM extraction over every chunk of text and return valid triples."""
|
|
93
|
+
out: List[Dict[str, Any]] = []
|
|
94
|
+
for index, chunk in enumerate(chunk_text(text, max_chars)):
|
|
95
|
+
raw = llm.complete(build_prompt(chunk, schema))
|
|
96
|
+
for triple in parse_triples(raw, schema):
|
|
97
|
+
triple["chunk"] = chunk
|
|
98
|
+
triple["chunk_index"] = index
|
|
99
|
+
out.append(triple)
|
|
100
|
+
return out
|
juuri-0.2.0/juuri/llm.py
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
"""LLM backends. Each backend is any object with `complete(prompt) -> str`."""
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
import urllib.error
|
|
5
|
+
import urllib.request
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class LLMError(RuntimeError):
|
|
9
|
+
"""Raised when an LLM backend call fails."""
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class OllamaLLM:
|
|
13
|
+
"""Calls a local Ollama server (https://ollama.com) over HTTP."""
|
|
14
|
+
|
|
15
|
+
def __init__(self, model: str, host: str = "http://localhost:11434", timeout: float = 120.0) -> None:
|
|
16
|
+
if not model:
|
|
17
|
+
raise ValueError("model is required")
|
|
18
|
+
self.model = model
|
|
19
|
+
self.host = host.rstrip("/")
|
|
20
|
+
self.timeout = timeout
|
|
21
|
+
|
|
22
|
+
def complete(self, prompt: str) -> str:
|
|
23
|
+
body = json.dumps(
|
|
24
|
+
{
|
|
25
|
+
"model": self.model,
|
|
26
|
+
"prompt": prompt,
|
|
27
|
+
"stream": False,
|
|
28
|
+
"format": "json",
|
|
29
|
+
"options": {"temperature": 0},
|
|
30
|
+
}
|
|
31
|
+
).encode("utf-8")
|
|
32
|
+
req = urllib.request.Request(
|
|
33
|
+
f"{self.host}/api/generate", data=body, headers={"Content-Type": "application/json"}
|
|
34
|
+
)
|
|
35
|
+
try:
|
|
36
|
+
with urllib.request.urlopen(req, timeout=self.timeout) as resp:
|
|
37
|
+
payload = json.loads(resp.read().decode("utf-8"))
|
|
38
|
+
except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
|
|
39
|
+
raise LLMError(f"Ollama request to {self.host} failed: {exc}") from exc
|
|
40
|
+
if "response" not in payload:
|
|
41
|
+
raise LLMError(f"Ollama returned no 'response' field: {payload.get('error', payload)}")
|
|
42
|
+
return payload["response"]
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
class OllamaEmbedder:
|
|
46
|
+
"""Embeds text with a local Ollama embedding model, e.g. nomic-embed-text."""
|
|
47
|
+
|
|
48
|
+
def __init__(self, model: str, host: str = "http://localhost:11434", timeout: float = 120.0) -> None:
|
|
49
|
+
if not model:
|
|
50
|
+
raise ValueError("model is required")
|
|
51
|
+
self.model = model
|
|
52
|
+
self.host = host.rstrip("/")
|
|
53
|
+
self.timeout = timeout
|
|
54
|
+
|
|
55
|
+
def embed(self, texts):
|
|
56
|
+
"""Return one vector (list of floats) per input text."""
|
|
57
|
+
texts = list(texts)
|
|
58
|
+
if not texts:
|
|
59
|
+
return []
|
|
60
|
+
body = json.dumps({"model": self.model, "input": texts}).encode("utf-8")
|
|
61
|
+
req = urllib.request.Request(
|
|
62
|
+
f"{self.host}/api/embed", data=body, headers={"Content-Type": "application/json"}
|
|
63
|
+
)
|
|
64
|
+
try:
|
|
65
|
+
with urllib.request.urlopen(req, timeout=self.timeout) as resp:
|
|
66
|
+
payload = json.loads(resp.read().decode("utf-8"))
|
|
67
|
+
except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
|
|
68
|
+
raise LLMError(f"Ollama embed request to {self.host} failed: {exc}") from exc
|
|
69
|
+
vectors = payload.get("embeddings")
|
|
70
|
+
if not isinstance(vectors, list) or len(vectors) != len(texts):
|
|
71
|
+
raise LLMError(f"Ollama returned unexpected embeddings: {payload.get('error', 'bad shape')}")
|
|
72
|
+
return vectors
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
"""Chains of triples returned by path, root-cause and blast-radius queries."""
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass
|
|
4
|
+
from typing import Tuple
|
|
5
|
+
|
|
6
|
+
from .provenance import Provenance
|
|
7
|
+
from .retrieve import _refs
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
@dataclass(frozen=True)
|
|
11
|
+
class Chain:
|
|
12
|
+
"""An ordered walk through the graph.
|
|
13
|
+
|
|
14
|
+
start / end: first and last entity of the walk.
|
|
15
|
+
triples: the edges in walk order, as stored (subject, predicate, object).
|
|
16
|
+
provenance: one tuple of Provenance records per triple.
|
|
17
|
+
cyclic: the walk stopped because the next entity was already on the chain,
|
|
18
|
+
so there is no single end point.
|
|
19
|
+
truncated: the walk stopped at max_hops while more edges existed.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
start: str
|
|
23
|
+
end: str
|
|
24
|
+
triples: Tuple[Tuple[str, str, str], ...]
|
|
25
|
+
provenance: Tuple[Tuple[Provenance, ...], ...]
|
|
26
|
+
cyclic: bool = False
|
|
27
|
+
truncated: bool = False
|
|
28
|
+
|
|
29
|
+
def __len__(self) -> int:
|
|
30
|
+
return len(self.triples)
|
|
31
|
+
|
|
32
|
+
def to_context(self, title: str = "CHAIN") -> str:
|
|
33
|
+
"""Render the chain as numbered, cited lines."""
|
|
34
|
+
lines = [f"{title}:"]
|
|
35
|
+
for i, (triple, prov) in enumerate(zip(self.triples, self.provenance), 1):
|
|
36
|
+
fake_hit = _HitLike(prov)
|
|
37
|
+
lines.append(f"{i}. {triple[0]} {triple[1]} {triple[2]} [{', '.join(_refs(fake_hit))}]")
|
|
38
|
+
if not self.triples:
|
|
39
|
+
lines.append(f"{self.start} (no further links)")
|
|
40
|
+
if self.cyclic:
|
|
41
|
+
lines.append("(cycle: no single end point)")
|
|
42
|
+
if self.truncated:
|
|
43
|
+
lines.append("(stopped at max_hops: more links exist)")
|
|
44
|
+
return "\n".join(lines)
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
@dataclass(frozen=True)
|
|
48
|
+
class _HitLike:
|
|
49
|
+
provenance: Tuple[Provenance, ...]
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
You list the factual claims made in an answer, as triples.
|
|
2
|
+
|
|
3
|
+
Allowed relations (NAME: SubjectClass -> ObjectClass):
|
|
4
|
+
{relations}
|
|
5
|
+
|
|
6
|
+
Rules:
|
|
7
|
+
- Write each claim as subject, predicate, object.
|
|
8
|
+
- Use a relation name from the list above whenever the claim fits one. Use the exact name.
|
|
9
|
+
- If a claim does not fit any listed relation, still list it and use a short UPPER_SNAKE_CASE predicate of your own.
|
|
10
|
+
- Use the entity names exactly as written in the answer.
|
|
11
|
+
- Include only claims the answer states. Do not add facts of your own.
|
|
12
|
+
- Reply with JSON only, in this shape: {{"claims": [{{"subject": "...", "predicate": "...", "object": "..."}}]}}
|
|
13
|
+
- If the answer makes no factual claims, reply with {{"claims": []}}.
|
|
14
|
+
|
|
15
|
+
Answer:
|
|
16
|
+
{answer}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
You extract knowledge graph triples from text.
|
|
2
|
+
|
|
3
|
+
Allowed entity classes: {classes}
|
|
4
|
+
|
|
5
|
+
Allowed relations (NAME: SubjectClass -> ObjectClass):
|
|
6
|
+
{relations}
|
|
7
|
+
|
|
8
|
+
Rules:
|
|
9
|
+
- Use only the relation names and classes listed above.
|
|
10
|
+
- Extract only facts stated in the text. Do not guess.
|
|
11
|
+
- Use the exact entity names as written in the text.
|
|
12
|
+
- Extract every fact in the text that fits the schema, not just the first one.
|
|
13
|
+
- Reply with JSON only, in this shape: {{"triples": [{{"subject": "...", "subject_type": "...", "predicate": "...", "object": "...", "object_type": "...", "confidence": 0.9}}]}}
|
|
14
|
+
- "confidence" is a number between 0 and 1.
|
|
15
|
+
- If the text has no facts that fit the schema, reply with {{"triples": []}}.
|
|
16
|
+
|
|
17
|
+
Text:
|
|
18
|
+
{text}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
"""Provenance records: where a fact came from and how sure we are."""
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass
|
|
4
|
+
from typing import Optional
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
@dataclass(frozen=True)
|
|
8
|
+
class Provenance:
|
|
9
|
+
"""One piece of evidence for a triple.
|
|
10
|
+
|
|
11
|
+
source: document name or path, or None if not given.
|
|
12
|
+
chunk_id: ID of the source chunk, e.g. "app.log#3", or None if not from a chunk.
|
|
13
|
+
confidence: extraction confidence between 0 and 1, or None if not scored.
|
|
14
|
+
timestamp: UTC ISO 8601 time the fact was recorded.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
source: Optional[str]
|
|
18
|
+
chunk_id: Optional[str]
|
|
19
|
+
confidence: Optional[float]
|
|
20
|
+
timestamp: str
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
"""Entity resolution helpers: name similarity and merge candidates."""
|
|
2
|
+
|
|
3
|
+
import re
|
|
4
|
+
from dataclasses import dataclass
|
|
5
|
+
from difflib import SequenceMatcher
|
|
6
|
+
from typing import List, Optional, Tuple
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
@dataclass(frozen=True)
|
|
10
|
+
class MergeCandidate:
|
|
11
|
+
"""A suggested merge of two entities.
|
|
12
|
+
|
|
13
|
+
keep: the name to keep (the entity with more triples, then the longer name).
|
|
14
|
+
merge: the name that would become an alias of `keep`.
|
|
15
|
+
score: 0 to 1. 1.0 means identical after normalising case, spacing and punctuation.
|
|
16
|
+
reason: why the pair was suggested.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
keep: str
|
|
20
|
+
merge: str
|
|
21
|
+
score: float
|
|
22
|
+
reason: str
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def tokens(name: str) -> List[str]:
|
|
26
|
+
return re.findall(r"\w+", name.casefold())
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def name_score(a: str, b: str, threshold: float) -> Optional[Tuple[float, str]]:
|
|
30
|
+
"""Score how likely two names refer to one entity, or None if they do not look alike."""
|
|
31
|
+
ta, tb = tokens(a), tokens(b)
|
|
32
|
+
if not ta or not tb:
|
|
33
|
+
return None
|
|
34
|
+
if ta == tb:
|
|
35
|
+
return 1.0, "same name after normalising case, spacing and punctuation"
|
|
36
|
+
short, long_ = (ta, tb) if len(ta) <= len(tb) else (tb, ta)
|
|
37
|
+
if len(short) < len(long_) and set(short) <= set(long_):
|
|
38
|
+
return 0.9, "one name's words are all in the other"
|
|
39
|
+
ratio = SequenceMatcher(None, " ".join(ta), " ".join(tb)).ratio()
|
|
40
|
+
if ratio >= threshold:
|
|
41
|
+
return ratio, "similar spelling"
|
|
42
|
+
return None
|