graphsearch-rag 0.2.1__py3-none-any.whl

graphsearch/__init__.py

@@ -0,0 +1,3 @@
+"""GraphSearch: a GraphQL API for Retrieval-Augmented Generation over your documents."""
+
+__version__ = "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/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/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

graphsearch/embeddings.py

@@ -0,0 +1,122 @@
+"""Embedding backends.
+
+Two implementations ship out of the box:
+
+- ``HashEmbedder`` — deterministic character n-gram hashing. No API key or
+  network needed, so the demo, tests, and CI all run offline. Retrieval
+  quality is lexical rather than semantic, but it exercises the exact same
+  pipeline.
+- ``LocalEmbedder`` — real semantic embeddings computed locally with
+  sentence-transformers. No API key, runs on CPU; the model (~80 MB for the
+  default all-MiniLM-L6-v2) is downloaded on first use.
+- ``OpenAIEmbedder`` — semantic embeddings via the OpenAI API.
+
+To add a new backend (e.g. Cohere, Voyage), subclass ``Embedder`` and
+register it in ``create_embedder``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from abc import ABC, abstractmethod
+
+import numpy as np
+
+from .config import Settings
+
+
+class Embedder(ABC):
+    """Turns text into a fixed-size vector. Vectors must be L2-normalized."""
+
+    dimension: int
+
+    @abstractmethod
+    def embed(self, texts: list[str]) -> np.ndarray:
+        """Return an array of shape ``(len(texts), self.dimension)``."""
+
+
+class HashEmbedder(Embedder):
+    """Offline embedding via hashed character n-grams (a 'hashing trick' TF vector)."""
+
+    def __init__(self, dimension: int = 512, ngram: int = 3) -> None:
+        self.dimension = dimension
+        self.ngram = ngram
+
+    def _embed_one(self, text: str) -> np.ndarray:
+        vec = np.zeros(self.dimension, dtype=np.float32)
+        normalized = " ".join(text.lower().split())
+        for i in range(max(len(normalized) - self.ngram + 1, 1)):
+            gram = normalized[i : i + self.ngram]
+            digest = hashlib.md5(gram.encode("utf-8")).digest()
+            bucket = int.from_bytes(digest[:4], "little") % self.dimension
+            vec[bucket] += 1.0
+        norm = np.linalg.norm(vec)
+        return vec / norm if norm > 0 else vec
+
+    def embed(self, texts: list[str]) -> np.ndarray:
+        if not texts:
+            return np.empty((0, self.dimension), dtype=np.float32)
+        return np.vstack([self._embed_one(t) for t in texts])
+
+
+class LocalEmbedder(Embedder):
+    """Semantic embeddings computed locally with sentence-transformers (no API key)."""
+
+    def __init__(self, model: str = "sentence-transformers/all-MiniLM-L6-v2") -> None:
+        try:
+            from sentence_transformers import SentenceTransformer
+        except ImportError as exc:  # pragma: no cover
+            raise RuntimeError(
+                "The 'sentence-transformers' package is required for "
+                "GRAPHSEARCH_EMBEDDINGS=local. "
+                "Install it with: pip install graphsearch-rag[local]"
+            ) from exc
+        self._model = SentenceTransformer(model)
+        # Renamed in newer sentence-transformers releases; support both.
+        get_dim = getattr(
+            self._model, "get_embedding_dimension", None
+        ) or self._model.get_sentence_embedding_dimension
+        self.dimension = get_dim()
+
+    def embed(self, texts: list[str]) -> np.ndarray:
+        if not texts:
+            return np.empty((0, self.dimension), dtype=np.float32)
+        matrix = self._model.encode(texts, normalize_embeddings=True, show_progress_bar=False)
+        return np.asarray(matrix, dtype=np.float32)
+
+
+class OpenAIEmbedder(Embedder):
+    """Semantic embeddings via the OpenAI embeddings API."""
+
+    def __init__(self, api_key: str, model: str = "text-embedding-3-small") -> None:
+        try:
+            from openai import OpenAI
+        except ImportError as exc:  # pragma: no cover
+            raise RuntimeError(
+                "The 'openai' package is required for GRAPHSEARCH_EMBEDDINGS=openai. "
+                "Install it with: pip install graphsearch-rag[openai]"
+            ) from exc
+        if not api_key:
+            raise RuntimeError("OPENAI_API_KEY must be set for GRAPHSEARCH_EMBEDDINGS=openai")
+        self._client = OpenAI(api_key=api_key)
+        self._model = model
+        self.dimension = 1536 if "small" in model or "ada" in model else 3072
+
+    def embed(self, texts: list[str]) -> np.ndarray:
+        if not texts:
+            return np.empty((0, self.dimension), dtype=np.float32)
+        response = self._client.embeddings.create(model=self._model, input=texts)
+        matrix = np.asarray([item.embedding for item in response.data], dtype=np.float32)
+        norms = np.linalg.norm(matrix, axis=1, keepdims=True)
+        norms[norms == 0] = 1.0
+        return matrix / norms
+
+
+def create_embedder(settings: Settings) -> Embedder:
+    if settings.embeddings == "hash":
+        return HashEmbedder()
+    if settings.embeddings == "local":
+        return LocalEmbedder(settings.local_embedding_model)
+    if settings.embeddings == "openai":
+        return OpenAIEmbedder(settings.openai_api_key, settings.openai_embedding_model)
+    raise ValueError(f"Unknown embeddings backend: {settings.embeddings!r}")

graphsearch/ingest.py

@@ -0,0 +1,52 @@
+"""CLI for bulk-ingesting documents from a directory.
+
+Usage:
+    graphsearch-ingest data/example_docs
+    python -m graphsearch.ingest data/example_docs
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .config import get_settings
+from .rag import RagService
+
+SUPPORTED_SUFFIXES = {".txt", ".md", ".markdown", ".rst"}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Ingest text/markdown files into GraphSearch")
+    parser.add_argument("path", type=Path, help="File or directory to ingest")
+    args = parser.parse_args(argv)
+
+    if not args.path.exists():
+        print(f"error: {args.path} does not exist", file=sys.stderr)
+        return 1
+
+    files = (
+        [args.path]
+        if args.path.is_file()
+        else sorted(
+            p for p in args.path.rglob("*") if p.suffix.lower() in SUPPORTED_SUFFIXES
+        )
+    )
+    if not files:
+        print(f"error: no ingestable files under {args.path}", file=sys.stderr)
+        return 1
+
+    service = RagService(get_settings())
+    try:
+        for path in files:
+            content = path.read_text(encoding="utf-8")
+            record = service.ingest(content, title=path.stem, source=str(path))
+            print(f"ingested {path} -> {record.id} ({record.chunk_count} chunks)")
+    finally:
+        service.close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

graphsearch/llm.py

@@ -0,0 +1,121 @@
+"""LLM backends for answer generation.
+
+Three implementations ship out of the box:
+
+- ``ExtractiveLLM`` — no API key needed. Returns the most relevant retrieved
+  passages verbatim. Useful for demos, tests, and CI.
+- ``OpenAILLM`` — chat completion via the OpenAI API.
+- ``AnthropicLLM`` — messages via the Anthropic API (Claude).
+
+Retrieved passages are numbered in the prompt and the model is instructed to
+cite them as ``[1]``, ``[2]``, … — the numbers correspond 1:1 to the order of
+``Answer.sources`` returned by the GraphQL API.
+
+To add another provider, subclass ``LLM`` and register it in ``create_llm``.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from .config import Settings
+from .vectorstore import SearchHit
+
+PROMPT_TEMPLATE = """\
+Answer the question using ONLY the numbered context passages below. If the
+context does not contain the answer, say you don't know rather than guessing.
+Cite the passages you used with bracketed numbers, e.g. [1] or [2][3].
+
+Context:
+{context}
+
+Question: {question}
+
+Answer:"""
+
+
+def format_passage(number: int, hit: SearchHit) -> str:
+    title = f" ({hit.document_title})" if hit.document_title else ""
+    return f"[{number}]{title}\n{hit.text}"
+
+
+def build_prompt(question: str, sources: list[SearchHit]) -> str:
+    if sources:
+        context = "\n\n".join(format_passage(i + 1, hit) for i, hit in enumerate(sources))
+    else:
+        context = "(no context found)"
+    return PROMPT_TEMPLATE.format(context=context, question=question)
+
+
+class LLM(ABC):
+    @abstractmethod
+    def generate(self, question: str, sources: list[SearchHit]) -> str:
+        """Produce an answer to ``question`` grounded in the retrieved ``sources``."""
+
+
+class ExtractiveLLM(LLM):
+    """Key-free fallback: returns the top retrieved passages as the answer."""
+
+    def generate(self, question: str, sources: list[SearchHit]) -> str:
+        if not sources:
+            return "No relevant documents found for this question."
+        passages = "\n\n".join(format_passage(i + 1, hit) for i, hit in enumerate(sources[:2]))
+        return (
+            "[extractive mode — configure GRAPHSEARCH_LLM=openai or anthropic "
+            "for generated answers]\n\nMost relevant passages:\n\n" + passages
+        )
+
+
+class OpenAILLM(LLM):
+    def __init__(self, api_key: str, model: str = "gpt-4o-mini") -> None:
+        try:
+            from openai import OpenAI
+        except ImportError as exc:  # pragma: no cover
+            raise RuntimeError(
+                "The 'openai' package is required for GRAPHSEARCH_LLM=openai. "
+                "Install it with: pip install graphsearch-rag[openai]"
+            ) from exc
+        if not api_key:
+            raise RuntimeError("OPENAI_API_KEY must be set for GRAPHSEARCH_LLM=openai")
+        self._client = OpenAI(api_key=api_key)
+        self._model = model
+
+    def generate(self, question: str, sources: list[SearchHit]) -> str:
+        response = self._client.chat.completions.create(
+            model=self._model,
+            messages=[{"role": "user", "content": build_prompt(question, sources)}],
+        )
+        return response.choices[0].message.content or ""
+
+
+class AnthropicLLM(LLM):
+    def __init__(self, api_key: str, model: str = "claude-sonnet-5") -> None:
+        try:
+            from anthropic import Anthropic
+        except ImportError as exc:  # pragma: no cover
+            raise RuntimeError(
+                "The 'anthropic' package is required for GRAPHSEARCH_LLM=anthropic. "
+                "Install it with: pip install graphsearch-rag[anthropic]"
+            ) from exc
+        if not api_key:
+            raise RuntimeError("ANTHROPIC_API_KEY must be set for GRAPHSEARCH_LLM=anthropic")
+        self._client = Anthropic(api_key=api_key)
+        self._model = model
+
+    def generate(self, question: str, sources: list[SearchHit]) -> str:
+        response = self._client.messages.create(
+            model=self._model,
+            max_tokens=1024,
+            messages=[{"role": "user", "content": build_prompt(question, sources)}],
+        )
+        return "".join(block.text for block in response.content if block.type == "text")
+
+
+def create_llm(settings: Settings) -> LLM:
+    if settings.llm == "extractive":
+        return ExtractiveLLM()
+    if settings.llm == "openai":
+        return OpenAILLM(settings.openai_api_key, settings.openai_model)
+    if settings.llm == "anthropic":
+        return AnthropicLLM(settings.anthropic_api_key, settings.anthropic_model)
+    raise ValueError(f"Unknown LLM backend: {settings.llm!r}")

graphsearch/main.py

@@ -0,0 +1,49 @@
+"""FastAPI application entrypoint. GraphQL is served at /graphql with GraphiQL enabled."""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from strawberry.fastapi import GraphQLRouter
+
+from . import __version__
+from .config import Settings, get_settings
+from .rag import RagService
+from .schema import schema
+
+
+def create_app(settings: Settings | None = None, rag_service: RagService | None = None) -> FastAPI:
+    settings = settings or get_settings()
+    service = rag_service or RagService(settings)
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        yield
+        service.close()
+
+    app = FastAPI(title="GraphSearch", version=__version__, lifespan=lifespan)
+
+    async def get_context() -> dict:
+        return {"rag_service": service}
+
+    graphql_router: GraphQLRouter = GraphQLRouter(schema, context_getter=get_context)
+    app.include_router(graphql_router, prefix="/graphql")
+
+    @app.get("/health")
+    async def health() -> dict:
+        return {"status": "ok", "version": __version__}
+
+    return app
+
+
+def run() -> None:
+    """Console entrypoint: ``graphsearch``."""
+    import uvicorn
+
+    settings = get_settings()
+    uvicorn.run(create_app(settings), host=settings.host, port=settings.port)
+
+
+if __name__ == "__main__":
+    run()

graphsearch/rag.py

@@ -0,0 +1,74 @@
+"""The RAG pipeline: ingest documents, retrieve relevant chunks, generate answers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .chunking import chunk_text
+from .config import Settings
+from .db import Database, DocumentRecord
+from .embeddings import Embedder, create_embedder
+from .llm import LLM, create_llm
+from .vectorstore import SearchHit, SqliteVectorStore, VectorStore
+
+
+@dataclass
+class AnswerResult:
+    text: str
+    sources: list[SearchHit]
+
+
+class RagService:
+    """Ties together the database, embedder, vector store, and LLM."""
+
+    def __init__(
+        self,
+        settings: Settings,
+        db: Database | None = None,
+        embedder: Embedder | None = None,
+        vector_store: VectorStore | None = None,
+        llm: LLM | None = None,
+    ) -> None:
+        self.settings = settings
+        self.db = db or Database(settings.database_path)
+        self.embedder = embedder or create_embedder(settings)
+        self.vector_store = vector_store or SqliteVectorStore(self.db)
+        self.llm = llm or create_llm(settings)
+
+    def ingest(
+        self, content: str, title: str | None = None, source: str | None = None
+    ) -> DocumentRecord:
+        """Chunk, embed, and store a document."""
+        chunks = chunk_text(content, self.settings.chunk_size, self.settings.chunk_overlap)
+        if not chunks:
+            raise ValueError("Document content is empty")
+        embeddings = self.embedder.embed(chunks)
+        record = self.db.insert_document(content, title, source, chunks, embeddings)
+        self.vector_store.invalidate()
+        return record
+
+    def delete_document(self, doc_id: str) -> bool:
+        """Delete a document and drop its chunks from the search index."""
+        deleted = self.db.delete_document(doc_id)
+        if deleted:
+            self.vector_store.invalidate()
+        return deleted
+
+    def search(self, query: str, top_k: int | None = None) -> list[SearchHit]:
+        """Embed the query and return the most similar chunks."""
+        top_k = top_k or self.settings.default_top_k
+        query_vector = self.embedder.embed([query])[0]
+        return self.vector_store.search(query_vector, top_k)
+
+    def answer(self, question: str, top_k: int | None = None) -> AnswerResult:
+        """Retrieve relevant chunks and generate a grounded answer.
+
+        Citation numbers in the answer text ([1], [2], …) refer to positions
+        in ``sources`` (1-indexed).
+        """
+        hits = self.search(question, top_k)
+        text = self.llm.generate(question, hits)
+        return AnswerResult(text=text, sources=hits)
+
+    def close(self) -> None:
+        self.db.close()

graphsearch/schema.py

@@ -0,0 +1,114 @@
+"""Strawberry GraphQL schema: types, queries, and mutations.
+
+Field names are camelCased by Strawberry, so the public API matches the
+project spec: ``answer(question:)``, ``uploadDocument(content:)``, etc.
+Resolvers delegate to ``RagService`` via ``asyncio.to_thread`` so blocking
+I/O (SQLite, provider APIs) never stalls the event loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import strawberry
+from strawberry.types import Info
+
+from .db import DocumentRecord
+from .rag import RagService
+from .vectorstore import SearchHit
+
+
+@strawberry.type
+class Document:
+    id: strawberry.ID
+    title: str | None
+    source: str | None
+    content: str
+    created_at: str
+    chunk_count: int
+
+    @staticmethod
+    def from_record(record: DocumentRecord) -> Document:
+        return Document(
+            id=strawberry.ID(record.id),
+            title=record.title,
+            source=record.source,
+            content=record.content,
+            created_at=record.created_at,
+            chunk_count=record.chunk_count,
+        )
+
+
+@strawberry.type
+class Chunk:
+    id: strawberry.ID
+    document_id: strawberry.ID
+    document_title: str | None
+    text: str
+    score: float
+
+    @staticmethod
+    def from_hit(hit: SearchHit) -> Chunk:
+        return Chunk(
+            id=strawberry.ID(hit.chunk_id),
+            document_id=strawberry.ID(hit.document_id),
+            document_title=hit.document_title,
+            text=hit.text,
+            score=hit.score,
+        )
+
+
+@strawberry.type
+class Answer:
+    text: str
+    sources: list[Chunk] = strawberry.field(
+        description="Retrieved passages; citations like [1] in `text` are 1-indexed into this list."
+    )
+
+
+def _service(info: Info) -> RagService:
+    return info.context["rag_service"]
+
+
+@strawberry.type
+class Query:
+    @strawberry.field(description="Ask a question and get an answer grounded in your documents.")
+    async def answer(self, info: Info, question: str, top_k: int | None = None) -> Answer:
+        result = await asyncio.to_thread(_service(info).answer, question, top_k)
+        return Answer(text=result.text, sources=[Chunk.from_hit(h) for h in result.sources])
+
+    @strawberry.field(description="Semantic search: return the most relevant chunks for a query.")
+    async def search(self, info: Info, query: str, top_k: int | None = None) -> list[Chunk]:
+        hits = await asyncio.to_thread(_service(info).search, query, top_k)
+        return [Chunk.from_hit(h) for h in hits]
+
+    @strawberry.field(description="List ingested documents, newest first.")
+    async def documents(self, info: Info, limit: int = 20, offset: int = 0) -> list[Document]:
+        records = await asyncio.to_thread(_service(info).db.list_documents, limit, offset)
+        return [Document.from_record(r) for r in records]
+
+    @strawberry.field(description="Fetch a single document by ID.")
+    async def document(self, info: Info, id: strawberry.ID) -> Document | None:
+        record = await asyncio.to_thread(_service(info).db.get_document, str(id))
+        return Document.from_record(record) if record else None
+
+
+@strawberry.type
+class Mutation:
+    @strawberry.mutation(description="Ingest a document: it is chunked, embedded, and indexed.")
+    async def upload_document(
+        self,
+        info: Info,
+        content: str,
+        title: str | None = None,
+        source: str | None = None,
+    ) -> Document:
+        record = await asyncio.to_thread(_service(info).ingest, content, title, source)
+        return Document.from_record(record)
+
+    @strawberry.mutation(description="Delete a document and its indexed chunks.")
+    async def delete_document(self, info: Info, id: strawberry.ID) -> bool:
+        return await asyncio.to_thread(_service(info).delete_document, str(id))
+
+
+schema = strawberry.Schema(query=Query, mutation=Mutation)

graphsearch/vectorstore.py

@@ -0,0 +1,84 @@
+"""Vector search over stored chunk embeddings.
+
+The default store keeps an in-memory copy of the embedding matrix (loaded
+from SQLite on first search, refreshed after writes), which is plenty for
+tens of thousands of chunks with zero extra infrastructure. The
+``VectorStore`` interface exists so alternative backends (Qdrant, Weaviate,
+Redis, pgvector, FAISS) can be added — see the "good first issue" list in
+the README.
+"""
+
+from __future__ import annotations
+
+import threading
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+import numpy as np
+
+from .db import ChunkRecord, Database
+
+
+@dataclass
+class SearchHit:
+    chunk_id: str
+    document_id: str
+    document_title: str | None
+    text: str
+    score: float
+
+
+class VectorStore(ABC):
+    @abstractmethod
+    def search(self, query_vector: np.ndarray, top_k: int) -> list[SearchHit]:
+        """Return the ``top_k`` most similar chunks by cosine similarity."""
+
+    def invalidate(self) -> None:  # noqa: B027 — intentional no-op default
+        """Called after documents are added or removed. Override if the store caches."""
+
+
+class SqliteVectorStore(VectorStore):
+    """Cosine search over embeddings stored in the SQLite database.
+
+    The chunk list and embedding matrix are cached in memory so queries are a
+    single numpy matrix-vector product; ``invalidate()`` (called by
+    ``RagService`` after ingest/delete) forces a reload on the next search.
+    Embeddings are L2-normalized at write time, so cosine similarity reduces
+    to a dot product.
+    """
+
+    def __init__(self, db: Database) -> None:
+        self._db = db
+        self._lock = threading.Lock()
+        self._chunks: list[ChunkRecord] | None = None
+        self._matrix: np.ndarray | None = None
+
+    def invalidate(self) -> None:
+        with self._lock:
+            self._chunks = None
+            self._matrix = None
+
+    def _load(self) -> tuple[list[ChunkRecord], np.ndarray]:
+        with self._lock:
+            if self._chunks is None or self._matrix is None:
+                self._chunks, self._matrix = self._db.all_embeddings()
+            return self._chunks, self._matrix
+
+    def search(self, query_vector: np.ndarray, top_k: int) -> list[SearchHit]:
+        chunks, matrix = self._load()
+        if not chunks:
+            return []
+        query = np.asarray(query_vector, dtype=np.float32).reshape(-1)
+        scores = matrix @ query
+        top_k = min(top_k, len(chunks))
+        top_indices = np.argsort(scores)[::-1][:top_k]
+        return [
+            SearchHit(
+                chunk_id=chunks[i].id,
+                document_id=chunks[i].document_id,
+                document_title=chunks[i].document_title,
+                text=chunks[i].text,
+                score=float(scores[i]),
+            )
+            for i in top_indices
+        ]

graphsearch_rag-0.2.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,17 @@
+graphsearch/__init__.py,sha256=g8QeIYITtHF4RhtHnpe0BjYe2TD2W9pUUF1SdeqpnYo,112
+graphsearch/chunking.py,sha256=OSD6mHrjVFGBsnIntc6vvlgu0r5vsT2ZJdzIYO2D6UY,1592
+graphsearch/config.py,sha256=5MxJpSbQJYLoyh--KuzuuHh3f6p7ss0-2O-CSmQGgjg,1659
+graphsearch/db.py,sha256=7xbb8H7Ryv4iAaztrXLierVSX4agl8DeIDZH02nLHHo,4742
+graphsearch/embeddings.py,sha256=VPpChmTE5cvcGpUKMC5Z3juzQGomEuuLsZLJ19cTtYc,4890
+graphsearch/ingest.py,sha256=9INaajUjjC_U5zmeQOC66l6YXTAyUf26vivBhbPeH8g,1454
+graphsearch/llm.py,sha256=UtW5qCK_CiW4hFoRqGr57JBGEHaa136WDesmcHfCpe4,4589
+graphsearch/main.py,sha256=fDABDF2lOq6uRMSSRC_paTtZecrPyQy5p5w3rD6sq2U,1333
+graphsearch/rag.py,sha256=HvlgEZlUAw81drY2gBb_BDz2edL2fRJpymfBxFY_xCY,2678
+graphsearch/schema.py,sha256=RkwOTFnyxd9R62sAnMCvVrsSDRWeyXcCrbIlwP4Js5E,3834
+graphsearch/vectorstore.py,sha256=Wa-Wz277xYjUmdUvoPpzcSVd249ooXWJtKrK2D5OPng,2829
+graphsearch_rag-0.2.1.dist-info/licenses/LICENSE,sha256=QOyvrKmYIhmfNPbKczjmkXyguf7mgl4TWPCZSt5DbHI,1081
+graphsearch_rag-0.2.1.dist-info/METADATA,sha256=9TxAUw6BzyU-krRSouXZhDKjaMPF-LxMWp1gqrVdo4E,7656
+graphsearch_rag-0.2.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+graphsearch_rag-0.2.1.dist-info/entry_points.txt,sha256=OT1M6yCLQgY93F4UVv4CbQeK6PVQhAuaq8fE2VHIqj0,98
+graphsearch_rag-0.2.1.dist-info/top_level.txt,sha256=m758MWbbz5dv3xwVp9_ge3ppA-JF3my8Xb4O3I4DRbc,12
+graphsearch_rag-0.2.1.dist-info/RECORD,,

graphsearch_rag-0.2.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

graphsearch_rag-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+graphsearch = graphsearch.main:run
+graphsearch-ingest = graphsearch.ingest:main

graphsearch_rag-0.2.1.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+graphsearch