Skip to content

Latest commit

 

History

History
491 lines (355 loc) · 15.3 KB

File metadata and controls

491 lines (355 loc) · 15.3 KB
WebScout Logo

Webscout

Your All-in-One Python Toolkit for Web Search, AI Interaction, Digital Utilities, and More

Access diverse search engines, cutting-edge AI models, temporary communication tools, media utilities, developer helpers, and powerful CLI interfaces -- all through one unified library.

PyPI Version Monthly Downloads Total Downloads Python Version Ask DeepWiki


Table of Contents


Important

Webscout supports three types of compatibility:

  • Native: Webscout's own native API for maximum flexibility
  • OpenAI-Compatible: Use providers with OpenAI-compatible interfaces
  • Local LLMs: Run local models with OpenAI-compatible servers via Inferno

Note

Webscout supports 90+ AI providers including: OpenAI, GROQ, Gemini, Meta, DeepInfra, Cohere, Cerebras, HuggingFace, OpenRouter, Nvidia, Sambanova, PerplexityLabs, and many more. See the full Provider Matrix.

Telegram Group YouTube Buy Me A Coffee


Features

Search & AI

  • Multi-Engine Search -- DuckDuckGo, Bing, Brave, Yahoo, Yep, Yandex, Mojeek, Wikipedia. (Search Docs)
  • 90+ AI Providers -- Native, OpenAI-compatible, and local LLM interfaces. (Architecture)
  • AI-Powered Search -- Perplexity, IAsk, Monica, AyeSoul, WebPilotAI. (Provider Matrix)
  • OpenAI-Compatible API Server -- Serve any Webscout provider via OpenAI endpoints. (Server Docs)
  • Unified Python Client -- Auto-failover chat and image generation. (Client Docs)

Media & Content

  • Text-to-Image -- PollinationsAI, Together, Miragic, MagicStudio. (TTI Docs)
  • Text-to-Speech -- ElevenLabs, Deepgram, OpenAI FM, Parler, Qwen, MurfAI, and more. (Model Registry)
  • Speech-to-Text -- ElevenLabs STT. (Provider Matrix)
  • YouTube Toolkit -- Video downloads, transcription, API access. (Docs)
  • Weather Tools -- Detailed weather info with ASCII display. (Weather Docs)

Developer Tools

Privacy & Utilities

  • Temp Mail -- Disposable email via Emailnator, MailTM, TempMailIO.
  • Proxy Manager -- Automatic proxy rotation. (Architecture)
  • Awesome Prompts -- Curated system prompts for AI personas. (Prompts Docs)

Installation

pip (Standard)

pip install -U webscout

# With API server support
pip install -U "webscout[api]"

# With development tools
pip install -U "webscout[dev]"

uv (Recommended)

uv add webscout

# Run without installing
uv run webscout --help

# Install as global tool
uv tool install webscout

Docker

docker pull OEvortex/webscout:latest
docker run -it OEvortex/webscout:latest

See docs/DOCKER.md for full Docker deployment options including compose profiles.


Quick Start

AI Chat (No API Key)

from webscout import Meta

ai = Meta()
response = ai.chat("Explain quantum computing in simple terms")
print(response)

Web Search

from webscout import DuckDuckGoSearch

search = DuckDuckGoSearch()
results = search.text("best practices for API design", max_results=5)
for result in results:
    print(f"{result['title']}: {result['href']}")

Image Generation

from webscout.Provider.TTI import PollinationsAI

gen = PollinationsAI()
path = gen.generate_image(prompt="A serene mountain landscape at sunset")
print(f"Saved to: {path}")

See docs/getting-started.md for the full quick-start guide.


Command Line Interface

Webscout provides a rich CLI powered by Rich with multi-engine support.

webscout --help                       # List all commands
webscout version                      # Show version
webscout text -k "python programming" # DuckDuckGo search (default)
webscout images -k "mountains"        # Image search
webscout news -k "AI breakthrough" -t w  # News from last week
webscout weather -l "New York"        # Weather info
webscout translate -k "Hola" --to en  # Translation

Supported Engines

Category Engines
text ddg, bing, brave, yahoo, yep, mojeek, dogpile, wikipedia, yandex
images ddg, bing, brave, yahoo, yep
videos ddg, brave, yahoo
news ddg, bing, brave, yahoo
suggestions ddg, bing, brave, yahoo, yep
weather ddg, yahoo
answers ddg
translate ddg
maps ddg
# Use a specific engine
webscout text -k "climate change" -e bing
webscout text -k "quantum physics" -e wikipedia

Full CLI reference: docs/cli.md


AI Chat Providers

Native Providers (No Auth Required)

from webscout import Meta, Toolbaz, LLMChat, SonusAI, Netwrck, PiAI

ai = Meta()
print(ai.chat("What is the capital of France?"))

Authenticated Providers

from webscout import OpenAI, GROQ, GEMINI, Cohere, DeepInfra

groq = GROQ(api_key="your-key")
response = groq.chat("Write a Python function to sort a list")

OpenAI-Compatible Providers

from webscout.Provider.OPENAI import ChatGPT, Groq, DeepInfra

chatgpt = ChatGPT()  # No auth required
response = chatgpt.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}]
)

See Provider.md for the complete provider matrix with file locations.


Search Engines

from webscout import DuckDuckGoSearch, BingSearch, YepSearch, YahooSearch, BraveSearch

# DuckDuckGo
ddg = DuckDuckGoSearch()
results = ddg.text("python frameworks", max_results=5)

# Bing
bing = BingSearch()
results = bing.text("climate change solutions")

# Brave
brave = BraveSearch()
results = bravesearch.text("machine learning tutorials")

Search docs: docs/search.md


Text-to-Image

from webscout.Provider.TTI import PollinationsAI, TogetherImage

# PollinationsAI
poll = PollinationsAI()
poll.generate_image(prompt="A cyberpunk city at night")

# Together AI
together = TogetherImage()
together.generate_image(prompt="A robot playing chess")

TTI docs: docs/getting-started.md#image-generation


Text-to-Speech

from webscout.Provider.TTS import ElevenlabsTTS, ParlerTTS

tts = ElevenlabsTTS()
tts.text_to_speech("Hello, world!", voice="alloy")

TTS model registry: docs/models.md


OpenAI-Compatible API Server

Run a local FastAPI server that serves any Webscout provider through standard OpenAI endpoints.

# Start the server
webscout-server

# Custom config
webscout-server --port 8080 --host 0.0.0.0 --debug

Use with the OpenAI Python Client

from openai import OpenAI

client = OpenAI(api_key="dummy", base_url="http://localhost:8000/v1")

response = client.chat.completions.create(
    model="ChatGPT/gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

Docker Deployment

docker-compose up webscout-api
docker-compose -f docker-compose.yml -f docker-compose.no-auth.yml up webscout-api

Full server docs: docs/openai-api-server.md | Docker: docs/DOCKER.md


Python Client

The unified Client class provides auto-failover across providers with smart model resolution.

from webscout.client import Client

client = Client(print_provider_info=True)

# Auto provider + model selection
resp = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Summarize Webscout."}]
)
print(resp.choices[0].message.content)

# Streaming
stream = client.chat.completions.create(
    model="ChatGPT/gpt-4o-mini",
    messages=[{"role": "user", "content": "Write a limerick about Python."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

# Image generation
img = client.images.generate(prompt="A neon owl", model="auto", size="1024x1024")
print(img.data[0].url)

Client docs: docs/client.md


Tool Calling

Webscout has a built-in tool calling system that works with any provider.

from webscout.Provider.Apriel import Apriel
from webscout.AIbase import Tool

def get_weather(city: str) -> str:
    return f"Weather in {city}: Sunny, 25C"

weather_tool = Tool(
    name="get_weather",
    description="Get current weather for a city.",
    parameters={"city": {"type": "string", "description": "City name."}},
    implementation=get_weather,
)

ai = Apriel(tools=[weather_tool])
print(ai.chat("What is the weather in London?"))

Tool calling docs: docs/tool-calling.md


Model Registry

Enumerate available models across all providers.

from webscout import model

# All LLM models
all_models = model.llm.list()
print(f"Total: {len(all_models)}")

# Models by provider
summary = model.llm.summary()
for provider, count in summary.items():
    print(f"  {provider}: {count}")

# TTS voices
voices = model.tts.list()
print(f"Total voices: {len(voices)}")

Model registry docs: docs/models.md


Developer Tools

Tool Description Docs
SwiftCLI CLI framework with decorators docs/swiftcli.md
Scout HTML parser & web crawler docs/scout.md
LitPrinter Styled debug printing docs/litprinter.md
LitAgent User-agent rotation docs/litagent.md
GitAPI GitHub data extraction docs/gitapi.md
GGUF Model conversion & quantization docs/gguf.md
ZeroArt ASCII art generator docs/zeroart.md
Weather Weather toolkit docs/weather.md
Decorators @timeIt and @retry docs/decorators.md
Sanitize Stream sanitization docs/sanitize.md
Prompts System prompt manager docs/awesome-prompts.md

Documentation

Resource Description
Getting Started Installation, first chat, web search, image generation
Architecture System design, layers, and data flows
CLI Reference All CLI commands and options
Python Client Unified client with auto-failover
API Server OpenAI-compatible FastAPI server
Model Registry Enumerate LLM, TTS, TTI models
Tool Calling Function calling with any provider
Search Docs Multi-engine search API
Scout HTML parser and crawler
Provider Development Create custom providers
Deployment Production deployment guide
Docker Docker setup and compose profiles
Inferno Local LLM server
Troubleshooting Common issues and solutions
Contributing How to contribute
Provider Matrix Complete provider listing
Docs Hub Full documentation index

Contributing

See docs/contributing.md for guidelines.

  1. Fork the repository
  2. Create a feature branch
  3. Make changes with descriptive commits
  4. Submit a pull request

License

Apache-2.0. See LICENSE.md.


Made with by the Webscout team