open-agent-search 1.0.0__tar.gz

open_agent_search-1.0.0/.dockerignore

@@ -0,0 +1,24 @@
+# Ignore Python/build artifacts in Docker image
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+.env.*
+.git/
+.github/
+.idea/
+.vscode/
+*.swp
+Thumbs.db
+.DS_Store
+tests/
+scripts/
+htmlcov/
+.coverage
+.pytest_cache/
+.mypy_cache/
+locust_report_*.html

open_agent_search-1.0.0/.env.example

@@ -0,0 +1,11 @@
+# Application environment: development | production
+APP_ENV=production
+
+# Server
+HOST=0.0.0.0
+PORT=8000
+LOG_LEVEL=info
+
+# DDGS settings
+DDGS_TIMEOUT=10
+# DDGS_PROXY=socks5h://127.0.0.1:9150  # Optional: Tor proxy

open_agent_search-1.0.0/.github/instructions/copilot.instructions.md

@@ -0,0 +1,23 @@
+---
+# description: Describe when these instructions should be loaded
+applyTo: "**" # when provided, instructions will automatically be added to the request context when the pattern matches an attached file
+---
+
+# Open Agent Search (OAS)
+
+Our project, **Open Agent Search**, is the definitive open-source search solution for the AI agent ecosystem. Our mission is to provide **unfiltered, agent-neutral access to the world's knowledge**.
+
+## Philosophy & Manners
+
+- **Independence**: We are not bound to any single agent framework (like OpenClaw, LangChain, or AutoGen). We stand independently as the sensory organ for AI.
+- **Privacy & Accuracy**: We prioritize privacy (leveraging DuckDuckGo) and accuracy above all else.
+- **Universal Access**: We support all deployment methods (HTTP, MCP, Pip, Docker, Vercel) to ensure any agent, anywhere, can see the world.
+- **Respect for the Ecosystem**: While we support specific frameworks (like OpenClaw via `openclaw-search`), we maintain our own identity as a foundational tool, not just a plugin.
+
+## Technical Context
+
+- We use **uv** for managing the virtual environment, running the server, and running tests.
+- When suggesting commands, prefer `uv run` over direct python execution.
+- We support OpenClaw integration natively.
+
+Keep this philosophy in mind while coding. We are building the eyes of the AI.

open_agent_search-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+    push:
+        branches: [main]
+    pull_request:
+        branches: [main]
+
+jobs:
+    lint:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - name: Install uv
+              uses: astral-sh/setup-uv@v7
+              with:
+                  version: ">=0.6.0"
+                  enable-cache: true
+            - name: Install Python
+              run: uv python install
+            - name: Install dependencies
+              run: uv sync --locked --dev
+            - run: uv run ruff check .
+            - run: uv run ruff format --check .
+
+    test:
+        runs-on: ubuntu-latest
+        needs: lint
+        strategy:
+            matrix:
+                python-version: ["3.12", "3.13"]
+        steps:
+            - uses: actions/checkout@v4
+            - name: Install uv
+              uses: astral-sh/setup-uv@v7
+              with:
+                  version: ">=0.6.0"
+                  python-version: ${{ matrix.python-version }}
+                  enable-cache: true
+            - name: Install dependencies
+              run: uv sync --locked --all-extras --dev
+            - name: Run tests
+              run: uv run pytest -v

open_agent_search-1.0.0/.github/workflows/docs.yml

@@ -0,0 +1,32 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: ">=0.6.0"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install docs dependencies
+        run: uv sync --group docs
+
+      - name: Build & deploy to GitHub Pages
+        run: uv run mkdocs gh-deploy --force

open_agent_search-1.0.0/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Environment variables
+.env
+.env.local
+.env.production
+
+# OS files
+Thumbs.db
+.DS_Store
+
+# Testing & coverage
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.pytest_cache/
+.mypy_cache/
+
+# Locust reports
+locust_report_*.html
+
+# Deployment
+.vercel/
+
+# Python build
+.Python
+
+# MkDocs
+site/

open_agent_search-1.0.0/.prettierignore

@@ -0,0 +1,3 @@
+docs/**
+site/**
+*.md

open_agent_search-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

open_agent_search-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing to Open Agent Search
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/Jayanth-MKV/open-agent-search.git
+cd open-agent-search
+
+# Install uv (if you haven't already)
+# https://docs.astral.sh/uv/getting-started/installation/
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Sync all dependencies (including dev tools)
+uv sync --dev
+```
+
+## Running the Server
+
+```bash
+uv run open-agent-search
+
+# With hot reload for development
+uv run uvicorn open_agent_search.app:app --reload --host 0.0.0.0 --port 8000
+```
+
+## Running Tests
+
+```bash
+uv run pytest
+```
+
+## Code Style
+
+- Follow [PEP 8](https://peps.python.org/pep-0008/) conventions.
+- Use type hints for all function signatures.
+- Format code with [Ruff](https://docs.astral.sh/ruff/):
+
+```bash
+uv run ruff check .
+uv run ruff format .
+```
+
+## Pull Request Process
+
+1. Fork the repo and create your branch from `main`.
+2. Add or update tests for any new functionality.
+3. Make sure `uv run ruff check .` and `uv run pytest` pass.
+4. Update the README if you changed any public API or behaviour.
+5. Open a pull request with a clear description of your changes.
+
+## Adding Dependencies
+
+```bash
+# Add a runtime dependency
+uv add <package>
+
+# Add a dev-only dependency
+uv add --group dev <package>
+```
+
+## Reporting Issues
+
+- Use [GitHub Issues](https://github.com/Jayanth-MKV/open-agent-search/issues).
+- Include steps to reproduce, expected behaviour, and actual behaviour.
+- Mention your Python version and OS.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

open_agent_search-1.0.0/DEVELOPER.md

@@ -0,0 +1,135 @@
+# Developer TLDR
+
+Quick reference for repo owner commands. No fluff.
+
+---
+
+## Setup
+
+```bash
+uv sync --dev --group docs   # everything: runtime + dev + docs
+```
+
+---
+
+## Day-to-Day
+
+```bash
+# Run server (pick one)
+uv run open-agent-search                                              # production
+uv run uvicorn open_agent_search.app:app --reload --host 0.0.0.0 --port 8000  # dev w/ hot reload
+uv run oas-mcp                                                 # MCP stdio only
+
+# Lint & format
+uv run ruff check .              # lint
+uv run ruff check --fix .        # lint + auto-fix
+uv run ruff format .             # format
+uv run ruff format --check .     # format dry-run (CI uses this)
+
+# Tests
+uv run pytest -v                 # unit tests
+uv run pytest -x                 # stop on first failure
+
+# Load tests
+uv run locust -f tests/locustfile.py --host=http://localhost:8000              # interactive UI
+uv run locust -f tests/locustfile.py --host=http://localhost:8000 \
+  --users 50 --spawn-rate 5 --run-time 2m --headless                           # headless
+```
+
+---
+
+## Docs (GitHub Pages)
+
+Site: `https://jayanth-mkv.github.io/open-agent-search/`
+
+```bash
+# Install docs deps (first time)
+uv sync --group docs
+
+# Local preview (live reload at http://127.0.0.1:8000)
+uv run mkdocs serve
+
+# Build (output → site/)
+uv run mkdocs build
+
+# Validate built HTML (checks grid card layout + emoji rendering)
+.\scripts\check_docs.ps1
+
+# Manual deploy to gh-pages branch
+uv run mkdocs gh-deploy --force
+```
+
+**Auto-deploy:** pushing to `main` with changes in `docs/` or `mkdocs.yml` triggers the `Deploy Docs` workflow. It builds and pushes to the `gh-pages` branch automatically.
+
+> **⚠ Do not run a markdown formatter on `docs/`.**  
+> Material for MkDocs grid cards require `    ---` separators with 4-space indentation inside list items. Auto-formatters (Prettier, Markdown All in One) collapse this to 2-space + `***`, breaking the card layout. VS Code format-on-save is disabled for `.md` files via `.vscode/settings.json`, and `.prettierignore` excludes `docs/`. Always run `.\scripts\check_docs.ps1` after editing docs.
+
+**First-time GitHub Pages setup:**
+
+1. Go to repo **Settings → Pages**
+2. Source: **Deploy from a branch**
+3. Branch: **gh-pages** / `/(root)`
+4. Save
+
+---
+
+## CI Workflows
+
+### `ci.yml` — Lint + Test
+
+| Trigger      | `push` / `pull_request` to `main`                          |
+| ------------ | ---------------------------------------------------------- |
+| **lint** job | `ruff check .` + `ruff format --check .`                   |
+| **test** job | `pytest -v` on Python 3.12 & 3.13 (runs after lint passes) |
+
+### `docs.yml` — Deploy Docs
+
+| Trigger        | `push` to `main` (only `docs/**`, `mkdocs.yml`) + manual `workflow_dispatch` |
+| -------------- | ---------------------------------------------------------------------------- |
+| **deploy** job | `mkdocs gh-deploy --force` → pushes built site to `gh-pages` branch          |
+
+---
+
+## Docker
+
+```bash
+docker compose up -d             # build + run
+docker compose logs -f           # tail logs
+docker compose down              # stop
+docker compose watch             # dev mode (live sync)
+docker build -t open-agent-search .    # manual build
+```
+
+---
+
+## Dependencies
+
+```bash
+uv add <pkg>               # add runtime dep
+uv add --group dev <pkg>   # add dev dep
+uv add --group docs <pkg>  # add docs dep
+uv lock                    # regenerate lockfile
+uv sync --locked           # install from lockfile (CI mode)
+```
+
+---
+
+## Publish to PyPI
+
+```bash
+uv build                        # builds wheel + sdist → dist/
+uv publish                      # upload to PyPI (needs token)
+```
+
+---
+
+## Key URLs (local)
+
+| URL                          | What                        |
+| ---------------------------- | --------------------------- |
+| http://localhost:8000        | API root                    |
+| http://localhost:8000/docs   | Swagger UI                  |
+| http://localhost:8000/redoc  | ReDoc                       |
+| http://localhost:8000/health | Health check                |
+| http://localhost:8000/ai/mcp | MCP endpoint                |
+| http://127.0.0.1:8000        | mkdocs serve (docs preview) |

open_agent_search-1.0.0/Dockerfile

@@ -0,0 +1,37 @@
+FROM python:3.12-slim AS builder
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+WORKDIR /app
+
+# Enable bytecode compilation for faster startup
+ENV UV_COMPILE_BYTECODE=1
+# Use copy mode (cache mount is on a separate filesystem)
+ENV UV_LINK_MODE=copy
+
+# Install dependencies first (better layer caching)
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --locked --no-install-project --no-dev
+
+# Copy the project into the image
+COPY . /app
+
+# Install the project itself
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --locked --no-dev --no-editable
+
+# --- Runtime stage ---
+FROM python:3.12-slim
+
+# Copy the virtual environment from the builder
+COPY --from=builder /app/.venv /app/.venv
+
+# Place the venv on PATH so entry points are available
+ENV PATH="/app/.venv/bin:$PATH"
+
+EXPOSE 8000
+
+CMD ["open-agent-search"]

open_agent_search-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jayanth-MKV
+
+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.

open_agent_search-1.0.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: open-agent-search
+Version: 1.0.0
+Summary: A production-ready metasearch API and MCP server powered by DuckDuckGo
+Project-URL: Homepage, https://github.com/Jayanth-MKV/open-agent-search
+Project-URL: Documentation, https://jayanth-mkv.github.io/open-agent-search/
+Project-URL: Repository, https://github.com/Jayanth-MKV/open-agent-search
+Project-URL: Issues, https://github.com/Jayanth-MKV/open-agent-search/issues
+Author: Jayanth-MKV
+License: MIT
+License-File: LICENSE
+Keywords: agent-search,duckduckgo,fastapi,mcp,open-agent-search,openclaw
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Requires-Python: >=3.12
+Requires-Dist: beautifulsoup4>=4.14.3
+Requires-Dist: ddgs>=9.8.0
+Requires-Dist: fastapi[standard]>=0.121.0
+Requires-Dist: fastmcp>=2.14.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: slowapi>=0.1.9
+Description-Content-Type: text/markdown
+
+# Open Agent Search (OAS)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.12+](https://img.shields.io/badge/Python-3.12%2B-blue.svg)](https://www.python.org/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.121+-green.svg)](https://fastapi.tiangolo.com/)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://jayanth-mkv.github.io/open-agent-search/)
+
+The **sensory organ** for the AI agent ecosystem. An independent, privacy-first search layer providing unfiltered access to the world's knowledge via [MCP](https://modelcontextprotocol.io/) and HTTP API.
+
+> **Open Agent Search is an independent foundational tool.** We are not bound to any single agent framework but support them all (including OpenClaw via `openclaw-search`). Our mission is accuracy, speed, and universal access.
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FJayanth-MKV%2Fopen-agent-search&project-name=open-agent-search&repository-name=open-agent-search)
+
+> **[Read the full documentation →](https://jayanth-mkv.github.io/open-agent-search/)**
+
+---
+
+## Quick Start
+
+### Zero-install (MCP)
+
+```bash
+# Works instantly — no clone or install needed
+uvx --from open-agent-search oas-mcp
+```
+
+### Install & Run
+
+```bash
+# Install from PyPI
+uv pip install open-agent-search
+
+# Start the HTTP API + MCP server
+open-agent-search
+# → http://localhost:8000 (API)
+# → http://localhost:8000/ai/mcp (MCP)
+```
+
+### From Source
+
+```bash
+git clone https://github.com/Jayanth-MKV/open-agent-search.git
+cd open-agent-search
+uv sync
+uv run open-agent-search
+```
+
+### Docker
+
+```bash
+docker compose up -d
+```
+
+---
+
+## What's Included
+
+| Feature                 | Description                                                                    |
+| ----------------------- | ------------------------------------------------------------------------------ |
+| **REST API**            | 8 search endpoints (text, images, videos, news, books, unified, content fetch) |
+| **MCP Server**          | 8 tools accessible via stdio or HTTP — works with every major AI coding client |
+| **OpenClaw Compatible** | Works as an OpenClaw skill via stdio MCP transport                             |
+| **Rate Limiting**       | Per-IP rate limits with configurable dev/prod profiles                         |
+| **One-Click Deploy**    | Deploy to Vercel in seconds                                                    |
+| **Docker**              | Multi-stage Dockerfile + Compose with health checks                            |
+
+---
+
+## MCP Client Setup
+
+> **[Full setup guides →](https://jayanth-mkv.github.io/open-agent-search/mcp/)**
+
+Add to any MCP client with `uvx` — zero install:
+
+```json
+{
+  "mcpServers": {
+    "open-agent-search": {
+      "command": "uvx",
+      "args": ["--from", "open-agent-search", "oas-mcp"]
+    }
+  }
+}
+```
+
+Guides available for: **Claude Desktop** · **Claude Code** · **Cursor** · **VS Code** · **Windsurf** · **OpenClaw** · [and more](https://jayanth-mkv.github.io/open-agent-search/mcp/other-clients/)
+
+---
+
+## API Endpoints
+
+| Endpoint                      | Method | Description                        |
+| ----------------------------- | ------ | ---------------------------------- |
+| `/api/search/text`            | GET    | Web / text search                  |
+| `/api/search/images`          | GET    | Image search                       |
+| `/api/search/videos`          | GET    | Video search                       |
+| `/api/search/news`            | GET    | News search                        |
+| `/api/search/books`           | GET    | Book search                        |
+| `/api/search/all`             | GET    | Unified parallel search            |
+| `/api/content/fetch`          | GET    | Fetch & extract content from a URL |
+| `/api/content/fetch-multiple` | POST   | Fetch content from multiple URLs   |
+| `/ai/mcp`                     | —      | MCP server endpoint                |
+
+> **[Full API reference →](https://jayanth-mkv.github.io/open-agent-search/api/endpoints/)**
+
+---
+
+## Documentation
+
+- [Installation](https://jayanth-mkv.github.io/open-agent-search/getting-started/installation/)
+- [Quick Start](https://jayanth-mkv.github.io/open-agent-search/getting-started/quickstart/)
+- [MCP Integration](https://jayanth-mkv.github.io/open-agent-search/mcp/)
+- [API Reference](https://jayanth-mkv.github.io/open-agent-search/api/endpoints/)
+- [Docker Deployment](https://jayanth-mkv.github.io/open-agent-search/deployment/docker/)
+- [Vercel Deployment](https://jayanth-mkv.github.io/open-agent-search/deployment/vercel/)
+- [Contributing](https://jayanth-mkv.github.io/open-agent-search/contributing/)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE)