ollama-web 1.0.0__tar.gz

ollama_web-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Build, Package & Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-pypi:
+    name: Build & Publish to PyPI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install build tools
+        run: pip install --upgrade build twine
+      - name: Build wheel and sdist
+        run: python -m build
+      - name: Publish to PyPI
+        if: startsWith(github.ref, 'refs/tags/v')
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload --skip-existing dist/*
+
+  build-binaries:
+    name: Build Standalone Binaries
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            artifact_name: ollama-web-linux-x86_64
+            binary_name: ollama-web
+          - os: macos-latest
+            artifact_name: ollama-web-macos-universal
+            binary_name: ollama-web
+          - os: windows-latest
+            artifact_name: ollama-web-windows-x64.exe
+            binary_name: ollama-web.exe
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install dependencies & PyInstaller
+        run: |
+          pip install --upgrade pyinstaller
+          pip install .
+      - name: Build standalone executable
+        run: |
+          pyinstaller --onefile --name ollama-web src/ollama_web/__main__.py
+      - name: Rename and Stage Binary
+        shell: bash
+        run: |
+          if [ "${{ runner.os }}" = "Windows" ]; then
+            mv dist/ollama-web.exe dist/${{ matrix.artifact_name }}
+          else
+            chmod +x dist/ollama-web
+            mv dist/ollama-web dist/${{ matrix.artifact_name }}
+          fi
+      - name: Upload to GitHub Release
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/${{ matrix.artifact_name }}

ollama_web-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.installed.cfg
+*.egg
+build/
+dist/
+.env
+.venv/
+env/
+venv/

ollama_web-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cicada & Antigravity Community
+
+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.

ollama_web-1.0.0/PKG-INFO

@@ -0,0 +1,305 @@
+Metadata-Version: 2.5
+Name: ollama-web
+Version: 1.0.0
+Summary: Universal live web search, deep HTML table scraper, desktop GUI proxy daemon, and MCP server for Ollama on Linux, macOS, and Windows.
+Project-URL: Homepage, https://github.com/AjarnSpencer/ollama-web
+Project-URL: Repository, https://github.com/AjarnSpencer/ollama-web
+Project-URL: Issues, https://github.com/AjarnSpencer/ollama-web/issues
+Author-email: Ajarn Spencer Littlewood <ajarnspencer@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: beautifulsoup4>=4.11.0
+Requires-Dist: ddgs>=1.0.0
+Requires-Dist: lxml>=4.9.0
+Requires-Dist: requests>=2.28.0
+Provides-Extra: all
+Requires-Dist: fastapi>=0.100.0; extra == 'all'
+Requires-Dist: ollama-speak>=1.0.0; extra == 'all'
+Requires-Dist: uvicorn>=0.22.0; extra == 'all'
+Provides-Extra: proxy
+Requires-Dist: fastapi>=0.100.0; extra == 'proxy'
+Requires-Dist: uvicorn>=0.22.0; extra == 'proxy'
+Provides-Extra: speak
+Requires-Dist: ollama-speak>=1.0.0; extra == 'speak'
+Description-Content-Type: text/markdown
+
+# 🌐 ollama-web (`oweb`)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+[![Ollama](https://img.shields.io/badge/Ollama-Local%20AI-orange.svg)](https://ollama.ai/)
+[![Zero API Keys](https://img.shields.io/badge/API%20Keys-Zero%20Required-green.svg)](#zero-key-architecture)
+
+> **Universal live web search, deep HTML table scraper, desktop GUI proxy daemon, and MCP server for Ollama on Linux, macOS, and Windows.**
+
+`ollama-web` bridges the gap between local AI and the live internet. It works universally across **any model** you have downloaded locally (`llama3.1`, `dolphin-llama3`, `gemma2`, `qwen2.5`, `mistral`, etc.), requires **zero API keys**, converts sports scores and fixture lists into structured markdown tables, and provides a **transparent proxy daemon** so desktop GUI apps (like Chatbox, LibreChat, and Open WebUI) get real-time internet search out of the box.
+
+---
+
+## ✨ Features
+
+- **Universal Model Agnostic:** Automatically queries your local Ollama daemon (`/api/tags`). Never assumes specific models are installed; dynamically resolves and fuzzy-matches whatever you have on disk.
+- **Interactive First-Run Setup:** If you don't specify a model, an interactive numbered menu shows your local models and lets you select a default with one keystroke, remembered across sessions.
+- **Zero API Key Requirement:** Combines DuckDuckGo and Google News RSS out of the box. Zero accounts, zero credit cards, zero rate-limit blocks.
+- **Deep HTML Table & JavaScript Scraper:** Automatically converts HTML tables into clean Markdown tables, and falls back to Jina Reader (`r.jina.ai`) for JavaScript-rendered scoreboards.
+- **Explicit URL Deep Reader:** Pass any URL in your prompt to scrape full page text (up to 7,500 chars) directly into your model context.
+- **Real-Time Terminal Streaming (Never Stare at a Blank Screen):** Live search queries and page-reading progress appear immediately so you always know what the tool is doing. Model tokens stream live token-by-token directly to your terminal—fully visible, readable, and copy-pasteable.
+- **Zero-Flag Spoken Audio:** Answers are automatically spoken aloud as soon as generation completes when the lightweight companion `ollama-speak` is installed. No complex pipes or extra flags needed! If you prefer silence, simply pass `-q` or `--mute`.
+- **Unix Composable Voice:** Seamlessly pairs with companion [`ollama-speak`](https://github.com/AjarnSpencer/ollama-speak) for multilingual spoken readout via pipes (`| ollama-speak`) or automatic background narration. Pipes never swallow text!
+- **Syntax Guardrails:** Proactively detects common CLI slip-ups like unclosed quotes (`"`) or accidental `-m web` flags without crashing.
+- **Transparent Desktop GUI Proxy (`--proxy`):** Runs a lightweight local proxy on `127.0.0.1:11435`. Point any Ollama GUI client (Ollama Desktop, Chatbox, LibreChat, Open WebUI) to port 11435 for instant live web search.
+- **Native MCP Server (`--mcp`):** Plugs directly into Claude Desktop, Cursor, and Antigravity as a Model Context Protocol tool provider.
+
+---
+
+## 🚀 Quickstart and Installation
+
+### Option 1 (Recommended) — One-Line Turnkey Installer
+Works cleanly on fresh Linux, macOS, and WSL systems without requiring manual virtual environments or tripping PEP 668 system python locks.
+
+**Linux and macOS:**
+```bash
+curl -fsSL https://raw.githubusercontent.com/AjarnSpencer/ollama-web/main/install.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/AjarnSpencer/ollama-web/main/install.ps1 | iex
+```
+
+What the turnkey installer does:
+- Sets up an isolated virtual environment in `~/.local/share/ollama-web/venv` (zero system conflicts).
+- Symlinks `ollama-web` and `oweb` launchers into `~/.local/bin/`.
+- Configures user `PATH` if not already set.
+
+---
+
+### Option 2 — Install from GitHub with pipx or pip
+If you prefer managing Python CLI tools via `pipx` (recommended by Python Packaging Authority for standalone tools) or an active virtual environment:
+
+**Using pipx (Recommended for Python users):**
+```bash
+pipx install git+https://github.com/AjarnSpencer/ollama-web.git
+```
+
+**Using pip in a virtual environment:**
+```bash
+pip install git+https://github.com/AjarnSpencer/ollama-web.git
+```
+
+---
+
+### Option 3 — Standalone Single-File Binaries (Zero Python Required)
+Download the standalone executable for your operating system from the [Latest Releases](https://github.com/AjarnSpencer/ollama-web/releases):
+- **Windows:** `ollama-web-windows-x64.exe`
+- **macOS:** `ollama-web-macos-universal`
+- **Linux:** `ollama-web-linux-x86_64` / `ollama-web-linux-arm64`
+
+---
+
+### 📦 Publishing to PyPI (For Maintainers)
+To unlock global installation via `pip install ollama-web` worldwide:
+1. Build distributions: `python3 -m build` (generates wheels and tarballs in `dist/`).
+2. Upload to PyPI: `twine upload dist/*` with your PyPI token.
+Once published, users can install directly via `pip install --upgrade ollama-web`.
+
+---
+
+## 📖 Complete Command Line Reference and Flags
+
+`ollama-web` accepts flexible argument ordering. You can pass flags anywhere or use positional tokens.
+
+### Flags Table
+
+| Flag | Short | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--model MODEL` | `-m` | `config.default_model` | Specify target Ollama model (fuzzy-matched against local models) |
+| `--install-hook` | | | Seamlessly add live search and voice to native `ollama run` in your terminal |
+| `--remove-hook` | | | Remove terminal shell hook from `.bashrc` / `.zshrc` |
+| `--mute` | `-q`, `--quiet` | `False` | Mute spoken audio output (silent text-only terminal mode) |
+| `--speak` | `-s` | `True` (auto) | Force spoken voice output (voice is already ON by default if companion is installed) |
+| `--proxy` | | `False` | Launch transparent desktop GUI proxy daemon |
+| `--port PORT` | | `11435` | Custom TCP port for the proxy daemon |
+| `--mcp` | | `False` | Run as standard Model Context Protocol (stdio MCP) server |
+| `--list-models` | `-l` | | Print table of all locally installed Ollama models and exit |
+| `--no-search` | | `False` | Query model directly without live web search |
+| `--think` | | `False` | Enable reasoning thinking stream (DeepSeek-R1, QwQ, etc.) |
+| `-h`, `--help` | | | Show full help manual and flag descriptions |
+
+---
+
+## 💡 Practical Tutorials and Workflows
+
+### Tutorial 1 — Quick Real-Time Web Search (Text + Automatic Voice)
+Run a live web search using your configured default model:
+```bash
+ollama-web "What are the latest breakthroughs in fusion energy this week?"
+```
+`ollama-web` will:
+1. Search live web sources and Google News RSS.
+2. Scrape top resulting pages with live status updates on stderr so you know what is happening.
+3. Stream tokens directly to your terminal in real time (fully readable and copy-pasteable).
+4. Automatically speak the summary aloud when finished if companion `ollama-speak` is installed.
+
+---
+
+### Tutorial 2 — Silent Terminal Mode (`-q` / `--mute`)
+If you want to read in silence without audio playback:
+```bash
+ollama-web -q "Latest developments in quantum computing"
+```
+Or use `--mute` anytime.
+
+---
+
+### Tutorial 3 — Native Terminal Integration (`ollama-web --install-hook`)
+If you want your standard `ollama` terminal command to automatically gain live web search and voice without changing your habits:
+```bash
+ollama-web --install-hook
+source ~/.bashrc   # or source ~/.zshrc
+```
+Now, whenever you use `ollama` in the terminal:
+- **One-shot prompt with live search + voice:**
+  ```bash
+  ollama run llama3.1 "What are today's top tech headlines?"
+  ```
+- **Direct web search shortcut:**
+  ```bash
+  ollama web "Champions League fixtures this week"
+  ```
+- **Standard Ollama commands:**
+  `ollama list`, `ollama pull`, and interactive sessions continue to pass through directly to the native `ollama` binary without modification.
+
+To remove the hook at any time:
+```bash
+ollama-web --remove-hook
+```
+
+---
+
+### Tutorial 4 — Targeting a Specific Local Model
+You can specify the model either with `-m` or by typing the model name directly as the first argument:
+```bash
+# Using the -m flag:
+ollama-web -m dolphin-llama3:70b "Latest UEFA Champions League results and standings"
+
+# Or using natural positional syntax:
+ollama-web qwen2.5:32b "Summarize today's top artificial intelligence headlines"
+```
+
+---
+
+### Tutorial 5 — Extracting HTML Tables into Markdown
+Ask for tables directly—`ollama-web` automatically converts complex HTML tables from web pages into clean Markdown tables:
+```bash
+ollama-web -m llama3.1 "Latest 5 English Premier League results and table standings"
+```
+
+---
+
+### Tutorial 6 — Deep Scraping Explicit URLs
+If you want your local LLM to read and analyze an exact web article or blog post, simply include the URL in your prompt:
+```bash
+ollama-web "https://arstechnica.com/science/ Summarize the lead space exploration article"
+```
+`ollama-web` will detect the URL, fetch its full clean text (up to 7,500 characters), and feed it directly into the prompt context alongside any web search results.
+
+---
+
+### Tutorial 7 — Reasoning Models with Thinking Mode (`--think`)
+For reasoning models (like `deepseek-r1`, `qwq`, or thinking-enabled checkpoints), pass `--think` to stream internal reasoning tokens before the final answer:
+```bash
+ollama-web -m deepseek-r1:14b --think "Analyze the current economic trends from today's market news"
+```
+
+---
+
+### Tutorial 8 — Pure Local Inference Without Web Search (`--no-search`)
+Need to ask your model a general programming or logic question without scraping the web? Pass `--no-search`:
+```bash
+ollama-web --no-search -m llama3.1 "Write a Python script to sort a dictionary by values"
+```
+
+---
+
+### Tutorial 9 — Interactive REPL Session
+Running `ollama-web` without arguments launches an interactive shell with conversation memory:
+```bash
+ollama-web
+```
+Inside the interactive prompt:
+- `/model <name>` — Switch the active local model on the fly
+- `/models` — List all local Ollama models and their parameters
+- `/mute` or `/speak` — Toggle companion voice audio on or off
+- `/clear` — Reset conversational memory
+- `/exit` — Quit the session
+
+---
+
+### Tutorial 10 — Spoken Voice with Companion `ollama-speak`
+`ollama-web` pairs natively with [`ollama-speak`](https://github.com/AjarnSpencer/ollama-speak):
+
+**Method A — Zero-Flag Automatic Voice:**
+Just run `ollama-web "..."`. The terminal prints text live while you listen to the spoken answer.
+
+**Method B — Unix Pipe (Zero-Swallow Output):**
+```bash
+ollama-web "Who won yesterday's basketball matches?" | ollama-speak
+```
+`ollama-speak` mirrors the text directly to `stdout` so pipes never swallow your screen output.
+
+---
+
+### Tutorial 11 — Transparent Desktop GUI Proxy (`--proxy`)
+Enable live web search inside your favorite Ollama desktop apps (Chatbox, LibreChat, Open WebUI, Jan.ai):
+
+1. **Start the proxy in a background terminal:**
+   ```bash
+   ollama-web --proxy --port 11435
+   ```
+2. **Point your desktop app's Ollama Base URL to port 11435:**
+   - Change `http://127.0.0.1:11434` to `http://127.0.0.1:11435`
+3. **Submit any question from your GUI:**
+   The proxy automatically searches the web, deep-scrapes tables, injects context, and streams tokens back into your graphical desktop app!
+
+---
+
+### Tutorial 12 — Model Context Protocol (MCP) in Claude Desktop
+To expose web search tools directly to Claude Desktop, Cursor, or Antigravity, add this to your `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "ollama-web": {
+      "command": "ollama-web",
+      "args": ["--mcp"]
+    }
+  }
+}
+```
+
+---
+
+## ⚙️ Persistent Configuration
+
+Your defaults are saved in `~/.config/ollama-web/config.json` (or `%APPDATA%\ollama-web\config.json` on Windows):
+
+```json
+{
+  "default_model": "llama3.1:70b",
+  "search_mode": "auto",
+  "num_ctx": 16384,
+  "max_search_results": 5,
+  "voice_enabled": true
+}
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions, issues, and feature requests are welcome! Feel free to check the [Issues page](https://github.com/AjarnSpencer/ollama-web/issues).
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).