ankn
a5f8fb49ab
Bahn: aisupport, Analyse-O2C-C2S, awesome-bahn-mcp-servers, beam-mcp,
Confluence_Bot, db-planet-mcp-server, O2C-Harness, project-audit,
Projekt-KIQ-HP, teamlandkarte-mcp
Dhive: Jury-Voting
Privat: CV, NoteGraph (NOTE: NoteGraph needs complete redo after consolidation)
Shared: AI-Orchestrator, OrgMyLife, power_skills_and_more
Shared/references: symphony (read-only)
Bahn repos remain available as independent remotes - this monorepo
pulls them in via subtree, the originals are untouched.
112 lines
9.1 KiB
Markdown
112 lines
9.1 KiB
Markdown
# 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.
|