Skip to content
Back to search

ragu

MarketplaceWorks with Claude CodeGitHub

Skills for working with RAGU — building knowledge graphs from unstructured text and querying them.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/RaguTeam/RAGU with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/RaguTeam/RAGU'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/raguteam--ragu/badge.svg)](/listings/raguteam--ragu)

HTML

<a href="/listings/raguteam--ragu"><img src="/api/listings/raguteam--ragu/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The recommended way is a local build:

git clone https://github.com/AsphodelRem/RAGU.git
cd RAGU
uv pip install -e .

From PyPI:

pip install graph_ragu

If you want to use local models (via transformers etc.), run:

pip install graph_ragu[local]

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "ragu",
  3. "version": "1.0.0",
  4. "owner": {
  5. "name": "AsphodelRem",
  6. "url": "https://github.com/AsphodelRem"
  7. },
  8. "description": "Skills for working with RAGU — building knowledge graphs from unstructured text and querying them.",
  9. "metadata": {
  10. "pluginRoot": "./.agents/skills"
  11. },
  12. "plugins": [
  13. {
  14. "name": "ragu-build",
  15. "source": "./ragu-build",
  16. "description": "Assemble a RAGU configuration through a short interview and generate a validated build script."
  17. }
  18. ]
  19. }
README.md · README · 481 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center">RAGU: Retrieval-Augmented Graph Utility</h1>
  2. <h3 align="center">Turn text into a knowledge graph and query it.
  3. ---
  4. <p align="center">
  5. <img src="https://raw.githubusercontent.com/RaguTeam/RAGU/main/assets/ragu_image.jpg" alt="RAGU logo" width="600" />
  6. </p>
  7. <h4 align="center">
  8. <a href="https://github.com/AsphodelRem/RAGU/blob/main/LICENSE">
  9. <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="RAGU is under the MIT license." alt="RAGU"/>
  10. </a>
  11. <img src="https://img.shields.io/badge/python->=3.10-blue">
  12. </h4>
  13. <h4 align="center">
  14. <a href="#install">Install</a> |
  15. <a href="#quickstart">Quickstart</a>
  16. </h4>
  17. ---
  18. ## Overview
  19. RAGU builds a knowledge graph from raw text and answers questions over it. It is
  20. built to move from a laptop to a server without rewrites, and to give you more
  21. than one way to retrieve.
  22. - **Retrieval that fits the question.** Local graph neighborhoods, global
  23. community summaries, naive chunk-vector RAG, and a mix engine — with query
  24. planning and optional token-by-token streaming.
  25. - **Reason over structure, not just chunks.** Extraction yields `Entity` and
  26. `Relation` typed by the NEREL ontology (29 entity, 49 relation types), then
  27. Leiden community detection clusters the graph — so you can ask broad, thematic
  28. questions, not only nearest-neighbor lookups.
  29. - **Async by design.** Batched embeddings, batched vector queries, and
  30. rate-limited LLM clients throughout.
  31. Partially based on [nano-graphrag](https://github.com/gusye1234/nano-graphrag/tree/main)
  32. Our huggingface community is [here](https://huggingface.co/RaguTeam/)
  33. ### Conceptual documentation
  34. - [RAGU components and methodology (EN)](docs/en/ragu_components.md) | [RU](docs/ru/ragu_components.md)
  35. - [NEREL ontology (EN)](docs/en/ontology.md) | [RU](docs/ru/ontology.md)
  36. - [RAGU-lm extraction model (EN)](docs/en/ragu_lm.md) | [RU](docs/ru/ragu_lm.md)
  37. ### Module documentation
  38. - [Package facade](ragu/README.md)
  39. - [Chunking](ragu/chunker/README.md)
  40. - [Common settings, prompts, and utilities](ragu/common/README.md)
  41. - [Prompt schemas and templates](ragu/common/prompts/README.md)
  42. - [Graph construction and index](ragu/graph/README.md)
  43. - [Models, embedders, sparse embedders, and rerankers](ragu/models/README.md)
  44. - [Search engines](ragu/search_engine/README.md)
  45. - [Storage contracts and adapters](ragu/storage/README.md)
  46. - [Graph storage adapters](ragu/storage/graph_storage_adapters/README.md)
  47. - [Vector DB adapters](ragu/storage/vdb_storage_adapters/README.md)
  48. - [Triplet/entity-relation extraction](ragu/triplet/README.md)
  49. - [Utilities](ragu/utils/README.md)
  50. ---
  51. ## Install
  52. The recommended way is a local build:
  53. ```commandline
  54. git clone https://github.com/AsphodelRem/RAGU.git
  55. cd RAGU
  56. uv pip install -e .
  57. ```
  58. From PyPI:
  59. ```bash
  60. pip install graph_ragu
  61. ```
  62. If you want to use local models (via transformers etc.), run:
  63. ```bash
  64. pip install graph_ragu[local]
  65. ```
  66. ---
  67. ## Quickstart
  68. ### Simple example of building knowledge graph
  69. ```python
  70. import asyncio
  71. import os
  72. import sys
  73. import shutil
  74. from ragu.common.logger import logger
  75. logger.remove()
  76. logger.add(sys.stdout, level="DEBUG")
  77. from ragu import (
  78. SimpleChunker,
  79. KnowledgeGraph,
  80. BuilderArguments,
  81. Settings,
  82. TwoStageArtifactsExtractorLLM,
  83. )
  84. from ragu.models.embedder import EmbedderOpenAI
  85. from ragu.models.llm import LLMOpenAI
  86. from ragu.models.openai import CachedAsyncOpenAI
  87. from ragu.utils.ragu_utils import read_text_from_files
  88. client = CachedAsyncOpenAI(
  89. base_url=os.environ['OPENAI_BASE_URL'],
  90. api_key=os.environ['OPENAI_API_KEY'],
  91. rate_min_delay=2,
  92. rate_max_simultaneous=10,
  93. retry_times_sec=(2, 2, 2, 2, 2),
  94. cache='./llm_cache',
  95. debug_errors_storage='./llm_debug',
  96. )
  97. llm = LLMOpenAI(
  98. client=client,
  99. model_name="mistralai/mistral-medium-3",
  100. )
  101. embedder = EmbedderOpenAI(
  102. client=client,
  103. model_name="emb-qwen/qwen3-embedding-8b",
  104. dim=4096,
  105. )
  106. # Configure working directory and language
  107. Settings.storage_folder = "ragu_working_dir"
  108. Settings.language = "english" # or "russian"
  109. # Remove dir to start building graph from scratch
  110. # shutil.rmtree(Settings.storage_folder, ignore_errors=True)
  111. docs = read_text_from_files("path/to/your/files")
  112. # Initialize chunker
  113. chunker = SimpleChunker(max_chunk_size=1000)
  114. # Set up artifact extractor
  115. from ragu.common.prompts import ICLConfig
  116. icl_config = ICLConfig(
  117. enabled=True,
  118. num_examples=2,
  119. )
  120. artifact_extractor = TwoStageArtifactsExtractorLLM(
  121. llm=llm,
  122. embedder=embedder,
  123. icl_config=icl_config,
  124. do_entity_validation=True,
  125. do_relation_validation=True,
  126. )
  127. # Configure builder settings
  128. builder_settings = BuilderArguments(
  129. use_llm_summarization=True,
  130. use_clustering=False,
  131. build_only_vector_context=False,
  132. make_community_summary=True,
  133. remove_isolated_nodes=True,
  134. )
  135. # Build knowledge graph
  136. knowledge_graph = KnowledgeGraph(
  137. llm=llm,
  138. embedder=embedder,
  139. chunker=chunker,
  140. artifact_extractor=artifact_extractor,
  141. builder_settings=builder_settings,
  142. )
  143. asyncio.run(knowledge_graph.build_from_docs(docs))
  144. ```
  145. > If you run the code with a storage folder that already contains a knowledge graph, RAGU will automatically load the existing graph.
  146. ### Example of querying
  147. RAGU ships four retrieval strategies plus a query-planning wrapper. Each engine
  148. exposes `a_search()` (retrieval only) and `a_query()` (retrieval + LLM answer);
  149. sync wrappers `search()` / `query()` are also available. For the conceptual
  150. workflow of each strategy see [`docs/en/ragu_components.md`](docs/en/ragu_components.md);
  151. for full parameters see [`ragu/search_engine/README.md`](ragu/search_engine/README.md).
  152. #### Local search
  153. Graph-neighborhood retrieval: find relevant entities, then expand to their relations, community summaries, and source chunks.
  154. ```python
  155. from ragu import LocalSearchEngine
  156. local_search = LocalSearchEngine(llm=llm, knowledge_graph=knowledge_graph, embedder=embedder)
  157. local_answer = await local_search.a_query("Who wrote Romeo and Juliet?", use_summary=True, use_chunks=True)
  158. print(local_answer.response)
  159. ```
  160. #### Global search
  161. Answers broad, corpus-wide questions from community summaries.
  162. ```python
  163. from ragu import GlobalSearchEngine
  164. global_search = GlobalSearchEngine(llm=llm, knowledge_graph=knowledge_graph)
  165. global_answer = await global_search.a_query("Your broad query here")
  166. print(global_answer.response)
  167. ```
  168. #### Naive search (vector RAG)
  169. Chunk-vector RAG without graph expansion.
  170. ```python
  171. from ragu import NaiveSearchEngine
  172. naive_search = NaiveSearchEngine(llm=llm, knowledge_graph=knowledge_graph, embedder=embedder)
  173. naive_answer = await naive_search.a_query("Your query here")
  174. print(naive_answer.response)
  175. ```
  176. #### Mixed search
  177. Runs several engines and asks the LLM to synthesize a single answer from their responses.
  178. ```python
  179. from ragu import MixSearchEngine
  180. mix_search = MixSearchEngine(llm=llm, engines=[local_search, naive_search, global_search])
  181. mixed_answer = await mix_search.a_query("Your query here")
  182. print(mixed_answer.response)
  183. ```
  184. #### Query planning wrapper
  185. Wraps any engine, decomposes a complex question into dependent subqueries, and feeds intermediate answers forward.
  186. ```python
  187. from ragu import QueryPlanEngine
  188. planned_local = QueryPlanEngine(local_search)
  189. result = await planned_local.a_query("Who wrote the novel 'Quo Vadis' and what country was the author from?")
  190. print(result.response)
  191. ```
  192. ---
  193. ### Advanced Configuration
  194. #### Builder Settings
  195. Configure the knowledge graph building pipeline using `BuilderArguments`:
  196. ```python
  197. from ragu import BuilderArguments, KnowledgeGraph
  198. builder_arguments = BuilderArguments(
  199. use_llm_summarization=True, # Enable LLM-based entity/relation summarization
  200. use_clustering=False, # Apply clustering before summarization. Use it if your text contains many similar entities.
  201. build_only_vector_context=False, # Skip graph extraction, only chunk embeddings
  202. make_community_summary=True, # Generate community summaries
  203. remove_isolated_nodes=True, # Remove entities without relations
  204. cluster_only_if_more_than=10000, # Minimum entities before clustering kicks in
  205. summarize_only_if_more_than=7, # Summarize descriptions only when there are many duplicates
  206. max_cluster_size=128, # Maximum entities per cluster
  207. random_seed=42,
  208. )
  209. knowledge_graph = KnowledgeGraph(
  210. llm=llm,
  211. embedder=embedder,
  212. chunker=chunker,
  213. artifact_extractor=artifact_extractor,
  214. builder_settings=builder_arguments,
  215. )
  216. await knowledge_graph.build_from_docs(docs)
  217. ```
  218. Common presets (naive vector RAG only, fast graph extraction without
  219. summarization, full GraphRAG with communities, and large-corpus clustering) with
  220. explanations and ready-to-run scripts are in
  221. [`ragu/graph/README.md`](ragu/graph/README.md).
  222. ---
  223. #### Client and Rate Limiting Configuration
  224. `CachedAsyncOpenAI` is the network-level client shared by `LLMOpenAI` and `EmbedderOpenAI`. It controls rate limiting, retries, caching, and timeouts.
  225. ```python
  226. client = CachedAsyncOpenAI(
  227. base_url="https://api.openai.com/v1",
  228. api_key="sk-...",
  229. rate_max_simultaneous=10,
  230. rate_max_per_minute=100,
  231. cache="./llm_cache",
  232. )
  233. llm = LLMOpenAI(client=client, model_name="gpt-4o-mini")
  234. embedder = EmbedderOpenAI(client=client, model_name="text-embedding-3-large", dim=3072)
  235. ```
  236. For the full parameter tables (`rate_*`, `retry_times_sec`, `embed_timeout`, `EmbedderOpenAI` batching and tokenizer overrides), the **shared vs. separate clients** guidance for large corpora, and the **debug store**, see [`ragu/models/README.md`](ragu/models/README.md).
  237. ---
  238. #### Token Limits and Settings
  239. RAGU centralises token-limit and tokenizer configuration in the `Settings` singleton. These defaults are used by `EmbedderOpenAI` (for embedding input truncation) and search engines (for LLM context truncation).
  240. ```python
  241. from ragu import Settings
  242. # Embedder truncation (applied automatically inside EmbedderOpenAI)
  243. Settings.embedder_token_limit = 8_192 # max tokens per embedding input
  244. Settings.tokenizer_embedder_backend = "tiktoken" # "tiktoken" or "local"
  245. Settings.tokenizer_embedder_name = "text-embedding-3-large"
  246. # LLM context truncation (applied by search engines before answer generation)
  247. Settings.llm_context_token_limit = 30_000 # max tokens for search-engine context
  248. Settings.tokenizer_llm_backend = "tiktoken" # "tiktoken" or "local"
  249. Settings.tokenizer_llm_name = "gpt-4o"
  250. ```
  251. Per-instance overrides on `EmbedderOpenAI` take precedence over `Settings`.
  252. For a local BGE model with a 512-token context, set
  253. `Settings.embedder_token_limit = 512`, `Settings.tokenizer_embedder_backend = "local"`,
  254. and `Settings.tokenizer_embedder_name = "BAAI/bge-large-en-v1.5"` (requires
  255. `pip install graph_ragu[local]`).
  256. ---
  257. #### Serializing Global Settings
  258. `Settings.save(path)` writes a JSON snapshot of the configuration;
  259. `Settings.load(path)` restores it. Serialization is never invoked automatically.
  260. For the list of serialized/excluded fields and the validation behavior, see
  261. [`ragu/common/README.md`](ragu/common/README.md).
  262. ```python
  263. from ragu import Settings
  264. Settings.save("./runs/exp_42/ragu_settings.json") # persist
  265. Settings.load("./runs/exp_42/ragu_settings.json") # restore in a fresh process
  266. ```
  267. ---
  268. #### In-Context Learning (Few-Shot Examples)
  269. RAGU extractors can use few-shot examples to improve extraction quality. When enabled, the extractor selects relevant examples and includes them in the LLM prompt.
  270. ```python
  271. from ragu.common.prompts import ICLConfig
  272. icl_config = ICLConfig(
  273. enabled=True, # Enable/disable ICL
  274. num_examples=2, # Number of examples per extraction call (1-3 recommended)
  275. selection_strategy="semantic", # "semantic" | "bm25" | "hybrid" | "random"
  276. )
  277. artifact_extractor = TwoStageArtifactsExtractorLLM(
  278. llm=llm,
  279. embedder=embedder, # Required for "semantic" and "hybrid"; optional for "bm25" and "random"
  280. icl_config=icl_config,
  281. )
  282. ```
  283. Four selection strategies are available (`"semantic"`, `"bm25"`, `"hybrid"`, `"random"`). Pre-built example files ship in `ragu/common/prompts/icl_examples/`; to generate custom ones, run `python scripts/generate_icl_examples.py --config config/icl_generation.yaml`. For the strategy comparison table and per-strategy embedder requirements, see [`ragu/common/prompts/README.md`](ragu/common/prompts/README.md).
  284. ---
  285. ### Knowledge Graph Construction
  286. Each text in the corpus is processed to extract structured information. It consists of:
  287. * **Entities** — textual representation, entity type, and a contextual description.
  288. * **Relations** — textual description of the link between two entities (or a relation class), as well as its confidence/strength.
  289. > **RAGU uses entity and relation classes from [NEREL](https://github.com/nerel-ds/NEREL).** The full type tables are available in English and Russian: [`docs/en/ontology.md`](docs/en/ontology.md) | [`docs/ru/ontology.md`](docs/ru/ontology.md). Pass custom `entity_types` / `relation_types` to the extractors to override the defaults.
  290. >
  291. > `Entity` and `Relation` are base graph model classes. They can be inherited to create richer domain-specific node and edge types, provided the storage `Node` / `Edge` contract is preserved. See [graph docs](ragu/graph/README.md) and [storage docs](ragu/storage/README.md).
  292. ### Extraction pipelines
  293. #### 1. Single-step LLM pipeline
  294. File: `ragu/triplet/llm_artifact_extractor.py`.
  295. A baseline pipeline that uses an LLM to extract entities, relations, and their descriptions in a single step. Supports optional in-context learning with few-shot examples and artifact validation.
  296. #### 2. Two-stage LLM pipeline
  297. File: `ragu/triplet/two_stage_extractor.py`.
  298. Extracts entities first, then extracts relations constrained by the entity list. It can separately validate entity and relation outputs. Supports optional in-context learning with few-shot examples.
  299. #### 3. RAGU-lm (Russian language)
  300. A compact model (Qwen-3-0.6B) fine-tuned on the NEREL dataset. Recognizes and normalizes entities, generates descriptions, and extracts relations. Full prompts, a worked example, and an F1 comparison live in [`docs/en/ragu_lm.md`](docs/en/ragu_lm.md) (RU: [`docs/ru/ragu_lm.md`](docs/ru/ragu_lm.md)).
  301. ---
  302. ### Prompt Customization
  303. All RAGU components that use LLMs inherit from `RaguGenerativeModule`, which provides `get_prompt`, `get_prompts`, and `update_prompt` to view and override instructions.
  304. ```python
  305. from ragu import LocalSearchEngine
  306. search_engine = LocalSearchEngine(
  307. llm=llm,
  308. knowledge_graph=knowledge_graph,
  309. embedder=embedder,
  310. )
  311. all_prompts = search_engine.get_prompts() # {'local_search': RAGUInstruction(...)}
  312. local_search_prompt = search_engine.get_prompt("local_search")
  313. print(local_search_prompt.messages.to_str()) # rendered prompt text
  314. print(local_search_prompt.pydantic_model) # response schema
  315. ```
  316. To override an instruction, build a new `RAGUInstruction` and call
  317. `search_engine.update_prompt("local_search", custom_instruction)`. Do **not**
  318. edit `DEFAULT_PROMPT_TEMPLATES` directly — `update_prompt` scopes the change to a
  319. single module instance. Full examples (including custom messages and few-shot
  320. formatters) are in [`ragu/common/prompts/README.md`](ragu/common/prompts/README.md).
  321. ---
  322. ### Contributors
  323. #### **Main Idea & Inspiration**
  324. - Ivan Bondarenko — idea, smart_chunker, NER model, ragu-lm
  325. #### **Core Development**
  326. - Mikhail Komarov
  327. #### **Benchmarks & Evaluation**
  328. - Roman Shuvalov
  329. - Yanya Dement'yeva
  330. - Alexandr Kuleshevskiy
  331. - Nikita Kukuzey
  332. - Stanislav Shtuka
  333. #### **Small Models Pipeline**
  334. - Matvey Solovyev
  335. - Ilya Myznikov
  336. ## Star History
  337. <p align="left">
  338. <img src="assets/star-history-2026722.png" alt="RAGU star history" width="600" />
  339. </p>
  340. ## Citation
  341. If you find this work useful, please consider citing our paper:
  342. ```python
  343. @misc{komarov2026ragumultistepgraphragengine,
  344. title={RAGU: A Multi-Step GraphRAG Engine with a Compact Domain-Adapted LLM},
  345. author={Mikhail Komarov and Ivan Bondarenko and Stanislav Shtuka and Oleg Sedukhin and Roman Shuvalov and Yana Dementyeva and Matvey Solovyov and Nikolay O. Nikitin},
  346. year={2026},
  347. eprint={2607.11683},
  348. archivePrefix={arXiv},
  349. primaryClass={cs.CL},
  350. url={https://arxiv.org/abs/2607.11683},
  351. }
  352. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.