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.
2.0 KiB
2.0 KiB
description
| description |
|---|
| Debug matching issues — investigate why capacity matching produces unexpected results (wrong scores, missing candidates, expired searches). |
$ARGUMENTS
Debugging Matching Issues
Common Issues
1. Unexpected scores (too high/low)
- Check
config.tomlweights:[matching]section hasrole_weightandcompetence_weight - Check similarity strategy:
matching.similarity.use_bm25_search(BM25 vs embeddings) - BM25 scores 0.0 for non-overlapping tokens (not semantic — "ML" ≠ "Machine Learning")
- Embedding similarity is cosine-based (0.0–1.0 range)
2. Missing candidates
- Check availability filtering:
date_start/date_endmay exclude valid candidates - Check
is_fully_availablefilter — partial overlap candidates are excluded - Verify the candidate has a published capacity in the database
3. Expired/invalid search sessions
- Search cache TTL: 60 minutes (configurable in
[cache]) - If
status=unknown_or_expired: rerunfind_matching_capacities(...)for fresh results - Never retry with a guessed search_id
4. Embedding failures
- Check Azure OpenAI connectivity and API key in
.env - Check
azure_openai.embedding_batch_sizein config (default: 128) - Failure is strict: no heuristic fallback
Diagnostic Steps
- Check config:
cat config.toml— verify weights, thresholds, similarity strategy - Check logs: server logs show embedding calls, cache hits, query execution
- Validate requirements: use
validate_task_requirements(task_id)to compare DB vs inferred - Check cache state: SQLite embedding cache at path configured in
[embedding_cache] - Run with verbose:
uv run pytest -v tests/test_similarity.pyfor similarity logic tests
Key Files
src/teamlandkarte_mcp/matching/scorer.py— scoring logicsrc/teamlandkarte_mcp/matching/similarity.py— similarity computationsrc/teamlandkarte_mcp/matching/matcher.py— orchestrationsrc/teamlandkarte_mcp/cache/— all cache layersconfig.toml— runtime configuration