# Research Bridge

SearXNG + Kimi for Coding research pipeline. Self-hosted alternative to Perplexity with **$0 running costs**.

[![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/)

**[Deutsche Version](README.de.md)**

---

## 🚀 Quick Start

### With Podman (Recommended)

```bash
# Clone repository
git clone git@github.com:B0rbor4d/research-bridge.git
cd research-bridge

# Start all services
podman-compose up -d

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

### Manual Setup

```bash
# Clone and setup
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

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

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

# Run
python -m src.main
```

---

## 📡 API Usage

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

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

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

---

## 🏗️ Architecture

```
┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│   Client        │────▶│  FastAPI     │────▶│  SearXNG        │
│   Request       │     │  Research    │     │  (Search)       │
└─────────────────┘     │  Bridge      │     └─────────────────┘
                        └──────┬───────┘              │
                               │                      │
                               ▼                      │
                        ┌──────────────┐              │
                        │  Kimi for    │◄─────────────┘
                        │  Coding      │   Raw Results
                        │  Synthesis   │
                        └──────┬───────┘
                               │
                               ▼
                        ┌──────────────┐
                        │  Synthesized │
                        │  Response    │
                        └──────────────┘
```

---

## 🔧 Configuration

Environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `RESEARCH_BRIDGE_KIMI_API_KEY` | Kimi for Coding API key | - |
| `RESEARCH_BRIDGE_SEARXNG_URL` | SearXNG instance URL | `http://searxng:8080` |
| `RESEARCH_BRIDGE_RATE_LIMIT_RPM` | Rate limit (requests/min) | `60` |
| `RESEARCH_BRIDGE_LOG_LEVEL` | Logging level | `info` |

---

## 📁 Project Structure

```
research-bridge/
├── src/
│   ├── api/           # FastAPI routes and middleware
│   ├── search/        # SearXNG client
│   ├── llm/           # Kimi for Coding synthesizer
│   ├── models/        # Pydantic models
│   └── middleware/    # Rate limiting, auth
├── tests/             # Test suite (unit, integration, e2e)
├── config/            # Docker and settings
├── docs/              # Documentation
├── Containerfile      # Podman/Docker build
└── podman-compose.yml # Full stack deployment
```

---

## 🧪 Testing

```bash
# Run all tests
pytest

# With coverage
pytest --cov=src --cov-report=html

# Specific test categories
pytest tests/unit/          # Fast, mocked
pytest tests/integration/   # With real SearXNG
pytest tests/e2e/           # Full pipeline
```

---

## 📚 Documentation

- [Technical Design Document](docs/TDD.md) - Complete specification
- [AI Council Review](docs/AI_COUNCIL_REVIEW.md) - Architecture review

---

## 🤝 Why Research Bridge?

| Service | Cost per 1K queries | Self-hosted | Privacy |
|---------|---------------------|-------------|---------|
| Perplexity Pro | ~$20/month | ❌ | ❌ |
| OpenAI GPT-4 | ~$10-30 | ❌ | ❌ |
| **Research Bridge** | **$0** | ✅ | ✅ |

---

## 📜 License

MIT © 2026 Florian Hartmann / Insight-IT GmbH