rag-python 0.3.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

rag_python/__init__.py

@@ -2,18 +2,29 @@
 
 Quick start::
 
-    from rag_python import RAG
+    pip install rag-python
+    export OPENAI_API_KEY=sk-...
+
+    # CLI
+    rag-python ingest ./docs --reindex
+    rag-python query "What is our leave policy?"
+    rag-python docs quickstart
 
-    rag = RAG(llm_model="gpt-4o-mini")
+    # Python
+    from rag_python import RAG
+    rag = RAG()
     rag.ingest(["./docs"], reindex=True)
     print(rag.query("What is our leave policy?").text)
+
+Documentation: https://github.com/RaghavOG/rag-python/tree/main/docs
 """
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 
 from .client import RAG, RAGAnswer
-from .rag_pipeline import ingest, query, RAGResponse
+from .rag_pipeline import ingest, query, query_stream, RAGResponse, RAGStream
 from .providers import make_llm_provider, make_embedding_provider
+from .log import configure_logging, get_logger
 from .options import (
     ChunkingConfig,
     DocumentConfig,
@@ -33,7 +44,11 @@ __all__ = [
     "QueryConfig",
     "ingest",
     "query",
+    "query_stream",
+    "RAGStream",
     "RAGResponse",
+    "configure_logging",
+    "get_logger",
     "make_llm_provider",
     "make_embedding_provider",
 ]

rag_python/cli.py

@@ -1,10 +1,14 @@
 """rag-python command-line interface."""
+from __future__ import annotations
+
 import argparse
 import json
+import sys
 from dataclasses import replace
 
 from . import __version__
 from .client import RAG
+from .help_text import CLI_EPILOG, list_topics, print_topic, print_topic_list
 
 
 def _build_rag(args: argparse.Namespace) -> RAG:
@@ -42,21 +46,44 @@ def _add_provider_args(parser: argparse.ArgumentParser) -> None:
         "--llm-provider",
         default="openai",
         choices=["openai", "azure_openai", "anthropic", "gemini", "ollama"],
+        metavar="PROVIDER",
+        help="LLM backend (default: openai). See: rag-python docs providers",
+    )
+    parser.add_argument(
+        "--llm-model",
+        default=None,
+        metavar="MODEL",
+        help="LLM model or Azure deployment name (default: from env LLM_MODEL)",
     )
-    parser.add_argument("--llm-model", default=None)
     parser.add_argument(
         "--embedding-provider",
         default="openai",
         choices=["openai", "azure_openai", "ollama", "local"],
+        metavar="PROVIDER",
+        help="Embedding backend (default: openai). Use local for offline embeddings",
     )
-    parser.add_argument("--embedding-model", default=None)
-    parser.add_argument("--ollama-base-url", default=None)
-    parser.add_argument("--azure-endpoint", default=None)
-    parser.add_argument("--azure-api-key", default=None)
-    parser.add_argument("--azure-api-version", default=None)
-    parser.add_argument("--openai-api-key", default=None)
-    parser.add_argument("--anthropic-api-key", default=None)
-    parser.add_argument("--gemini-api-key", default=None)
+    parser.add_argument(
+        "--embedding-model",
+        default=None,
+        metavar="MODEL",
+        help="Embedding model name (default: from env EMBEDDING_MODEL)",
+    )
+    parser.add_argument(
+        "--ollama-base-url",
+        default=None,
+        metavar="URL",
+        help="Ollama server URL (default: http://localhost:11434 or OLLAMA_BASE_URL)",
+    )
+    parser.add_argument("--azure-endpoint", default=None, help="Azure OpenAI endpoint URL")
+    parser.add_argument("--azure-api-key", default=None, help="Azure OpenAI API key")
+    parser.add_argument(
+        "--azure-api-version",
+        default=None,
+        help="Azure API version (default: 2023-09-01-preview)",
+    )
+    parser.add_argument("--openai-api-key", default=None, help="OpenAI API key (overrides env)")
+    parser.add_argument("--anthropic-api-key", default=None, help="Anthropic API key")
+    parser.add_argument("--gemini-api-key", default=None, help="Gemini API key")
 
 
 def _add_search_args(parser: argparse.ArgumentParser) -> None:
@@ -64,37 +91,135 @@ def _add_search_args(parser: argparse.ArgumentParser) -> None:
         "--retriever",
         choices=["vector", "multi_query", "hybrid"],
         default=None,
-        help="Retrieval strategy (default: multi_query; hybrid needs pip install rag-python[hybrid])",
+        metavar="MODE",
+        help=(
+            "Retrieval mode: vector (single query), multi_query (default, with rewriting), "
+            "or hybrid (BM25+vector; requires pip install rag-python[hybrid])"
+        ),
     )
     parser.add_argument(
         "--metadata-filter",
         type=_parse_metadata_filter,
         default=None,
-        help='Chroma metadata filter as JSON, e.g. \'{"filename": "policy.pdf"}\'',
+        metavar="JSON",
+        help='Filter chunks by metadata, e.g. \'{"filename": "policy.pdf"}\'',
     )
 
 
-def main() -> None:
+def _make_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="rag-python",
-        description="rag-python — modular RAG with query rewriting, reranking, guardrails, and multi-LLM support.",
+        description=(
+            "Production-grade RAG for Python — ingest documents, ask questions, "
+            "get grounded answers with multi-LLM support."
+        ),
+        epilog=CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
     )
-    parser.add_argument("--version", action="version", version=f"rag-python {__version__}")
-    sub = parser.add_subparsers(dest="command", required=True)
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
 
-    ing = sub.add_parser("ingest", help="Ingest files/folders into the vector store")
-    ing.add_argument("paths", nargs="+", help="Files or folders to ingest")
-    ing.add_argument("--reindex", action="store_true", help="Clear vector store and re-ingest")
+    ing = sub.add_parser(
+        "ingest",
+        help="Load files into the vector store (chunk + embed)",
+        description=(
+            "Ingest one or more files or directories into the ChromaDB vector store.\n"
+            "Supported formats: .txt .md .pdf .docx .csv .json .html"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "examples:\n"
+            "  rag-python ingest ./data --reindex\n"
+            "  rag-python ingest policy.pdf handbook/ --embedding-provider local"
+        ),
+    )
+    ing.add_argument(
+        "paths",
+        nargs="+",
+        metavar="PATH",
+        help="File or directory paths to ingest",
+    )
+    ing.add_argument(
+        "--reindex",
+        action="store_true",
+        help="Delete existing vectors before ingesting (fresh index)",
+    )
     _add_provider_args(ing)
 
-    q = sub.add_parser("query", help="Ask a question against ingested documents")
-    q.add_argument("question", nargs="+", help="Question text")
-    q.add_argument("--no-multi-query", action="store_true", help="Use vector retriever only")
-    q.add_argument("-v", "--verbose", action="store_true")
+    q = sub.add_parser(
+        "query",
+        help="Ask a question against ingested documents",
+        description=(
+            "Run the full RAG pipeline: retrieve relevant chunks, generate an answer, "
+            "optionally stream tokens and show sources."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "examples:\n"
+            '  rag-python query "How many days of annual leave?"\n'
+            "  rag-python query \"PTO policy\" --stream -v\n"
+            '  rag-python query "benefits" --retriever hybrid --metadata-filter \'{"filename": "hr.pdf"}\''
+        ),
+    )
+    q.add_argument(
+        "question",
+        nargs="+",
+        metavar="QUESTION",
+        help="Question text (multiple words are joined)",
+    )
+    q.add_argument(
+        "--no-multi-query",
+        action="store_true",
+        help="Use single-query vector retrieval (same as --retriever vector)",
+    )
+    q.add_argument(
+        "--stream",
+        action="store_true",
+        help="Stream answer tokens to stdout as they are generated",
+    )
+    q.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="After the answer, print evaluation scores and top source paths",
+    )
     _add_provider_args(q)
     _add_search_args(q)
 
-    args = parser.parse_args()
+    docs = sub.add_parser(
+        "docs",
+        help="Show user documentation in the terminal",
+        description="Print built-in help topics. Full docs: https://github.com/RaghavOG/rag-python/tree/main/docs",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="topics: " + ", ".join(list_topics()),
+    )
+    docs.add_argument(
+        "topic",
+        nargs="?",
+        default="quickstart",
+        choices=list_topics(),
+        metavar="TOPIC",
+        help="Documentation topic (default: quickstart)",
+    )
+    docs.add_argument(
+        "--list",
+        action="store_true",
+        help="List all available documentation topics",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = _make_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "docs":
+        if args.list:
+            print_topic_list()
+        else:
+            print_topic(args.topic)
+        return
 
     if args.command == "ingest":
         rag = _build_rag(args)
@@ -113,6 +238,20 @@ def main() -> None:
             retriever=retriever or rag.config.search.retriever,
             metadata_filter=args.metadata_filter or rag.config.search.metadata_filter,
         )
+        if args.stream:
+            stream = rag.query_stream(question, search=search)
+            for token in stream:
+                print(token, end="", flush=True)
+            print()
+            result = stream.result
+            if args.verbose:
+                print("\n--- evaluation ---")
+                print(result.evaluation)
+                print("\n--- sources ---")
+                for s in result.sources[:5]:
+                    print(s.get("metadata", {}).get("source", ""), "score:", s.get("score"))
+            return
+
         ans = rag.query(question, search=search)
         print(ans.text)
         if args.verbose:
@@ -124,4 +263,4 @@ def main() -> None:
 
 
 if __name__ == "__main__":
-    main()
+    main(sys.argv[1:])

rag_python/client.py

@@ -30,7 +30,7 @@ from .options import (
     SearchConfig,
 )
 from .providers import make_llm_provider, make_embedding_provider
-from .rag_pipeline import ingest as _ingest, query as _query, RAGResponse
+from .rag_pipeline import ingest as _ingest, query as _query, query_stream as _query_stream, RAGResponse, RAGStream
 from .vector_store import set_persist_dir
 
 
@@ -191,3 +191,21 @@ class RAG:
             evaluation=resp.evaluation,
             retried=resp.retried,
         )
+
+    def query_stream(
+        self,
+        question: str,
+        *,
+        search: SearchConfig | None = None,
+        query_config: QueryConfig | None = None,
+    ) -> RAGStream:
+        """Stream answer tokens; call ``stream.result`` after iterating."""
+        return _query_stream(
+            question,
+            search=search or self.config.search,
+            query_config=query_config or self.config.query,
+            llm_model=self.llm_model,
+            embedding_model=self.embedding_model,
+            llm=self.llm,
+            embedder=self.embedder,
+        )

rag_python/generation.py

@@ -1,6 +1,9 @@
 """LLM generation with context (RAG)."""
+from collections.abc import Iterator
+
 from .config import LLM_MODEL
 from .providers import LLMProvider, make_llm_provider
+from .providers.streaming import stream_generate
 
 
 RAG_SYSTEM = (
@@ -10,6 +13,11 @@ RAG_SYSTEM = (
 )
 
 
+def _build_user_prompt(query: str, context_chunks: list[str]) -> str:
+    context = "\n\n---\n\n".join(context_chunks)
+    return f"Context:\n{context}\n\nQuestion: {query}\n\nAnswer:"
+
+
 def generate(
     query: str,
     context_chunks: list[str],
@@ -20,12 +28,11 @@ def generate(
 ) -> str:
     """Generate answer from query and retrieved context."""
     llm = llm or make_llm_provider("openai")
-    context = "\n\n---\n\n".join(context_chunks)
     sys = system_prompt or RAG_SYSTEM
     try:
         return llm.generate(
             system=sys,
-            user=f"Context:\n{context}\n\nQuestion: {query}\n\nAnswer:",
+            user=_build_user_prompt(query, context_chunks),
             model=model or LLM_MODEL,
             temperature=0.2,
             max_tokens=1024,
@@ -33,3 +40,26 @@ def generate(
     except Exception as e:
         return f"[Generation error: {e}]"
 
+
+def generate_stream(
+    query: str,
+    context_chunks: list[str],
+    *,
+    model: str | None = None,
+    system_prompt: str | None = None,
+    llm: LLMProvider | None = None,
+) -> Iterator[str]:
+    """Stream answer tokens from query and retrieved context."""
+    llm = llm or make_llm_provider("openai")
+    sys = system_prompt or RAG_SYSTEM
+    try:
+        yield from stream_generate(
+            llm,
+            system=sys,
+            user=_build_user_prompt(query, context_chunks),
+            model=model or LLM_MODEL,
+            temperature=0.2,
+            max_tokens=1024,
+        )
+    except Exception as e:
+        yield f"[Generation error: {e}]"

rag_python/help_text.py

@@ -0,0 +1,229 @@
+"""User-facing documentation printed by ``rag-python docs``."""
+from __future__ import annotations
+
+DOCS_BASE_URL = "https://github.com/RaghavOG/rag-python/tree/main/docs"
+
+CLI_EPILOG = """
+examples:
+  rag-python ingest ./data --reindex
+  rag-python query "How many days of annual leave?"
+  rag-python query "leave policy" --stream -v
+  rag-python query "benefits" --retriever hybrid
+  rag-python docs quickstart
+  rag-python docs --list
+
+online docs:
+  {base_url}
+""".format(base_url=DOCS_BASE_URL).strip()
+
+TOPICS: dict[str, str] = {
+    "quickstart": """
+rag-python — Quick start
+========================
+
+1. Install
+   pip install rag-python
+
+2. Set your API key (OpenAI default)
+   export OPENAI_API_KEY=sk-...
+
+3. Ingest documents (TXT, MD, PDF, DOCX, CSV, JSON, HTML)
+   rag-python ingest ./my-docs --reindex
+
+4. Ask a question
+   rag-python query "What is our leave policy?"
+   rag-python query "annual leave" --stream -v
+
+Python API
+----------
+  from rag_python import RAG
+
+  rag = RAG(llm_model="gpt-4o-mini")
+  rag.ingest(["./my-docs"], reindex=True)
+  print(rag.query("What is our leave policy?").text)
+
+More: rag-python docs install | cli | config | providers | features
+Online: {base_url}
+""".format(base_url=DOCS_BASE_URL).strip(),
+    "install": """
+rag-python — Install & optional extras
+======================================
+
+Base install (OpenAI + Chroma + document loaders):
+  pip install rag-python
+
+Optional extras:
+  pip install rag-python[local]      Offline embeddings (sentence-transformers)
+  pip install rag-python[hybrid]     BM25 + vector hybrid search
+  pip install rag-python[rerank]     Cross-encoder reranking
+  pip install rag-python[anthropic]  Claude LLM
+  pip install rag-python[gemini]     Gemini LLM
+  pip install rag-python[all]        All optional features
+
+From source:
+  git clone https://github.com/RaghavOG/rag-python.git
+  cd rag-python
+  pip install -e ".[dev,all]"
+
+Verify:
+  rag-python --version
+  pytest
+""".strip(),
+    "cli": """
+rag-python — CLI reference
+==========================
+
+USAGE
+  rag-python ingest PATH [PATH ...] [options]
+  rag-python query QUESTION [options]
+  rag-python docs [TOPIC]
+  rag-python --version
+
+INGEST
+  paths                 Files or directories to ingest
+  --reindex             Clear vector store before ingesting
+  --llm-provider        openai | azure_openai | anthropic | gemini | ollama
+  --embedding-provider  openai | azure_openai | ollama | local
+  --llm-model           Model or deployment name
+  --embedding-model     Embedding model name
+  --openai-api-key      Override OPENAI_API_KEY
+  --ollama-base-url     Ollama URL (default http://localhost:11434)
+
+QUERY
+  question              Natural-language question (words joined if multiple)
+  --retriever           vector | multi_query | hybrid (default: multi_query)
+  --no-multi-query      Shortcut for --retriever vector
+  --metadata-filter     JSON Chroma filter, e.g. '{"filename": "policy.pdf"}'
+  --stream              Stream answer tokens to stdout
+  -v, --verbose         Show evaluation scores and source paths
+
+ENVIRONMENT
+  OPENAI_API_KEY        Required for default OpenAI provider
+  RAG_PYTHON_DATA_DIR   Document storage (default ./data)
+  RAG_PYTHON_CHROMA_DIR Vector DB path (default ./chroma_db)
+
+Examples:
+  rag-python ingest ./policies ./handbook.pdf --reindex
+  rag-python query "How many vacation days?" -v
+  rag-python query "PTO policy" --retriever hybrid --stream
+  rag-python query "benefits" --metadata-filter '{"filename": "hr.pdf"}'
+""".strip(),
+    "config": """
+rag-python — Configuration
+==========================
+
+Environment variables (.env supported via python-dotenv):
+
+  OPENAI_API_KEY          OpenAI LLM + embeddings
+  ANTHROPIC_API_KEY       Claude (LLM only)
+  GEMINI_API_KEY          Gemini (LLM only)
+  AZURE_OPENAI_ENDPOINT   Azure OpenAI
+  AZURE_OPENAI_API_KEY    Azure OpenAI
+  OPENAI_API_VERSION      Azure API version
+  OLLAMA_BASE_URL         Local Ollama server
+  LOCAL_EMBEDDING_MODEL   Model for embedding_provider=local
+  RAG_PYTHON_DATA_DIR     Default ./data
+  RAG_PYTHON_CHROMA_DIR   Default ./chroma_db
+
+  CHUNK_SIZE, CHUNK_OVERLAP, CHUNK_STRATEGY
+  TOP_K_RETRIEVE, TOP_K_RERANK, MULTI_QUERY_N
+  GUARDRAILS_ENABLED, MAX_RETRIES, RERANKER_MODEL
+
+Python RAGConfig:
+  from rag_python import RAG, RAGConfig, ChunkingConfig, SearchConfig
+
+  rag = RAG(
+      config=RAGConfig(
+          chunking=ChunkingConfig(strategy="recursive", chunk_size=512),
+          search=SearchConfig(
+              retriever="hybrid",
+              top_k_retrieve=20,
+              metadata_filter={"filename": "policy.pdf"},
+          ),
+      ),
+  )
+
+Shorthand on RAG():
+  chunk_strategy, chunk_size, retriever, metadata_filter,
+  top_k_retrieve, document_extensions, ...
+
+Logging:
+  import rag_python
+  rag_python.configure_logging()
+""".strip(),
+    "providers": """
+rag-python — Providers
+======================
+
+LLM (generation, rewriting, guardrails):
+  openai         OPENAI_API_KEY (default)
+  azure_openai   AZURE_OPENAI_ENDPOINT + AZURE_OPENAI_API_KEY
+  anthropic      ANTHROPIC_API_KEY + pip install rag-python[anthropic]
+  gemini         GEMINI_API_KEY + pip install rag-python[gemini]
+  ollama         Local Ollama — set --llm-model to your model name
+
+Embeddings (retrieval):
+  openai         OPENAI_API_KEY (default)
+  azure_openai   Azure deployment for embeddings
+  ollama         Local embedding model via Ollama
+  local          Offline sentence-transformers + pip install rag-python[local]
+
+Common combos:
+  OpenAI end-to-end:
+    RAG(llm_provider="openai", embedding_provider="openai")
+
+  Claude + OpenAI embeddings:
+    RAG(llm_provider="anthropic", llm_model="claude-opus-4-6",
+        embedding_provider="openai")
+
+  Fully local embeddings:
+    RAG(llm_provider="ollama", llm_model="llama3.1",
+        embedding_provider="local", embedding_model="all-MiniLM-L6-v2")
+""".strip(),
+    "features": """
+rag-python — Features
+=====================
+
+Ingest pipeline
+  Loaders: .txt .md .pdf .docx .csv .json .html
+  Cleaning, chunking (recursive | structure_aware | semantic)
+  Embeddings → ChromaDB vector store
+
+Query pipeline
+  Query rewriting + multi-query retrieval
+  Hybrid search: BM25 + vector (pip install rag-python[hybrid])
+  Cross-encoder reranking (pip install rag-python[rerank])
+  Metadata filters on retrieval (source, filename, ...)
+  Streaming answers: rag.query_stream()
+  Guardrails: prompt injection + hallucination checks
+  Evaluation + self-correction retry loop
+
+CLI
+  rag-python ingest | query | docs
+  rag-python --version
+
+Docs
+  rag-python docs [topic]
+  https://github.com/RaghavOG/rag-python/tree/main/docs
+""".strip(),
+}
+
+
+def list_topics() -> list[str]:
+    return sorted(TOPICS.keys())
+
+
+def print_topic(topic: str) -> None:
+    key = topic.lower().strip()
+    if key not in TOPICS:
+        available = ", ".join(list_topics())
+        raise SystemExit(f"Unknown topic '{topic}'. Available: {available}\nUse: rag-python docs --list")
+    print(TOPICS[key])
+
+
+def print_topic_list() -> None:
+    print("rag-python documentation topics:\n")
+    for name in list_topics():
+        print(f"  {name}")
+    print("\nUsage: rag-python docs <topic>")
+    print(f"Online: {DOCS_BASE_URL}")

rag_python/log.py

@@ -0,0 +1,21 @@
+"""Structured logging helpers for rag-python."""
+from __future__ import annotations
+
+import logging
+
+PACKAGE_LOGGER = "rag_python"
+
+
+def get_logger(name: str | None = None) -> logging.Logger:
+    """Return a namespaced logger (default: ``rag_python``)."""
+    if name:
+        return logging.getLogger(f"{PACKAGE_LOGGER}.{name}")
+    return logging.getLogger(PACKAGE_LOGGER)
+
+
+def configure_logging(level: int = logging.INFO) -> None:
+    """Enable default console logging for the package (optional convenience)."""
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s %(levelname)s [%(name)s] %(message)s",
+    )

rag_python/providers/anthropic_provider.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from collections.abc import Iterator
+
 
 class AnthropicProvider:
     def __init__(self, *, api_key: str | None = None) -> None:
@@ -36,6 +38,27 @@ class AnthropicProvider:
                 parts.append(text)
         return ("\n".join(parts)).strip()
 
+    def generate_stream(
+        self,
+        *,
+        user: str,
+        system: str | None = None,
+        model: str | None = None,
+        temperature: float = 0.2,
+        max_tokens: int = 1024,
+    ) -> Iterator[str]:
+        if not model:
+            raise RuntimeError("AnthropicProvider requires `model=...` (e.g. claude-...)")
+        with self._client.messages.stream(
+            model=model,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            system=system or "",
+            messages=[{"role": "user", "content": user}],
+        ) as stream:
+            for text in stream.text_stream:
+                yield text
+
     def embed(self, texts: list[str], *, model: str | None = None) -> list[list[float]]:
         raise RuntimeError("Anthropic does not provide embeddings in this package. Use OpenAI/Ollama or local embeddings.")