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.
46 lines
2.0 KiB
Markdown
46 lines
2.0 KiB
Markdown
---
|
||
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.toml` weights: `[matching]` section has `role_weight` and `competence_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_end` may exclude valid candidates
|
||
- Check `is_fully_available` filter — 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`: rerun `find_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_size` in config (default: 128)
|
||
- Failure is strict: no heuristic fallback
|
||
|
||
### Diagnostic Steps
|
||
|
||
1. Check config: `cat config.toml` — verify weights, thresholds, similarity strategy
|
||
2. Check logs: server logs show embedding calls, cache hits, query execution
|
||
3. Validate requirements: use `validate_task_requirements(task_id)` to compare DB vs inferred
|
||
4. Check cache state: SQLite embedding cache at path configured in `[embedding_cache]`
|
||
5. Run with verbose: `uv run pytest -v tests/test_similarity.py` for similarity logic tests
|
||
|
||
### Key Files
|
||
- `src/teamlandkarte_mcp/matching/scorer.py` — scoring logic
|
||
- `src/teamlandkarte_mcp/matching/similarity.py` — similarity computation
|
||
- `src/teamlandkarte_mcp/matching/matcher.py` — orchestration
|
||
- `src/teamlandkarte_mcp/cache/` — all cache layers
|
||
- `config.toml` — runtime configuration
|