Benjamin_Boenisch/breakpilot-lehrer

Fork 0

Files

History

…

cmd/server

…

internal

…

policies

…

rules

…

scripts

…

seeds

…

Dockerfile

…

go.mod

…

go.sum

…

README.md

…

README.md

edu-search-service

Spezialisierter Suchdienst für deutsche Bildungsinhalte - eine Alternative zu Tavily, optimiert für den deutschen Bildungssektor.

Übersicht

Der edu-search-service crawlt, extrahiert und indiziert Bildungsinhalte von deutschen Bildungsquellen (Kultusministerien, Bildungsserver, wissenschaftliche Studien, etc.) und stellt eine Such-API bereit.

Features

BM25 Keyword-Suche mit German Analyzer (OpenSearch)
Semantic Search mit Embeddings (OpenAI oder Ollama)
Hybrid Search kombiniert BM25 + Vektor-Ähnlichkeit
Automatisches Tagging für Dokumenttyp, Fächer, Schulstufe, Bundesland
Trust-Score basierend auf Domain-Reputation und Content-Qualität
Rate-Limited Crawler mit robots.txt Respekt
Admin API für Seed-Verwaltung und Crawl-Steuerung

Architektur

┌─────────────────────────────────────────────────────────────────────┐
│                        edu-search-service                           │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   ┌─────────┐    ┌───────────┐    ┌────────┐    ┌─────────┐       │
│   │ Crawler │───▶│ Extractor │───▶│ Tagger │───▶│ Indexer │       │
│   └─────────┘    └───────────┘    └────────┘    └─────────┘       │
│        │                                              │             │
│        ▼                                              ▼             │
│   ┌─────────┐                                  ┌────────────┐      │
│   │  Seeds  │                                  │ OpenSearch │      │
│   └─────────┘                                  └────────────┘      │
│                                                      │             │
│                     ┌────────────┐                   │             │
│                     │ Search API │◀──────────────────┘             │
│                     └────────────┘                                 │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Komponenten

Crawler (`internal/crawler/`)

Rate-Limited HTTP Client (Standard: 0.2 req/sec pro Domain)
Denylist-Support für ungewünschte Domains
Seeds aus Backend-API (primär) oder lokale Seed-Files (Fallback)
URL-Normalisierung und Deduplication
Seed-Metadaten: Trust-Boost, Crawl-Tiefe, Kategorie, Bundesland
Crawl-Status-Feedback an Backend (Dokumentenzahl, Dauer, Fehler)

Robots (`internal/robots/`)

robots.txt Parser mit Caching (24h TTL)
Unterstützt Disallow, Allow, Crawl-delay
Wildcard-Patterns (*) und End-Anchors ($)
User-Agent-spezifische Regeln
Leniente Behandlung bei fehlenden robots.txt

Extractor (`internal/extractor/`)

HTML-Extraktion mit goquery
PDF-Textextraktion mit ledongthuc/pdf Bibliothek
- ExtractPDF() - Standard-Extraktion mit GetPlainText
- ExtractPDFWithMetadata() - Seiten-weise Extraktion für mehr Kontrolle
- Fallback-Extraktion bei beschädigten PDFs
- Automatische Titel-Erkennung (erste signifikante Zeile)
- Heading-Erkennung (All-Caps, nummerierte Zeilen)
Metadaten-Extraktion (og:title, description, etc.)
Content-Feature-Berechnung (Ad-Density, Link-Density)
Sprach-Erkennung (Deutsch/Englisch)

Tagger (`internal/tagger/`)

Regelbasiertes Tagging via YAML-Konfiguration
DocType-Erkennung (Lehrplan, Arbeitsblatt, Studie, etc.)
Fächer-Erkennung (Mathematik, Deutsch, etc.)
Schulstufen-Erkennung (Grundschule, Sek I/II, etc.)
Bundesland-Erkennung aus URL-Patterns
Trust-Score-Berechnung

Quality (`internal/quality/`)

Multi-Faktor Quality-Score (0-1)
- Content Length (20%)
- Heading Structure (15%)
- Link/Ad Quality (15%)
- Text-to-HTML Ratio (15%)
- Metadata Presence (10%)
- Language Clarity (10%)
- Content Freshness (10%)
- PDF-Specific Signals (5%)
Konfigurierbare Gewichtungen
Date-Indicator-Extraktion für Frische-Bewertung

Indexer (`internal/indexer/`)

OpenSearch 2.11 Client
German Analyzer für BM25
Bulk-Indexierung
Custom Mapping für Bildungsdokumente

Search (`internal/search/`)

Multi-Match Query mit Boosting
Filter für alle Taxonomie-Felder
Function-Score mit Trust/Quality-Boosting
Highlighting-Support
Drei Suchmodi:
- keyword - Klassische BM25-Suche (Default)
- semantic - Reine Vektor-Ähnlichkeitssuche (k-NN)
- hybrid - Kombination aus BM25 und Vektor-Score

Embedding (`internal/embedding/`)

OpenAI Provider - text-embedding-3-small (1536 Dimensionen)
Ollama Provider - Lokale Modelle (z.B. nomic-embed-text, 384-768 Dim.)
Batch-Embedding für effiziente Indexierung
Automatische Text-Kürzung (max. 30.000 Zeichen)

Scheduler (`internal/scheduler/`)

Automatisches Crawling in konfigurierbaren Intervallen
Default: täglich um 2:00 Uhr (minimale Auswirkung)
Manuelles Triggern via Admin-API
Status-Tracking (letzter Lauf, nächster Lauf, Ergebnis)

API Endpoints

Public Endpoints

Method	Endpoint	Beschreibung
GET	`/v1/health`	Health Check (kein Auth)
POST	`/v1/search`	Suche ausführen
GET	`/v1/document`	Einzeldokument abrufen

Admin Endpoints (Auth erforderlich)

Method	Endpoint	Beschreibung
GET	`/v1/admin/seeds`	Alle Seeds abrufen
POST	`/v1/admin/seeds`	Neuen Seed erstellen
PUT	`/v1/admin/seeds/:id`	Seed aktualisieren
DELETE	`/v1/admin/seeds/:id`	Seed löschen
GET	`/v1/admin/stats`	Crawl-Statistiken
POST	`/v1/admin/crawl/start`	Crawl starten

API Dokumentation

POST /v1/search

Request Body:

{
  "q": "Lehrplan Mathematik Gymnasium",
  "mode": "keyword",
  "limit": 10,
  "offset": 0,
  "filters": {
    "language": ["de"],
    "doc_type": ["Lehrplan"],
    "school_level": ["Gymnasium"],
    "state": ["BY", "NW"],
    "subjects": ["Mathematik"],
    "min_trust_score": 0.5
  },
  "include": {
    "snippets": true,
    "highlights": true
  }
}

Such-Modi (mode):

Mode	Beschreibung
`keyword`	BM25-Textsuche (Default)
`semantic`	Vektor-Ähnlichkeitssuche via Embeddings
`hybrid`	Kombination: 70% BM25 + 30% Vektor-Score

Hinweis: semantic und hybrid Modi erfordern SEMANTIC_SEARCH_ENABLED=true und konfigurierte Embedding-Provider.

Response:

{
  "query_id": "q-12345",
  "results": [
    {
      "doc_id": "uuid-...",
      "title": "Lehrplan Mathematik Gymnasium Bayern",
      "url": "https://www.isb.bayern.de/...",
      "domain": "isb.bayern.de",
      "language": "de",
      "doc_type": "Lehrplan",
      "school_level": "Gymnasium",
      "subjects": ["Mathematik"],
      "scores": {
        "bm25": 12.5,
        "trust": 0.85,
        "quality": 0.9,
        "final": 10.6
      },
      "snippet": "Der Lehrplan für das Fach Mathematik...",
      "highlights": ["<em>Lehrplan</em> für das Fach <em>Mathematik</em>..."]
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total_estimate": 156
  }
}

Filter-Optionen

Filter	Werte
`language`	`de`, `en`
`doc_type`	`Lehrplan`, `Arbeitsblatt`, `Unterrichtsentwurf`, `Erlass_Verordnung`, `Pruefung_Abitur`, `Studie_Bericht`, `Sonstiges`
`school_level`	`Grundschule`, `Sek_I`, `Gymnasium`, `Berufsschule`, `Hochschule`, `Alle`, `NA`
`state`	`BW`, `BY`, `BE`, `BB`, `HB`, `HH`, `HE`, `MV`, `NI`, `NW`, `RP`, `SL`, `SN`, `ST`, `SH`, `TH`
`subjects`	`Mathematik`, `Deutsch`, `Englisch`, `Geschichte`, `Physik`, `Biologie`, `Chemie`, etc.

Konfiguration

Umgebungsvariablen

Variable	Beschreibung	Default
`PORT`	Server Port	`8084`
`OPENSEARCH_URL`	OpenSearch URL	`http://opensearch:9200`
`OPENSEARCH_USERNAME`	OpenSearch User	`admin`
`OPENSEARCH_PASSWORD`	OpenSearch Passwort	`admin`
`INDEX_NAME`	Index Name	`bp_documents_v1`
`USER_AGENT`	Crawler User Agent	`BreakpilotEduCrawler/1.0`
`RATE_LIMIT_PER_SEC`	Requests pro Sekunde/Domain	`0.2`
`MAX_DEPTH`	Max Crawl-Tiefe	`4`
`MAX_PAGES_PER_RUN`	Max Seiten pro Crawl	`500`
`SEEDS_DIR`	Seed-Dateien Verzeichnis	`./seeds`
`RULES_DIR`	Tagging-Regeln Verzeichnis	`./rules`
`EDU_SEARCH_API_KEY`	API Key für Auth	``
`BACKEND_URL`	URL zum Python Backend	`http://backend:8000`
`SEEDS_FROM_API`	Seeds aus API laden	`true`
Semantic Search
`SEMANTIC_SEARCH_ENABLED`	Semantic Search aktivieren	`false`
`EMBEDDING_PROVIDER`	Provider: `openai`, `ollama`, `none`	`none`
`OPENAI_API_KEY`	API Key für OpenAI Embeddings	``
`EMBEDDING_MODEL`	Embedding-Modell	`text-embedding-3-small`
`EMBEDDING_DIMENSION`	Vektor-Dimension	`1536`
`OLLAMA_URL`	Ollama Server URL	`http://ollama:11434`
Scheduler
`SCHEDULER_ENABLED`	Automatisches Crawling aktivieren	`false`
`SCHEDULER_INTERVAL`	Crawl-Intervall	`24h` (täglich)

Installation & Start

Docker (empfohlen)

# Im edu-search-service Verzeichnis
docker compose up -d

# Logs anzeigen
docker compose logs -f edu-search

# Nur der Service (OpenSearch extern)
docker build -t edu-search-service .
docker run -p 8084:8084 \
  -e OPENSEARCH_URL=http://host.docker.internal:9200 \
  edu-search-service

Lokal (Entwicklung)

# Dependencies installieren
go mod download

# Service starten
go run cmd/server/main.go

# Tests ausführen
go test -v ./...

Seed-Kategorien

Kategorie	Beschreibung	Beispiele
`federal`	Bundesweite Institutionen	KMK, BMBF, IQB
`states`	Landeskultusbehörden	Kultusministerien, Landesinstitute
`science`	Wissenschaftliche Studien	PISA, IGLU, TIMSS
`universities`	Hochschulen	Pädagogische Hochschulen
`schools`	Schulen direkt	Schulhomepages
`portals`	Bildungsportale	Lehrer-Online, 4teachers
`eu`	EU-Bildungsprogramme	Erasmus+, Eurydice
`authorities`	Schulbehörden	Regierungspräsidien

Tagging-Regeln

Die YAML-Regeldateien im rules/ Verzeichnis definieren das Tagging:

doc_type_rules.yaml - Dokumenttyp-Erkennung
subject_rules.yaml - Fächer-Erkennung
level_rules.yaml - Schulstufen-Erkennung
trust_rules.yaml - Trust-Score-Berechnung

Beispiel: doc_type_rules.yaml

doc_types:
  Lehrplan:
    strong_terms:
      - Lehrplan
      - Kernlehrplan
      - Bildungsplan
    medium_terms:
      - Curriculum
      - Kompetenzerwartungen
    url_patterns:
      - /lehrplan
      - /kernlehrplan

priority_order:
  - Pruefung_Abitur
  - Lehrplan
  - Arbeitsblatt

Projektstruktur

edu-search-service/
├── cmd/
│   └── server/
│       └── main.go          # Entry Point
├── internal/
│   ├── api/
│   │   └── handlers/
│   │       ├── handlers.go       # Search & Health Handler
│   │       └── admin_handlers.go # Admin API Handler
│   ├── config/
│   │   └── config.go        # Konfiguration
│   ├── crawler/
│   │   ├── crawler.go       # URL Fetcher
│   │   └── api_client.go    # Backend API Client (Seeds)
│   ├── robots/
│   │   └── robots.go        # robots.txt Parser & Checker
│   ├── embedding/
│   │   └── embedding.go     # Embedding Provider (OpenAI/Ollama)
│   ├── extractor/
│   │   └── extractor.go     # HTML/PDF Extraktion
│   ├── indexer/
│   │   └── mapping.go       # OpenSearch Indexer
│   ├── pipeline/
│   │   └── pipeline.go      # Crawl Orchestrierung
│   ├── quality/
│   │   └── quality.go       # Multi-Faktor Quality Scoring
│   ├── scheduler/
│   │   └── scheduler.go     # Automatisches Crawl-Scheduling
│   ├── search/
│   │   └── search.go        # Search Service (Keyword/Semantic/Hybrid)
│   └── tagger/
│       └── tagger.go        # Regelbasiertes Tagging
├── rules/
│   ├── doc_type_rules.yaml
│   ├── subject_rules.yaml
│   ├── level_rules.yaml
│   └── trust_rules.yaml
├── seeds/
│   ├── federal.txt
│   ├── states.txt
│   └── denylist.txt
├── Dockerfile
├── docker-compose.yml
├── go.mod
└── README.md

Abhängigkeiten

Package	Version	Beschreibung	Lizenz
`github.com/gin-gonic/gin`	v1.9+	HTTP Framework	MIT
`github.com/opensearch-project/opensearch-go/v2`	v2.3+	OpenSearch Client	Apache-2.0
`github.com/PuerkitoBio/goquery`	v1.8+	HTML Parser	BSD-3-Clause
`github.com/ledongthuc/pdf`	v0.0.0-20240201	PDF Text Extraktion	MIT
`gopkg.in/yaml.v3`	v3.0+	YAML Parser	MIT
`github.com/google/uuid`	v1.4+	UUID Generation	BSD-3-Clause
`golang.org/x/net`	v0.19+	HTML Utilities	BSD-3-Clause

Tests ausführen

# Alle Tests
go test -v ./...

# Mit Coverage
go test -cover ./...

# Nur Tagger Tests
go test -v ./internal/tagger/...

# Nur Crawler Tests
go test -v ./internal/crawler/...

Lizenz

Proprietär - BreakPilot GmbH

Kontakt

Security Issues: security@breakpilot.com
Bugs: https://github.com/breakpilot/edu-search-service/issues

README.md

edu-search-service

Übersicht

Features

Architektur

Komponenten

Crawler (internal/crawler/)

Robots (internal/robots/)

Extractor (internal/extractor/)

Tagger (internal/tagger/)

Quality (internal/quality/)

Indexer (internal/indexer/)

Search (internal/search/)

Embedding (internal/embedding/)

Scheduler (internal/scheduler/)

API Endpoints

Public Endpoints

Admin Endpoints (Auth erforderlich)

API Dokumentation

POST /v1/search

Filter-Optionen

Konfiguration

Umgebungsvariablen

Installation & Start

Docker (empfohlen)

Lokal (Entwicklung)

Seed-Kategorien

Tagging-Regeln

Beispiel: doc_type_rules.yaml

Projektstruktur

Abhängigkeiten

Tests ausführen

Lizenz

Kontakt

Crawler (`internal/crawler/`)

Robots (`internal/robots/`)

Extractor (`internal/extractor/`)

Tagger (`internal/tagger/`)

Quality (`internal/quality/`)

Indexer (`internal/indexer/`)

Search (`internal/search/`)

Embedding (`internal/embedding/`)

Scheduler (`internal/scheduler/`)