docs(claude): fix Embedding-Configuration SSoT — JSON-File, nicht Neo4j (#958) - #959
Conversation
CLAUDE.md-Abschnitt "Embedding-Configuration (ADR-0007)" behauptete fälschlich, aktive Konfiguration lebe in Neo4j (EmbeddingConfiguration- Knoten). Code (embedding_configuration_store.py) persistiert aber in einer flachen JSON-Datei unter AGORA_DATA_DIR/ mit flock + atomarem Write (os.replace) + Datei-Modus 0600. ADR-0007 selbst beschreibt genau diesen Store korrekt — nur der CLAUDE.md-Absatz war gedriftet. Korrigiert auf EmbeddingConfigurationStore (JSON-Datei), Verweis auf embedding_contract.py (Pydantic-Vertrag, kein Neo4j-Knoten) sowie embedding_configurations/service.py + legacy.py. Migrations-Lifecycle- und Gemini-Aussagen unverändert (waren korrekt). Refs #958 Co-Authored-By: Claude <noreply@anthropic.com>
|
Warning Review limit reached
Next review available in: 6 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2837de6bab
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ## Embedding-Configuration (ADR-0007) | ||
|
|
||
| Aktive Konfiguration lebt in Neo4j (`EmbeddingConfiguration`-Knoten, eindeutig pro Provider/Model/Dim). Lese-/Schreibpfade ausschließlich über `backend/app/services/embedding_service.py` und `embedding_migration.py`. Bei Modell-Wechsel: Migrations-Lifecycle `pending → running → validating → completed | failed | rolled_back`. Gemini-Re-Embedding ist explizit „noch nicht unterstützt“ — nicht vortäuschen. | ||
| Aktive Konfiguration wird vom [`EmbeddingConfigurationStore`](backend/app/services/embedding_configuration_store.py) in einer flachen JSON-Datei unter `AGORA_DATA_DIR/embedding_configurations.json` persistiert (`flock`-Sperre, atomares Write via `os.replace`, Datei-Modus 0600) — **nicht** in Neo4j. Index-Versionen liegen in einer Sibling-JSON (`embedding_index_versions.json`). `EmbeddingConfiguration` ist ein Pydantic-Vertrag ([`backend/app/contracts/embedding_contract.py`](backend/app/contracts/embedding_contract.py)), kein Neo4j-Knoten. Lese-/Schreibpfade über `backend/app/services/embedding_service.py` und `embedding_migration.py`; Service-Logik in `backend/app/services/embedding_configurations/service.py`, Legacy-Read-Only-Adapter in `…/legacy.py`. Bei Modell-Wechsel: Migrations-Lifecycle `pending → running → validating → completed | failed | rolled_back`. Gemini-Re-Embedding ist explizit „noch nicht unterstützt“ — nicht vortäuschen. |
There was a problem hiding this comment.
When an agent follows the newly linked read/write path, it resolves to backend/app/services/embedding_service.py, which does not exist; the embedding implementation is at backend/app/storage/embedding_service.py, while configuration persistence is handled by embedding_configuration_store.py and embedding_configurations/service.py. This makes the SSoT guidance lead to a dead path, so the link and wording should identify the appropriate existing module.
Useful? React with 👍 / 👎.
1 participant
Kontext
Behebt die SSoT-Discrepancy aus #958, die bei der Codex-Findings-Verifikation an PR #957 zutage trat.
Befund
Der Agora-spezifische
CLAUDE.md-Abschnitt „Embedding-Configuration (ADR-0007)" behauptete:Das ist falsch. Code ist führend:
backend/app/services/embedding_configuration_store.py(Modul-Docstring) persistiert in einer flachen JSON-Datei unterAGORA_DATA_DIR/embedding_configurations.json—flock-Sperre, atomares Write viaos.replace, Datei-Modus 0600.EmbeddingConfigurationist ein Pydantic-Vertrag inbackend/app/contracts/embedding_contract.py, kein Neo4j-Knoten.embedding_index_versions.json).ADR-0007 selbst ist korrekt — es beschreibt genau diesen Store (
flock, atomares Write, 0600). Auchdocs/agents/architecture-ssot.mdnennt nur die Services und ist nicht betroffen. Nur derCLAUDE.md-Absatz war gedriftet.Änderung
Einzeilige Korrektur des Absatzes auf
EmbeddingConfigurationStore(JSON-Datei), mit Verweisen aufembedding_contract.py,embedding_configurations/service.pyund…/legacy.py. Migrations-Lifecycle- und Gemini-Aussagen unverändert (waren korrekt).Warum Option A (Code kanonisch)
Option B (Code nach Neo4j migrieren) ist nicht tragfähig: ADR-0007 selbst spezifiziert den JSON-Store als Umsetzung für Slice 4.2. Die JSON-Persistenz ist bewusst so designed (atomic, secret-frei, file-locked). Neo4j-Persistenz war nie intendiert — die CLAUDE.md-Aussage war reine Doku-Drift.
Verifikation
schemas: green (46 Schemas, Version 0.8.0, STATUS synchron).Closes #958.