groundworkers 0.6.0__tar.gz → 0.7.1__tar.gz

groundworkers-0.7.1/.github/workflows/ci.yml

@@ -0,0 +1,92 @@
+name: CI
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+jobs:
+  label-gate:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/label-gate.yml@main
+  build-test:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/build-test.yml@main
+  build-test-postgres:
+    uses: AustralianCancerDataNetwork/cava-devops/.github/workflows/build-test-postgres.yml@main
+    with:
+      ty-src: src
+      postgres-image: pgvector/pgvector:pg18
+      postgres-db: test_db
+      postgres-user: postgres
+      postgres-password: postgres
+      setup-commands: |
+        mkdir -p "$RUNNER_TEMP/omop"
+        cp tests/support/postgres_ci_config.toml "$RUNNER_TEMP/omop/config.toml"
+        export OA_CONFIG_PATH="$RUNNER_TEMP/omop/config.toml"
+        export GROUNDWORKERS_CONFIG_PATH="$RUNNER_TEMP/omop/config.toml"
+        export GROUNDWORKERS_REQUIRE_INTEGRATION=1
+        export GROUNDWORKERS_TEST_DATABASE_URL="postgresql+psycopg://postgres:postgres@localhost:5432/test_db"
+        echo "OA_CONFIG_PATH=$RUNNER_TEMP/omop/config.toml" >> "$GITHUB_ENV"
+        echo "GROUNDWORKERS_CONFIG_PATH=$RUNNER_TEMP/omop/config.toml" >> "$GITHUB_ENV"
+        echo "GROUNDWORKERS_REQUIRE_INTEGRATION=1" >> "$GITHUB_ENV"
+        echo "GROUNDWORKERS_TEST_DATABASE_URL=postgresql+psycopg://postgres:postgres@localhost:5432/test_db" >> "$GITHUB_ENV"
+        uv run omop-config connections add pg_test \
+          --dialect postgresql+psycopg \
+          --host localhost \
+          --port 5432 \
+          --user postgres \
+          --password postgres \
+          --database-name test_db \
+          --test-only false
+        uv run omop-config databases add cdm test_cdm_db --connection pg_test --cdm-schema gw_primary --vocab-schema gw_vocab
+        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
+        uv run omop-config configure groundworkers \
+          --cdm-db test_cdm_db \
+          --vector-store-name test_embeddings
+        uv run python -m tests.support.seed_postgres_fixture
+  test-evidence:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v6
+      - name: Run hermetic suite with coverage and skip reasons
+        run: |
+          uv sync --frozen --all-extras --dev
+          export GROUNDWORKERS_REQUIRE_FORMAT_TESTS=1
+          echo "GROUNDWORKERS_REQUIRE_FORMAT_TESTS=1" >> "$GITHUB_ENV"
+          COVERAGE_FILE="$RUNNER_TEMP/groundworkers.coverage" uv run pytest -q -ra \
+            --cov=groundworkers --cov-branch \
+            --cov-report=xml:"$RUNNER_TEMP/coverage.xml" \
+            --junitxml="$RUNNER_TEMP/pytest.xml"
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: groundworkers-test-evidence
+          path: |
+            ${{ runner.temp }}/coverage.xml
+            ${{ runner.temp }}/pytest.xml
+          if-no-files-found: warn
+  wheel-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v6
+      - name: Build and smoke-test base and optional wheel installs
+        run: |
+          uv build --wheel
+          wheel="$(find dist -maxdepth 1 -name '*.whl' -print -quit)"
+          wheel="$(pwd)/$wheel"
+          uv venv "$RUNNER_TEMP/gw-wheel-base" --python 3.12
+          uv pip install --python "$RUNNER_TEMP/gw-wheel-base/bin/python" "$wheel"
+          mkdir -p "$RUNNER_TEMP/gw-wheel-run"
+          cd "$RUNNER_TEMP/gw-wheel-run"
+          "$RUNNER_TEMP/gw-wheel-base/bin/python" "$GITHUB_WORKSPACE/tests/support/wheel_smoke.py" base
+          uv venv "$RUNNER_TEMP/gw-wheel-extras" --python 3.12
+          uv pip install --python "$RUNNER_TEMP/gw-wheel-extras/bin/python" "$wheel[all_source,tui]" httpx
+          "$RUNNER_TEMP/gw-wheel-extras/bin/python" "$GITHUB_WORKSPACE/tests/support/wheel_smoke.py" extras

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

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

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

@@ -1,16 +1,16 @@
 Metadata-Version: 2.5
 Name: groundworkers
-Version: 0.6.0
+Version: 0.7.1
 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.1}/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.1}/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.1/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.1}/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.1}/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.1}/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.1}/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.1}/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.1}/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.1}/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.7.1/docs/usage/testing.md

@@ -0,0 +1,45 @@
+# Testing
+
+## Test lanes
+
+Groundworkers uses distinct lanes because an isolated unit run cannot prove the database, optional parser, plugin-entry-point, or built-wheel contracts.
+
+| Lane | What it proves | CI behavior |
+|---|---|---|
+| Unit and service | Deterministic policy, adapter boundaries, source planning, transport behavior, and controlled provider responses | Runs without a live database or model service |
+| Optional dependency | Real XLSX, DOCX, and PDF parsing plus missing-extra guidance | Required format tests must pass in the all-extras CI lane; missing-extra behavior is simulated |
+| PostgreSQL integration | Seeded graph retrieval, real pgvector storage and reader behavior, model selection, filters, and embedding-tier grounding | Required: every required_integration case must be collected and pass |
+| Wheel smoke | Base and optional-extra installations, package entry-point discovery, CLI startup, and successful MCP/REST planning operations | Builds once and runs outside the checkout |
+| Optional live provider | Real configured model-provider connectivity | Opt-in developer smoke only; never substitutes for seeded embedding tests |
+
+## Running tests
+
+~~~bash
+# Hermetic suite, including real optional-format parsers
+uv run pytest -q -ra
+
+# Unit tests only
+uv run pytest tests/unit/
+
+# Required PostgreSQL cases; provide a seeded test stack first
+GROUNDWORKERS_CONFIG_PATH=/path/to/stack.toml \
+GROUNDWORKERS_REQUIRE_INTEGRATION=1 \
+GROUNDWORKERS_TEST_DATABASE_URL=postgresql+psycopg://... \
+uv run pytest -m required_integration -q -ra
+
+# Coverage for local review
+COVERAGE_FILE=/tmp/groundworkers.coverage uv run pytest -q -ra \
+  --cov=groundworkers --cov-branch --cov-report=term-missing
+~~~
+
+The required integration gate derives its cases from the `required_integration` marker, so every marked case is checked for collection and a passing result. Missing configuration, unavailable adapters, and absent seeded rows fail in that lane. The all-extras CI job applies the same execution check to `required_format` cases, so a missing parser cannot silently turn the format contract into a skip. Without the corresponding `GROUNDWORKERS_REQUIRE_*` flag, PostgreSQL and optional-format fixtures remain opt-in and skip with a reason.
+
+## Configuration and optional provider smoke
+
+Set GROUNDWORKERS_CONFIG_PATH (or GROUNDWORKERS_CONFIG) to the explicit Groundworkers stack file for integration tests. OA_CONFIG_PATH selects the oa-configurator default stack, but does not by itself opt the graph integration tests into a required run. PostgreSQL CI sets both paths and seeds a compact fixture before pytest starts.
+
+The external-provider smoke tests are separate from seeded deterministic embedding tests. To run them locally, set GROUNDWORKERS_RUN_EMBEDDING_INTEGRATION=1, GROUNDWORKERS_CONFIG_PATH, and GROUNDWORKERS_TEST_CONCEPT_ID; they require a configured provider and a concept with stored vectors.
+
+## Coverage and skip evidence
+
+CI publishes coverage.xml and pytest.xml from the hermetic all-extras run. The JUnit report carries named skip reasons. PostgreSQL CI separately enforces the required test list, so optional local skips cannot satisfy that gate. Coverage percentages are review evidence, not a global pass threshold. Prioritize unexecuted behavior at database, provider, transport, and packaging boundaries.

groundworkers-0.7.1/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.1}/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",
@@ -112,5 +112,8 @@ include = ["src"]
 testpaths = ["tests"]
 markers = [
   "integration: requires a live backend or database",
+  "required_integration: deterministic integration contract required by CI",
+  "required_format: optional document-format contract required in all-extras CI",
+  "optional_integration: environment-dependent integration smoke test",
   "requires_client: requires an embedding API client",
 ]