Metadata-Version: 2.4
Name: hyperbeam
Version: 0.1.2
Summary: Hyperbeam is a Python library designed to provide intelligent search tooling.
Author-email: Sean McCurdy <sean@hyprbm.com>
License: MIT License
        
        Copyright (c) 2025 hyprbm, inc.
        
        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.
        
Project-URL: Homepage, https://github.com/hyprbm/hyperbeam
Project-URL: Repository, https://github.com/hyprbm/hyperbeam
Project-URL: Bug Tracker, https://github.com/hyprbm/hyperbeam/issues
Keywords: search,web search,duckduckgo,scraperapi,hyperbeam,intelligent search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: duckduckgo-search>=8.0.2
Requires-Dist: scraperapi-sdk>=1.5.3
Requires-Dist: bs4>=0.0.2
Requires-Dist: twine>=6.1.0
Provides-Extra: development
Requires-Dist: black[jupyter]>=25.1.0; extra == "development"
Requires-Dist: flake8>=7.2.0; extra == "development"
Requires-Dist: isort>=6.0.1; extra == "development"
Dynamic: license-file

# hyperbeam

Hyperbeam is a Python library designed to provide intelligent search tooling. 

## Features

- Search via DuckDuckGo for text, news, videos, and images.
- Optional integration with ScraperAPI for proxied requests.
- Standardized output schema for search results across different modes.
- Site-specific search limiting.

## Prerequisites

- Python 3.10+ (as seen in your virtual environment path)
- [uv](https://github.com/astral-sh/uv): A fast Python package installer and resolver, written in Rust.
- A ScraperAPI API key.

## Installation

1.  **Clone the repository:**
    ```bash
    git clone https://github.com/hyprbm/hyperbeam.git
    cd hyperbeam
    ```

2.  **Set up the environment variable for ScraperAPI:**
    Create a `.env` file in the root of the project directory and add your ScraperAPI key:
    ```
    SCRAPERAPI_API_KEY="your_actual_api_key_here"
    ```
    Alternatively, you can set this environment variable directly in your system.
    The `src/web_search.py` module will raise a ValueError if this key is not set.

3.  **Create a virtual environment and install dependencies using uv:**
    ```bash
    uv venv # Create a virtual environment (e.g., .venv)
    source .venv/bin/activate # Activate the virtual environment (Linux/macOS)
    # For Windows (PowerShell): .venv\Scripts\Activate.ps1
    # For Windows (CMD): .venv\Scripts\activate.bat
    ```
    If you have a `requirements.txt` file:
    ```bash
    uv pip install -r requirements.txt
    ```
    If your project is packaged with `pyproject.toml` and you want to install it (e.g., in editable mode for development):
    ```bash
    uv pip install -e .
    ```
    (Ensure your `pyproject.toml` is configured correctly for this.)

## Usage

The primary search functionality can be accessed via the `web_search` function in `src/web_search.py`.

Example (from `src/example.ipynb` or a Python script):

```python
from src.web_search import web_search, ddgs_scraperapi_patch

# Important: If you want to use ScraperAPI for all DDGS calls,
# ensure SCRAPERAPI_API_KEY is set in your environment and then call the patch:
ddgs_scraperapi_patch()

# Perform a text search
text_results = web_search(keywords="latest advancements in AI", mode="text")
for result in text_results[:2]: # Print first two results
    print(result)

# Perform a news search for the last week
news_results = web_search(keywords="python programming news", mode="news", timeframe="w")
for result in news_results[:2]:
    print(result)

# Perform a video search
video_results = web_search(keywords="uv python tutorial", mode="video")
for result in video_results[:2]:
    print(result)
```

Refer to the `src/example.ipynb` notebook for more detailed examples and to experiment with the different search modes and parameters.

## Development

(Optional: Add details about running tests, linters, or contributing guidelines here if applicable.)
