Rework on-demand embedding config, drop CaVa tokenizer, migrate to oa-configurator 1.0

[nicoloesch]

Depends on: omop-emb and oa-configurator's new vector_stores domain plus its database-kind split, both must merge and publish first. Bumps pyproject.toml's oa-configurator pin (main + dev extra); flags omop-emb/omop-alchemy pins as needing their own next-breaking-release bump too (see version-constraint markers below), # TODO markers in the diff.

Summary

• KnowledgeGraphEmbeddingConfiguration reworked:
  -backend: EmbeddingBackend and resolved_model: ResolvedModel both required fields (not Optional)
  • write: bool/compute_missing_embeddings: bool/faiss_cache_dir: str | None. model_name/provider_type are now plain properties reading straight off resolved_model (.model/.provider.provider)
  • Verification in __post_init__
• Fixed on-demand embedding computation as it used to raise a TypeError on a read-only-configured KG
  • Split get_embedding_writer_interface() (raises, for call sites that already guarantee write) from a new try_get_embedding_writer_interface() (never raises, for opportunistic on-demand use).
• Dropped the CaVa NLP tokenizer (utils/text_utils.py, OMOPTextAnnotatorInterface's tokenizer param)
  • dead weight, since annotate_text() already grounds the whole text in one call rather than iterating spans.
  • was never used anyways
• OmopGraphConfig:
  • same rename pattern (resource → database + connection).
  • required_resources/owned_resources collapse into a single cdm_db: RefTo(CDMDatabaseConfig) field, and
  • engine resolution now goes through this package's own config instead of hardcoding OmopAlchemyConfig.
  • Also gained embedding_model_name/vector_store_name
    • both Optional RefTo fields (ModelConfig/VectorStoreConfig), meaning no configuration necessary
    • omop-graph itself never reads them as of now but the functionality is there in case a CLI entrypoint eventually exists for omop-graph. Preemptively setting the structure so it doesn't need to happen

Relationship to open PRs and issues

Config resolution boundary, absorbs omop-graph#30/#31 (30-remove-config-reads)

• Absorbs Remove config calls from internal functions and expose only at interf… #31 rather than merged standalone. Its design is adopted here, taken further than the original PR did.

  • Closes Refactor: move config reads out of dataclasses and algorithmic functions #30

• graph/paths.py: find_shortest_paths/find_shortest_paths_batch/find_standard_paths take plain max_depth: int = 6/max_paths: int = 20 defaults.

  • No internal OmopGraphConfig.get_config() read; caller supplies the resolved value.

• reasoning/grounding.py: GroundingConstraints.max_depth is a plain int = 6, same fix, default_factory removed.

• graph/kg.py's .emb property: no longer imports omop_emb.config/OmopEmbConfig at all.

  • This goes further than #31, which only updated the resolve_backend() call's parameters but kept the OmopEmbConfig.get_config() read for faiss_cache_dir.
  • KnowledgeGraphEmbeddingConfiguration now accepts an already-constructed EmbeddingBackend as a parameter (plus, for the read-only path, faiss_cache_dir: str | None). The caller resolves the vector store itself via the new vector_stores domain and passes the built backend in. omop-graph resolves nothing.

• oaklib_interface/omop_implementation.py:

  • OMOPAlchemyImplementation.__init__'s silent no-args omop_resource() fallback removed. Raises ValueError naming the explicit fix (resource=omop_resource()) when neither engine_string nor resource is given.
  • annotate_text() gains an explicit max_depth: Optional[int] = None parameter, consistent with how this method already extends OAK's base TextAnnotatorInterface signature with query_embedding/annotations. Threaded into GroundingConstraints(max_depth=...) when given. No config read inside this method; the caller resolves its own value.

• Docstring Notes section added to OmopGraphConfig.

RAG context

• Absorbs Add optional context parameter to embedding-based grounding #29 rather than merged standalone. Its design is adopted as-is, with one wording update.
  • Closes Increase Context for Grounding in RAG #19
• reasoning/grounding.py: new _query_text_with_context(query: str, context: Optional[str]) -> str helper
  • folds optional free-form context into the on-demand query-embedding text (blank-line-separated)
  • ground_term() gains context: Optional[str] = None -> no effect when omitted or when query_embedding is supplied directly.
• The original #29 design's docstring rationale referenced omop-emb's embedding-error wrapping (EmbeddingClientError) as the reason no length guard is needed here.
  • That wrapping no longer exists in the omop_llm-based world
  • Updated the docstring to reference any_llm.exceptions.ContextLengthExceededError (surfaced raw, uncaught, through omop_emb/omop_llm) as what actually surfaces an oversized-input failure now.
• No input-length confinement added beyond that. Relevance of supplied context is a caller responsibility, not something this function can validate.

Semver ranges

• Absorbs Widen omop-alchemy, oa-configurator, and omop-emb pins to semver ranges #33