groundworkers 0.6.0__tar.gz → 0.7.0__tar.gz

{groundworkers-0.6.0 → groundworkers-0.7.0}/.github/workflows/ci.yml

@@ -35,14 +35,8 @@ jobs:
           --password postgres \
           --database-name test_db \
           --test-only false
-        uv run omop-config databases add test_cdm_db \
-          --kind cdm \
-          --connection pg_test \
-          --schema-name public
-        uv run omop-config databases add test_vector_db \
-          --kind generic \
-          --connection pg_test \
-          --schema-name public
+        uv run omop-config databases add cdm test_cdm_db --connection pg_test --cdm-schema public
+        uv run omop-config databases add generic test_vector_db --connection pg_test --schema-name embeddings
         uv run omop-config vector-stores add test_embeddings \
           --backend-type pgvector \
           --database test_vector_db

{groundworkers-0.6.0 → groundworkers-0.7.0}/.gitignore

@@ -19,4 +19,5 @@ settings.json
 site/
 _knowledge/
 data/
-.env
+.env
+*.db

{groundworkers-0.6.0 → groundworkers-0.7.0}/PKG-INFO

@@ -1,16 +1,16 @@
 Metadata-Version: 2.5
 Name: groundworkers
-Version: 0.6.0
+Version: 0.7.0
 Summary: Groundworkers MCP server — read-only agentive access to OMOP vocabularies, concept graphs, and embeddings.
 Requires-Python: >=3.12
 Requires-Dist: fastapi<1.0,>=0.110
 Requires-Dist: mcp[cli]<2,>=1
 Requires-Dist: numpy<3,>=1.26
-Requires-Dist: oa-configurator<2,>=1.3.0
-Requires-Dist: omop-alchemy<2,>=1.1
-Requires-Dist: omop-emb<3,>=2.1
-Requires-Dist: omop-graph<3,>=2.1
-Requires-Dist: omop-llm<2,>=1
+Requires-Dist: oa-configurator<3,>=2.0.0
+Requires-Dist: omop-alchemy<3,>=2.0.0
+Requires-Dist: omop-emb<4,>=3.0.0
+Requires-Dist: omop-graph<4,>=3.0.0
+Requires-Dist: omop-llm<2,>=1.0.2
 Requires-Dist: omop-semantics<1,>=0.6
 Requires-Dist: psutil<8,>=5.9
 Requires-Dist: psycopg[binary]<4,>=3.1
@@ -43,13 +43,13 @@ Requires-Dist: python-docx>=1.0; extra == 'docx'
 Provides-Extra: embedding-artifacts
 Requires-Dist: h5py<4,>=3.10; extra == 'embedding-artifacts'
 Provides-Extra: embedding-faiss
-Requires-Dist: omop-emb[faiss-cpu]<3,>=2.1; extra == 'embedding-faiss'
+Requires-Dist: omop-emb[faiss-cpu]<4,>=3.0.0; extra == 'embedding-faiss'
 Provides-Extra: embedding-pgvector
-Requires-Dist: omop-emb[pgvector]<3,>=2.1; extra == 'embedding-pgvector'
+Requires-Dist: omop-emb[pgvector]<4,>=3.0.0; extra == 'embedding-pgvector'
 Provides-Extra: pdf
 Requires-Dist: pdfplumber>=0.10; extra == 'pdf'
 Provides-Extra: tui
-Requires-Dist: groundskeeping<1,>=0.8.1; extra == 'tui'
+Requires-Dist: groundskeeping<1,>=0.9.1; extra == 'tui'
 Requires-Dist: rich<15,>=13; extra == 'tui'
 Requires-Dist: textual>=0.60; extra == 'tui'
 Provides-Extra: xlsx
@@ -77,6 +77,7 @@ Start with the [documentation home](docs/index.md), or choose a path directly:
 - [Initial local setup](docs/from-scratch.md) walks through a fresh CDM-backed deployment.
 - [Integrations](docs/usage/integrations.md) shows MCP, REST, and Python calls.
 - [Configuration](docs/usage/configuration.md) explains shared-stack references and optional capabilities.
+- [Upgrading from 0.6](docs/usage/upgrading-from-0.6.md) lists the 0.7 configuration and runtime changes.
 - [Tools overview](docs/tools/overview.md) maps jobs to the discoverable MCP surface.
 
 ## Quick start

{groundworkers-0.6.0 → groundworkers-0.7.0}/README.md

@@ -19,6 +19,7 @@ Start with the [documentation home](docs/index.md), or choose a path directly:
 - [Initial local setup](docs/from-scratch.md) walks through a fresh CDM-backed deployment.
 - [Integrations](docs/usage/integrations.md) shows MCP, REST, and Python calls.
 - [Configuration](docs/usage/configuration.md) explains shared-stack references and optional capabilities.
+- [Upgrading from 0.6](docs/usage/upgrading-from-0.6.md) lists the 0.7 configuration and runtime changes.
 - [Tools overview](docs/tools/overview.md) maps jobs to the discoverable MCP surface.
 
 ## Quick start

{groundworkers-0.6.0 → groundworkers-0.7.0}/config/groundworkers.example.toml

@@ -1,4 +1,4 @@
-# groundworkers example config — oa-configurator 1.x StackConfig format
+# groundworkers example config — oa-configurator 2.0 StackConfig format
 #
 # Copy to a path selected by the setup console and fill in your values.
 # Full reference: https://oa-configurator.readthedocs.io (or run omop-config --help)
@@ -33,19 +33,19 @@ database_name = "cava"
 # Databases — logical roles over those connections
 # ---------------------------------------------------------------------------
 
-# kind = "cdm" bundles the CDM, vocabulary, and results roles. vocab_connection
-# and vocab_schema fall back to the primary connection and schema when unset.
+# kind = "cdm" bundles the CDM, vocabulary, and results roles. The role schema
+# fields fall back to the primary schema when unset. Omit these fields for SQLite.
 [databases.cdm_db]
 kind         = "cdm"
 connection   = "cdm_main"
-schema_name  = "public"
+cdm_schema   = "public"
 vocab_schema = "public"
 
-# The embedding store's database. kind = "generic": no CDM role-splitting.
+# The embedding store's database. Keep its schema distinct from the CDM schema.
 [databases.emb_db]
 kind        = "generic"
 connection  = "cdm_main"
-schema_name = "public"
+schema_name = "groundworkers"
 
 # ---------------------------------------------------------------------------
 # Providers and models — endpoints, then the named models served through them

groundworkers-0.7.0/docs/adapters/cdm.md

@@ -0,0 +1,51 @@
+# CDM Adapter
+
+`CDMAdapter` holds the primary engine, vocabulary engine, and routed session factory for a resolved CDM database. It is the shared connection layer used by `VocabService` and `OmopGraphAdapter`.
+
+## What it is
+
+`CDMAdapter` is a thin connection-management object. It does not issue queries itself. Its purpose is to:
+
+- hold the primary and vocabulary `sqlalchemy.Engine` objects
+- expose a routed session factory for callers that query role-tagged OMOP tables
+- be constructed once per CDM database in `build_application()` and shared across the components that need it
+
+## Who uses it
+
+| Component | How |
+|---|---|
+| `VocabService` | Takes a `CDMAdapter` as its only constructor argument. Uses the session factory to open per-call sessions for vocabulary table queries. |
+| `OmopGraphAdapter` | Uses the routed session factory so vocabulary and primary-role graph tables reach their configured databases. |
+
+The adapter is created once per CDM database at application startup and wired through `build_application()`. It is not per-request.
+
+## Construction
+
+`CDMAdapter` is config-agnostic. It accepts an engine and optional routed factory, while `build_application()` creates them through `omop_alchemy.config.create_cdm_engines()` and `omop_alchemy.cross_database.cdm_sessionmaker()`:
+
+- the adapter remains testable by passing a SQLite engine directly
+- changing the connection source means changing `build_application()` only;`CDMAdapter` and every service that uses it are untouched
+
+## Usage from `build_application()`
+
+```python
+from groundworkers.app import build_application
+from groundworkers.bootstrap import build_app_config
+
+config = build_app_config()
+app = build_application(config)
+
+# CDMAdapter is available at:
+app.adapters.cdm
+```
+
+`VocabService` is wired automatically:
+```python
+app.services.vocab  # backed by app.adapters.cdm
+```
+
+## Lifecycle
+
+`build_app_config()` creates role engines through `create_cdm_engines(..., register_claims=False)`. Startup fails fast when either database role is unreachable and prints the scrubbed reason with a database recovery hint. `CDMAdapter.is_available()` also performs a lightweight Core query (`SELECT 1`).
+
+`close()` disposes both role engines. Call it explicitly in teardown (for example in a test fixture `yield`/`finally` block) when you need to ensure connections are returned promptly. Process-level startup and shutdown wiring belongs in the application or transport layer, not in the adapter itself.

{groundworkers-0.6.0 → groundworkers-0.7.0}/docs/adapters/omop_emb.md

@@ -10,15 +10,15 @@ The adapter is responsible for:
 - optional on-the-fly query encoding through an embedding client
 - exposing backend availability and registered model metadata
 
-The adapter does **not** resolve stack config itself. `build_application(...)` constructs it from the already-resolved `omop-emb` package config and any required engines.
+The adapter does **not** resolve stack config itself. `build_application(...)` constructs it from Groundworkers' `[tools.groundworkers]` `embedding_model_name` and `vector_store_name` references.
 
 ## Backends
 
 `groundworkers` supports the same primary storage backends it wires from `omop-emb`:
 
-| Backend | omop-emb config |
+| Backend | Groundworkers stack config |
 |---|---|
-| `sqlitevec` | `backend = "sqlitevec"` plus `sqlite_path` |
+| `sqlitevec` | a `[vector_stores.*]` entry with `backend_type = "sqlitevec"` and a database reference |
 | `pgvector` | a `[vector_stores.*]` entry with `backend_type = "pgvector"` and a `database` reference |
 
 FAISS remains a sidecar acceleration layer rather than a standalone primary backend.
@@ -34,7 +34,7 @@ No live model API is required.
 
 ### Text search mode
 
-Requires an embedding client configured through `omop-emb` package settings.
+Requires `embedding_model_name` and `vector_store_name`, plus a configured embedding provider/model.
 
 - `embedding_search` encodes a text query on the fly
 - `embedding_search_batch` encodes and searches multiple text queries with one provider/index batch, returning rows aligned to input order

{groundworkers-0.6.0 → groundworkers-0.7.0}/docs/development/integration.md

@@ -18,7 +18,8 @@ app = build_application(config)
 |---|---|
 | `groundworkers` | `GroundworkersConfig` |
 | `cdm_database` | `ResolvedCDMDatabase` |
-| `cdm_engine`, `vocabulary_engine` | `sqlalchemy.Engine` |
+| `cdm_engine`, `cdm_vocab_engine` | `sqlalchemy.Engine` |
+| `cdm_session_factory` | Routed SQLAlchemy session factory for primary, vocabulary, and results roles |
 | `embedding_model` | `ResolvedModel \| None` |
 | `vector_store` | `ResolvedVectorStore \| None` |
 
@@ -42,6 +43,8 @@ services.source_planning
 
 A CDM-only configuration is fully supported. Graph availability follows the resolved CDM database — there is no separate section to enable.
 
+The engines are created by `omop_alchemy.config.create_cdm_engines(..., register_claims=False)`, and `cdm_session_factory` comes from `omop_alchemy.cross_database.cdm_sessionmaker`. Use the session factory for queries that may touch more than one OMOP role. On PostgreSQL, engine creation checks role schema claims eagerly, so the configured databases must be reachable while `build_app_config()` runs.
+
 ## Grounding free text
 
 ```python
@@ -127,6 +130,6 @@ operation = (
 controller = ConfigWizardController(cdm_setup_workflow(operation), service)
 ```
 
-The same shape covers `MODEL_SETUP_TARGET` / `model_setup_workflow` and `LLM_SETUP_TARGET` / `llm_setup_workflow`. The provider decides create-versus-update from the current file, owns revision checking and redaction, and returns `conflicted` rather than clobbering another writer. `model_discoverer` is the injected seam for live model inventory; supply your own to avoid network calls in tests.
+The same shape covers `MODEL_SETUP_TARGET` / `model_setup_workflow`, `LLM_SETUP_TARGET` / `llm_setup_workflow`, and `VECTOR_STORE_SETUP_TARGET` / `vector_store_setup_workflow`. The provider decides create-versus-update from the current file, owns revision checking and redaction, and returns `conflicted` rather than clobbering another writer. `model_discoverer` is the injected seam for live model inventory; supply your own to avoid network calls in tests.
 
 This requires the `tui` extra for Groundskeeping, but not Textual — the provider and controller are host-agnostic.

{groundworkers-0.6.0 → groundworkers-0.7.0}/docs/development/plugins.md

@@ -59,7 +59,7 @@ For example, a plugin recommending comparator cohorts might reason like this.
 
 | Use case | What you need | How you get it |
 |---|---|---|
-| Look up existing OMOP concepts | Read access to the CDM vocabulary connection Groundworkers already opened | `context.cdm_engine` / `context.resolver` |
+| Look up existing OMOP concepts | Read access through Groundworkers' routed vocabulary session | `context.cdm_session_factory` / `context.resolver` |
 | Rank or filter by similarity to concepts Groundworkers already embedded | The concept embeddings Groundworkers already populated, via omop-emb | `context.vector_store` + `context.embedding_backend_factory` |
 | Ask an LLM to help decide something | The chat model Groundworkers already configured, via omop-llm | `context.chat_backend_factory` |
 
@@ -76,12 +76,14 @@ The concept-embedding row and the free-text-embedding row look similar but are n
 
 ### Assumptions this table is making
 
-- **Vocabulary only, so far.** Every example above reads OMOP *vocabulary* i.e. operations over concepts, concept relationships, concept embeddings, or the host's shared grounding cascade. Nothing about `context.cdm_engine` restricts a plugin to vocabulary tables specifically, however. These tables are available over the same CDM connection groundworkers itself uses, and a plugin *could* query clinical/person-level tables (`condition_occurrence`, `drug_exposure`, etc.) through it just as easily, subject to whatever environmental and procedural access controls actually govern that data.
+- **Vocabulary only, so far.** Every example above reads OMOP vocabulary: concepts, concept relationships, concept embeddings, or the host's shared grounding cascade. `context.cdm_session_factory` routes vocabulary and primary roles, including on split-vocabulary deployments. Clinical/person-level queries need a database role explicitly configured for them.
 - **Shared mapping access.** `PluginContext.mapping_context` is an optional,read-only capability façade over the host's mapping and grounding policy. Use its operations when a plugin needs candidate bundles, text grounding, or concept context. `concept_shared_standard_ancestor(concept_ids, max_depth=5)` returns the unique nearest shared standard ancestor when one exists; raise `max_depth` to widen the hierarchy search. The underlying vocabulary, graph, and service objects are deliberately not exposed. Do not construct a second `omop-graph` or vocabulary adapter from `context.cdm_engine`. The field is `None` only when the host did not compose services for the plugin context.
 
 ## Build and register a new plugin
 
-`build()` receives `PluginContext`. The context provides the resolved CDM database and engine, vector store, shared lazy model backend factories, the optional read-only `mapping_context`, and a deliberately narrow resolver for independent named OA resources. Return `None` when a prerequisite is unavailable. Groundworkers then keeps serving its core capabilities and reports why the plugin was not activated.
+`build()` receives `PluginContext`. The context provides the resolved CDM database and primary engine, routed `cdm_session_factory`, vocabulary engine, vector store, shared lazy model backend factories, the optional read-only `mapping_context`, and a deliberately narrow resolver for independent named OA resources. Return `None` when a prerequisite is unavailable. Groundworkers then keeps serving its core capabilities and reports why the plugin was not activated.
+
+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.
 
 `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:
 
@@ -158,7 +160,8 @@ Schemas requiring live discovery or a conditional flow (and therefore not fittin
 ```python
 from typing import Annotated, ClassVar
 
-from oa_configurator import PackageConfigBase, Sensitive
+from oa_configurator import PackageConfigBase
+from oa_configurator.refs import Sensitive, Secret
 from pydantic import Field
 
 
@@ -167,10 +170,23 @@ class ExampleConfig(PackageConfigBase):
     api_token: Annotated[str | None, Sensitive()] = Field(default=None)
 ```
 
-The `oa_configurator.Secret` alias is equivalent to `Annotated[str | None, Sensitive()]`. Prefer a `RefTo` field when a plugin can reuse an existing database, model, provider, or vector-store entry. The plugin then stores only the logical reference name; sensitivity remains declared on the referenced schema, such as `ConnectionConfig.password` or `ProviderConfig.api_key`, and the generic recursive configuration workflow preserves those declarations.
+The `Secret` alias is equivalent to `Annotated[str | None, Sensitive()]`. Prefer a `RefTo` field when a plugin can reuse an existing database, model, provider, or vector-store entry. The plugin then stores only the logical reference name; sensitivity remains declared on the referenced schema, such as `ConnectionConfig.password` or `ProviderConfig.api_key`, and the generic recursive configuration workflow preserves those declarations.
 
 This protects display and logging surfaces; it does not encrypt persisted configuration. Plugin documentation must describe the storage expectations for any secret it introduces.
 
+## Upgrading plugins to Groundworkers 0.7
+
+1. Require `oa-configurator>=2,<3` and `groundworkers>=0.7,<0.8` in the plugin package.
+2. Import `Sensitive` and `Secret` from `oa_configurator.refs`, and load files with `load_stack_config(path)`.
+3. Create CDM role engines with `omop_alchemy.config.create_cdm_engines(resolved, register_claims=False)` for read-only plugin access; use `context.cdm_session_factory` when Groundworkers provides the database.
+4. Remove schema fields from SQLite database entries. For PostgreSQL CDM entries, use `cdm_schema`; vector-store database entries continue to use `schema_name`.
+5. Keep accepting `context.cdm_engine` for integrations that need the primary SQLAlchemy engine. The routed factory handles vocabulary, primary, and results roles for ORM queries.
+6. Treat `context.embedding_backend_factory()` as a read-only omop-emb 3.0 `EmbeddingStoreReader`. It is shared with Groundworkers tools and status; reader methods no longer accept `metric_type`, and model enumeration is `get_registered_models()`. Do not use it to register models, create tables, or write vectors. Use a plugin-owned store and explicit setup operation for plugin data.
+7. Pass `context.cdm_session_factory` when constructing `OmopGraphAdapter`; Engine mode only works for colocated databases. `context.cdm_engine` is the primary-role engine and cannot query vocabulary on a split deployment.
+8. Use the current public error codes: `LEGACY_REGISTRY`, `MISPLACED_REGISTRY`, `MISSING_STORAGE_TABLE`, `MODEL_REGISTRATION_CONFLICT`, and `READ_ONLY_STORE`.
+9. Update `describe()` consumers for the `llm_model`, `stack`, `groundworkers`, and `app_name` keys and `cdm_schema` / `vocab_schema` names. The old `base.sql` schema/engine helpers have been removed; use oa-configurator's `physical_schema_of`, `qualified`, `supports_schemas`, and `schema_for_role` APIs.
+10. Update direct `AppConfig` construction for the required `stack`, `groundworkers`, `cdm_database`, `cdm_engine`, `cdm_vocab_engine`, `cdm_session_factory`, `embedding_model`, `llm_model`, `vector_store`, and `knowledge_root` fields; prefer `build_app_config()` in plugins and tests.
+
 ## Setup steps
 
 Plugin data preparation belongs in registered setup steps. A plugin may expose a `setup_steps` tuple of `PluginSetupStep` instances. Each step declares a stable key, operator copy, typed arguments, and a `build_plan(values, config_path)` callable that returns a `MaintenancePlan`.

{groundworkers-0.6.0 → groundworkers-0.7.0}/docs/index.md

@@ -69,6 +69,7 @@ The output includes the active tools, prompts, resources, plugins, redacted conf
 - [Initial local setup](from-scratch.md) for a fresh local deployment
 - [Integrations](usage/integrations.md) for MCP, REST, and direct Python usage
 - [Configuration](usage/configuration.md) for the shared-stack config model and runtime combinations
+- [Upgrading from 0.6](usage/upgrading-from-0.6.md) for the 0.7 configuration and plugin changes
 - [Tools overview](tools/overview.md) for the discoverable MCP surface
 
 ## Relationship to groundcrew

{groundworkers-0.6.0 → groundworkers-0.7.0}/docs/tools/embedding.md

@@ -1,6 +1,6 @@
 # Embedding Tools
 
-Five tools expose the embedding index. All require `omop_emb` to be enabled in the config.
+Five tools expose the embedding index. They require `embedding_model_name` and `vector_store_name` in `[tools.groundworkers]`.
 
 ## `embedding_index_status`
 
@@ -23,12 +23,16 @@ Returns the status of the embedding backend and all registered models. Takes no
 }
 ```
 
-When the backend is unavailable or no models are registered, `"available"` is `false` and `"models"` is an empty array. This tool never returns an error dict — it degrades gracefully.
+When the backend is unavailable or no models are registered, `"available"` is `false` and `"models"` is an empty array. This tool never returns an error dict — it degrades gracefully. A legacy registry, misplaced registry, or missing model table is reported in `detail` with a specific explanation.
+
+Groundworkers opens the store through omop-emb's read-only reader for status and query tools. A pre-3.0 store reports `LEGACY_REGISTRY`. The migration script is tracked in oa-configurator issue #40; once it ships, Groundworkers will show omop-emb's migration command. Groundworkers does not migrate the store.
 
 ## `embedding_neighbours`
 
 Returns the nearest embedding-space neighbours for one OMOP concept by looking up its existing vector in the index.
 
+By default `standard_only` and `active_only` are both `true`, matching the partial HNSW index predicate. Set either to `false` to widen the result set.
+
 ```json
 {"concept_id": 4119419, "limit": 10, "model_name": "qwen3-embedding:0.6b"}
 ```
@@ -66,9 +70,10 @@ Encodes a text query on the fly and returns the nearest concepts by vector simil
 
 All parameters except `query` are optional.
 
-!!! warning "Requires `api_base` configuration"
+!!! warning "Requires a configured embedding model"
     `embedding_search` must encode the query string using a live embedding model.
-    This requires `omop_emb.api_base` (and `api_key`) to be configured.  Without it
+    Configure `embedding_model_name` in `[tools.groundworkers]` and give its
+    `[models.*]` entry a provider in `[providers.*]`. Without a live model client,
     the tool returns `BACKEND_UNAVAIL`.
 
 ## `embedding_search_batch`
@@ -110,4 +115,4 @@ Encodes a text string into one query embedding vector.
 }
 ```
 
-Like `embedding_search`, this requires `omop_emb.api_base` and `omop_emb.api_key` to be configured.
+Like `embedding_search`, this requires a configured `embedding_model_name` and a live provider client.

{groundworkers-0.6.0 → groundworkers-0.7.0}/docs/usage/configuration.md

@@ -64,7 +64,7 @@ database_name = "omop"
 [databases.cdm_db]
 kind = "cdm"
 connection = "cdm_main"
-schema_name = "public"
+cdm_schema = "public"
 vocab_schema = "public"
 
 [providers.local_ollama]
@@ -86,6 +86,11 @@ structured_output = true
 backend_type = "pgvector"
 database = "vector_db"
 
+[databases.vector_db]
+kind = "generic"
+connection = "cdm_main"
+schema_name = "groundworkers"
+
 [tools.groundworkers]
 cdm_db = "cdm_db"
 embedding_model_name = "embedding_model"
@@ -169,7 +174,7 @@ REST is selected explicitly with `--transport rest`; it is not started alongside
 | `rest_port` | `int` | `8080` |
 | `rest_base_path` | `str` | `/v1` |
 
-`base_path` is validated to begin with `/`.
+`rest_base_path` is validated to begin with `/`.
 
 ### `llm_model_name` and chat
 
@@ -201,9 +206,9 @@ Groundworkers-owned grounding policy. omop-graph's traversal limits are per-call
 | `grounding_min_fulltext_overlap` | `float` | `0.0` |
 | `grounding_max_depth` | `int` (1-10) | `5` |
 
-`min_fulltext_overlap` must be between `0.0` and `1.0`. It is the minimum proportion of query tokens that must appear in a matched concept name for a full-text hit to be accepted; below the threshold grounding falls through to the next tier.
+`grounding_min_fulltext_overlap` must be between `0.0` and `1.0`. It is the minimum proportion of query tokens that must appear in a matched concept name for a full-text hit to be accepted; below the threshold grounding falls through to the next tier.
 
-`max_depth` bounds the hierarchy distance between a grounding candidate and a required parent concept, or the identity-hop count when grounding runs without `parent_ids`.
+`grounding_max_depth` bounds the hierarchy distance between a grounding candidate and a required parent concept, or the identity-hop count when grounding runs without `parent_ids`.
 
 ### Concept flag contract
 
@@ -289,6 +294,10 @@ Both references are required. With only one configured, status reports an action
 
 The store must be populated before the embedding tier can return anything. Population is explicit (see the Embeddings setup section) and never starts at query time. The server holds the graph read-only (`write=False`), so Groundworkers encodes query text for the embedding tier but never writes vectors.
 
+Groundworkers opens vector stores with omop-emb's read-only reader for MCP tools, status, coverage, and setup diagnostics. Explicit store initialization uses omop-emb's writer. A database supports one vector store per model: reuse the existing store or choose another database when registering a model that is already present. On PostgreSQL, the wizard stores vectors in the dedicated `groundworkers` schema. omop-emb also creates `omop_emb_registry`, and oa-configurator may create `oa_configurator_provenance`. SQLite uses its database file without a schema.
+
+If the store predates omop-emb 3.0, Groundworkers reports `LEGACY_REGISTRY`. The migration script is tracked in oa-configurator issue #40; once it ships, Groundworkers will show omop-emb's migration command. Groundworkers does not migrate legacy stores.
+
 ### With `groundworkers.llm_model_name` configured
 
 You additionally get:
@@ -342,4 +351,4 @@ mapping = app.services.mapping
 
 Service attributes are `None` only when their prerequisites are not available in the resolved runtime.
 
-`config.describe()` returns a redacted summary keyed by `database`, `model`, and `vector_store`. Passwords and API keys are masked; safe URLs never carry credentials.
+`config.describe()` returns a redacted summary keyed by `database`, `model`, `llm_model`, `vector_store`, `stack`, `groundworkers`, and `app_name`. CDM schema keys are `cdm_schema` and `vocab_schema`; generic/vector-store databases continue to use `schema_name`. Passwords and API keys are masked; safe URLs never carry credentials.

{groundworkers-0.6.0 → groundworkers-0.7.0}/docs/usage/setup_journey.md

@@ -5,11 +5,11 @@ The setup console is organized by the capability being configured:
 1. **Overview** — CDM readiness, optional capabilities, and integration output;
 2. **Database** — physical connections and logical CDM database entries;
 3. **Graph** — CDM-backed search and graph preparation;
-4. **Chat Model** — provider and model entries for LLM-backed features;
-5. **Embeddings** — vector-store setup, coverage, and population;
-6. **Performance** — graph, trigram, and embedding-index readiness;
+4. **Performance** — graph, trigram, and embedding-index readiness;
+5. **LLM provider** — provider and model entries for language features;
+6. **Embeddings** — vector-store setup, coverage, and population;
 7. **Chat** — checks for the selected chat model;
-8. **View Configuration** — redacted stack configuration; and
+8. **Configuration** — redacted stack configuration; and
 9. **Runs** — progress and history for durable maintenance work.
 
 For a minimal local setup, use **Overview → Configure CDM → Test connections**. Optional capabilities can be configured later. Configuration changes show the redacted entries that will be written before they are applied.

{groundworkers-0.6.0 → groundworkers-0.7.0}/docs/usage/testing.md

@@ -18,7 +18,7 @@ pytest tests/unit/test_concept_tools.py
 Integration tests that query the OMOP database require a `.env` file at the repo root (or an environment-variable equivalent):
 
 ```dotenv
-OMOP_CDM_DB_URL=postgresql://user:pass@localhost:5432/omop
+OA_CONFIG_PATH=/path/to/stack.toml
 ```
 
 Unit tests mock the adapter layer and run without a live database.
@@ -31,4 +31,4 @@ Unit tests mock the adapter layer and run without a live database.
 | Resolver tools | `concept_ground`: empty query rejection, result ordering by score, match_kind on exact hits |
 | Embedding tools | `embedding_index_status`, `embedding_neighbours`, `embedding_search`, `embedding_search_batch`, `embedding_encode`: correct responses, clamped limits, aligned batch rows, error propagation |
 | Server registry | `create_server` with and without each adapter; system tools always present; adapter-conditional tool registration |
-| Config validation | `OmopGraphConfig` schema name validation; `OmopEmbConfig` enabled-without-url guard; extra field rejection |
+| Config validation | oa-configurator stack validation, Groundworkers package fields, and extra field rejection |

groundworkers-0.7.0/docs/usage/upgrading-from-0.6.md

@@ -0,0 +1,31 @@
+# Upgrading from Groundworkers 0.6
+
+Groundworkers 0.7 uses the oa-configurator 2.0 stack and supports a vocabulary database separate from the primary CDM database.
+
+## Configuration changes
+
+- Rename the former database `schema_name` setting to `cdm_schema` for a CDM database. Use `vocab_schema` when vocabulary has a distinct schema. Generic databases, including vector-store databases, still use `schema_name`.
+- SQLite has no schemas. Remove schema settings from SQLite database entries; setup ignores those fields and tells you when they are unavailable.
+- A PostgreSQL vector store colocated with the CDM uses the dedicated `groundworkers` schema. Its database is a generic entry on the CDM connection:
+
+  ```toml
+  [databases.groundworkers_vectors]
+  kind = "generic"
+  connection = "cdm_main"
+  schema_name = "groundworkers"
+  ```
+
+- Add databases with the 2.0 CLI syntax, for example:
+
+  ```bash
+  omop-config databases add cdm clinical --connection cdm_main --cdm-schema public
+  omop-config databases add generic vectors --connection cdm_main --schema-name groundworkers
+  ```
+
+- Startup now fails fast if either the primary or vocabulary endpoint cannot be reached. The console prints the first scrubbed cause and a database recovery hint.
+- A pre-3.0 embedding store reports `LEGACY_REGISTRY`. The migration script is tracked in oa-configurator issue #40; once it ships, Groundworkers will provide the omop-emb migration command.
+- To split the vocabulary, set `vocab_connection` on the CDM database entry. Groundworkers 0.7 routes vocabulary reads to that connection, including setup diagnostics and graph searches.
+
+## Plugin changes
+
+See [Upgrading plugins to Groundworkers 0.7](../development/plugins.md#upgrading-plugins-to-groundworkers-07) for the full API checklist. Plugins should require `groundworkers>=0.7,<0.8`, pass `cdm_session_factory` for OMOP graph/vocabulary access, and treat `embedding_backend_factory()` as a read-only `EmbeddingStoreReader`.

{groundworkers-0.6.0 → groundworkers-0.7.0}/pyproject.toml

@@ -14,11 +14,11 @@ dependencies = [
   "psycopg[binary]>=3.1,<4",
   "python-dotenv>=1,<2",
   "psutil>=5.9,<8",
-  "oa-configurator>=1.3.0,<2",
-  "omop-alchemy>=1.1,<2",
-  "omop-graph>=2.1,<3",
-  "omop-emb>=2.1,<3",
-  "omop-llm>=1,<2",
+  "oa-configurator>=2.0.0,<3",
+  "omop-alchemy>=2.0.0,<3",
+  "omop-graph>=3.0.0,<4",
+  "omop-emb>=3.0.0,<4",
+  "omop-llm>=1.0.2,<2",
   "omop-semantics>=0.6,<1",
   "uvicorn[standard]>=0.29,<1.0",
 ]
@@ -31,7 +31,7 @@ pdf = [
   "pdfplumber>=0.10",
 ]
 tui = [
-  "groundskeeping>=0.8.1,<1",
+  "groundskeeping>=0.9.1,<1",
   "textual>=0.60",
   "rich>=13,<15",
 ]
@@ -48,10 +48,10 @@ all_source = [
   "python-docx>=1.0",
 ]
 embedding-pgvector = [
-  "omop-emb[pgvector]>=2.1,<3",
+  "omop-emb[pgvector]>=3.0.0,<4",
 ]
 embedding-faiss = [
-  "omop-emb[faiss-cpu]>=2.1,<3",
+  "omop-emb[faiss-cpu]>=3.0.0,<4",
 ]
 dev = [
   "httpx>=0.27,<1",

{groundworkers-0.6.0 → groundworkers-0.7.0}/src/groundworkers/adapters/cdm.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
-from sqlalchemy import text
+from collections.abc import Callable
+
+from sqlalchemy import literal, select
 from sqlalchemy.engine import Engine
-from sqlalchemy.orm import sessionmaker
+from sqlalchemy.orm import Session, sessionmaker
 
 
 class CDMAdapter:
@@ -16,15 +18,32 @@ class CDMAdapter:
     Use session() for services that need a scoped session context manager.
     """
 
-    def __init__(self, engine: Engine) -> None:
+    def __init__(
+        self,
+        engine: Engine,
+        *,
+        vocab_engine: Engine | None = None,
+        session_factory: Callable[[], Session] | None = None,
+    ) -> None:
         self._engine = engine
-        self._session_factory = sessionmaker(engine)
+        self._vocab_engine = vocab_engine or engine
+        self._session_factory = session_factory or sessionmaker(bind=engine)
 
     @property
     def engine(self) -> Engine:
         """The underlying SQLAlchemy engine."""
         return self._engine
 
+    @property
+    def vocab_engine(self) -> Engine:
+        """The engine routed to the OMOP vocabulary role."""
+        return self._vocab_engine
+
+    @property
+    def session_factory(self) -> Callable[[], Session]:
+        """The session factory routed across the primary and vocabulary roles."""
+        return self._session_factory
+
     def session(self):
         """Return a session context manager."""
         return self._session_factory()
@@ -33,7 +52,7 @@ class CDMAdapter:
         """Return True if the CDM database is reachable (SELECT 1 probe)."""
         try:
             with self._engine.connect() as conn:
-                conn.execute(text("SELECT 1"))
+                conn.execute(select(literal(1)))
             return True
         except Exception:
             return False
@@ -41,3 +60,5 @@ class CDMAdapter:
     def close(self) -> None:
         """Dispose the engine and release the connection pool."""
         self._engine.dispose()
+        if self._vocab_engine is not self._engine:
+            self._vocab_engine.dispose()