Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ build/
*.egg-info/
.DS_Store
_design/
/evaluation/
*.log
*.bak
*.tmp
Expand All @@ -20,4 +21,4 @@ site/
_knowledge/
data/
.env
*.db
*.db
5 changes: 5 additions & 0 deletions docs/development/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,11 @@ The concept-embedding row and the free-text-embedding row look similar but are n

Use `context.cdm_session_factory` for role-tagged OMOP queries. `context.cdm_engine` remains available for primary-role access. On split-vocabulary stacks, plugins must use the routed factory; an Engine-based OmopGraphAdapter or DomainNameResolver cannot route vocabulary queries and will fail with upgrade guidance.

Plugins may pass `toolsets=("my_toolset",)` to `server.tool()` to declare their
own toolsets. When omitted or empty during plugin registration, the server uses
`plugin:<name>`, where `<name>` is the plugin's registered name. Toolsets appear in
`--describe` and stay outside MCP tool definitions.

`register()` adds MCP tools, prompts, or resources against the state returned by `build()`. The shared MCP registration wrapper supplies the same safe error translation used by core tools. Code-defined prompts can continue to derive their arguments from the callable signature. A plugin publishing data-defined prompts can pass explicit string metadata with `PromptArgument`; this keeps dynamic pack fields out of Python closure signatures:

```python
Expand Down
2 changes: 1 addition & 1 deletion docs/services/graph.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Return a serialized OMOP concept from a known identifier.

### `get_ancestors(...)` and `get_descendants(...)`

Walk the OMOP hierarchy with bounded depth and serialized results.
Read the stored `concept_ancestor` table with bounded minimum separation and serialized results. `get_descendants(...)` can also filter exact concept class IDs before paging; unpaged and paged results use the same stored rows.

### `get_edges(...)` and `get_neighbors(...)`

Expand Down
35 changes: 24 additions & 11 deletions docs/tools/concept.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,22 +69,35 @@ Returns stored non-self ancestors up to minimum separation `max_depth` (default

---

Ancestry is read directly from the stored OMOP closure, with non-self
zero-separation ancestors retained. `max_depth` accepts 0..20 and measures stored
minimum separation; invalid values are rejected. The response preserves
`ancestors` and reports `ancestry_source`, `distance_metric`, effective `max_depth`
and `include_self=false`. A zero-distance link does not imply interchangeability.
Parent/child primitives and descendant traversal keep their existing semantics.
Ancestry is read directly from the stored OMOP closure, with non-self zero-separation ancestors retained. `max_depth` accepts 0..20 and measures stored minimum separation; invalid values are rejected. The response preserves `ancestors` and reports `ancestry_source`, `distance_metric`, effective `max_depth` and `include_self=false`. A zero-distance link does not imply interchangeability. Parent/child primitives expose direct graph relationships. Descendant results use the stored `concept_ancestor` table.

## `concept_descendants`

Returns descendants of a concept up to `max_depth` hops (default 3, max 10).
Returns descendants from the stored `concept_ancestor` table (default depth 3, range 1..10). `depth` is the stored minimum separation, not a count of graph relationship hops. Results are ordered by depth and then concept ID. Use `limit` (default 50, range 1..500) and `offset` (default 0, minimum 0) to page through the stored ancestry. `concept_class_ids` optionally filters by exact `concept_class_id` before paging; `total` counts only matching descendants. For drug concepts, filter by classes such as `["Clinical Drug"]` because greater depth does not mean greater drug specificity. Unknown class IDs are rejected.

```json
{"concept_id": 441484, "max_depth": 2}
{"concept_id": 1503297, "max_depth": 3, "limit": 50, "offset": 0, "concept_class_ids": ["Clinical Drug"]}
```

**Response**: same shape as ancestors, with `"descendants"` key instead of `"ancestors"`.
**Response**:

```json
{
"concept_id": 441484,
"descendants": [
{"concept_id": 441485, "depth": 1},
{"concept_id": 441486, "depth": 1}
],
"total": 12,
"returned": 2,
"truncated": true,
"limit": 50,
"offset": 0,
"max_depth": 2
}
```

`total` counts all descendants within `max_depth`; `truncated` is true when more rows remain after the returned page. Results are ordered by minimum depth, then `concept_id`.

---

Expand Down Expand Up @@ -140,7 +153,7 @@ Returns the shortest path between two concepts traversing only identity (and opt

All parameters except `source_id` and `target_id` are optional.

`allow_hierarchical_traversal=false` (default): only IDENTITY predicates (`Maps to`, `Concept same_as`, `Concept poss_eq`, etc.). The connection found represents a direct cross-vocabulary equivalence with no loss of specificity.
`allow_hierarchical_traversal=false` (default): only IDENTITY predicates, including `Maps to`, `Concept same_as`, cross-vocabulary equivalence and replacement links. `Concept poss_eq` is an ASSOCIATION predicate and is excluded.

`allow_hierarchical_traversal=true`: also allows HIERARCHY predicates (`Is a` / `Subsumes`). A path may then step up or down the ancestry chain; the connection may be at a broader level of abstraction.

Expand Down Expand Up @@ -307,7 +320,7 @@ Use the ancestor/descendant tools for the usual “what is this a kind of?” qu

## `concept_map_to_standard`

Maps a non-standard concept (identified by vocabulary + code) to its standard OMOP equivalent via IDENTITY-type relationship edges.
Resolves a vocabulary/code pair through all IDENTITY-type relationship edges. These include `Maps to value` and `Maps to unit`, so standard value or unit targets can appear alongside the `Maps to` target. For `Maps to` targets alone, use `concept_navigate_to_standard` with the source concept ID.

```json
{"vocabulary_id": "ICD10CM", "concept_code": "C34.1"}
Expand Down
8 changes: 4 additions & 4 deletions docs/tools/domain.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ It is a thin wrapper over `DomainService`.

## `domain_classify`

Classifies field labels into OMOP domains using the label text and any example response values supplied by the caller.
Uses a language model to guess the domain of each field from its label and at most the first 10 example values.

```json
{
Expand All @@ -25,7 +25,7 @@ Classifies field labels into OMOP domains using the label text and any example r

`label_values` is required. It maps each field label to a list of example response-value strings. Use an empty list when no values are known.

`model_name` is optional and overrides the default model from the LLM config for this call.
`model_name` is optional and accepts only the configured chat model or null.

**Response:**

Expand All @@ -39,7 +39,7 @@ Classifies field labels into OMOP domains using the label text and any example r
}
```

Only confident classifications are returned. Labels that the model cannot place confidently into a single OMOP domain are omitted so the caller can continue with fallback logic.
Assignments with null or invalid domain values are omitted. There is no confidence score or confidence threshold, and model-returned label keys are not checked against the input labels.

Valid returned domains are:

Expand All @@ -66,7 +66,7 @@ Prefer text tools when you need to normalize or decompose clinical phrases. Pref

| Error code | Condition |
|---|---|
| `BACKEND_UNAVAIL` | LLM API unreachable, authentication failure, or LLM backend not configured |
| `BACKEND_UNAVAIL` | Configured LLM API unreachable or authentication failure |
| `QUERY_ERROR` | Model API error or response could not be parsed |

## Typical downstream use
Expand Down
2 changes: 1 addition & 1 deletion docs/tools/embedding.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,4 +115,4 @@ Encodes a text string into one query embedding vector.
}
```

Like `embedding_search`, this requires a configured `embedding_model_name` and a live provider client.
Like `embedding_search`, this requires a configured `embedding_model_name` and a live provider client. Encoding accepts only that configured live model, even when other models are registered for stored-vector operations.
2 changes: 1 addition & 1 deletion docs/tools/knowledge.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ The knowledge tools are registered when at least one packs root is available. `k

## `knowledge_catalogue`

Find packs whose applicability matches the supplied context. Omit filters to list all discovered packs.
Find packs whose applicability matches the supplied context. Begin mapping and review jobs by discovering applicable packs with the involved domains, then load them before choosing candidates. Omit filters to list all discovered packs.

```json
{
Expand Down
78 changes: 36 additions & 42 deletions docs/tools/mapping.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,13 +31,13 @@ flowchart TD

## `concept_ground` vs mapping tools

`concept_ground` is the simplest choice for a single ranked grounding result.
Start source-term searches with `concept_candidate_bundle`. Use `concept_ground` for a fast lead from the first matching resolver tier.

The mapping tools are better when you want to inspect evidence and make an explicit selection.

| If you want... | Prefer... |
|---|---|
| One best-answer grounding result | `concept_ground` |
| A fast lead from the first matching tier | `concept_ground` |
| Multiple retrieval channels in one packet | `concept_candidate_bundle` |
| Deterministic normalized matching before ranked retrieval | `concept_search_normalized` |
| Rich context for a selected concept | `concept_mapping_context` |
Expand Down Expand Up @@ -66,7 +66,7 @@ Useful response fields:

## `concept_candidate_bundle`

Builds one evidence packet by combining:
The default source-term search builds one evidence packet by combining:

- exact search
- normalized search
Expand All @@ -90,11 +90,16 @@ Builds one evidence packet by combining:

Representative response sections:

- `channels`
- `channels`: each MCP channel contains only `available` and `count`
- `standardized_candidates`
- `candidate_union`
- `warnings`

In the MCP response, `channels` has the shape `{"exact": {"available": true, "count": 2}}`, with one entry per channel that ran. Counts describe the channel results before deduplication or the merged-list limit. Candidate details remain in `candidate_union`, where `retrieved_by` identifies their channels. `standardized_candidates`, `constraints` and `warnings` retain their existing shapes. The direct Python service and REST endpoint continue to return full channel result lists.

Hierarchy previews and relationship summaries enrich only the first five
merged candidates.

## `concept_nearest_standard_ancestor`

Finds the nearest active standard ancestor using stored OMOP separation, abstaining on equal-distance ties. Accepts either a free-text query or an explicit `concept_id`. Useful when a source concept is too specific or non-standard and you need a broader standard parent.
Expand All @@ -107,6 +112,8 @@ Finds the nearest active standard ancestor using stored OMOP separation, abstain
}
```

In query mode, `vocabulary_id` and `parent_ids` constrain grounded seeds; they do not filter ancestor targets. `candidate_limit` bounds the retrieved seed list, and only its first candidate is used for ancestor selection.

Useful response fields:

- `seed_candidates`
Expand Down Expand Up @@ -141,6 +148,20 @@ Possible sections include:
- `embedding_neighbors`
- `warnings`

Set `include_descendants=true` to include up to `descendant_limit` rows (default 10, range 1..10) from three stored hierarchy levels. `descendant_scope` reports `max_depth`, `limit`, the full `total`, and whether more rows remain in `truncated`. The row limit does not change which descendants qualify.

```json
{
"descendants": [{"concept_id": 441484, "depth": 1}],
"descendant_scope": {
"max_depth": 3,
"limit": 1,
"total": 12,
"truncated": true
}
}
```

## `concept_map_to_value`

Finds `Maps to value` relationships for a source vocabulary ID and concept code.
Expand Down Expand Up @@ -175,7 +196,9 @@ Expands a simple list of concept items with support for:

## `mapping_evaluate_candidates`

Compares predicted mappings with a reference mapping set using `standard_concept_id` agreement.
Compares predicted mappings with a reference mapping set using hit-at-k agreement: the reference ID must occur within the first `top_k` predicted IDs. Omitting `top_k` uses all predictions. IDs are compared in memory without checking the vocabulary.

Rows are paired by `source_key`, `source_id` or `source_term`, in that order. Reference rows require `reference_standard_concept_id`; prediction rows use a ranked `predicted_standard_concept_ids` list (or `predicted_concept_ids`).

```json
{
Expand Down Expand Up @@ -221,51 +244,22 @@ context = mapping.concept_mapping_context(201826)

## `concept_shared_standard_ancestor`

Read-only, deterministic common-ancestor selection for alternative concept IDs
representing one source record. It needs a configured vocabulary/graph, not an
embedding or LLM backend. Do not use separate combination ingredients as if they
were alternative product candidates.
Read-only, deterministic common-ancestor selection for alternative concept IDs representing one source record. It needs a configured vocabulary/graph, not an embedding or LLM backend. Do not use separate combination ingredients as if they were alternative product candidates.

Supply `concept_ids` (2..200 positive strict integers, at least two distinct),
`max_depth` (0..20, default 5), optional `concept_class_ids` / `vocabulary_ids`,
and display `limit` (1..50, default 10) / `offset` (default 0). Filters must use
exact installed catalogue IDs; null is unrestricted, empty/blank/unknown filters
are invalid. RxNorm alone does not include RxNorm Extension.
Supply `concept_ids` (2..200 positive strict integers, at least two distinct), `max_depth` (0..20, default 5), optional `concept_class_ids` / `vocabulary_ids`, and display `limit` (1..50, default 10) / `offset` (default 0). Filters must use exact installed catalogue IDs; null is unrestricted, empty/blank/unknown filters are invalid. RxNorm alone does not include RxNorm Extension.

```json
{"concept_ids": [40166038, 41038881], "concept_class_ids": ["Clinical Drug"], "vocabulary_ids": ["RxNorm", "RxNorm Extension"], "max_depth": 5}
```

The response is `{error, code, message, data}`. On success `data.status` is
`selected`, `ambiguous`, `no_match`, or `incompatible_inputs`. `found` indicates a
unique selection, so it is false for an ancestry tie. Eligible targets must be
active standard concepts in the same domain as every input. The response echoes
constraints, complete-set counts and per-input distances for any selected target.
The response is `{error, code, message, data}`. On success `data.status` is `selected`, `ambiguous`, `no_match`, or `incompatible_inputs`. `found` indicates a unique selection, so it is false for an ancestry tie. Eligible targets must be active standard concepts in the same domain as every input. The response echoes constraints, complete-set counts and per-input distances for any selected target.

Distances are stored minimum separation from `CONCEPT_ANCESTOR`. Include each
seed itself at zero; retain distinct zero-separation ancestors. Such a connection
does not prove clinical interchangeability. Nearest means the lowest maximum
distance across all inputs. Equal nearest distances abstain. Display pagination
never changes that computation; `limit=1` cannot force a selection. A selected
concept is returned independently of the candidate display page.
Distances are stored minimum separation from `CONCEPT_ANCESTOR`. Include each seed itself at zero; retain distinct zero-separation ancestors. Such a connection does not prove clinical interchangeability. Nearest means the lowest maximum distance across all inputs. Equal nearest distances abstain. Display pagination never changes that computation; `limit=1` cannot force a selection. A selected concept is returned independently of the candidate display page.

Native MCP argument/schema errors set `isError=true`. Errors from the service
use the typed envelope with `error=true` and `data=null`. Backend failure is never
a no-match. Text and structured payloads are normalized to the same envelope.
Native MCP argument/schema errors set `isError=true`. Errors from the service use the typed envelope with `error=true` and `data=null`. Backend failure is never a no-match. Text and structured payloads are normalized to the same envelope.

### Ancestry consistency changes

`concept_nearest_standard_ancestor` and hierarchy previews now use the same stored
ancestry as `concept_ancestors`. Nearest-standard ties abstain instead of selecting
the first row. Query mode still starts from the first grounded candidate, which
is disclosed as `seed_selection_policy`; source-concept ambiguity remains the
agent's responsibility. Maps-to fallback is labelled `evidence_route=maps_to`,
with multiple targets left ambiguous. Missing relationship paths do not invalidate
stored ancestor evidence and are reported separately.

`concept_mapping_context` uses `ancestor_limit` only as a display count (1..50).
`ancestor_max_depth` independently sets stored separation (0..20, default 5).
`ancestor_scope` reports the full count and whether the display was truncated.
Ancestor bounds now reject invalid values rather than silently clamping them.
For the runtime contract and bounded relationship-neighborhood behavior see
[stored ancestry and shared targets](../adapters/ancestry.md).
`concept_nearest_standard_ancestor` and hierarchy previews now use the same stored ancestry as `concept_ancestors`. Nearest-standard ties abstain instead of selecting the first row. Query mode still starts from the first grounded candidate, which is disclosed as `seed_selection_policy`; source-concept ambiguity remains the agent's responsibility. Maps-to fallback is labelled `evidence_route=maps_to`, with multiple targets left ambiguous. Missing relationship paths do not invalidate stored ancestor evidence and are reported separately.

`concept_mapping_context` uses `ancestor_limit` only as a display count (1..50). `ancestor_max_depth` independently sets stored separation (0..20, default 5). `ancestor_scope` reports the full count and whether the display was truncated. Ancestor bounds now reject invalid values rather than silently clamping them. Descendants use a fixed stored-ancestry depth of 3; `descendant_limit` remains a row count (1..10), and `descendant_scope` reports the full count and truncation. For the runtime contract and bounded relationship-neighborhood behavior see [stored ancestry and shared targets](../adapters/ancestry.md).
Loading
Loading