Orchestrator/bahn/teamlandkarte-mcp/.kiro/specs/remove-embedding-competence-similarity/requirements.md

Anforderungsdokument

Einleitung

Dieses Dokument beschreibt die Anforderungen für die Entfernung der Embedding-basierten Kompetenz-Similarity zugunsten von BM25 als einzigem Kompetenz-Matching-Verfahren, die Umstellung der Rollen-Inferenz und Rollen-Similarity auf einen LLM-Ansatz sowie die vollständige Entfernung der Embedding-Infrastruktur. Das System wird vollständig BM25 + LLM-basiert.

Glossar

• SimilarityEngine: Modul in matching/similarity.py, das Ähnlichkeitsberechnungen für Kompetenzen und Rollen durchführt.
• VocabularyCache: Modul in matching/vocabulary.py, das Vokabular-Embeddings vorhält und Inferenz-Funktionen bereitstellt.
• BM25: Probabilistisches Ranking-Verfahren für Textähnlichkeit basierend auf Termfrequenz und inverser Dokumentfrequenz.
• RRF: Reciprocal Rank Fusion – Verfahren zur Kombination mehrerer Rankings.
• AutoTagger: LLM-basiertes Modul zur Erweiterung von Kompetenzlisten vor dem BM25-Scoring.
• AzureOpenAIClient: Client-Wrapper für Azure OpenAI API-Aufrufe (Embeddings und Chat Completions).
• SimilarityConfig: Konfigurationsklasse für die Similarity-Engine in config.py.
• infer_primary_role: Funktion, die einer Aufgabe die passendste Rolle aus der Datenbank zuordnet.
• LLM: Large Language Model – hier Azure OpenAI Chat Completion.
• Preload: Eageres Vorladen von Embeddings beim Server-Start.
• EmbeddingCache: Cache-Modul für gespeicherte Embedding-Vektoren.
• compute_role_similarity: Funktion in der SimilarityEngine, die die semantische Ähnlichkeit zwischen einer geforderten Rolle und einer Kandidaten-Rolle berechnet.

Anforderungen

Anforderung 1: Entfernung der Embedding-basierten Kompetenz-Similarity

User Story: Als Entwickler möchte ich, dass BM25+RRF das einzige Verfahren für Kompetenz-Matching ist, damit die Codebasis vereinfacht wird und keine Embedding-Kosten für Kompetenz-Vergleiche anfallen.

Akzeptanzkriterien

1. THE SimilarityEngine SHALL use BM25+RRF as the sole method for computing competence similarity scores.
2. WHEN compute_competence_similarity is called, THE SimilarityEngine SHALL execute the BM25+RRF path without checking a strategy flag or use_bm25_search parameter.
3. THE SimilarityEngine SHALL no longer contain the _per_skill_similarity method for embedding-based per-skill competence matching.
4. THE SimilarityEngine SHALL no longer contain the _aggregate_similarity method for embedding-based aggregate competence matching.
5. THE SimilarityEngine SHALL no longer accept a strategy parameter in its constructor for competence similarity strategy selection.
6. THE SimilarityEngine SHALL no longer accept a use_bm25_search parameter in its constructor.
7. THE SimilarityEngine SHALL remove the prefetch_embeddings and _embed methods, since role similarity also switches to LLM and no embedding use cases remain.

Anforderung 2: Entfernung des Konfigurationsparameters use_bm25_search

User Story: Als Entwickler möchte ich, dass der Parameter use_bm25_search aus der Konfiguration entfernt wird, da BM25 nun immer aktiv ist und der Parameter redundant geworden ist.

Akzeptanzkriterien

1. THE SimilarityConfig SHALL no longer contain the field use_bm25_search.
2. THE SimilarityConfig SHALL no longer contain the field strategy (da nur noch BM25 verwendet wird).
3. WHEN the configuration is loaded, THE Config-Loader SHALL not read or validate use_bm25_search from the TOML file.
4. WHEN the configuration is loaded, THE Config-Loader SHALL not read or validate matching.similarity.strategy from the TOML file.
5. THE SimilarityEngine SHALL no longer expose a use_bm25_search property.
6. THE Matcher SHALL build the global BM25 index unconditionally for all filtered candidates without checking a use_bm25_search flag.

Anforderung 3: LLM-basierte Rollen-Inferenz

User Story: Als Entwickler möchte ich, dass infer_primary_role einen LLM-Ansatz (Chat Completion) verwendet anstelle von Embedding-Cosine-Similarity, damit die Rollenzuordnung kontextbezogener und genauer erfolgt.

Akzeptanzkriterien

1. WHEN infer_primary_role is called, THE VocabularyCache SHALL use an LLM chat completion to determine the best matching role for a given task text.
2. WHEN infer_primary_role is called, THE VocabularyCache SHALL provide the list of all available role names from the database as context to the LLM.
3. WHEN infer_primary_role is called, THE VocabularyCache SHALL provide the task text (title and/or description) as input to the LLM.
4. THE VocabularyCache SHALL return the role name and a confidence score from the LLM response.
5. IF the LLM call fails, THEN THE VocabularyCache SHALL return None rather than raising an unhandled exception.
6. THE VocabularyCache SHALL no longer require a task embedding as input parameter for infer_primary_role.
7. THE VocabularyCache SHALL accept the task text directly as input parameter for infer_primary_role.
8. WHEN infer_primary_role is called, THE VocabularyCache SHALL instruct the LLM to select exactly one role from the provided list and return a structured JSON response.
9. THE infer_primary_role tool in mcp_server.py SHALL call the new LLM-based infer_primary_role without first generating a task embedding.

Anforderung 4: Entfernung des Embedding-Preloads offener Tasks

User Story: Als Entwickler möchte ich, dass Embeddings offener Tasks nicht mehr beim Server-Start vorgeladen werden und auch nicht mehr on-demand erzeugt werden, da keine Embedding-basierte Verarbeitung mehr stattfindet.

Akzeptanzkriterien

1. THE MCP-Server SHALL no longer preload embeddings for open tasks during startup.
2. THE _startup_preload_embeddings function SHALL be removed entirely.
3. THE VocabularyCache SHALL no longer provide an ensure_task_embedding method, since task embeddings are not needed in the BM25 + LLM architecture.
4. THE MCP-Server SHALL no longer preload role or competence vocabulary embeddings at startup, since all similarity computations now use BM25 or LLM.
5. THE startup time of the MCP-Server SHALL be reduced by eliminating all embedding preload loops.

Anforderung 5: Umstellung der Rollen-Similarity im Matcher auf LLM

User Story: Als Entwickler möchte ich, dass die Rollen-Similarity im Matcher (compute_role_similarity) ebenfalls einen LLM-Ansatz (Chat Completion) nutzt anstelle von Embedding-Cosine-Similarity, damit das gesamte System ohne Embeddings auskommt und konsistent BM25 + LLM-basiert ist.

Akzeptanzkriterien

1. WHEN compute_role_similarity is called, THE SimilarityEngine SHALL use an LLM chat completion to determine the semantic similarity between the required role and the candidate role.
2. WHEN compute_role_similarity is called, THE SimilarityEngine SHALL provide both role names to the LLM and request a numeric similarity score between 0.0 and 1.0.
3. THE SimilarityEngine SHALL instruct the LLM to return a structured JSON response containing the similarity score.
4. THE SimilarityEngine SHALL no longer use embedding cosine similarity for role comparisons.
5. THE SimilarityEngine SHALL no longer call _embed or prefetch_embeddings for role similarity computation.
6. IF the LLM call fails, THEN THE SimilarityEngine SHALL return a default similarity score of 0.0 rather than raising an unhandled exception.
7. THE VocabularyCache SHALL no longer preload role vocabulary embeddings at startup, since they are not needed for LLM-based role similarity.
8. THE SimilarityEngine SHALL cache LLM-based role similarity results for identical role pairs within a matching run to avoid redundant API calls.

Anforderung 6: Vollständige Entfernung der Embedding-Infrastruktur

User Story: Als Entwickler möchte ich, dass die gesamte Embedding-Infrastruktur entfernt wird, da weder Kompetenz-Matching noch Rollen-Similarity noch Rollen-Inferenz Embeddings benötigen und das System vollständig BM25 + LLM-basiert ist.

Akzeptanzkriterien

1. THE SimilarityEngine SHALL remove the prefetch_embeddings method entirely.
2. THE SimilarityEngine SHALL remove the _embed method entirely.
3. THE VocabularyCache SHALL remove _preload_competence_vocab entirely.
4. THE VocabularyCache SHALL remove _preload_role_vocab (or equivalent role embedding preload logic) entirely.
5. THE VocabularyCache SHALL remove infer_competences if embedding-based competence inference is no longer used.
6. THE EmbeddingCache module SHALL be removed entirely, since no code path requires cached embeddings.
7. THE AzureOpenAIClient SHALL remove the embedding API method (e.g. get_embeddings or equivalent batch embedding call), retaining only chat completion methods.
8. THE config.py SHALL remove embedding-related configuration fields (e.g. embedding_model, embedding_dimensions, embedding batch size settings).
9. THE config.py SHALL remove the InferenceConfig dataclass if max_competences and min_similarity are no longer used.
10. THE SimilarityConfig SHALL remove any fields related to embedding thresholds or embedding model selection.
11. THE config.toml SHALL remove embedding-related configuration entries.
12. THE MCP-Server SHALL remove the _startup_preload_embeddings function entirely if no embedding preloads remain.