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 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
@@ -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