riff-kg-kit 0.7.0__tar.gz

riff_kg_kit-0.7.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.coverage
+htmlcov/
+.mypy_cache/

riff_kg_kit-0.7.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.7.0
+
+- Hybrid retrieval improvements: `search_segments_hybrid` now supports `rrf` and `weighted` strategies via `merge_segment_hits_hybrid`.
+- Graph-hop retrieval: added `graph_hop_subgraph` with `GraphEntityNode` and `GraphRelationEdge`.
+- Docs: added publishing checklist and retrieval examples.
+
+## 0.6.0 and earlier
+
+- Phases 0–4: package skeleton, migrations, ingest, extract, commit/reject, and docs.

riff_kg_kit-0.7.0/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Ellen
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

riff_kg_kit-0.7.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: riff-kg-kit
+Version: 0.7.0
+Summary: Opinionated knowledge-graph ingest, staged proposals, and retrieval for Riff (FastAPI) apps
+Project-URL: Homepage, https://pypi.org/project/riff-kg-kit/
+Author: Ellen
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,knowledge-graph,rag,riff
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: dev
+Requires-Dist: asyncpg>=0.29; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# riff-kg-kit
+
+PyPI-first Python library for **staged knowledge-graph ingestion** and **agent-approved commits**, designed to plug into **Riff** apps (FastAPI + Postgres + `pgvector`).
+
+## Status
+
+**0.7.0 — Retrieval+ updates.** Adds hybrid reranking strategies and graph-hop retrieval helpers on top of vector/FTS segment search and `pack_context`.
+
+## Install
+
+```bash
+pip install riff-kg-kit
+```
+
+Editable (local dev):
+
+```bash
+pip install -e ".[dev,yaml]"
+```
+
+## Quick use
+
+```python
+from riff_kg import KgConfig
+
+cfg = KgConfig.model_validate_json('{"embedding_dimension": 768}')
+assert cfg.embedding_dimension == 768
+```
+
+## Roadmap (summary)
+
+1. Migrations + core tables (`signal`, `signal_segment`, `staged_proposal`, …)
+2. Normalize → segment → embed
+3. Extract → stage (LLM proposals only)
+4. Approve → commit (validated canonical graph)
+5. Search / pack-context / retrieval (implemented: `riff_kg.search`)
+
+### Retrieval (Phase 5)
+
+```python
+from riff_kg import KgConfig
+from riff_kg.search import pack_context, search_segments_vector
+
+# After migrations and ingest with embeddings, pass a query embedding
+# (same dimension as KgConfig.embedding_dimension, e.g. 768):
+# hits = await search_segments_vector(conn, cfg, query_vec, scope_id="my_scope")
+# text = pack_context(hits)
+```
+
+### Hybrid rerank and graph hops
+
+```python
+from riff_kg.search import graph_hop_subgraph, search_segments_hybrid
+
+# Hybrid search with Reciprocal Rank Fusion (default)
+# hits = await search_segments_hybrid(conn, cfg, query_embedding=qvec, fts_query="topic")
+
+# Graph neighborhood around a committed entity
+# nodes, edges = await graph_hop_subgraph(conn, root_entity_id=entity_id, max_hops=2, scope_id="my_scope")
+```
+
+## Publishing checklist
+
+1. Bump version in `pyproject.toml` and `src/riff_kg/__init__.py`.
+2. Update `CHANGELOG.md` and README status/examples.
+3. Run `python -m ruff check src tests` and `python -m pytest tests -q`.
+4. Build distributions: `python -m build`.
+5. Upload to TestPyPI first, verify install, then publish to PyPI.
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).

riff_kg_kit-0.7.0/README.md

@@ -0,0 +1,72 @@
+# riff-kg-kit
+
+PyPI-first Python library for **staged knowledge-graph ingestion** and **agent-approved commits**, designed to plug into **Riff** apps (FastAPI + Postgres + `pgvector`).
+
+## Status
+
+**0.7.0 — Retrieval+ updates.** Adds hybrid reranking strategies and graph-hop retrieval helpers on top of vector/FTS segment search and `pack_context`.
+
+## Install
+
+```bash
+pip install riff-kg-kit
+```
+
+Editable (local dev):
+
+```bash
+pip install -e ".[dev,yaml]"
+```
+
+## Quick use
+
+```python
+from riff_kg import KgConfig
+
+cfg = KgConfig.model_validate_json('{"embedding_dimension": 768}')
+assert cfg.embedding_dimension == 768
+```
+
+## Roadmap (summary)
+
+1. Migrations + core tables (`signal`, `signal_segment`, `staged_proposal`, …)
+2. Normalize → segment → embed
+3. Extract → stage (LLM proposals only)
+4. Approve → commit (validated canonical graph)
+5. Search / pack-context / retrieval (implemented: `riff_kg.search`)
+
+### Retrieval (Phase 5)
+
+```python
+from riff_kg import KgConfig
+from riff_kg.search import pack_context, search_segments_vector
+
+# After migrations and ingest with embeddings, pass a query embedding
+# (same dimension as KgConfig.embedding_dimension, e.g. 768):
+# hits = await search_segments_vector(conn, cfg, query_vec, scope_id="my_scope")
+# text = pack_context(hits)
+```
+
+### Hybrid rerank and graph hops
+
+```python
+from riff_kg.search import graph_hop_subgraph, search_segments_hybrid
+
+# Hybrid search with Reciprocal Rank Fusion (default)
+# hits = await search_segments_hybrid(conn, cfg, query_embedding=qvec, fts_query="topic")
+
+# Graph neighborhood around a committed entity
+# nodes, edges = await graph_hop_subgraph(conn, root_entity_id=entity_id, max_hops=2, scope_id="my_scope")
+```
+
+## Publishing checklist
+
+1. Bump version in `pyproject.toml` and `src/riff_kg/__init__.py`.
+2. Update `CHANGELOG.md` and README status/examples.
+3. Run `python -m ruff check src tests` and `python -m pytest tests -q`.
+4. Build distributions: `python -m build`.
+5. Upload to TestPyPI first, verify install, then publish to PyPI.
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).

riff_kg_kit-0.7.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling>=1.24.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "riff-kg-kit"
+version = "0.7.0"
+description = "Opinionated knowledge-graph ingest, staged proposals, and retrieval for Riff (FastAPI) apps"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+authors = [{ name = "Ellen" }]
+keywords = ["knowledge-graph", "riff", "rag", "agents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+dependencies = ["pydantic>=2.7,<3"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.6",
+    "asyncpg>=0.29",
+]
+postgres = ["asyncpg>=0.29"]
+yaml = ["PyYAML>=6.0"]
+
+[project.urls]
+Homepage = "https://pypi.org/project/riff-kg-kit/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/riff_kg"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/README.md", "/CHANGELOG.md", "/LICENSE"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

riff_kg_kit-0.7.0/src/riff_kg/__init__.py

@@ -0,0 +1,19 @@
+"""Riff knowledge-graph kit: staged ingest, approve/commit, retrieval."""
+
+from riff_kg import commit, extract, ingest, models, pipeline, search, stage, text
+from riff_kg.config import KgConfig
+
+__version__ = "0.7.0"
+
+__all__ = [
+    "__version__",
+    "KgConfig",
+    "commit",
+    "extract",
+    "ingest",
+    "models",
+    "pipeline",
+    "search",
+    "stage",
+    "text",
+]

riff_kg_kit-0.7.0/src/riff_kg/commit.py

@@ -0,0 +1,272 @@
+"""Phase 4: validate staged proposals and write canonical entities / relations."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import asyncpg
+
+from riff_kg.config import KgConfig
+
+
+def _payload_dict(raw: Any) -> dict[str, Any]:
+    if raw is None:
+        return {}
+    if isinstance(raw, dict):
+        return raw
+    if isinstance(raw, str):
+        return json.loads(raw)
+    raise TypeError("payload must be dict or json string")
+
+
+def _require_str(d: dict[str, Any], key: str) -> str:
+    v = d.get(key)
+    if not isinstance(v, str) or not v.strip():
+        raise ValueError(f"payload missing or invalid string field: {key!r}")
+    return v.strip()
+
+
+def _optional_str(d: dict[str, Any], key: str) -> str | None:
+    v = d.get(key)
+    if v is None:
+        return None
+    if isinstance(v, str):
+        s = v.strip()
+        return s or None
+    raise ValueError(f"payload field {key!r} must be string or null")
+
+
+def _optional_dict(d: dict[str, Any], key: str) -> dict[str, Any]:
+    v = d.get(key)
+    if v is None:
+        return {}
+    if isinstance(v, dict):
+        return v
+    raise ValueError(f"payload field {key!r} must be object")
+
+
+def _parse_uuid(s: str) -> uuid.UUID:
+    try:
+        return uuid.UUID(str(s).strip())
+    except ValueError as e:
+        raise ValueError(f"invalid uuid: {s!r}") from e
+
+
+@dataclass(frozen=True)
+class CommitResult:
+    """One committed staged proposal."""
+
+    proposal_id: uuid.UUID
+    record_kind: Literal["entity", "relation"]
+    record_id: uuid.UUID
+
+
+@dataclass(frozen=True)
+class CommitSummary:
+    """Batch outcome for `commit_proposals`."""
+
+    committed: tuple[CommitResult, ...]
+    skipped_already_approved: tuple[uuid.UUID, ...]
+
+
+async def commit_proposals(
+    conn: asyncpg.Connection,
+    cfg: KgConfig,
+    proposal_ids: list[uuid.UUID],
+    *,
+    committed_by: str | None = None,
+) -> CommitSummary:
+    """Commit pending proposals: entities first, then relations. Idempotent: skips `approved`."""
+    if not proposal_ids:
+        return CommitSummary(committed=(), skipped_already_approved=())
+
+    uniq = list(dict.fromkeys(proposal_ids))
+    rows = await conn.fetch(
+        """
+        SELECT sp.id, sp.proposal_kind, sp.payload, sp.segment_id, sp.char_start, sp.char_end,
+               sp.status AS proposal_status, s.scope_id, sp.extraction_run_id
+        FROM riff_kg.staged_proposals sp
+        JOIN riff_kg.signal_segments seg ON seg.id = sp.segment_id
+        JOIN riff_kg.signals s ON s.id = seg.signal_id
+        WHERE sp.id = ANY($1::uuid[])
+        """,
+        uniq,
+    )
+    by_id = {r["id"]: r for r in rows}
+    missing = [pid for pid in uniq if pid not in by_id]
+    if missing:
+        raise ValueError(f"unknown or inaccessible proposal ids: {missing}")
+
+    sorted_rows = sorted(
+        rows,
+        key=lambda r: (0 if str(r["proposal_kind"]).strip() == "entity" else 1, str(r["id"])),
+    )
+
+    committed: list[CommitResult] = []
+    skipped: list[uuid.UUID] = []
+
+    async with conn.transaction():
+        for row in sorted_rows:
+            pid: uuid.UUID = row["id"]
+            st = row["proposal_status"]
+            if st == "approved":
+                skipped.append(pid)
+                continue
+            if st != "pending_review":
+                raise ValueError(f"proposal {pid} is not pending_review ({st})")
+
+            scope_raw = row["scope_id"]
+            scope_id = scope_raw if isinstance(scope_raw, str) else str(scope_raw or "")
+            pk = row["proposal_kind"]
+            kind = str(pk).strip() if pk is not None else ""
+            if not kind:
+                raise ValueError(f"proposal {pid} has empty proposal_kind")
+            payload = _payload_dict(row["payload"])
+
+            if kind == "entity":
+                entity_type = _require_str(payload, "entity_type")
+                if entity_type not in cfg.entity_types:
+                    raise ValueError(f"entity_type {entity_type!r} not allowed by KgConfig")
+                label = _require_str(payload, "label")
+                can_key = _optional_str(payload, "canonical_key")
+                attrs = json.dumps(_optional_dict(payload, "attrs"))
+
+                if can_key:
+                    existing = await conn.fetchrow(
+                        """
+                        SELECT id FROM riff_kg.entities
+                        WHERE scope_id = $1 AND entity_type = $2 AND canonical_key = $3
+                        """,
+                        scope_id,
+                        entity_type,
+                        can_key,
+                    )
+                    if existing:
+                        eid = existing["id"]
+                        await conn.execute(
+                            """
+                            UPDATE riff_kg.entities
+                            SET label = $1, attrs = attrs || $2::jsonb
+                            WHERE id = $3
+                            """,
+                            label,
+                            attrs,
+                            eid,
+                        )
+                    else:
+                        eid = await conn.fetchval(
+                            """
+                            INSERT INTO riff_kg.entities (
+                                scope_id, entity_type, label, canonical_key, attrs
+                            )
+                            VALUES ($1, $2, $3, $4, $5::jsonb)
+                            RETURNING id
+                            """,
+                            scope_id,
+                            entity_type,
+                            label,
+                            can_key,
+                            attrs,
+                        )
+                else:
+                    eid = await conn.fetchval(
+                        """
+                        INSERT INTO riff_kg.entities (
+                            scope_id, entity_type, label, canonical_key, attrs
+                        )
+                        VALUES ($1, $2, $3, NULL, $4::jsonb)
+                        RETURNING id
+                        """,
+                        scope_id,
+                        entity_type,
+                        label,
+                        attrs,
+                    )
+
+                await conn.execute(
+                    """
+                    UPDATE riff_kg.staged_proposals
+                    SET status = 'approved', resolution_note = NULL
+                    WHERE id = $1
+                    """,
+                    pid,
+                )
+                committed.append(CommitResult(pid, "entity", eid))
+
+            elif kind == "relation":
+                rel_type = _require_str(payload, "relation_type")
+                if rel_type not in cfg.relation_types:
+                    raise ValueError(f"relation_type {rel_type!r} not allowed by KgConfig")
+                src = _parse_uuid(_require_str(payload, "src_entity_id"))
+                dst = _parse_uuid(_require_str(payload, "dst_entity_id"))
+                rattrs = json.dumps(_optional_dict(payload, "attrs"))
+
+                rid = await conn.fetchval(
+                    """
+                    INSERT INTO riff_kg.relations (
+                        scope_id, src_entity_id, dst_entity_id, relation_type, attrs,
+                        evidence_segment_id, evidence_char_start, evidence_char_end,
+                        staged_proposal_id, extraction_run_id, committed_by
+                    )
+                    VALUES (
+                        $1, $2, $3, $4, $5::jsonb,
+                        $6, $7, $8, $9, $10, $11
+                    )
+                    RETURNING id
+                    """,
+                    scope_id,
+                    src,
+                    dst,
+                    rel_type,
+                    rattrs,
+                    row["segment_id"],
+                    row["char_start"],
+                    row["char_end"],
+                    pid,
+                    row["extraction_run_id"],
+                    committed_by,
+                )
+
+                await conn.execute(
+                    """
+                    UPDATE riff_kg.staged_proposals SET status = 'approved', resolution_note = NULL
+                    WHERE id = $1
+                    """,
+                    pid,
+                )
+                committed.append(CommitResult(pid, "relation", rid))
+            else:
+                raise ValueError(f"unsupported proposal_kind for commit: {kind!r}")
+
+    return CommitSummary(
+        committed=tuple(committed),
+        skipped_already_approved=tuple(skipped),
+    )
+
+
+async def reject_proposals(
+    conn: asyncpg.Connection,
+    proposal_ids: list[uuid.UUID],
+    *,
+    reason: str,
+) -> int:
+    """Mark pending proposals rejected; returns number of rows updated."""
+    if not proposal_ids:
+        return 0
+    status = await conn.execute(
+        """
+        UPDATE riff_kg.staged_proposals
+        SET status = 'rejected', resolution_note = $2
+        WHERE id = ANY($1::uuid[]) AND status = 'pending_review'
+        """,
+        list(dict.fromkeys(proposal_ids)),
+        reason[:10_000],
+    )
+    # asyncpg returns "UPDATE N"
+    prefix = "UPDATE "
+    if status.startswith(prefix):
+        return int(status.split()[-1])
+    return 0

riff_kg_kit-0.7.0/src/riff_kg/config.py

@@ -0,0 +1,39 @@
+"""Runtime configuration: chunking, embeddings, closed-world type registry."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class KgConfig(BaseModel):
+    """Kit behavior for one Riff app deployment. Load from JSON/YAML or env."""
+
+    model_config = {"extra": "forbid"}
+
+    embedding_dimension: int = Field(default=768, ge=32, le=4096)
+    chunk_max_chars: int = Field(default=8000, ge=500)
+    chunk_overlap_chars: int = Field(default=400, ge=0)
+    chunk_if_longer_than_chars: int = Field(
+        default=12000,
+        ge=1000,
+        description="Below this size, keep a single segment (still stored as segment index 0).",
+    )
+    entity_types: tuple[str, ...] = Field(
+        default=("Entity",),
+        description="Allowed entity type labels at commit validation.",
+    )
+    relation_types: tuple[str, ...] = Field(
+        default=("related_to",),
+        description="Allowed relation predicates at commit validation.",
+    )
+    profile_uri: str | None = Field(
+        default=None,
+        description="Optional storage key or path to extraction JSON schema profile.",
+    )
+
+    def effective_chunking(self) -> dict[str, int]:
+        return {
+            "chunk_max_chars": self.chunk_max_chars,
+            "chunk_overlap_chars": self.chunk_overlap_chars,
+            "chunk_if_longer_than_chars": self.chunk_if_longer_than_chars,
+        }

riff_kg_kit-0.7.0/src/riff_kg/embedder.py

@@ -0,0 +1,13 @@
+"""Pluggable text embedding (Phase 2)."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Embedder(Protocol):
+    """Embed segment bodies; each vector length must match `KgConfig.embedding_dimension`."""
+
+    async def embed_texts(self, texts: list[str]) -> list[list[float]]:
+        ...