docs: lobes embedder as the reference deployment; scores are model-relative (#10, #11)

[OriNachum]

Summary

Documentation-only change (colleague#291 slice S2, relates to issues #10/#11 — colleague#293 is the consumer side). Adds a README "Reference deployment" note (Meaning Gradient section) and a matching coherence/meaning/embed.py docstring addition naming the lobes gateway's embedder role (lobes-cli >= 0.38, discoverable via GET /capabilities) as the reference COHERENCE_EMBED_URL/COHERENCE_EMBED_MODEL deployment — consumers such as colleague resolve the endpoint from lobes and inject those two env vars when armed. Both spots also note, worded per issues #10/#11, that each meaning score is a model-relative, anchor-defined measurement (the embedding model + anchor set are the score's reference frame/gauge) — never universal meaning. No defaults, code behavior, or tests changed.

Also re-syncs uv.lock's recorded coherence-cli version, which was stale at 0.4.1 while pyproject.toml/CHANGELOG.md had already moved to 0.5.0 — a self-heal, not a new behavior change.

Honest note on provenance: the documentation change itself (README + embed.py docstring) was authored by the colleague backend (the locally served 27B model, via colleague work), not by Claude, and was graded 5/5 through colleague's own feedback loop. This PR's version bump + CHANGELOG entry (this commit) were prepared by Claude following the standard release mechanics for the colleague#291 integration arc.

Test plan

• uv run pytest -n auto -q — 146 passed

No known deviations or honest limits — this is a docs-only change.

🤖 Generated with Claude Code

• colleague (Claude)

[qodo-code-review]

PR Summary by Qodo

Docs: clarify lobes embedder reference deployment & model-relative meaning scores

📝 Documentation ⚙️ Configuration changes 🕐 10-20 Minutes

AI Description

• Document lobes gateway embedder role as the reference embedding deployment for consumers.
• Clarify meaning scores are model-relative and anchor-defined (not universal meaning).
• Bump package version to 0.5.1 and record the change in the changelog.

Diagram

graph TD
  A[Consumer (e.g., colleague)] --> B[Lobes gateway]
  B --> C[Capabilities lookup]
  C --> D[Set COHERENCE_EMBED_URL/MODEL]
  D --> E[coherence-cli meaning score]
  E --> F[Embedding endpoint]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Add first-class lobes discovery in coherence-cli

• ➕ Eliminates manual env var injection for consumers
• ➕ Reduces configuration drift between consumer and CLI
• ➕ Centralizes the reference deployment logic in one place
• ➖ Introduces a new runtime dependency/behavior (network discovery)
• ➖ Requires defining failure modes, caching, and precedence rules vs env vars
• ➖ Higher testing and backward-compatibility burden than a docs-only change

2. Publish a fixed canonical hosted embed endpoint

• ➕ Simplifies setup: no discovery needed
• ➕ Easier to reproduce scores if model + anchors are pinned
• ➖ Operational overhead and availability/SLA concerns
• ➖ May conflict with deployments that require local/private models
• ➖ Still doesn’t solve model-relative interpretation without additional metadata

Recommendation: Keep the current docs-first approach: it clarifies the intended reference deployment (lobes embedder) and the critical interpretability constraint (scores are model-relative and anchor-defined) without introducing new runtime behavior. If consumer friction persists, consider a follow-up PR to optionally support lobes discovery in coherence-cli while preserving env-var override semantics.

Files changed (4) +43 / -1

Documentation (3) +42 / -0

CHANGELOG.mdAdd 0.5.1 release notes covering reference deployment and score framing +20/-0

Add 0.5.1 release notes covering reference deployment and score framing

• Introduces a 0.5.1 entry describing the new documentation clarifying lobes as the reference embedder deployment and that meaning scores are model-relative and anchor-defined. Records the release date and summarizes the scope as documentation-focused.

CHANGELOG.md

README.mdDocument lobes 'embedder' reference deployment and model-relative meaning scores +12/-0

Document lobes 'embedder' reference deployment and model-relative meaning scores

• Adds a "Reference deployment" subsection explaining that lobes exposes an 'embedder' role discoverable via 'GET /capabilities', and that consumers can inject 'COHERENCE_EMBED_URL' / 'COHERENCE_EMBED_MODEL'. Clarifies that meaning scores are measurements relative to the chosen embedding model and anchor set (not universal meaning).

README.md

embed.pyExtend module docstring with lobes embedder reference deployment guidance +10/-0

Extend module docstring with lobes embedder reference deployment guidance

• Expands the module-level documentation to mirror the README guidance on using lobes' 'embedder' role as the reference deployment and setting 'COHERENCE_EMBED_URL' / 'COHERENCE_EMBED_MODEL'. Adds the note that meaning scores are model-relative and anchor-defined, serving as a reference frame (gauge).

coherence/meaning/embed.py

Other (1) +1 / -1

pyproject.tomlBump coherence-cli version to 0.5.1 +1/-1

Bump coherence-cli version to 0.5.1

• Updates the project version from 0.5.0 to 0.5.1 to reflect the new release documented in the changelog.

pyproject.toml

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review