168 lines
4.5 KiB
Markdown
168 lines
4.5 KiB
Markdown
# Research Bridge
|
|
|
|
SearXNG + Kimi for Coding research pipeline. Self-hosted alternative to Perplexity with **$0 running costs**.
|
|
|
|
[](https://www.python.org/downloads/)
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](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
|