research-bridge/README.md

Research Bridge

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

Deutsche Version

---

🚀 Quick Start

With Podman (Recommended)

# 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

# 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

curl http://localhost:8000/health

Search (Passthrough)

curl "http://localhost:8000/search?q=python+async+best+practices"

Research with Synthesis

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

# 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 - Complete specification
• AI Council Review - 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