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

Dependency-shaped wrapper around the omop-graph backend runtime.

This adapter owns everything omop-graph specific: the KnowledgeGraph lifecycle and embedding configuration, translation of omop-graph/SQLAlchemy exceptions into GroundworkersError, and a set of normalized primitives that each map to roughly one omop-graph operation and return plain dicts / tuples (never raw omop-graph objects).

Multi-step orchestration (hierarchy walks, path assembly, grounding tier selection, neighbourhood shaping) lives in GraphService, which composes these primitives. Keep this class dependency-shaped: no caller-facing policy.

embedding_resolver_active property

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

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

concept_views(concept_ids)

Batch-fetch normalized concept views keyed by concept_id.

Returns an empty dict when no ids are supplied or the lookup fails, so callers can treat a missing key as "unknown concept" without special-casing backend errors during enrichment.

edges(concept_id, *, direction, predicate_kinds=None, active_only)

Return normalized edges for one concept (no concept-name enrichment).

Each edge: {subject_id, object_id, predicate_id, predicate_kind, valid}.

probe()

Return (available, detail) without raising.

run_ground_tier(resolvers, query, *, constraints, limit)

Run one resolver tier through omop-graph and normalize the hits.

Returns ground hits without concept-view enrichment; GraphService adds vocabulary/domain/class fields and applies tier-selection policy.

set_embedding_client(client, model_name=None)

Configure an EmbeddingClient so the embedding grounding tier can encode queries.

Safe to call after construction. Any cached KnowledgeGraph is invalidated so the embedding-enabled graph configuration is rebuilt on the next request.

shortest_paths(source_id, target_id, *, max_depth, predicate_kinds=None, within_domain)

Return shortest paths as lists of normalized steps (no name enrichment).

Each step: {subject_id, object_id, predicate, predicate_kind}.

traverse_neighborhood(concept_id, *, predicate_kind_names, max_depth, max_nodes)

Bounded BFS from a seed concept.

Returns {neighbor_ids, edges, edge_count, terminated_reason} where edges are normalized ({subject_id, predicate_id, predicate_kind, object_id}) and neighbor_ids excludes the seed. Raises INVALID_INPUT for an unknown predicate-kind name.

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_client_for_model(model_name=None)

Return a configured query-time embedding client for one model.

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.

resolve_model_name(model_name=None)

Resolve a caller-supplied or default embedding model name.

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>"}.