runic-py 0.4.0__tar.gz → 0.4.2__tar.gz

{runic_py-0.4.0 → runic_py-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runic-py
-Version: 0.4.0
+Version: 0.4.2
 Summary: Graph schema migrations and OGM for Cypher-based graph databases.
 Project-URL: Homepage, https://runic.rehpoehler.de
 Project-URL: Repository, https://github.com/jenreh/runic
@@ -16,7 +16,7 @@ Requires-Python: >=3.14
 Requires-Dist: mako<2.0.0,>=1.3.0
 Requires-Dist: rich<16.0.0,>=14.0.0
 Requires-Dist: shellingham<2.0.0,>=1.5.0
-Requires-Dist: typer<1.0.0,>=0.26.0
+Requires-Dist: typer<0.27.0,>=0.24.0
 Provides-Extra: age
 Requires-Dist: psycopg<4.0.0,>=3.3.4; extra == 'age'
 Provides-Extra: age-binary
@@ -47,12 +47,12 @@ Description-Content-Type: text/markdown
 **A type-safe OGM for Cypher graph databases.<br>
 Define your models once, run them on any backend.**
 
-![Version](https://img.shields.io/badge/version-0.4.0-blue)
+![Version](https://img.shields.io/badge/version-0.4.2-blue)
 [![PyPI](https://img.shields.io/pypi/v/runic-py.svg)](https://pypi.org/project/runic-py/)
 [![Python](https://img.shields.io/badge/python-3.14%2B-orange)](https://www.python.org)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE.md)
 
-[Why Runic](#why-runic) • [The OGM](#the-ogm) • [Migrations](#migrations) • [Installation](#installation) • [Docs](https://runic.rehpoehler.de)
+[Why Runic](#why-runic) • [The OGM](#the-ogm) • [Migrations](#migrations) • [Graph-RAG](#graph-rag) • [Installation](#installation) • [Docs](https://runic.rehpoehler.de)
 
 </div>
 
@@ -61,7 +61,8 @@ Define your models once, run them on any backend.**
 Runic maps Python classes to graph nodes and edges. You declare typed `Node` and `Edge` models
 and get change tracking, lazy and eager relationships, a composable query API, and schema
 migrations — on top of a pluggable driver layer that runs the same model code on FalkorDB,
-Neo4j, Memgraph, ArcadeDB, and Apache AGE.
+Neo4j, Memgraph, ArcadeDB, and Apache AGE. A built-in [Graph-RAG SDK](#graph-rag) layers
+document ingestion and cited, knowledge-graph-grounded question answering on top of the OGM.
 
 ## Why Runic
 
@@ -303,6 +304,55 @@ print("current:", runic.migrate.current())
 
 ---
 
+## Graph-RAG
+
+`runic.rag` turns unstructured text into a knowledge graph and answers questions over it with
+citations — chunking, entity/relation extraction, embedding, storage, and hybrid (vector +
+fulltext + graph-expansion) retrieval are handled for you. It builds on the same OGM and driver
+layer, so it runs on any supported backend. OpenAI is the default for the LLM and embeddings;
+point it at Ollama for a fully local run.
+
+```python
+from runic.ogm import create_driver
+from runic.rag import GraphRAG, Ontology, RagSettings
+
+settings = RagSettings()
+driver = create_driver(
+    "falkordb", host="localhost", port=6379, graph=settings.falkordb_graph
+)
+
+# with_defaults() wires the full adapter stack from your environment:
+# paragraph chunker, extractor, embedder, resolver, retrievers, reranker, synthesizer.
+rag = GraphRAG.with_defaults(driver, settings=settings, ontology=Ontology.default())
+rag.bootstrap_schema()   # create entity types + indexes (idempotent)
+
+# Ingest: chunk -> extract entities/relations -> embed -> resolve -> write the graph.
+rag.ingest_text(
+    "Ada Lovelace worked with Charles Babbage on the Analytical Engine in London.",
+    source="inline-demo",
+)
+
+# mode="auto" classifies the question and picks the retrieval strategy automatically.
+answer = rag.query("Who worked on the Analytical Engine?")
+print(answer.text)
+for citation in answer.citations:
+    print(f"  - [{citation.source}] {citation.text[:80]}...")
+```
+
+Every stage is a port with a default adapter you can swap — custom ontologies, chunkers,
+extractors, or retrievers — and the optional **`runic-rag-docling`** add-on plugs Docling in for
+layout-aware parsing and chunking of PDFs and office documents.
+
+```bash
+uv add "runic-py[graphrag,falkordb]"   # Graph-RAG extras + a backend driver
+```
+
+> [!NOTE]
+> Set `OPENAI_API_KEY` (or place it in a local `.env`) before running, or set
+> `RUNIC_RAG_LLM_PROVIDER=ollama` and `RUNIC_RAG_EMBEDDING_PROVIDER=ollama` to run fully local.
+
+---
+
 ## Installation
 
 Install the core package plus the extra for your backend. The core has **no graph-driver
@@ -316,6 +366,7 @@ dependency** — you only pull in what you use.
 | ArcadeDB | `arcadedb` | `neo4j` (Bolt) |
 | Apache AGE | `age` | `psycopg[binary]` |
 | All backends | `all` | all of the above |
+| Graph-RAG | `graphrag` | `pydantic-ai`, `pymupdf` (combine with a backend) |
 
 ```bash
 uv add "runic-py[falkordb]"   # FalkorDB
@@ -324,6 +375,7 @@ uv add "runic-py[memgraph]"   # Memgraph (Bolt)
 uv add "runic-py[arcadedb]"   # ArcadeDB (Bolt)
 uv add "runic-py[age]"        # Apache AGE (PostgreSQL extension)
 uv add "runic-py[all]"        # everything
+uv add "runic-py[graphrag,falkordb]"   # Graph-RAG SDK + a backend driver
 ```
 
 > [!NOTE]
@@ -333,8 +385,8 @@ uv add "runic-py[all]"        # everything
 
 ## Documentation
 
-Full conceptual overview, async usage, advanced CLI flags, and the complete API reference live
-at the **[Runic Documentation](https://runic.rehpoehler.de)**.
+Full conceptual overview, async usage, advanced CLI flags, the Graph-RAG guides, and the
+complete API reference live at the **[Runic Documentation](https://runic.rehpoehler.de)**.
 
 ## License
 

{runic_py-0.4.0 → runic_py-0.4.2}/README.md

@@ -6,12 +6,12 @@
 **A type-safe OGM for Cypher graph databases.<br>
 Define your models once, run them on any backend.**
 
-![Version](https://img.shields.io/badge/version-0.4.0-blue)
+![Version](https://img.shields.io/badge/version-0.4.2-blue)
 [![PyPI](https://img.shields.io/pypi/v/runic-py.svg)](https://pypi.org/project/runic-py/)
 [![Python](https://img.shields.io/badge/python-3.14%2B-orange)](https://www.python.org)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE.md)
 
-[Why Runic](#why-runic) • [The OGM](#the-ogm) • [Migrations](#migrations) • [Installation](#installation) • [Docs](https://runic.rehpoehler.de)
+[Why Runic](#why-runic) • [The OGM](#the-ogm) • [Migrations](#migrations) • [Graph-RAG](#graph-rag) • [Installation](#installation) • [Docs](https://runic.rehpoehler.de)
 
 </div>
 
@@ -20,7 +20,8 @@ Define your models once, run them on any backend.**
 Runic maps Python classes to graph nodes and edges. You declare typed `Node` and `Edge` models
 and get change tracking, lazy and eager relationships, a composable query API, and schema
 migrations — on top of a pluggable driver layer that runs the same model code on FalkorDB,
-Neo4j, Memgraph, ArcadeDB, and Apache AGE.
+Neo4j, Memgraph, ArcadeDB, and Apache AGE. A built-in [Graph-RAG SDK](#graph-rag) layers
+document ingestion and cited, knowledge-graph-grounded question answering on top of the OGM.
 
 ## Why Runic
 
@@ -262,6 +263,55 @@ print("current:", runic.migrate.current())
 
 ---
 
+## Graph-RAG
+
+`runic.rag` turns unstructured text into a knowledge graph and answers questions over it with
+citations — chunking, entity/relation extraction, embedding, storage, and hybrid (vector +
+fulltext + graph-expansion) retrieval are handled for you. It builds on the same OGM and driver
+layer, so it runs on any supported backend. OpenAI is the default for the LLM and embeddings;
+point it at Ollama for a fully local run.
+
+```python
+from runic.ogm import create_driver
+from runic.rag import GraphRAG, Ontology, RagSettings
+
+settings = RagSettings()
+driver = create_driver(
+    "falkordb", host="localhost", port=6379, graph=settings.falkordb_graph
+)
+
+# with_defaults() wires the full adapter stack from your environment:
+# paragraph chunker, extractor, embedder, resolver, retrievers, reranker, synthesizer.
+rag = GraphRAG.with_defaults(driver, settings=settings, ontology=Ontology.default())
+rag.bootstrap_schema()   # create entity types + indexes (idempotent)
+
+# Ingest: chunk -> extract entities/relations -> embed -> resolve -> write the graph.
+rag.ingest_text(
+    "Ada Lovelace worked with Charles Babbage on the Analytical Engine in London.",
+    source="inline-demo",
+)
+
+# mode="auto" classifies the question and picks the retrieval strategy automatically.
+answer = rag.query("Who worked on the Analytical Engine?")
+print(answer.text)
+for citation in answer.citations:
+    print(f"  - [{citation.source}] {citation.text[:80]}...")
+```
+
+Every stage is a port with a default adapter you can swap — custom ontologies, chunkers,
+extractors, or retrievers — and the optional **`runic-rag-docling`** add-on plugs Docling in for
+layout-aware parsing and chunking of PDFs and office documents.
+
+```bash
+uv add "runic-py[graphrag,falkordb]"   # Graph-RAG extras + a backend driver
+```
+
+> [!NOTE]
+> Set `OPENAI_API_KEY` (or place it in a local `.env`) before running, or set
+> `RUNIC_RAG_LLM_PROVIDER=ollama` and `RUNIC_RAG_EMBEDDING_PROVIDER=ollama` to run fully local.
+
+---
+
 ## Installation
 
 Install the core package plus the extra for your backend. The core has **no graph-driver
@@ -275,6 +325,7 @@ dependency** — you only pull in what you use.
 | ArcadeDB | `arcadedb` | `neo4j` (Bolt) |
 | Apache AGE | `age` | `psycopg[binary]` |
 | All backends | `all` | all of the above |
+| Graph-RAG | `graphrag` | `pydantic-ai`, `pymupdf` (combine with a backend) |
 
 ```bash
 uv add "runic-py[falkordb]"   # FalkorDB
@@ -283,6 +334,7 @@ uv add "runic-py[memgraph]"   # Memgraph (Bolt)
 uv add "runic-py[arcadedb]"   # ArcadeDB (Bolt)
 uv add "runic-py[age]"        # Apache AGE (PostgreSQL extension)
 uv add "runic-py[all]"        # everything
+uv add "runic-py[graphrag,falkordb]"   # Graph-RAG SDK + a backend driver
 ```
 
 > [!NOTE]
@@ -292,8 +344,8 @@ uv add "runic-py[all]"        # everything
 
 ## Documentation
 
-Full conceptual overview, async usage, advanced CLI flags, and the complete API reference live
-at the **[Runic Documentation](https://runic.rehpoehler.de)**.
+Full conceptual overview, async usage, advanced CLI flags, the Graph-RAG guides, and the
+complete API reference live at the **[Runic Documentation](https://runic.rehpoehler.de)**.
 
 ## License
 

{runic_py-0.4.0 → runic_py-0.4.2}/packages/runic-rag-docling/pyproject.toml

@@ -41,7 +41,10 @@ dev = [
 commit = false
 current_version = "0.2.0"
 tag = false
-allow-dirty = false
+# This package lives in the shared ``runic`` monorepo, whose working tree
+# routinely carries unrelated sibling changes and whose ``v*`` tags belong to
+# ``runic-py``; allow a dirty tree so the package-scoped bump isn't blocked.
+allow_dirty = true
 
 [[tool.bumpversion.files]]
 filename = "pyproject.toml"
@@ -72,6 +75,13 @@ build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["runic_rag_docling"]
 
+[tool.hatch.build.targets.sdist]
+# Ship only the source package and metadata; never the local virtualenv
+# (``.venv.mac``), caches, or build artefacts, which break ``uv build`` with
+# "external symlinks are not allowed".
+include = ["/runic_rag_docling", "/README.md", "/pyproject.toml"]
+exclude = [".venv*"]
+
 [tool.pytest.ini_options]
 # ``tests`` is a package; put the package root on the path so ``tests.fakes``
 # imports resolve regardless of the invocation directory.

{runic_py-0.4.0 → runic_py-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "runic-py"
-version = "0.4.0"
+version = "0.4.2"
 description = "Graph schema migrations and OGM for Cypher-based graph databases."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -16,7 +16,7 @@ classifiers = [
 ]
 
 dependencies = [
-    "typer>=0.26.0,<1.0.0",
+    "typer>=0.24.0,<0.27.0",
     "rich>=14.0.0,<16.0.0",
     "mako>=1.3.0,<2.0.0",
     "shellingham>=1.5.0,<2.0.0",
@@ -101,7 +101,7 @@ exclude = [
 
 [tool.bumpversion]
 commit = false
-current_version = "0.4.0"
+current_version = "0.4.2"
 tag = false
 allow-dirty = false
 

{runic_py-0.4.0 → runic_py-0.4.2}/runic/rag/config.py

@@ -3,7 +3,9 @@
 All ``RUNIC_RAG_*`` environment variables map onto :class:`RagSettings`
 field names (env_prefix ``RUNIC_RAG_``). ``OPENAI_API_KEY`` and
 ``OLLAMA_BASE_URL`` are read UNPREFIXED so they match the conventions of the
-underlying OpenAI / Ollama clients. Defaults mirror ``.env.example`` exactly.
+underlying OpenAI / Ollama clients (the ``RUNIC_RAG_``-prefixed form and direct
+keyword init are also accepted via ``populate_by_name``). Defaults mirror
+``.env.example`` exactly.
 """
 
 from __future__ import annotations
@@ -37,6 +39,7 @@ class RagSettings(BaseSettings):
         env_file_encoding="utf-8",
         extra="ignore",
         case_sensitive=False,
+        populate_by_name=True,
     )
 
     # ── LLM provider ────────────────────────────────────────────────────────