Skip to content

Adapters — API Reference

CDMAdapter

groundworkers.adapters.cdm

CDMAdapter

Adapter for a CDM (Common Data Model) database connection.

Holds the SQLAlchemy engine and session factory for an OMOP CDM database. Shared by services that need to query the CDM directly (VocabService, OmopGraphAdapter).

Pass engine to adapters that wrap their own session management. Use session() for services that need a scoped session context manager.

engine property

The underlying SQLAlchemy engine.

close()

Dispose the engine and release the connection pool.

is_available()

Return True if the CDM database is reachable (SELECT 1 probe).

session()

Return a session context manager.

OmopGraphAdapter

groundworkers.adapters.omop_graph

OmopGraphAdapter

embedding_resolver_active property

True when an EmbeddingClient is configured and the embedding tier in concept_ground is live.

Independent from OmopEmbAdapter.is_available() — both must be True to confirm the full embedding pipeline is operational.

find_equivalency_path(source_id, target_id, max_depth, allow_hierarchical_traversal=False)

Find paths restricted to identity (and optionally hierarchy) edges.

When allow_hierarchical_traversal=False only IDENTITY predicates are traversed (Maps to, Concept same_as, Concept poss_eq, etc.) — the result represents a direct cross-vocabulary equivalence with no loss of specificity.

When allow_hierarchical_traversal=True HIERARCHY predicates (Is a / Subsumes) are also allowed. A path may then step up or down the ancestry chain to find a connection, meaning the target may be an ancestor of the source — equivalence at a broader level.

within_domain is always False for equivalency paths: identity relationships are designed to cross vocabulary/domain boundaries.

get_neighbors(concept_id, max_depth, predicate_kinds, max_nodes, include_edges)

Bounded multi-hop neighborhood exploration via BFS.

Follows outgoing relationship edges from the seed concept up to max_depth hops, collecting all reachable concepts and (optionally) the edges that connect them.

ground(query, limit, domain, vocabulary_id, parent_ids=None)

Ground free text to ranked standard OMOP concepts.

Returns a dict with keys

results — ranked list of grounded concepts with scoring fields grounding_explanation — summary of which tier matched and what constraints ran

probe()

Return (available, detail) without raising.

set_embedding_client(client, model_name=None)

Configure an EmbeddingClient so concept_ground can encode query strings on-the-fly.

Safe to call after construction — the knowledge graph does not need to be rebuilt.

OmopEmbAdapter

groundworkers.adapters.omop_emb

OmopEmbAdapter

Adapter for an omop-emb vector store backend.

Two operation modes are available depending on configuration:

  • Index lookup (get_neighbours): uses pre-stored embeddings from the backend; no encoding client is required.
  • Text search (search, encode): encodes a query string on-the-fly before searching; requires an encoding client (api_base / api_key in config).

has_client() reflects which mode is available at runtime.

close()

Release cached backend and client references.

encode(text, model_name)

Return the embedding vector for text. Requires an encoding client.

get_neighbours(concept_id, limit, model_name)

Return the limit nearest concepts to concept_id using its stored embedding.

Does not require an encoding client. Raises NOT_FOUND if the concept has no stored embedding in the index.

has_client()

Return True if an encoding client is configured (required for search and encode).

index_status()

Return index availability and per-model statistics.

Always returns a dict — never raises. On backend failure, returns {"available": False, "backend_type": ..., "models": [], "detail": "<reason>"}.

is_available()

Return True if the backend is reachable and at least one model is registered.

search(query, limit, domain, vocabulary, standard_only, active_only, model_name)

Encode query and return the nearest matching concepts.

Requires an encoding client (has_client() must be True). Results are optionally filtered by domain, vocabulary, standard status, and active status.

LLMAdapter

groundworkers.adapters.llm

LLMAdapter

Adapter for OpenAI-compatible LLM chat completion APIs.

Works with any provider that implements the OpenAI chat completions API: local deployments (Ollama, vLLM, LM Studio) and remote services (OpenAI, Azure OpenAI, and compatible cloud APIs). Configure api_base to point at the correct endpoint.

Two completion modes are available:

  • Text completion (complete_text): returns a raw text response.
  • Structured completion (complete_structured): requests a JSON response matching a caller-supplied schema. Preferred for MCP-facing tools where downstream agents need to parse the output reliably.

close()

Release the cached client.

complete_structured(prompt, response_schema, *, system_prompt=None, model_name=None, temperature=0.0)

Complete a prompt and return a parsed JSON dict guided by response_schema.

The schema is injected into the system prompt and JSON mode is requested from the API. This is compatible with Ollama, vLLM, and OpenAI endpoints.

The response is parsed but not validated against the schema — callers are responsible for validating the returned dict (e.g. with Pydantic).

Raises INVALID_INPUT if no model is resolvable or if response_schema is not JSON-serializable. Raises BACKEND_UNAVAIL if the API call fails. Raises QUERY_ERROR if the response is not valid JSON.

complete_text(prompt, *, system_prompt=None, model_name=None, temperature=0.0)

Complete a prompt and return the response text.

Raises INVALID_INPUT if no model is resolvable. Raises BACKEND_UNAVAIL if the API call fails.

is_available()

Return True if the LLM API is reachable.

status()

Return availability and configuration details. Never raises.

Probes the API with a short timeout. On failure returns {"available": False, ..., "detail": "<reason>"}.