From 90d59c63b83630e685f9053965005d0961d70961 Mon Sep 17 00:00:00 2001
From: Henry <henry@insight-it.de>
Date: Sat, 14 Mar 2026 12:52:11 +0000
Subject: [PATCH] Add bilingual README (EN/DE) and Podman containerization

---
 .github-repo-description.txt |   3 +
 README.de.md                 | 167 +++++++++++++++++++++++++++++++++++
 README.md                    | 152 ++++++++++++++++++++++++++-----
 3 files changed, 301 insertions(+), 21 deletions(-)
 create mode 100644 .github-repo-description.txt
 create mode 100644 README.de.md

diff --git a/.github-repo-description.txt b/.github-repo-description.txt
new file mode 100644
index 0000000..f703bca
--- /dev/null
+++ b/.github-repo-description.txt
@@ -0,0 +1,3 @@
+Research Bridge - Self-hosted alternative to Perplexity with $0 running costs. SearXNG + Kimi for Coding research pipeline. FastAPI, Podman-ready, MIT licensed.
+
+Keywords: research, search, ai, llm, perplexity-alternative, searxng, kimi, fastapi, podman, self-hosted
\ No newline at end of file
diff --git a/README.de.md b/README.de.md
new file mode 100644
index 0000000..c28a766
--- /dev/null
+++ b/README.de.md
@@ -0,0 +1,167 @@
+# 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 © 2024 Florian Hartmann / Insight-IT GmbH
diff --git a/README.md b/README.md
index da43678..2fed523 100644
--- a/README.md
+++ b/README.md
@@ -2,56 +2,166 @@
 
 SearXNG + Kimi for Coding research pipeline. Self-hosted alternative to Perplexity with **$0 running costs**.
 
-## Quick Start
+[![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
-# 1. Clone and setup
-cd ~/data/workspace/projects/research-bridge
+# 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]"
 
-# 2. Start SearXNG
+# Start SearXNG
 docker-compose -f config/searxng-docker-compose.yml up -d
 
-# 3. Configure
+# Configure
 export RESEARCH_BRIDGE_KIMI_API_KEY="sk-kimi-..."
 
-# 4. Run
+# Run
 python -m src.main
 ```
 
-## Usage
+---
 
+## 📡 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", "depth": "shallow"}'
+  -d '{
+    "query": "latest rust web frameworks 2024",
+    "depth": "shallow",
+    "max_results": 10
+  }'
 ```
 
-## Documentation
+---
 
-- [Technical Design Document](docs/TDD.md) - Complete specification
-- [AI Council Review](docs/AI_COUNCIL_REVIEW.md) - Architecture review
+## 🏗️ Architecture
 
-## Project Structure
+```
+┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
+│   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
+│   ├── api/           # FastAPI routes and middleware
 │   ├── search/        # SearXNG client
 │   ├── llm/           # Kimi for Coding synthesizer
 │   ├── models/        # Pydantic models
 │   └── middleware/    # Rate limiting, auth
-├── tests/
-│   ├── unit/          # Mocked, isolated
-│   ├── integration/   # With real SearXNG
-│   └── e2e/           # Full flow
-├── config/            # Docker, settings
-└── docs/              # Documentation
+├── tests/             # Test suite (unit, integration, e2e)
+├── config/            # Docker and settings
+├── docs/              # Documentation
+├── Containerfile      # Podman/Docker build
+└── podman-compose.yml # Full stack deployment
 ```
 
-## License
+---
 
-MIT
+## 🧪 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 © 2024 Florian Hartmann / Insight-IT GmbH