raggity 0.1.0__py3-none-any.whl

raggity/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

raggity/answerer.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+
+from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage
+
+from .models import Answer, Chunk
+from .prompts import (SYSTEM_PROMPT, ABSTAIN_MESSAGE, build_user_prompt,
+                      verify_citations)
+from .registry import register
+
+
+class Answerer(ABC):
+    @abstractmethod
+    async def answer(self, question: str, chunks: list[Chunk]) -> Answer: ...
+
+
+class ClaudeAgentAnswerer(Answerer):
+    def __init__(self, model: str = "claude-opus-4-8", auth: str = "auto") -> None:
+        self.model = model
+        self.auth = auth
+
+    def _options(self) -> ClaudeAgentOptions:
+        if self.auth == "subscription":
+            # Subscription-primary: pass os.environ minus ANTHROPIC_API_KEY so
+            # the Agent SDK cannot fall back to a per-token API key and must use
+            # the `claude login` subscription session.
+            env = {k: v for k, v in os.environ.items() if k != "ANTHROPIC_API_KEY"}
+            return ClaudeAgentOptions(
+                system_prompt=SYSTEM_PROMPT,
+                model=self.model,
+                allowed_tools=[],
+                permission_mode="dontAsk",
+                env=env,
+            )
+        if self.auth == "api_key":
+            # api_key mode: the SDK reads ANTHROPIC_API_KEY from the environment.
+            if not os.environ.get("ANTHROPIC_API_KEY"):
+                raise RuntimeError(
+                    "auth='api_key' but ANTHROPIC_API_KEY is not set. "
+                    "Set the key, or use auth='subscription' after `claude login`."
+                )
+            return ClaudeAgentOptions(
+                system_prompt=SYSTEM_PROMPT,
+                model=self.model,
+                allowed_tools=[],
+                permission_mode="dontAsk",
+            )
+        # auth == "auto": leave env untouched — SDK resolves key-first, then
+        # subscription session if no key is present.
+        return ClaudeAgentOptions(
+            system_prompt=SYSTEM_PROMPT,
+            model=self.model,
+            allowed_tools=[],
+            permission_mode="dontAsk",
+        )
+
+    async def answer_stream(self, question: str, chunks: list[Chunk]):
+        """Yield text-delta str items as they arrive, then a final Answer."""
+        if not chunks:
+            yield ABSTAIN_MESSAGE
+            yield Answer(text=ABSTAIN_MESSAGE, citations=[], abstained=True)
+            return
+        prompt = build_user_prompt(question, chunks)
+        opts = self._options()
+        try:
+            opts.include_partial_messages = True
+        except Exception:
+            pass
+        parts: list[str] = []
+        async for message in query(prompt=prompt, options=opts):
+            if isinstance(message, AssistantMessage):
+                for block in message.content:
+                    text = getattr(block, "text", None)
+                    if text:
+                        parts.append(text)
+                        yield text
+        text = "".join(parts).strip()
+        abstained = text == ABSTAIN_MESSAGE
+        citations = [] if abstained else verify_citations(text, chunks)
+        yield Answer(text=text, citations=citations, abstained=abstained)
+
+    async def answer(self, question: str, chunks: list[Chunk]) -> Answer:
+        if not chunks:
+            return Answer(text=ABSTAIN_MESSAGE, citations=[], abstained=True)
+        prompt = build_user_prompt(question, chunks)
+        parts: list[str] = []
+        async for message in query(prompt=prompt, options=self._options()):
+            if isinstance(message, AssistantMessage):
+                for block in message.content:
+                    text = getattr(block, "text", None)
+                    if text:
+                        parts.append(text)
+        text = "".join(parts).strip()
+        abstained = text.strip() == ABSTAIN_MESSAGE
+        citations = [] if abstained else verify_citations(text, chunks)
+        return Answer(text=text, citations=citations, abstained=abstained)
+
+
+register("answerer", "claude", "raggity.answerer:ClaudeAgentAnswerer")

raggity/cache.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+import hashlib
+import json
+import logging
+import os
+from pathlib import Path
+
+from .models import Answer, Citation
+
+log = logging.getLogger("raggity.cache")
+
+
+def cache_key(question: str, chunk_ids: list[str], model: str) -> str:
+    payload = question + "|" + "|".join(sorted(chunk_ids)) + "|" + model
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def load(path: str) -> dict:
+    if not os.path.isfile(path):
+        return {}
+    try:
+        with open(path, encoding="utf-8") as fh:
+            return json.load(fh)
+    except Exception as exc:
+        log.warning("ignoring unreadable answer cache %s: %s", path, exc)
+        return {}
+
+
+def save(path: str, data: dict) -> None:
+    Path(path).parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(data, fh)
+
+
+def answer_to_dict(a: Answer) -> dict:
+    return {"text": a.text, "abstained": a.abstained,
+            "citations": [{"chunk_id": c.chunk_id, "source_path": c.source_path,
+                           "title": c.title, "supported": c.supported}
+                          for c in a.citations]}
+
+
+def answer_from_dict(d: dict) -> Answer:
+    return Answer(text=d["text"],
+                  citations=[Citation(c["chunk_id"], c["source_path"], c["title"], c["supported"])
+                             for c in d.get("citations", [])],
+                  abstained=d.get("abstained", False))

raggity/cached_embedder.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+from pathlib import Path
+
+from .embedder import Embedder
+
+log = logging.getLogger("raggity.cached_embedder")
+
+
+class CachedEmbedder(Embedder):
+    def __init__(self, inner: Embedder, cache_path: str) -> None:
+        self._inner = inner
+        self._path = cache_path
+        self._cache = self._load()
+
+    def _load(self) -> dict:
+        if not os.path.isfile(self._path):
+            return {}
+        try:
+            with open(self._path, encoding="utf-8") as fh:
+                return json.load(fh)
+        except Exception as exc:
+            log.warning("ignoring unreadable embed cache %s: %s", self._path, exc)
+            return {}
+
+    def _save(self) -> None:
+        Path(self._path).parent.mkdir(parents=True, exist_ok=True)
+        with open(self._path, "w", encoding="utf-8") as fh:
+            json.dump(self._cache, fh)
+
+    @property
+    def dim(self) -> int:
+        return self._inner.dim
+
+    def embed_query(self, text: str) -> list[float]:
+        return self._inner.embed_query(text)
+
+    def embed_documents(self, texts: list[str]) -> list[list[float]]:
+        keys = [hashlib.sha256(t.encode("utf-8")).hexdigest() for t in texts]
+        missing = [i for i, k in enumerate(keys) if k not in self._cache]
+        if missing:
+            vecs = self._inner.embed_documents([texts[i] for i in missing])
+            for i, v in zip(missing, vecs):
+                self._cache[keys[i]] = v
+            self._save()
+        return [self._cache[k] for k in keys]

raggity/chunker.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import hashlib
+import re
+
+from .models import Chunk, Document
+
+_HEADER_RE = re.compile(r"^(#{1,6})\s+(.*)$")
+
+
+def estimate_tokens(text: str) -> int:
+    # Dependency-free heuristic; tiktoken is wrong for Claude and unneeded here.
+    return max(1, len(text) // 4)
+
+
+def _split_into_sections(text: str) -> list[tuple[str, str]]:
+    """Return (heading_path, section_body) preserving markdown header hierarchy."""
+    sections: list[tuple[str, str]] = []
+    stack: list[str] = []
+    buf: list[str] = []
+
+    def flush():
+        body = "\n".join(buf).strip()
+        if body:
+            sections.append((" > ".join(stack), body))
+
+    for line in text.splitlines():
+        m = _HEADER_RE.match(line)
+        if m:
+            flush()
+            buf = []
+            level = len(m.group(1))
+            title = m.group(2).strip()
+            stack = stack[: level - 1]
+            while len(stack) < level - 1:
+                stack.append("")
+            stack.append(title)
+        else:
+            buf.append(line)
+    flush()
+    if not sections:
+        sections.append(("", text.strip()))
+    return sections
+
+
+def _split_body(body: str, target_tokens: int, overlap_tokens: int) -> list[str]:
+    paras = [p.strip() for p in re.split(r"\n\s*\n", body) if p.strip()]
+    pieces: list[str] = []
+    cur: list[str] = []
+    cur_tok = 0
+    for para in paras:
+        ptok = estimate_tokens(para)
+        if cur and cur_tok + ptok > target_tokens:
+            pieces.append("\n\n".join(cur))
+            # overlap: carry tail paragraphs until ~overlap_tokens
+            carry: list[str] = []
+            ctok = 0
+            for prev in reversed(cur):
+                carry.insert(0, prev)
+                ctok += estimate_tokens(prev)
+                if ctok >= overlap_tokens:
+                    break
+            cur = carry[:]
+            cur_tok = sum(estimate_tokens(x) for x in cur)
+        cur.append(para)
+        cur_tok += ptok
+    if cur:
+        pieces.append("\n\n".join(cur))
+    return pieces or [body]
+
+
+def _chunk_flat(doc: Document, target_tokens: int, overlap_tokens: int) -> list[Chunk]:
+    chunks: list[Chunk] = []
+    ordinal = 0
+    for heading_path, body in _split_into_sections(doc.text):
+        full_path = doc.title if not heading_path else f"{doc.title} > {heading_path}"
+        for piece in _split_body(body, target_tokens, overlap_tokens):
+            header = full_path
+            chunk_text = f"{header}\n\n{piece}" if header else piece
+            chunk_id = hashlib.sha256(
+                f"{doc.path}|{ordinal}|{piece}".encode("utf-8")
+            ).hexdigest()
+            chunks.append(
+                Chunk(
+                    text=chunk_text,
+                    source_path=doc.path,
+                    title=doc.title,
+                    heading_path=heading_path or doc.title,
+                    ordinal=ordinal,
+                    chunk_id=chunk_id,
+                )
+            )
+            ordinal += 1
+    return chunks
+
+
+def _chunk_parent(doc: Document, parent_tokens: int, child_tokens: int,
+                  overlap_tokens: int) -> list[Chunk]:
+    chunks: list[Chunk] = []
+    ordinal = 0
+    parent_index = 0
+    for heading_path, body in _split_into_sections(doc.text):
+        full_path = doc.title if not heading_path else f"{doc.title} > {heading_path}"
+        for parent_piece in _split_body(body, parent_tokens, overlap_tokens):
+            parent_text = f"{full_path}\n\n{parent_piece}" if full_path else parent_piece
+            parent_id = hashlib.sha256(
+                f"{doc.path}|parent|{parent_index}".encode("utf-8")
+            ).hexdigest()
+            for child_piece in _split_body(parent_piece, child_tokens, overlap_tokens):
+                child_text = f"{full_path}\n\n{child_piece}" if full_path else child_piece
+                chunk_id = hashlib.sha256(
+                    f"{doc.path}|{ordinal}|{child_piece}".encode("utf-8")
+                ).hexdigest()
+                chunks.append(Chunk(
+                    text=child_text, source_path=doc.path, title=doc.title,
+                    heading_path=heading_path or doc.title, ordinal=ordinal,
+                    chunk_id=chunk_id, parent_id=parent_id, parent_text=parent_text,
+                ))
+                ordinal += 1
+            parent_index += 1
+    return chunks
+
+
+def chunk_document(doc: Document, target_tokens: int = 512,
+                   overlap_tokens: int = 64, parent_document: bool = False,
+                   parent_target_tokens: int = 1024,
+                   child_target_tokens: int = 256) -> list[Chunk]:
+    if not parent_document:
+        return _chunk_flat(doc, target_tokens, overlap_tokens)
+    return _chunk_parent(doc, parent_target_tokens, child_target_tokens, overlap_tokens)

raggity/cli.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import shutil
+import typer
+from rich.console import Console
+
+from .config import load_config
+from .core import Raggity
+from .evaluate import evaluate, load_golden
+
+app = typer.Typer(help="raggity — local-first RAG over your notes, answered by Claude.")
+console = Console()
+
+
+def _rag(config: str | None) -> Raggity:
+    return Raggity(load_config(config))
+
+
+@app.command()
+def ingest(config: str = typer.Option(None, "--config")):
+    """Incrementally index configured source folders."""
+    report = _rag(config).ingest()
+    console.print(
+        f"[green]Indexed.[/green] added={report.added} updated={report.updated} "
+        f"deleted={report.deleted} unchanged={report.unchanged}"
+    )
+
+
+@app.command()
+def ask(question: str, config: str = typer.Option(None, "--config"),
+        plain: bool = typer.Option(False, "--plain"),
+        expand: bool = typer.Option(False, "--expand"),
+        hyde: bool = typer.Option(False, "--hyde"),
+        step_back: bool = typer.Option(False, "--step-back"),
+        no_stream: bool = typer.Option(False, "--no-stream"),
+        decompose: bool = typer.Option(False, "--decompose"),
+        no_cache: bool = typer.Option(False, "--no-cache")):
+    """Ask a question against your knowledge base."""
+    import asyncio
+    rag = _rag(config)
+    if decompose:
+        if expand or hyde or step_back:
+            typer.echo("note: --decompose overrides other query transforms", err=True)
+        typer.echo("Decomposing query (+model calls)…", err=True)
+        answer = rag.ask_decompose(question)
+        if plain:
+            typer.echo(answer.text)
+        else:
+            console.print(answer.text)
+    else:
+        if expand or hyde or step_back:
+            typer.echo("Query transforms enabled (+model calls)…", err=True)
+        expand_arg = True if expand else None
+        hyde_arg = True if hyde else None
+        step_back_arg = True if step_back else None
+        use_cache_arg = False if no_cache else None
+        if plain or no_stream:
+            # Buffered path — honors cache (unless --no-cache)
+            answer = rag.ask(question, expand=expand_arg, hyde=hyde_arg, step_back=step_back_arg,
+                             use_cache=use_cache_arg)
+            if plain:
+                typer.echo(answer.text)
+            else:
+                console.print(answer.text)
+        else:
+            # Streaming path — default; always calls the model (cache is buffered-only)
+            async def _stream():
+                final = None
+                async for piece in rag.aask_stream(question, expand=expand_arg,
+                                                   hyde=hyde_arg, step_back=step_back_arg):
+                    if isinstance(piece, str):
+                        print(piece, end="", flush=True)
+                    else:
+                        final = piece
+                print()
+                return final
+            answer = asyncio.run(_stream())
+    if answer is not None and answer.citations and not plain:
+        console.print("\n[dim]Sources:[/dim]")
+        seen = set()
+        for c in answer.citations:
+            if c.supported and c.source_path not in seen:
+                seen.add(c.source_path)
+                console.print(f"  [dim]- {c.source_path}[/dim]")
+
+
+@app.command()
+def status(config: str = typer.Option(None, "--config")):
+    """Show index statistics."""
+    st = _rag(config).status()
+    for k, v in st.items():
+        console.print(f"{k}: {v}")
+
+
+@app.command()
+def reindex(config: str = typer.Option(None, "--config"),
+            force: bool = typer.Option(False, "--force")):
+    """Rebuild the index from scratch."""
+    cfg = load_config(config)
+    if force:
+        shutil.rmtree(cfg.index.path, ignore_errors=True)
+    report = Raggity(cfg).ingest()
+    console.print(f"[green]Reindexed.[/green] added={report.added}")
+
+
+@app.command(name="eval")
+def eval_cmd(golden: str = typer.Argument(...),
+             config: str = typer.Option(None, "--config"),
+             k: int = typer.Option(5, "--k"),
+             llm_judge: bool = typer.Option(False, "--llm-judge")):
+    """Run free CPU retrieval metrics against a golden.jsonl set."""
+    rag = _rag(config)
+    if llm_judge:
+        typer.echo("Running LLM-judge eval (+2 model calls per question)…", err=True)
+        import asyncio
+        from .evaluate import llm_judge as run_judge
+        res = asyncio.run(run_judge(rag, load_golden(golden),
+                                    model=rag.cfg.generation.model,
+                                    auth=rag.cfg.generation.auth))
+        console.print(f"Faithfulness={res.faithfulness:.3f}  "
+                      f"AnswerRelevance={res.answer_relevance:.3f}  (n={res.n})")
+        console.print("(note: self-assessed — same model family generates and grades)")
+    else:
+        res = evaluate(rag.retriever, load_golden(golden), k=k)
+        console.print(f"Hit@{k}={res.hit_rate:.3f}  MRR={res.mrr:.3f}  "
+                      f"Recall@{k}={res.recall:.3f}  (n={res.n})")
+
+
+@app.command()
+def watch(config: str = typer.Option(None, "--config"),
+          debounce: float = typer.Option(2.0, "--debounce")):
+    """Watch source folders and re-index on change (Ctrl-C to stop)."""
+    rag = _rag(config)
+    try:
+        from .watch import run_watch
+    except ImportError:
+        console.print("[red]watch needs extra deps:[/red] pip install raggity[watch]")
+        raise typer.Exit(1)
+    try:
+        observer = run_watch(rag, rag.cfg.sources.include, debounce)
+    except RuntimeError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(1)
+    console.print(f"[green]Watching[/green] {len(rag.cfg.sources.include)} source pattern(s). Ctrl-C to stop.")
+    import time
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        observer.stop()
+    observer.join()
+
+
+@app.command()
+def serve(config: str = typer.Option(None, "--config"),
+          host: str = typer.Option("127.0.0.1", "--host"),
+          port: int = typer.Option(8000, "--port")):
+    """Run the local HTTP API server."""
+    try:
+        import uvicorn
+        from .server import create_app
+    except ImportError:
+        console.print("[red]The server needs extra deps:[/red] pip install raggity[server]")
+        raise typer.Exit(1)
+    uvicorn.run(create_app(load_config(config)), host=host, port=port)
+
+
+if __name__ == "__main__":
+    app()

raggity/config.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+import platformdirs
+from pydantic import BaseModel, Field
+
+
+class SourcesConfig(BaseModel):
+    include: list[str] = Field(default_factory=list)
+
+
+class EmbeddingConfig(BaseModel):
+    model: str = "BAAI/bge-small-en-v1.5"
+    provider: str = "cpu"  # cpu | cuda | directml | rocm
+    batch_size: int = 256
+    parallel: int = 0
+    cache: bool = False
+
+
+class RetrievalConfig(BaseModel):
+    hybrid: bool = True
+    rrf_k: int = 60
+    candidates: int = 30
+    rerank: bool = True
+    rerank_model: str = "Xenova/ms-marco-MiniLM-L-6-v2"
+    top_k: int = 5
+    dedup_cosine: float = 0.92
+    # Dense-cosine sufficiency floor: governs abstention. Reliable signal (~0.6–0.8
+    # for relevant, ~0.43–0.47 for off-topic). When max_dense < this value, abstain.
+    sufficiency_floor: float = 0.5
+    # OPTIONAL secondary rerank-score filter. 0.0 = off (default). Only applied when
+    # rerank=True and relevance_floor > 0. Cross-encoder absolute score is unreliable
+    # for abstention, so this is off by default.
+    relevance_floor: float = 0.0
+    parent_document: bool = False
+    parent_target_tokens: int = 1024
+    child_target_tokens: int = 256
+    expand: bool = False
+    expand_n: int = 3
+    hyde: bool = False
+    step_back: bool = False
+
+
+class GenerationConfig(BaseModel):
+    auth: str = "auto"  # auto | subscription | api_key
+    model: str = "claude-opus-4-8"
+    cache: bool = False
+
+
+class IndexConfig(BaseModel):
+    path: str = ".raggity/index"
+    backend: str = "lancedb"
+    ann_threshold: int = 50000
+    qdrant_location: str = ":memory:"
+    qdrant_collection: str = "raggity"
+    qdrant_api_key: str | None = None
+
+
+class RaggityConfig(BaseModel):
+    sources: SourcesConfig = Field(default_factory=SourcesConfig)
+    embedding: EmbeddingConfig = Field(default_factory=EmbeddingConfig)
+    retrieval: RetrievalConfig = Field(default_factory=RetrievalConfig)
+    generation: GenerationConfig = Field(default_factory=GenerationConfig)
+    index: IndexConfig = Field(default_factory=IndexConfig)
+
+
+def _find_config_path(explicit: str | None) -> Path | None:
+    if explicit:
+        return Path(explicit)
+    local = Path.cwd() / "raggity.toml"
+    if local.is_file():
+        return local
+    user = Path(platformdirs.user_config_dir("raggity")) / "raggity.toml"
+    if user.is_file():
+        return user
+    return None
+
+
+def load_config(path: str | None = None) -> RaggityConfig:
+    cfg_path = _find_config_path(path)
+    if cfg_path is None:
+        return RaggityConfig()
+    with open(cfg_path, "rb") as fh:
+        data = tomllib.load(fh)
+    return RaggityConfig.model_validate(data)