Metadata-Version: 2.4
Name: s-websearch
Version: 1.0.1
Summary: SearXNG-basierte Suche mit Intent-Klassifikation, Domain-Trust und Cross-Encoder-Reranking (persönliches Tool, siehe README fuer Import-Verhalten)
Author: sxbo
License-Expression: MIT
Project-URL: Homepage, https://github.com/DEIN_USERNAME/s-search
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24
Requires-Dist: sentence-transformers>=2.2
Requires-Dist: transformers>=4.30
Requires-Dist: curl_cffi>=0.6
Requires-Dist: beautifulsoup4>=4.11

# s-websearch

Fortgeschrittene Such-Pipeline auf Basis von SearXNG: Multi-Page-Abfrage, Domain-Discovery,
Zero-Shot-Intent-Klassifikation (News / Dokument / Fakt), Cross-Encoder-Reranking und
Hybrid-Scoring (SERP-Position + Domain-Trust + Relevanz).

## ⚠️ Wichtig, bevor du installierst

Dieses Paket wurde primär für den eigenen Gebrauch veröffentlicht (persönliches Tool, das
von überall abrufbar sein soll). Es verhält sich **nicht** wie eine normale, "stille" Python-Bibliothek:

- **Blockierender Import:** Allein durch `import s_websearch` bzw. `from s_websearch import Web`
  wird automatisch Setup-Code ausgeführt — inklusive Laden von ML-Modellen
  (`sentence-transformers` / `transformers`, mehrere hundert MB Downloads beim ersten Mal)
  und Print-Ausgaben. Das kann je nach Internetverbindung/Hardware mehrere Sekunden bis
  Minuten dauern, **bevor dein restlicher Code überhaupt weiterläuft.**
- **Startet ggf. automatisch einen Docker-Container:** Falls Docker auf dem System installiert
  ist, versucht das Paket beim Import, selbstständig eine lokale SearXNG-Instanz per
  `docker compose up -d` zu starten (kein Rückfrage-Dialog).
- **Fällt sonst auf öffentliche SearXNG-Instanzen zurück:** Ist kein Docker vorhanden, sendet
  das Paket Suchanfragen automatisch an fremde, öffentliche SearXNG-Server (z. B. `searx.be`).
- **Große Abhängigkeiten:** `sentence-transformers` und `transformers` ziehen ML-Modelle nach,
  der Installations-Fußabdruck ist deutlich größer als bei einem einfachen Scraping-Paket.
- Über die Umgebungsvariable `SMART_SEARCH_SKIP_INIT=1` kann der komplette Auto-Setup-Block
  beim Import übersprungen werden, falls du das nicht willst (z. B. für CI/Tests).

**Kurz gesagt:** Wenn du nur schnell `pip install`en und direkt lostippen willst, ohne dass im
Hintergrund Modelle geladen oder Docker-Container gestartet werden, ist das hier vermutlich
nicht das richtige Paket für dich.

## Installation

```bash
pip install s-websearch
```

Vorausgesetzt (optional, aber empfohlen): Docker installiert, damit lokal eine SearXNG-Instanz
läuft statt öffentlicher Fallback-Instanzen.

## Verwendung

```python
from s_websearch import Web

results = Web.search("python packaging", result_count=10, source="on")
for r in results:
    print(r["title"], r["source"], r["content"])
```

### Nutzung in Agents / async-Frameworks

`Web.search()` funktioniert automatisch auch dann, wenn es innerhalb eines bereits
laufenden asyncio-Event-Loops aufgerufen wird (z. B. aus einem Agent- oder Tool-Framework
heraus). Der Aufruf bleibt dabei ganz normal synchron — kein `await` nötig:

```python
from s_websearch import Web

async def my_tool(query: str):
    return Web.search(query, result_count=5)
```

### Auto-Setup überspringen

```bash
# vor dem Import setzen
export SMART_SEARCH_SKIP_INIT=1
```

```python
import os
os.environ["SMART_SEARCH_SKIP_INIT"] = "1"

from s_websearch import Web
Web.preload(background=False)   # Modelle explizit laden, wenn du bereit bist
```

## Architektur (kurz)

1. SearXNG lokal (automatisch per Docker gestartet, falls nötig)
2. Parallele Multi-Page-Abfrage (async)
3. Regelbasierte Zwei-Phasen-Domain-Discovery (site:-Deep-Dive)
4. Zero-Shot-Intent-Classifier (News / Dokument / Fakt)
5. Cross-Encoder-Reranking
6. Hybrid-Score: SERP-Position + Domain-Trust + Cross-Encoder-Relevanz

## Changelog

### 1.0.1
- `Web.search()` funktioniert jetzt auch bei bereits laufendem asyncio-Event-Loop
  (z. B. in Agent-/Tool-Frameworks). Läuft in diesem Fall intern in einem eigenen
  Thread, bleibt nach außen aber ganz normal synchron aufrufbar — kein Absturz
  mehr, kein manuelles `await smart_search(...)` mehr nötig.

### 1.0.0
- Erste Version: SearXNG-Pipeline mit Intent-Klassifikation, Domain-Discovery
  und Cross-Encoder-Reranking.
