# Hypothesis Proximity Update > Update hypothesis proximity state by invoking the canonical embedding bridge for one hypothesis. - Skill: `panjose/hypothesis-proximity-update` (Agent Skill) - Install (CLI): `npx skillmds@latest add panjose/hypothesis-proximity-update` - Raw SKILL.md: https://api.skillmd.com/api/skills/panjose/hypothesis-proximity-update/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: panjose (https://skillmd.com/u/panjose) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/panjose/hypothesis-proximity-update --- # hypothesis-proximity-update Goal: - Update hypothesis proximity state by invoking the canonical embedding bridge for one hypothesis. Inputs: - optional existing `state/PROXIMITY_GRAPH.json` - target `hypothesis_id` - run-frozen embedding provider settings from `state/RESOLVED_RUN_CONFIG.json` Outputs: - updated `state/proximity_receipts/.json` - updated `state/PROXIMITY_STATUS.json` - updated in-memory `ProximityGraphContract` - updated `state/PROXIMITY_GRAPH.json` when the provider returns a valid embedding - updated `state/PIPELINE_STATE.json` - updated `state/CURRENT_STAGE.json` Context Loading: - Open `skills/shared-references/schema-index.md`. - Read `packages/agent_contracts/state.py` and confirm the exact `ProximityGraphContract` shape before writing `state/PROXIMITY_GRAPH.json`. - Read `packages/agent_contracts/proximity.py` and confirm the proximity receipt and status schemas before interpreting provider outcomes. - Read `packages/agent_contracts/pipeline_runtime.py` before updating `state/PIPELINE_STATE.json` or `state/CURRENT_STAGE.json`. - Load the current proximity graph if it exists. If it does not exist yet, start from an empty `ProximityGraphContract`. - Treat embedding generation as a bridge/tool concern. Host agents must not generate, infer, paste, or hand-write numeric embeddings in prompt output. - Do not skip this skill merely because no embedding vector is already present in the execution context. Execution Contract: - This skill is deterministic and must not call an LLM. - Use `from tools import sync_pipeline_stage_artifacts` as the canonical paired write surface for entering the `Proximity` substage. - On entry, call `tools.sync_pipeline_stage_artifacts(run_dir, current_phase="Proximity", current_skill="hypothesis-proximity-update")`. - Use `from tools import update_hypothesis_proximity` as the stable invocation surface. - The exported bridge is implemented in `packages/agent_mechanics/hypothesis_embedding.py`. - The canonical hypothesis-to-embedding text formatter is implemented in `packages/agent_mechanics/hypothesis_embedding_text.py`. - The helper signature is `update_hypothesis_proximity(run_dir, hypothesis_id, config=None, provider=None) -> ProximityEmbeddingReceiptContract`. - The bridge formats the hypothesis text, reads the run-frozen proximity provider settings from `state/RESOLVED_RUN_CONFIG.json` unless an explicit test config is passed, calls the configured provider when enabled, records a proximity receipt/status, and updates `state/PROXIMITY_GRAPH.json` only when a valid embedding is returned. - Provider-specific backends such as `openai_compatible` and `gemini` must remain behind `tools.update_hypothesis_proximity(...)`; host agents must not call provider SDKs directly or paste provider-returned vectors into artifacts. - The lower-level graph helper remains `tools.update_proximity_graph(...)`, implemented in `packages/agent_mechanics/proximity_update.py`; host agents must not call it with prompt-fabricated vectors. - This skill must not hand-write embeddings, infer embeddings from hypothesis prose, or fabricate placeholder numeric vectors. - If the provider is disabled, unavailable, invalid, or fails, preserve the bridge-written receipt/status, do not fabricate a graph update, and return control to ranking with receipt-gated fallback semantics. Execution Steps: 1. Open `skills/shared-references/schema-index.md`, then read `packages/agent_contracts/state.py`, `packages/agent_contracts/proximity.py`, and `packages/agent_contracts/pipeline_runtime.py` before writing proximity or run-level stage artifacts. 2. Before running the bridge, call `tools.sync_pipeline_stage_artifacts(run_dir, current_phase="Proximity", current_skill="hypothesis-proximity-update")`. 3. Confirm the target `hypothesis_id` identifies an existing canonical `hypotheses//HYPOTHESIS.json` artifact. 4. Call `tools.update_hypothesis_proximity(run_dir, hypothesis_id)` exactly once for the target hypothesis. 5. Inspect the returned `ProximityEmbeddingReceiptContract` and the persisted `state/proximity_receipts/.json`. 6. If the receipt status is `succeeded`, validate the updated `state/PROXIMITY_GRAPH.json`. 7. If the receipt status is `skipped_disabled`, `skipped_provider_unavailable`, `failed_provider_error`, or `failed_invalid_embedding`, preserve the receipt/status and return control to ranking. Do not infer or fabricate placeholder embeddings from text, IDs, or manual feature heuristics. 8. Validate the updated receipt/status artifacts before declaring completion. Artifact Rules: - `state/PROXIMITY_GRAPH.json` must remain the canonical persisted graph artifact. - `state/proximity_receipts/.json` is the canonical per-hypothesis embedding bridge receipt. - `state/PROXIMITY_STATUS.json` is the canonical run-level proximity bridge status artifact. - Similarity edges must stay symmetric across both hypothesis IDs. - Each persisted graph embedding should include metadata for provider, model, dimensions, input text hash, and embedding config hash. - If the graph already contains the target hypothesis ID with the same embedding input hash and embedding config hash, the bridge may confirm the existing state through a `succeeded` receipt with `graph_updated=false`; do not duplicate entries. - If the graph already contains the target hypothesis ID with different or missing input/config metadata, preserve the bridge receipt and do not overwrite the existing embedding in prompt code. - Placeholder embeddings, manually engineered stand-in vectors, or prose-derived pseudo-embeddings must never be written into the canonical graph artifact. Completion Rule: - This skill is complete only when `tools.update_hypothesis_proximity(run_dir, hypothesis_id)` has returned a persisted receipt and either `state/PROXIMITY_GRAPH.json` validates after a `succeeded` receipt or the receipt/status explicitly records why the graph was not updated.