# Research Bridge

SearXNG + Kimi for Coding Research Pipeline. Self-hosted Alternative zu Perplexity mit **$0 laufenden Kosten**.

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Podman Ready](https://img.shields.io/badge/podman-ready-green.svg)](https://podman.io/)

**[English Version](README.md)**

---

## 🚀 Schnellstart

### Mit Podman (Empfohlen)

```bash
# Repository klonen
git clone git@gitea.ragtag.rocks:b0rbor4d/research-bridge.git
cd research-bridge

# Alle Services starten
podman-compose up -d

# Health-Check
curl http://localhost:8000/health
```

### Manuelle Einrichtung

```bash
# Repository klonen und einrichten
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# SearXNG starten
docker-compose -f config/searxng-docker-compose.yml up -d

# Konfigurieren
export RESEARCH_BRIDGE_KIMI_API_KEY="sk-kimi-..."

# Starten
python -m src.main
```

---

## 📡 API-Nutzung

### Health Check
```bash
curl http://localhost:8000/health
```

### Suche (Passthrough)
```bash
curl "http://localhost:8000/search?q=python+async+best+practices"
```

### Recherche mit Synthese
```bash
curl -X POST http://localhost:8000/research \
  -H "Content-Type: application/json" \
  -d '{
    "query": "neue rust web frameworks 2024",
    "depth": "shallow",
    "max_results": 10
  }'
```

---

## 🏗️ Architektur

```
┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│   Client        │────▶│  FastAPI     │────▶│  SearXNG        │
│   Request       │     │  Research    │     │  (Suche)        │
└─────────────────┘     │  Bridge      │     └─────────────────┘
                        └──────┬───────┘              │
                               │                      │
                               ▼                      │
                        ┌──────────────┐              │
                        │  Kimi for    │◄─────────────┘
                        │  Coding      │   Rohdaten
                        │  Synthese    │
                        └──────┬───────┘
                               │
                               ▼
                        ┌──────────────┐
                        │  Synthetisierte│
                        │  Antwort     │
                        └──────────────┘
```

---

## 🔧 Konfiguration

Umgebungsvariablen:

| Variable | Beschreibung | Standard |
|----------|-------------|----------|
| `RESEARCH_BRIDGE_KIMI_API_KEY` | Kimi for Coding API-Key | - |
| `RESEARCH_BRIDGE_SEARXNG_URL` | SearXNG Instanz-URL | `http://searxng:8080` |
| `RESEARCH_BRIDGE_RATE_LIMIT_RPM` | Rate-Limit (Anfragen/Min) | `60` |
| `RESEARCH_BRIDGE_LOG_LEVEL` | Log-Level | `info` |

---

## 📁 Projektstruktur

```
research-bridge/
├── src/
│   ├── api/           # FastAPI Routen und Middleware
│   ├── search/        # SearXNG Client
│   ├── llm/           # Kimi for Coding Synthese
│   ├── models/        # Pydantic Modelle
│   └── middleware/    # Rate-Limiting, Auth
├── tests/             # Tests (Unit, Integration, E2E)
├── config/            # Docker und Einstellungen
├── docs/              # Dokumentation
├── Containerfile      # Podman/Docker Build
└── podman-compose.yml # Vollständiger Stack
```

---

## 🧪 Tests

```bash
# Alle Tests ausführen
pytest

# Mit Coverage
pytest --cov=src --cov-report=html

# Spezifische Test-Kategorien
pytest tests/unit/          # Schnell, gemockt
pytest tests/integration/   # Mit echtem SearXNG
pytest tests/e2e/           # Komplette Pipeline
```

---

## 📚 Dokumentation

- [Technical Design Document](docs/TDD.md) - Vollständige Spezifikation (EN)
- [AI Council Review](docs/AI_COUNCIL_REVIEW.md) - Architektur-Review (EN)

---

## 🤝 Warum Research Bridge?

| Service | Kosten pro 1K Anfragen | Self-hosted | Datenschutz |
|---------|------------------------|-------------|-------------|
| Perplexity Pro | ~$20/Monat | ❌ | ❌ |
| OpenAI GPT-4 | ~$10-30 | ❌ | ❌ |
| **Research Bridge** | **$0** | ✅ | ✅ |

---

## 📜 Lizenz

MIT © 2026 Florian Hartmann / Insight-IT GmbH