add CLI controlled demo

README.md

@@ -159,7 +159,12 @@ search:
 
 ```bash
 pip install "visual-rag-toolkit[ui,qdrant,embedding,pdf]"
-streamlit run demo/app.py
+
+# Option A: from Python
+python -c "import visual_rag; visual_rag.demo()"
+
+# Option B: CLI launcher
+visual-rag-demo
 ```
 
 ## 📊 Benchmark Evaluation

pyproject.toml

@@ -73,6 +73,8 @@ cloudinary = [
 ui = [
     "streamlit>=1.25.0",
     "httpx>=0.24.0",
+    "pandas>=2.0.0",
+    "altair>=5.0.0",
 ]
 
 # All dependencies
@@ -90,6 +92,8 @@ all = [
     # ui
     "streamlit>=1.25.0",
     "httpx>=0.24.0",
+    "pandas>=2.0.0",
+    "altair>=5.0.0",
 ]
 
 # Development dependencies
@@ -103,6 +107,7 @@ dev = [
 
 [project.scripts]
 visual-rag = "visual_rag.cli.main:main"
+visual-rag-demo = "visual_rag.demo_runner:main"
 
 [project.urls]
 Homepage = "https://github.com/Ara-Yeroyan/visual-rag-toolkit"
@@ -111,7 +116,7 @@ Repository = "https://github.com/Ara-Yeroyan/visual-rag-toolkit"
 Issues = "https://github.com/Ara-Yeroyan/visual-rag-toolkit/issues"
 
 [tool.hatch.build.targets.wheel]
-packages = ["visual_rag", "benchmarks"]
+packages = ["visual_rag", "benchmarks", "demo"]
 
 [tool.hatch.build.targets.sdist]
 # Keep source distributions clean (no local artifacts, eval results, caches).

visual_rag/__init__.py

@@ -71,6 +71,11 @@ try:
 except ImportError:
     QdrantAdmin = None
 
+try:
+    from visual_rag.demo_runner import demo
+except ImportError:
+    demo = None
+
 # Config utilities (always available)
 from visual_rag.config import load_config, get, get_section
 
@@ -86,6 +91,7 @@ __all__ = [
     "TwoStageRetriever",
     "MultiVectorRetriever",
     "QdrantAdmin",
+    "demo",
     
     # Config utilities
     "load_config",

visual_rag/demo_runner.py

@@ -0,0 +1,89 @@
+"""
+Launch the Streamlit demo from an installed package.
+
+Why:
+- After `pip install visual-rag-toolkit`, the repo layout isn't present.
+- We package the `demo/` module and expose `visual_rag.demo()` + `visual-rag-demo`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+def demo(
+    *,
+    host: str = "0.0.0.0",
+    port: int = 7860,
+    headless: bool = True,
+    open_browser: bool = False,
+    extra_args: Optional[list[str]] = None,
+) -> int:
+    """
+    Launch the Streamlit demo UI.
+
+    Requirements:
+    - `visual-rag-toolkit[ui,qdrant,embedding,pdf]` (or `visual-rag-toolkit[all]`)
+
+    Returns:
+        Streamlit process exit code.
+    """
+    try:
+        import streamlit  # noqa: F401
+    except Exception as e:  # pragma: no cover
+        raise RuntimeError(
+            "Streamlit is not installed. Install with:\n"
+            '  pip install "visual-rag-toolkit[ui,qdrant,embedding,pdf]"'
+        ) from e
+
+    # Resolve the installed demo entrypoint path.
+    mod = importlib.import_module("demo.app")
+    app_path = Path(getattr(mod, "__file__", "")).resolve()
+    if not app_path.exists():  # pragma: no cover
+        raise RuntimeError("Could not locate installed demo app (demo.app).")
+
+    # Build a stable Streamlit invocation.
+    cmd = [sys.executable, "-m", "streamlit", "run", str(app_path)]
+    cmd += ["--server.address", str(host)]
+    cmd += ["--server.port", str(int(port))]
+    cmd += ["--server.headless", "true" if headless else "false"]
+    cmd += ["--browser.gatherUsageStats", "false"]
+    cmd += ["--server.runOnSave", "false"]
+    cmd += ["--browser.serverAddress", str(host)]
+    if not open_browser:
+        cmd += ["--browser.serverPort", str(int(port))]
+        cmd += ["--browser.open", "false"]
+
+    if extra_args:
+        cmd += list(extra_args)
+
+    env = os.environ.copy()
+    # Make sure the demo doesn't spam internal Streamlit warnings in logs.
+    env.setdefault("STREAMLIT_BROWSER_GATHER_USAGE_STATS", "false")
+
+    return subprocess.call(cmd, env=env)
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(description="Launch the Visual RAG Toolkit Streamlit demo.")
+    p.add_argument("--host", default="0.0.0.0")
+    p.add_argument("--port", type=int, default=7860)
+    p.add_argument("--no-headless", action="store_true", help="Run with a browser window (not headless).")
+    p.add_argument("--open", action="store_true", help="Open browser automatically.")
+    args, unknown = p.parse_known_args()
+
+    rc = demo(
+        host=args.host,
+        port=args.port,
+        headless=(not args.no_headless),
+        open_browser=bool(args.open),
+        extra_args=unknown,
+    )
+    raise SystemExit(rc)
+