jehoctor-rag-demo 0.1.1.dev1__tar.gz → 0.2.0__tar.gz

jehoctor_rag_demo-0.2.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.3
+Name: jehoctor-rag-demo
+Version: 0.2.0
+Summary: Chat with Wikipedia
+Author: James Hoctor
+Author-email: James Hoctor <JEHoctor@protonmail.com>
+Requires-Dist: aiosqlite==0.21.0
+Requires-Dist: chromadb>=1.3.4
+Requires-Dist: datasets>=4.4.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: huggingface-hub>=0.36.0
+Requires-Dist: langchain>=1.0.5
+Requires-Dist: langchain-anthropic>=1.0.2
+Requires-Dist: langchain-community>=0.4.1
+Requires-Dist: langchain-huggingface>=1.1.0
+Requires-Dist: langchain-ollama>=1.0.0
+Requires-Dist: langchain-openai>=1.0.2
+Requires-Dist: langgraph-checkpoint-sqlite>=3.0.1
+Requires-Dist: llama-cpp-python>=0.3.16
+Requires-Dist: nvidia-ml-py>=13.590.44
+Requires-Dist: ollama>=0.6.0
+Requires-Dist: platformdirs>=4.5.0
+Requires-Dist: psutil>=7.1.3
+Requires-Dist: py-cpuinfo>=9.0.0
+Requires-Dist: pydantic>=2.12.4
+Requires-Dist: pyperclip>=1.11.0
+Requires-Dist: textual>=6.5.0
+Requires-Dist: typer>=0.20.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# RAG-demo
+
+Chat with (a small portion of) Wikipedia
+
+⚠️ RAG functionality is still under development. ⚠️
+
+![app screenshot](screenshots/screenshot_062f205a.png "App screenshot (this AI response is not accurate)")
+
+## Requirements
+
+ 1. [uv](https://docs.astral.sh/uv/)
+ 2. At least one of the following:
+    - A suitable terminal emulator. In particular, on macOS consider using [iTerm2](https://iterm2.com/) instead of the default Terminal.app ([explanation](https://textual.textualize.io/FAQ/#why-doesnt-textual-look-good-on-macos)). On Linux, you might want to try [kitty](https://sw.kovidgoyal.net/kitty/), [wezterm](https://wezterm.org/), [alacritty](https://alacritty.org/), or [ghostty](https://ghostty.org/) instead of the terminal that came with your DE ([reason](https://darren.codes/posts/textual-copy-paste/)). Windows Terminal should be fine as far as I know.
+    - Any common web browser
+
+## Optional stuff that could make your experience better
+
+ 1. [Hugging Face login](https://huggingface.co/docs/huggingface_hub/quick-start#login)
+ 2. API key for your favorite LLM provider (support coming soon)
+ 3. Ollama installed on your system if you have a GPU
+ 4. Run RAG-demo on a more capable (bigger GPU) machine over SSH if you can. It is a terminal app after all.
+
+
+## Run from the repository
+
+First, clone this repository. Then, run one of the options below.
+
+Run in a terminal:
+```bash
+uv run chat
+```
+
+Or run in a web browser:
+```bash
+uv run textual serve chat
+```
+
+## Run from the latest version on PyPI
+
+TODO: test uv automatic torch backend selection:
+https://docs.astral.sh/uv/guides/integration/pytorch/#automatic-backend-selection
+
+Run in a terminal:
+```bash
+uvx --from=jehoctor-rag-demo chat
+```
+
+Or run in a web browser:
+```bash
+uvx --from=jehoctor-rag-demo textual serve chat
+```
+
+## CUDA acceleration via Llama.cpp
+
+If you have an NVIDIA GPU with CUDA and build tools installed, you might be able to get CUDA acceleration without installing Ollama.
+
+```bash
+CMAKE_ARGS="-DGGML_CUDA=on" uv run chat
+```
+
+## Metal acceleration via Llama.cpp (on Apple Silicon)
+
+On an Apple Silicon machine, make sure `uv` runs an ARM interpreter as this should cause it to install Llama.cpp with Metal support.
+
+## Ollama on Linux
+
+Remember that you have to keep Ollama up-to-date manually on Linux.
+A recent version of Ollama (v0.11.10 or later) is required to run the [embedding model we use](https://ollama.com/library/embeddinggemma).
+See this FAQ: https://docs.ollama.com/faq#how-can-i-upgrade-ollama.

jehoctor_rag_demo-0.2.0/README.md

@@ -0,0 +1,69 @@
+# RAG-demo
+
+Chat with (a small portion of) Wikipedia
+
+⚠️ RAG functionality is still under development. ⚠️
+
+![app screenshot](screenshots/screenshot_062f205a.png "App screenshot (this AI response is not accurate)")
+
+## Requirements
+
+ 1. [uv](https://docs.astral.sh/uv/)
+ 2. At least one of the following:
+    - A suitable terminal emulator. In particular, on macOS consider using [iTerm2](https://iterm2.com/) instead of the default Terminal.app ([explanation](https://textual.textualize.io/FAQ/#why-doesnt-textual-look-good-on-macos)). On Linux, you might want to try [kitty](https://sw.kovidgoyal.net/kitty/), [wezterm](https://wezterm.org/), [alacritty](https://alacritty.org/), or [ghostty](https://ghostty.org/) instead of the terminal that came with your DE ([reason](https://darren.codes/posts/textual-copy-paste/)). Windows Terminal should be fine as far as I know.
+    - Any common web browser
+
+## Optional stuff that could make your experience better
+
+ 1. [Hugging Face login](https://huggingface.co/docs/huggingface_hub/quick-start#login)
+ 2. API key for your favorite LLM provider (support coming soon)
+ 3. Ollama installed on your system if you have a GPU
+ 4. Run RAG-demo on a more capable (bigger GPU) machine over SSH if you can. It is a terminal app after all.
+
+
+## Run from the repository
+
+First, clone this repository. Then, run one of the options below.
+
+Run in a terminal:
+```bash
+uv run chat
+```
+
+Or run in a web browser:
+```bash
+uv run textual serve chat
+```
+
+## Run from the latest version on PyPI
+
+TODO: test uv automatic torch backend selection:
+https://docs.astral.sh/uv/guides/integration/pytorch/#automatic-backend-selection
+
+Run in a terminal:
+```bash
+uvx --from=jehoctor-rag-demo chat
+```
+
+Or run in a web browser:
+```bash
+uvx --from=jehoctor-rag-demo textual serve chat
+```
+
+## CUDA acceleration via Llama.cpp
+
+If you have an NVIDIA GPU with CUDA and build tools installed, you might be able to get CUDA acceleration without installing Ollama.
+
+```bash
+CMAKE_ARGS="-DGGML_CUDA=on" uv run chat
+```
+
+## Metal acceleration via Llama.cpp (on Apple Silicon)
+
+On an Apple Silicon machine, make sure `uv` runs an ARM interpreter as this should cause it to install Llama.cpp with Metal support.
+
+## Ollama on Linux
+
+Remember that you have to keep Ollama up-to-date manually on Linux.
+A recent version of Ollama (v0.11.10 or later) is required to run the [embedding model we use](https://ollama.com/library/embeddinggemma).
+See this FAQ: https://docs.ollama.com/faq#how-can-i-upgrade-ollama.

jehoctor_rag_demo-0.2.0/pyproject.toml

@@ -0,0 +1,102 @@
+[project]
+name = "jehoctor-rag-demo"
+version = "0.2.0"
+description = "Chat with Wikipedia"
+readme = "README.md"
+authors = [
+    { name = "James Hoctor", email = "JEHoctor@protonmail.com" }
+]
+requires-python = ">=3.12"
+# TODO: Reverse pinning of aiosqlite to 0.21.0 to work around this issue:
+# https://github.com/langchain-ai/langgraph/issues/6583
+dependencies = [
+    "aiosqlite==0.21.0",
+    "chromadb>=1.3.4",
+    "datasets>=4.4.1",
+    "httpx>=0.28.1",
+    "huggingface-hub>=0.36.0",
+    "langchain>=1.0.5",
+    "langchain-anthropic>=1.0.2",
+    "langchain-community>=0.4.1",
+    "langchain-huggingface>=1.1.0",
+    "langchain-ollama>=1.0.0",
+    "langchain-openai>=1.0.2",
+    "langgraph-checkpoint-sqlite>=3.0.1",
+    "llama-cpp-python>=0.3.16",
+    "nvidia-ml-py>=13.590.44",
+    "ollama>=0.6.0",
+    "platformdirs>=4.5.0",
+    "psutil>=7.1.3",
+    "py-cpuinfo>=9.0.0",
+    "pydantic>=2.12.4",
+    "pyperclip>=1.11.0",
+    "textual>=6.5.0",
+    "typer>=0.20.0",
+]
+
+[project.scripts]
+chat = "rag_demo.__main__:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "ruff>=0.14.3",
+    "mypy>=1.18.2",
+    "textual-dev>=1.8.0",
+    "ipython>=9.7.0",
+    "pytest-cov>=7.0.0",
+    "pytest-asyncio>=1.3.0",
+]
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[[tool.uv.index]]
+name = "llama-cpp-metal"
+url = "https://abetlen.github.io/llama-cpp-python/whl/metal"
+explicit = true
+
+[tool.uv.sources]
+llama-cpp-python = [
+    { index = "llama-cpp-metal", marker = "platform_machine == 'arm64' and sys_platform == 'darwin'" },
+]
+
+[build-system]
+requires = ["uv_build>=0.8.0,<0.9"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "rag_demo"
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+per-file-ignores = { "__init__.py" = ["F401"] }  # Ignore unused-import in all __init__.py files.
+select = ["ALL"]
+ignore = [
+    "E501",   # Handled by ruff format (line-too-long)
+    "D100",   # undocumented-public-module
+    "D104",   # undocumented-public-package
+    "D203",   # Conflicts with Google style D211/D212
+    "ANN101", # Missing type annotation for self
+    "ANN102", # Missing type annotation for cls
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.flake8-boolean-trap]
+extend-allowed-calls = ["textual.reactive.reactive"]
+
+[tool.mypy]
+strict = true
+show_error_codes = true
+warn_unused_ignores = true
+files = ["src/", "tests/"]
+
+[tool.mypy.plugins]
+pydantic.mypy.plugins = { enabled = true }

jehoctor_rag_demo-0.2.0/src/rag_demo/__main__.py

@@ -0,0 +1,31 @@
+import time
+
+# Measure the application start time.
+APPLICATION_START_TIME = time.time()
+
+# Disable "module import not at top of file" (aka E402) when importing Typer. This is necessary so that Typer's
+# initialization is included in the application startup time.
+import typer  # noqa: E402
+
+
+def _main(
+    name: str | None = typer.Option(None, help="The name you want to want the AI to use with you."),
+) -> None:
+    """Talk to Wikipedia."""
+    # Import here so that imports run within the typer.run context for prettier stack traces if errors occur.
+    # We ignore PLC0415 because we do not want these imports to be at the top of the module as is usually preferred.
+    from rag_demo.app import RAGDemo  # noqa: PLC0415
+    from rag_demo.logic import Logic  # noqa: PLC0415
+
+    logic = Logic(username=name, application_start_time=APPLICATION_START_TIME)
+    app = RAGDemo(logic)
+    app.run()
+
+
+def main() -> None:
+    """Entrypoint for the rag demo, specifically the `chat` command."""
+    typer.run(_main)
+
+
+if __name__ == "__main__":
+    main()

jehoctor_rag_demo-0.2.0/src/rag_demo/app.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import TYPE_CHECKING, ClassVar
+
+from textual.app import App
+from textual.binding import Binding
+
+from rag_demo.modes import ChatScreen, ConfigScreen, HelpScreen
+
+if TYPE_CHECKING:
+    from rag_demo.logic import Logic, Runtime
+
+
+class RAGDemo(App):
+    """Main application UI.
+
+    This class is responsible for creating the modes of the application, which are defined in :mod:`rag_demo.modes`.
+    """
+
+    TITLE = "RAG Demo"
+    CSS_PATH = Path(__file__).parent / "app.tcss"
+    BINDINGS: ClassVar = [
+        Binding("z", "switch_mode('chat')", "chat"),
+        Binding("c", "switch_mode('config')", "configure"),
+        Binding("h", "switch_mode('help')", "help"),
+    ]
+    MODES: ClassVar = {
+        "chat": ChatScreen,
+        "config": ConfigScreen,
+        "help": HelpScreen,
+    }
+
+    def __init__(self, logic: Logic) -> None:
+        """Initialize the main app.
+
+        Args:
+            logic (Logic): Object implementing the application logic.
+        """
+        super().__init__()
+        self.logic = logic
+        self._runtime_future: asyncio.Future[Runtime] = asyncio.Future()
+
+    async def on_mount(self) -> None:
+        """Set the initial mode to chat and initialize async parts of the logic."""
+        self.switch_mode("chat")
+        self.run_worker(self._hold_runtime())
+
+    async def _hold_runtime(self) -> None:
+        async with self.logic.runtime(app_like=self) as runtime:
+            self._runtime_future.set_result(runtime)
+            # Pause the task until Textual cancels it when the application closes.
+            await asyncio.Event().wait()
+
+    async def runtime(self) -> Runtime:
+        """Returns the application runtime logic."""
+        return await self._runtime_future

jehoctor_rag_demo-0.2.0/src/rag_demo/db.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import aiosqlite
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class AtomicIDManager:
+    """A database manager for managing thread IDs.
+
+    This was written by Claude, and I fixed it up with feedback from Ruff and Flake8.
+    Maybe one day the app logic database will require something fancier, but this gets the job done now.
+
+    As you can see from the conversation with Claude, this was quite a simple task for it:
+    https://claude.ai/share/227d08ff-96a3-495a-9f56-509a1fd528f7
+    """
+
+    def __init__(self, db_path: str | Path) -> None:
+        """Initialize the database manager."""
+        self.db_path = db_path
+
+    async def initialize(self) -> None:
+        """Initialize the database and create the table if it doesn't exist."""
+        async with aiosqlite.connect(self.db_path) as db:
+            # Enable WAL mode for better concurrent access
+            await db.execute("PRAGMA journal_mode=WAL")
+
+            await db.execute("""
+                CREATE TABLE IF NOT EXISTS claimed_ids (
+                    id INTEGER PRIMARY KEY
+                )
+            """)
+            await db.commit()
+
+    async def claim_next_id(self) -> int:
+        """Atomically find the max id, increment it, and claim it. Returns the newly claimed ID.
+
+        This operation is atomic and multiprocess-safe because:
+        1. SQLite serializes writes by default
+        2. We use IMMEDIATE transaction to acquire write lock immediately
+        3. The entire operation happens in a single transaction
+        """
+        async with aiosqlite.connect(self.db_path) as db:
+            # Start an IMMEDIATE transaction to get write lock right away
+            await db.execute("BEGIN IMMEDIATE")
+
+            try:
+                # Find the current max ID
+                async with db.execute("SELECT MAX(id) FROM claimed_ids") as cursor:
+                    row = await cursor.fetchone()
+                    max_id = row[0] if row is not None and row[0] is not None else 0
+
+                # Calculate next ID
+                next_id = max_id + 1
+
+                # Insert the new ID
+                await db.execute("INSERT INTO claimed_ids (id) VALUES (?)", (next_id,))
+
+                # Commit the transaction
+                await db.commit()
+
+            except Exception:
+                await db.rollback()
+                raise
+
+            else:
+                return next_id
+
+    async def get_all_claimed_ids(self) -> list[int]:
+        """Retrieve all claimed IDs."""
+        async with (
+            aiosqlite.connect(self.db_path) as db,
+            db.execute("SELECT id FROM claimed_ids ORDER BY id") as cursor,
+        ):
+            rows = await cursor.fetchall()
+            return [row[0] for row in rows]
+
+    async def get_count(self) -> int:
+        """Get the total number of claimed IDs."""
+        async with aiosqlite.connect(self.db_path) as db, db.execute("SELECT COUNT(*) FROM claimed_ids") as cursor:
+            row = await cursor.fetchone()
+            if row is None:
+                raise ValueError("A SQL COUNT query should always return at least one row")  # noqa: EM101, TRY003
+            return row[0]

jehoctor_rag_demo-0.2.0/src/rag_demo/dirs.py

@@ -0,0 +1,14 @@
+from pathlib import Path
+
+from platformdirs import PlatformDirs
+
+_appdirs = PlatformDirs(appname="jehoctor-rag-demo", ensure_exists=True)
+
+
+def _ensure(dir_: Path) -> Path:
+    dir_.mkdir(parents=True, exist_ok=True)
+    return dir_
+
+
+DATA_DIR = _appdirs.user_data_path
+CONFIG_DIR = _appdirs.user_config_path