graphsearch-rag 0.2.1__tar.gz

graphsearch_rag-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GraphSearch contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

graphsearch_rag-0.2.1/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: graphsearch-rag
+Version: 0.2.1
+Summary: GraphSearch: a GraphQL API server for Retrieval-Augmented Generation (RAG) over your documents
+Author: GraphSearch contributors
+License: MIT
+Project-URL: Homepage, https://github.com/mohithgowdak/graphsearch
+Project-URL: Issues, https://github.com/mohithgowdak/graphsearch/issues
+Keywords: graphql,rag,semantic-search,llm,retrieval-augmented-generation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110
+Requires-Dist: strawberry-graphql[fastapi]>=0.220
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: numpy>=1.26
+Provides-Extra: local
+Requires-Dist: sentence-transformers>=2.7; extra == "local"
+Provides-Extra: openai
+Requires-Dist: openai>=1.30; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == "anthropic"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# GraphSearch
+
+[![CI](https://github.com/mohithgowdak/graphsearch/actions/workflows/ci.yml/badge.svg)](https://github.com/mohithgowdak/graphsearch/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+
+**A GraphQL API server for Retrieval-Augmented Generation (RAG) over your documents.**
+
+Upload documents through a GraphQL mutation, then ask questions through a GraphQL query.
+GraphSearch chunks and embeds your documents, retrieves the most relevant passages with
+vector similarity search, and feeds them to an LLM to generate a grounded answer — all
+behind a single, typed, introspectable GraphQL endpoint.
+
+```graphql
+query {
+  answer(question: "How do I reset my password?") {
+    text                                # cites sources as [1], [2], ...
+    sources { documentTitle text score }
+  }
+}
+```
+
+![GraphSearch demo: asking "How do I get my money back?" in GraphiQL and getting the returns policy with ranked sources](docs/demo.gif)
+
+*Semantic retrieval with the offline `local` backend: "How do I get my money back?" finds the returns policy — no shared keywords needed.*
+
+## Why GraphQL for RAG?
+
+- **One endpoint, typed schema** — clients ask for exactly the fields they need
+  (answer text, source chunks, scores) instead of juggling REST routes.
+- **Introspection & tooling for free** — GraphiQL, codegen'd TypeScript clients,
+  and schema docs come with the ecosystem.
+- **Composable** — `answer`, `search`, and document management live in one schema
+  and can be combined in a single request.
+
+## Quickstart
+
+### Install
+
+```bash
+pip install graphsearch-rag        # from PyPI (imports as `graphsearch`)
+# or run the prebuilt image:
+docker run -p 8000:8000 ghcr.io/mohithgowdak/graphsearch:latest
+# or from source:
+git clone https://github.com/mohithgowdak/graphsearch && cd graphsearch
+pip install -e ".[dev]"
+```
+
+### Run locally (no API keys needed)
+
+The default configuration is fully offline: a hashing-trick embedder plus an
+extractive answer mode. It exercises the entire pipeline and is perfect for
+kicking the tires, tests, and CI.
+
+```bash
+# Ingest some documents (bundled examples shown; any .md/.txt works)
+graphsearch-ingest data/example_docs
+
+# Start the server
+graphsearch
+```
+
+Open **http://localhost:8000/graphql** for the GraphiQL playground and try:
+
+```graphql
+query {
+  answer(question: "What is the return policy?") {
+    text
+    sources { text score }
+  }
+}
+```
+
+### Run with Docker
+
+```bash
+docker compose up --build
+```
+
+### Semantic search without any API key
+
+The `local` backend runs [sentence-transformers](https://www.sbert.net/)
+on your CPU — real semantic retrieval ("How do I get my money back?" finds
+the refund policy), still zero keys and zero external services:
+
+```bash
+pip install -e ".[local]"
+export GRAPHSEARCH_EMBEDDINGS=local   # $env:GRAPHSEARCH_EMBEDDINGS='local' on Windows
+graphsearch-ingest data/example_docs  # re-ingest: embeddings are created at ingest time
+graphsearch
+```
+
+The default model (`all-MiniLM-L6-v2`, ~80 MB) downloads on first use.
+
+### Generated answers with citations
+
+Point the LLM stage at OpenAI or Anthropic and answers become generated
+text that cites its sources — `[1]`, `[2]`, … map 1:1 to the `sources`
+list returned alongside the answer:
+
+```bash
+export GRAPHSEARCH_LLM=anthropic          # or openai
+export ANTHROPIC_API_KEY=sk-ant-...
+pip install -e ".[anthropic]"
+graphsearch
+```
+
+| Setting | Options | Default |
+|---|---|---|
+| `GRAPHSEARCH_EMBEDDINGS` | `hash` (offline), `local` (offline, semantic), `openai` | `hash` |
+| `GRAPHSEARCH_LLM` | `extractive` (offline), `openai`, `anthropic` | `extractive` |
+
+> **Note:** documents are embedded at ingest time, so re-ingest after switching
+> embedding backends.
+
+## GraphQL API
+
+### Queries
+
+```graphql
+answer(question: String!, topK: Int): Answer!      # RAG: retrieve + generate
+search(query: String!, topK: Int): [Chunk!]!       # raw semantic search
+documents(limit: Int = 20, offset: Int = 0): [Document!]!
+document(id: ID!): Document
+```
+
+### Mutations
+
+```graphql
+uploadDocument(content: String!, title: String, source: String): Document!
+deleteDocument(id: ID!): Boolean!
+```
+
+### Example: ingest and ask in one session
+
+```graphql
+mutation {
+  uploadDocument(
+    content: "Support hours are 9am-5pm PST, Monday through Friday."
+    title: "support-hours"
+  ) { id chunkCount }
+}
+
+query {
+  answer(question: "When is support available?") {
+    text
+    sources { documentId score }
+  }
+}
+```
+
+## Architecture
+
+```
+Client ── GraphQL (FastAPI + Strawberry) ── RagService
+                                              ├─ chunking       (paragraph-aware splitter)
+                                              ├─ Embedder       (hash | sentence-transformers | OpenAI)
+                                              ├─ VectorStore    (SQLite-backed, in-memory cosine search)
+                                              ├─ Database       (SQLite: documents, chunks, vectors)
+                                              └─ LLM            (extractive | OpenAI | Anthropic)
+```
+
+Every pipeline stage is an abstract interface (`Embedder`, `VectorStore`, `LLM`),
+so new backends are drop-in additions — see [Contributing](#contributing).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .          # lint
+pytest -v             # tests run fully offline
+```
+
+## Roadmap / good first issues
+
+- [ ] Additional vector store backends: Qdrant, Weaviate, Redis/Valkey, pgvector, FAISS
+- [ ] Additional embedding backends: Cohere, Voyage
+- [ ] Streaming answers via GraphQL subscriptions
+- [ ] Metadata filters on `search` (tags, date ranges) and hybrid keyword+vector search
+- [ ] Auth (API keys / JWT) and rate limiting
+- [ ] Query/embedding caching
+- [ ] Auto-generated TypeScript client (GraphQL Code Generator)
+- [ ] Evaluation harness with known Q&A pairs; Prometheus metrics
+- [ ] Advanced RAG: query rewriting, multi-hop retrieval, citation spans
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup,
+style, and PR guidelines, and the issue tracker for `good first issue` labels.
+
+## License
+
+[MIT](LICENSE)

graphsearch_rag-0.2.1/README.md

@@ -0,0 +1,193 @@
+# GraphSearch
+
+[![CI](https://github.com/mohithgowdak/graphsearch/actions/workflows/ci.yml/badge.svg)](https://github.com/mohithgowdak/graphsearch/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+
+**A GraphQL API server for Retrieval-Augmented Generation (RAG) over your documents.**
+
+Upload documents through a GraphQL mutation, then ask questions through a GraphQL query.
+GraphSearch chunks and embeds your documents, retrieves the most relevant passages with
+vector similarity search, and feeds them to an LLM to generate a grounded answer — all
+behind a single, typed, introspectable GraphQL endpoint.
+
+```graphql
+query {
+  answer(question: "How do I reset my password?") {
+    text                                # cites sources as [1], [2], ...
+    sources { documentTitle text score }
+  }
+}
+```
+
+![GraphSearch demo: asking "How do I get my money back?" in GraphiQL and getting the returns policy with ranked sources](docs/demo.gif)
+
+*Semantic retrieval with the offline `local` backend: "How do I get my money back?" finds the returns policy — no shared keywords needed.*
+
+## Why GraphQL for RAG?
+
+- **One endpoint, typed schema** — clients ask for exactly the fields they need
+  (answer text, source chunks, scores) instead of juggling REST routes.
+- **Introspection & tooling for free** — GraphiQL, codegen'd TypeScript clients,
+  and schema docs come with the ecosystem.
+- **Composable** — `answer`, `search`, and document management live in one schema
+  and can be combined in a single request.
+
+## Quickstart
+
+### Install
+
+```bash
+pip install graphsearch-rag        # from PyPI (imports as `graphsearch`)
+# or run the prebuilt image:
+docker run -p 8000:8000 ghcr.io/mohithgowdak/graphsearch:latest
+# or from source:
+git clone https://github.com/mohithgowdak/graphsearch && cd graphsearch
+pip install -e ".[dev]"
+```
+
+### Run locally (no API keys needed)
+
+The default configuration is fully offline: a hashing-trick embedder plus an
+extractive answer mode. It exercises the entire pipeline and is perfect for
+kicking the tires, tests, and CI.
+
+```bash
+# Ingest some documents (bundled examples shown; any .md/.txt works)
+graphsearch-ingest data/example_docs
+
+# Start the server
+graphsearch
+```
+
+Open **http://localhost:8000/graphql** for the GraphiQL playground and try:
+
+```graphql
+query {
+  answer(question: "What is the return policy?") {
+    text
+    sources { text score }
+  }
+}
+```
+
+### Run with Docker
+
+```bash
+docker compose up --build
+```
+
+### Semantic search without any API key
+
+The `local` backend runs [sentence-transformers](https://www.sbert.net/)
+on your CPU — real semantic retrieval ("How do I get my money back?" finds
+the refund policy), still zero keys and zero external services:
+
+```bash
+pip install -e ".[local]"
+export GRAPHSEARCH_EMBEDDINGS=local   # $env:GRAPHSEARCH_EMBEDDINGS='local' on Windows
+graphsearch-ingest data/example_docs  # re-ingest: embeddings are created at ingest time
+graphsearch
+```
+
+The default model (`all-MiniLM-L6-v2`, ~80 MB) downloads on first use.
+
+### Generated answers with citations
+
+Point the LLM stage at OpenAI or Anthropic and answers become generated
+text that cites its sources — `[1]`, `[2]`, … map 1:1 to the `sources`
+list returned alongside the answer:
+
+```bash
+export GRAPHSEARCH_LLM=anthropic          # or openai
+export ANTHROPIC_API_KEY=sk-ant-...
+pip install -e ".[anthropic]"
+graphsearch
+```
+
+| Setting | Options | Default |
+|---|---|---|
+| `GRAPHSEARCH_EMBEDDINGS` | `hash` (offline), `local` (offline, semantic), `openai` | `hash` |
+| `GRAPHSEARCH_LLM` | `extractive` (offline), `openai`, `anthropic` | `extractive` |
+
+> **Note:** documents are embedded at ingest time, so re-ingest after switching
+> embedding backends.
+
+## GraphQL API
+
+### Queries
+
+```graphql
+answer(question: String!, topK: Int): Answer!      # RAG: retrieve + generate
+search(query: String!, topK: Int): [Chunk!]!       # raw semantic search
+documents(limit: Int = 20, offset: Int = 0): [Document!]!
+document(id: ID!): Document
+```
+
+### Mutations
+
+```graphql
+uploadDocument(content: String!, title: String, source: String): Document!
+deleteDocument(id: ID!): Boolean!
+```
+
+### Example: ingest and ask in one session
+
+```graphql
+mutation {
+  uploadDocument(
+    content: "Support hours are 9am-5pm PST, Monday through Friday."
+    title: "support-hours"
+  ) { id chunkCount }
+}
+
+query {
+  answer(question: "When is support available?") {
+    text
+    sources { documentId score }
+  }
+}
+```
+
+## Architecture
+
+```
+Client ── GraphQL (FastAPI + Strawberry) ── RagService
+                                              ├─ chunking       (paragraph-aware splitter)
+                                              ├─ Embedder       (hash | sentence-transformers | OpenAI)
+                                              ├─ VectorStore    (SQLite-backed, in-memory cosine search)
+                                              ├─ Database       (SQLite: documents, chunks, vectors)
+                                              └─ LLM            (extractive | OpenAI | Anthropic)
+```
+
+Every pipeline stage is an abstract interface (`Embedder`, `VectorStore`, `LLM`),
+so new backends are drop-in additions — see [Contributing](#contributing).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .          # lint
+pytest -v             # tests run fully offline
+```
+
+## Roadmap / good first issues
+
+- [ ] Additional vector store backends: Qdrant, Weaviate, Redis/Valkey, pgvector, FAISS
+- [ ] Additional embedding backends: Cohere, Voyage
+- [ ] Streaming answers via GraphQL subscriptions
+- [ ] Metadata filters on `search` (tags, date ranges) and hybrid keyword+vector search
+- [ ] Auth (API keys / JWT) and rate limiting
+- [ ] Query/embedding caching
+- [ ] Auto-generated TypeScript client (GraphQL Code Generator)
+- [ ] Evaluation harness with known Q&A pairs; Prometheus metrics
+- [ ] Advanced RAG: query rewriting, multi-hop retrieval, citation spans
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup,
+style, and PR guidelines, and the issue tracker for `good first issue` labels.
+
+## License
+
+[MIT](LICENSE)

graphsearch_rag-0.2.1/graphsearch/__init__.py

@@ -0,0 +1,3 @@
+"""GraphSearch: a GraphQL API for Retrieval-Augmented Generation over your documents."""
+
+__version__ = "0.2.1"

graphsearch_rag-0.2.1/graphsearch/chunking.py

@@ -0,0 +1,46 @@
+"""Split documents into overlapping chunks suitable for embedding."""
+
+from __future__ import annotations
+
+
+def chunk_text(text: str, chunk_size: int = 800, overlap: int = 100) -> list[str]:
+    """Split ``text`` into chunks of at most ``chunk_size`` characters.
+
+    Prefers paragraph boundaries, then falls back to a sliding window with
+    ``overlap`` characters of context carried between adjacent chunks.
+    """
+    if chunk_size <= 0:
+        raise ValueError("chunk_size must be positive")
+    if overlap >= chunk_size:
+        raise ValueError("overlap must be smaller than chunk_size")
+
+    text = text.strip()
+    if not text:
+        return []
+
+    paragraphs = [p.strip() for p in text.split("\n\n") if p.strip()]
+
+    chunks: list[str] = []
+    current = ""
+    for para in paragraphs:
+        candidate = f"{current}\n\n{para}" if current else para
+        if len(candidate) <= chunk_size:
+            current = candidate
+            continue
+        if current:
+            chunks.append(current)
+        if len(para) <= chunk_size:
+            current = para
+        else:
+            # Paragraph alone exceeds chunk_size: sliding window.
+            step = chunk_size - overlap
+            for start in range(0, len(para), step):
+                piece = para[start : start + chunk_size]
+                if len(piece) < overlap and chunks:
+                    # Tiny tail already covered by the previous window's overlap.
+                    break
+                chunks.append(piece)
+            current = ""
+    if current:
+        chunks.append(current)
+    return chunks

graphsearch_rag-0.2.1/graphsearch/config.py

@@ -0,0 +1,54 @@
+"""Application configuration, loaded from environment variables / .env file.
+
+All GraphSearch-specific settings use the ``GRAPHSEARCH_`` prefix
+(e.g. ``GRAPHSEARCH_LLM=openai``). Provider API keys use their
+conventional names: ``OPENAI_API_KEY`` and ``ANTHROPIC_API_KEY``.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="GRAPHSEARCH_", env_file=".env", extra="ignore"
+    )
+
+    # Storage
+    database_path: str = "graphsearch.db"
+
+    # Chunking
+    chunk_size: int = 800
+    chunk_overlap: int = 100
+
+    # Retrieval
+    default_top_k: int = 4
+
+    # Backends: which implementation to use for each pipeline stage.
+    #   embeddings: "hash" (offline, no key needed), "local" (sentence-transformers), or "openai"
+    #   llm: "extractive" (offline), "openai", or "anthropic"
+    embeddings: str = "hash"
+    llm: str = "extractive"
+
+    # Model names (only used when the matching backend is selected)
+    local_embedding_model: str = "sentence-transformers/all-MiniLM-L6-v2"
+    openai_embedding_model: str = "text-embedding-3-small"
+    openai_model: str = "gpt-4o-mini"
+    anthropic_model: str = "claude-sonnet-5"
+
+    # Provider keys (no prefix — conventional env var names)
+    openai_api_key: str = Field(default="", alias="OPENAI_API_KEY")
+    anthropic_api_key: str = Field(default="", alias="ANTHROPIC_API_KEY")
+
+    # Server
+    host: str = "0.0.0.0"
+    port: int = 8000
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

graphsearch_rag-0.2.1/graphsearch/db.py

@@ -0,0 +1,139 @@
+"""SQLite persistence for documents, chunks, and their embeddings.
+
+A single SQLite file stores everything, which keeps the default deployment
+zero-dependency. Embeddings are stored as float32 blobs on the ``chunks``
+table and searched in memory with numpy (see ``vectorstore.py``).
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import threading
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+import numpy as np
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS documents (
+    id TEXT PRIMARY KEY,
+    title TEXT,
+    source TEXT,
+    content TEXT NOT NULL,
+    created_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS chunks (
+    id TEXT PRIMARY KEY,
+    document_id TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    idx INTEGER NOT NULL,
+    text TEXT NOT NULL,
+    embedding BLOB NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_chunks_document ON chunks(document_id);
+"""
+
+
+@dataclass
+class DocumentRecord:
+    id: str
+    title: str | None
+    source: str | None
+    content: str
+    created_at: str
+    chunk_count: int
+
+
+@dataclass
+class ChunkRecord:
+    id: str
+    document_id: str
+    idx: int
+    text: str
+    document_title: str | None = None
+
+
+class Database:
+    """Thread-safe wrapper around a SQLite connection."""
+
+    def __init__(self, path: str) -> None:
+        self._conn = sqlite3.connect(path, check_same_thread=False)
+        self._conn.execute("PRAGMA foreign_keys = ON")
+        self._conn.executescript(_SCHEMA)
+        self._lock = threading.Lock()
+
+    def close(self) -> None:
+        self._conn.close()
+
+    # -- documents ---------------------------------------------------------
+
+    def insert_document(
+        self,
+        content: str,
+        title: str | None,
+        source: str | None,
+        chunks: list[str],
+        embeddings: np.ndarray,
+    ) -> DocumentRecord:
+        if len(chunks) != len(embeddings):
+            raise ValueError("chunks and embeddings must have the same length")
+        doc_id = uuid.uuid4().hex
+        created_at = datetime.now(timezone.utc).isoformat()
+        with self._lock, self._conn:
+            self._conn.execute(
+                "INSERT INTO documents (id, title, source, content, created_at)"
+                " VALUES (?, ?, ?, ?, ?)",
+                (doc_id, title, source, content, created_at),
+            )
+            self._conn.executemany(
+                "INSERT INTO chunks (id, document_id, idx, text, embedding)"
+                " VALUES (?, ?, ?, ?, ?)",
+                [
+                    (
+                        uuid.uuid4().hex,
+                        doc_id,
+                        i,
+                        chunk,
+                        np.asarray(emb, dtype=np.float32).tobytes(),
+                    )
+                    for i, (chunk, emb) in enumerate(zip(chunks, embeddings, strict=True))
+                ],
+            )
+        return DocumentRecord(doc_id, title, source, content, created_at, len(chunks))
+
+    def get_document(self, doc_id: str) -> DocumentRecord | None:
+        row = self._conn.execute(
+            "SELECT d.id, d.title, d.source, d.content, d.created_at,"
+            " (SELECT COUNT(*) FROM chunks c WHERE c.document_id = d.id)"
+            " FROM documents d WHERE d.id = ?",
+            (doc_id,),
+        ).fetchone()
+        return DocumentRecord(*row) if row else None
+
+    def list_documents(self, limit: int = 20, offset: int = 0) -> list[DocumentRecord]:
+        rows = self._conn.execute(
+            "SELECT d.id, d.title, d.source, d.content, d.created_at,"
+            " (SELECT COUNT(*) FROM chunks c WHERE c.document_id = d.id)"
+            " FROM documents d ORDER BY d.created_at DESC LIMIT ? OFFSET ?",
+            (limit, offset),
+        ).fetchall()
+        return [DocumentRecord(*row) for row in rows]
+
+    def delete_document(self, doc_id: str) -> bool:
+        with self._lock, self._conn:
+            cursor = self._conn.execute("DELETE FROM documents WHERE id = ?", (doc_id,))
+        return cursor.rowcount > 0
+
+    # -- chunks / embeddings -------------------------------------------------
+
+    def all_embeddings(self) -> tuple[list[ChunkRecord], np.ndarray]:
+        """Return every chunk with its embedding matrix (rows align with chunks)."""
+        rows = self._conn.execute(
+            "SELECT c.id, c.document_id, c.idx, c.text, d.title, c.embedding"
+            " FROM chunks c JOIN documents d ON d.id = c.document_id"
+        ).fetchall()
+        if not rows:
+            return [], np.empty((0, 0), dtype=np.float32)
+        records = [ChunkRecord(r[0], r[1], r[2], r[3], r[4]) for r in rows]
+        matrix = np.vstack([np.frombuffer(r[5], dtype=np.float32) for r in rows])
+        return records, matrix