Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(config): isolate account runtime resources (#5323)
runyunzhoud370ca6a7da0
diff --git a/docs/design/runtime-configuration-design.md b/docs/design/runtime-configuration-design.mdindex 1dd874649..2be477c25 100644--- a/docs/design/runtime-configuration-design.md+++ b/docs/design/runtime-configuration-design.md@@ -5,24 +5,46 @@OpenViking has two configuration planes:- `ov.conf` is the startup configuration. It defines the process baseline and the runtime-config source selection. It is read during startup and is never rewritten by the runtime configuration API.-- Runtime overrides are sparse values persisted by a `ConfigSource`. They can be published without rebuilding the process and are resolved independently at Cluster and Account scopes.+- Runtime settings are persisted independently for Cluster and each Account by a `ConfigSource`. They can be published without rebuilding the process.The runtime configuration layer is narrower than the complete `OpenVikingConfig` model. A field must be declared with `RuntimeField` to be exposed through the generic configuration API. Plain Pydantic fields remain startup-only.The design goals are:-1. Keep the startup baseline immutable while rebuilding published Cluster configuration from sparse overrides.-2. Keep Account overrides sparse and resolve fallback at read time instead of materializing inherited values.+1. Keep the startup baseline immutable while rebuilding published Cluster configuration from its runtime settings.+2. Keep Account configuration independent from Cluster configuration.3. Use one PATCH and validation contract for Cluster and Account scopes.4. Separate persistence, publication, cache invalidation, and consumer notification.5. Allow storage providers to be replaced without coupling the manager to AGFS or a concrete database.+6. Keep business defaults and Account/Cluster composition outside the generic configuration manager.## 2. Configuration model-`OpenVikingConfig` is the Cluster model. `AccountConfig` is a sparse Account model; every Account field defaults to `None`, which means that the account has no explicit override. `RuntimeField` records two independent properties:+`OpenVikingConfig` is the Cluster model. `AccountConfig` is the Account model.+An optional Account field set to `None` means only that the Account has not+configured that value. The consuming business decides what absence means.+`RuntimeField` records lifecycle metadata:- `dynamic`: whether the field can be modified after creation;-- `fallback`: an optional Cluster field path used when an Account field is unset.+- `fallback`: a deprecated compatibility-only Cluster field path.++Legacy `fallback` applies only to a completely unset top-level Account section+and returns the complete Cluster section. It does not recursively merge fields.+New configuration must not use it; business resolvers should explicitly combine+the independently published Account and Cluster models when that is the desired+behavior.++Runtime fallback in the current VLM and vector resolvers also keeps existing+Account documents usable when those documents predate complete Account settings.+This is a migration compatibility path, not the target lifecycle for new+configuration. New Account provisioning and new Account-scoped features should+use Cluster configuration only as a creation template: materialize a complete+Account-owned configuration during create, persist it with create-if-absent+semantics, and thereafter change it only through that Account's API. Later+Cluster changes then define defaults for future Accounts and do not implicitly+change existing Accounts. Until existing Account documents are migrated or+materialized, their missing sections continue to use the current resolver+fallback behavior.Cluster-versus-Account scope comes from the model declaring the field, not from `RuntimeField` itself. A plain `Field` is outside the runtime API surface.@@ -31,17 +53,39 @@ Current runtime field declarations:| Scope | Field | Lifecycle | Fallback / consumer status || --- | --- | --- | --- || Cluster | `agent_evolution` | Dynamic | Cluster default; consumed by session and Agent Evolution paths |-| Account | `agent_evolution` | Dynamic | Declares whole-section fallback to Cluster `agent_evolution`; consumed through the manager |+| Account | `agent_evolution` | Dynamic | Uses deprecated whole-section fallback to Cluster `agent_evolution` for compatibility || Account | `feishu` | Dynamic | No declarative fallback; an unset section uses Cluster `feishu`, while a set section uses Account values/defaults for every field except the Cluster-owned `domain`. Used by Feishu imports, preflight, and watch token refresh || Account | `github`, `acl` | Dynamic | No Cluster fallback; GitHub and ACL consumers read the Account value through the manager |--Account `vlm`, `memory`, `embedding`, and `vectordb` are not declared on the current Account runtime model and are rejected by both creation-time settings validation and later PATCH requests. `query_planner`, Cluster `embedding`, Cluster `vlm`, Cluster `memory`, Cluster `feishu`, and the other plain Cluster configuration sections are not writable through the runtime configuration API.+| Account | `vlm`, `query_planner` | Dynamic | ROOT-only; the VLM resolver combines Account-owned model identity and credentials with selected Cluster runtime behavior |+| Account | `embedding` | Mixed | ROOT-only; credentials and runtime policy are dynamic, while model identity, vector-space fields, text source and input token limit are create-only |+| Account | `vectordb` | Create-only | ROOT-only; an explicit Account section owns the remote connection and authentication; an absent section selects the Cluster backend |++Account `memory` is not declared on the current Account runtime model and is rejected by both creation-time settings validation and later PATCH requests. ADMIN responses omit `vlm`, `query_planner`, `embedding`, and `vectordb`; only ROOT can read or write these sections. Cluster `embedding`, `vlm`, `query_planner`, `memory`, `feishu`, and the other plain Cluster configuration sections are not writable through the runtime configuration API.++An Account VLM or Query Planner section requires `model` and a non-empty+`credentials` array. Model-service identity, endpoints and credentials come from+that Account section. Selected runtime behavior comes from Cluster; Account+`timeout`, when set, overrides Cluster `timeout`, and an unset or reset value+uses Cluster `timeout`. Query Planner selection is Account `query_planner`,+Account `vlm`, Cluster `query_planner`, then Cluster `vlm`.++The vector resolver resolves and validates Embedding and VectorDB together.+Account embedding may contain only runtime policy or an explicit empty object;+without an Account model mode, it uses Cluster model bindings. Declared Account+model modes replace the Cluster mode set, and their credential arrays provide+complete provider bindings without borrowing Cluster connection or authentication+fields. An explicit Account VectorDB section similarly owns its complete+connection and authentication, even when it uses the same backend type as Cluster.+Account backends support `http`, `volcengine`, and `vikingdb`; their remote+collections, indexes and authorization must already be provisioned externally.+See the [Admin API](../en/api/08-admin.md#runtime-configuration) for the field+surface and compatibility requirements.## 3. RuntimeConfigManager`RuntimeConfigManager` owns storage-independent behavior:-- sparse three-state PATCH merging;+- three-state PATCH merging within one scope;- scope-local read/merge/write serialization;- model construction and validation through caller-provided hooks;- copy-on-write publication;@@ -51,7 +95,12 @@ Account `vlm`, `memory`, `embedding`, and `vectordb` are not declared on the curThe manager does not import concrete Cluster or Account models. The service supplies hooks for reading and replacing the Cluster singleton, building a validated Cluster model, and building an `AccountConfig` model.-Cluster overrides are always applied to the immutable startup baseline. They are not merged into the previously published effective object, which prevents removed overrides from remaining accidentally materialized. Account overrides remain sparse; fallback is resolved only when an Account field is read.+Cluster runtime settings are always applied to the immutable startup baseline.+They are not merged into the previously published Cluster object, which prevents+removed values from remaining accidentally materialized. Account settings are+constructed and published independently. The manager retains whole-section+fallback only for existing compatibility fields; domain-specific defaults are+resolved by business code.## 4. PATCH and validation@@ -67,7 +116,7 @@ Both scopes use the same request shape:}```-The stored override has three states:+The PATCH has three states:- an absent field keeps its current value;- a concrete value sets or replaces the value;@@ -75,20 +124,26 @@ The stored override has three states:Objects merge recursively and arrays replace as a whole. A nested `null` removes only that leaf. It does not create a missing parent or remove an existing parent that becomes empty. Removing a parent requires an explicit parent-level `null`; `{}` remains an explicit empty object.-Validation has two stages:+Validation has three stages:1. Structural validation checks that every path is on the target model's `RuntimeField` surface, rejects unknown paths, and rejects `dynamic=False` paths on a non-creating PATCH.2. The merged result is constructed into the target Pydantic model for type validation and cross-field constraints.+3. Registered Account candidate validators check the business-effective configuration before persistence. Vector validation checks the complete Embedding/VectorDB pair on creation, loading, refresh and PATCH; an embedding update also checks that an existing Account's mode and dimension remain unchanged.-A `dynamic=False` field can be supplied while an Account is created, but any later PATCH touching that field is rejected. The current Account model does not declare any create-only fields.+A `dynamic=False` field can be supplied in Account creation `settings`, but later additions, changes and resets are rejected, including ROOT requests. This applies to the whole `vectordb` section and to embedding model identity, dimension, input, query/document parameters, version, `text_source` and `max_input_tokens`. Removing a parent object cannot bypass the restrictions on its stored create-only fields.-The API returns the explicit override at the addressed scope. It does not return inherited or effective values. Declarative fallback is a whole-section operation, currently used by Account `agent_evolution`. Feishu intentionally uses a domain-specific resolver instead: an absent Account Feishu section returns the complete Cluster section; once the Account section exists, only `domain` is copied from Cluster and omitted or reset Account leaves use `FeishuConfig` defaults.+The API returns settings from the addressed scope, not a business-effective+Account/Cluster composition. Declarative fallback is deprecated compatibility+behavior, applies only to a whole section, and is currently used by Account+`agent_evolution`. Feishu demonstrates the preferred design: its business+resolver receives Account and Cluster configuration and applies Feishu-specific+defaulting without extending the generic manager.## 5. Publication and consumersA successful update follows this order:-1. Read the current sparse override.+1. Read the current settings for the addressed scope.2. Apply and validate the patch.3. Persist the new override.4. Publish the new Cluster object or Account cache entry.@@ -99,7 +154,20 @@ Consumer exceptions are logged and swallowed. They do not roll back persistenceCluster publication uses atomic pointer replacement. The new object is built and validated before the singleton is swapped, so concurrent readers see either the old or new object. Account consumers are notified of eviction independently of section filters so they can drop account-local derived state.-All currently declared Account sections have business consumers: GitHub, ACL, and Agent Evolution read through the manager, while Feishu is resolved for resource imports, source preflight, and watch token refresh. VLM, memory, embedding, and vector database account overrides remain follow-up work and are not accepted by the current API.+All currently declared Account sections have business consumers. GitHub, ACL,+and Agent Evolution read through the manager; Feishu is resolved for resource+imports, source preflight, and watch token refresh. Account VLM and Query Planner+configuration is resolved for model work and retrieval planning. Account+Embedding and VectorDB configuration is used by queries, queue writes, reindexing,+OVPack and account-scoped observers. Configuration consumers invalidate derived+model and vector resources after relevant updates or Account eviction. Account+`memory` remains outside the runtime configuration API.++Embedding and vector backend resources track active operations so retirement+waits for in-flight work. Account VLM callers retain an account-bound proxy+rather than a model client. Each asynchronous model call borrows the current+client; configuration invalidation retires the old client and closes it after+that call completes. No task-wide configuration lease is used.## 6. Persistence@@ -127,14 +195,23 @@ This distinction prevents a transient storage failure from replacing a known-goo## 8. Compatibility and verification-The old Account `settings` endpoints and the Agent Evolution endpoint remain compatibility adapters. They translate writes into `RuntimeConfigManager` operations and do not maintain a second persistence path.+The old Account `settings` endpoints, the Agent Evolution endpoint, and+declarative whole-section fallback remain compatibility adapters. New Account+features should read complete Account-owned configuration directly. Cluster+defaults should be materialized by Account provisioning rather than introduced+as new runtime fallback dependencies. Existing resolver fallback remains until+pre-materialization Account documents have been migrated.Extended Account sections should not be written while old replicas share the same Account directory if those replicas reject unknown fields in `setting.json`.The focused mechanism tests are:```bash-pytest tests/config/test_runtime_config.py+.venv/bin/python -m pytest tests/config --no-cov```-They cover field discovery, three-state merging, runtime-surface validation, lazy Account loading, publication isolation, consumer notification, idle eviction, fallback, Feishu overlay behavior, and file-source backup behavior.+They cover field discovery, three-state merging, runtime-surface validation,+lazy Account loading, publication isolation, consumer notification, idle+eviction, legacy whole-section fallback, Feishu business resolution, and+file-source backup behavior, together with Account vector compatibility,+credential isolation, cache invalidation and embedding resource lifecycle.diff --git a/docs/en/api/08-admin.md b/docs/en/api/08-admin.mdindex 3e9ac4704..6415cacbf 100644--- a/docs/en/api/08-admin.md+++ b/docs/en/api/08-admin.md@@ -442,34 +442,373 @@ three-state: an absent key is unchanged, `null` deletes that layer's value, anda concrete value updates it.The Cluster runtime surface currently contains `agent_evolution`. The Account-surface contains `feishu`, `agent_evolution`, `github`, and `acl`, all of which-are dynamic. Account `vlm`, `memory`, `embedding`, and `vectordb` are not on the-current API surface and are rejected even during Account creation. Cluster+surface contains `feishu`, `agent_evolution`, `github`, `acl`, `vlm`, and+`query_planner`, all of which are dynamic. Account `vlm` and `query_planner`+are visible and writable only to ROOT. Each configured section is complete:+`model` and a non-empty `credentials` array are required, while `timeout` is+optional. ADMIN responses omit both sections, and ADMIN PATCH requests+containing either section are rejected. Account `memory` is not on the current API+surface. Account `embedding` and `vectordb` are also ROOT-only, including reads.+`vectordb` can only be supplied in Account creation `settings`; subsequent additions,+changes and resets are rejected, including ROOT requests. Cluster`embedding`, `vlm`, `query_planner`, `memory`, `feishu`, storage, parser, andretrieval fields are startup-only because they are not declared as runtimefields.-Account Agent Evolution uses whole-section Cluster fallback when unset. Account-Feishu also uses the complete Cluster section when unset. Once an Account Feishu-section is set, `app_id`, `app_secret`, `max_rows_per_sheet`,+Account `embedding` and `vectordb` use dedicated allowlist schemas. Account and+Cluster settings are published independently; the vector resolver applies+domain-specific Cluster defaults. Provider connection fields are accepted only+inside `credentials`, which replaces the complete provider binding. Each+credential must independently supply its provider and required connection and+authentication parameters. A credential may use the effective outer model.+VectorDB does not expose local paths, cuVS tuning, or custom adapter parameters.++Existing Accounts may PATCH complete embedding credential/deployment bindings,+retry/concurrency, failback and circuit-breaker settings. Setting an optional+runtime field such as `max_retries` to `null` removes the Account value, after+which the vector resolver applies its Cluster default. Required credentials+cannot be removed from a configured model mode. Outer model identity, mode, dimension, input, query/document parameters,+version, text source and input token limit are create-only. Provider fields outside+`credentials`, batch size, encoding format, extra body, local model paths,+fusion/video settings and metadata override are not on the Account API surface.+Every change validates the effective Embedding/VectorDB pair before persistence.++An explicit `embedding: {}` is valid and declares no Account model mode or runtime+policy. As a PATCH, `{}` merges with existing settings and does not clear them.+When no Account model mode is configured, Cluster model bindings are used.+An explicit Account VectorDB connection replaces Cluster connection and+authentication fields even when the backend type is unchanged; only remote+backends `http`, `volcengine` and `vikingdb` are accepted.++```json+{"settings":{"embedding":{"dense":{"credentials":[{"provider":"openai","model":"compatible-deployment","api_base":"https://embedding.example/v1","api_key":"account-key"}]}}}}+```++Queries, indexing, reindexing and OVPack use the target Account, including ROOT+requests. Endpoint updates apply to subsequent embedding calls; in-flight calls finish.+The caller must ensure semantic model compatibility: equal dimension does not prove+equal model weights. No automatic historical-vector migration is performed. Remote+collections/indexes and authorization must be provisioned externally; runtime errors+never select another Account's or Cluster's database.++Account and Cluster settings are stored independently. Agent Evolution retains+deprecated whole-section Cluster fallback solely for compatibility. Account+Feishu defaults are resolved by Feishu business code: when its Account section+is absent it uses the complete Cluster section; once present, `app_id`,+`app_secret`, `max_rows_per_sheet`,`max_records_per_table`, `download_images`, and `request_timeout` come from theAccount section or their Feishu defaults; only `domain` remains Cluster-owned.GitHub and ACL have no Cluster fallback.+VLM business resolution uses Cluster VLM when an Account has no VLM section.+Once the Account section exists, its model-service identity fields come+exclusively from Account settings, while selected runtime behavior is composed+with Cluster settings. Account `timeout` overrides Cluster `timeout` when set;+omitting or resetting it uses Cluster `timeout`. Query Planner precedence is+Account `query_planner`, Account `vlm`, Cluster `query_planner`, then Cluster `vlm`.+These are VLM business rules, not generic configuration inheritance.+The PATCH is validated structurally before the merged configuration is built:unknown paths and fields outside the runtime surface are rejected. Objects mergerecursively; arrays replace wholesale. A nested null removes only that leaf. Toremove a whole object override, send null at the parent path; an empty objectremains an explicit empty object.-Both GET endpoints return only the explicit values persisted at the addressed-layer. They do not expand fallback values. After persistence, the new+Both GET endpoints return only values persisted at the addressed scope. They do+not return business-resolved defaults. After persistence, the newconfiguration is published and matching in-process consumers are awaited.Consumer failures are logged without rolling back the persisted override, soa successful response confirms the configuration update but does not certifythat every derived client has applied it. The current business integrationsare documented in the [runtime configuration design](../../design/runtime-configuration-design.md).+#### Account Configuration Reference++Initialize Account configuration through `settings` on the create endpoint,+then read and update it through the configuration endpoints:++| Method | Path | Authorization | Return value |+| --- | --- | --- | --- |+| `POST` | `/api/v1/admin/accounts` | ROOT | New Account; accepts create-time `settings` |+| `GET` | `/api/v1/admin/accounts/{account_id}/configuration` | ROOT, or the target Account's ADMIN | Explicit persisted `settings` for that Account |+| `PATCH` | `/api/v1/admin/accounts/{account_id}/configuration` | ROOT, or the target Account's ADMIN | Merged explicit `settings` |++`vlm`, `query_planner`, `embedding`, and `vectordb` are sensitive+infrastructure settings. Only ROOT can create, read, or modify them. An ADMIN+GET response for its own Account removes those sections; a PATCH body containing+any of them immediately returns `403 PERMISSION_DENIED`. ADMIN cannot manage a+different Account. Structural and semantic validation errors return+`400 INVALID_ARGUMENT`; an unknown Account returns `404 NOT_FOUND`.++Create-only fields can be supplied only through `settings` on+`POST /api/v1/admin/accounts`. A later PATCH that touches one, including a+parent-object `null`, returns `400 INVALID_ARGUMENT` and persists no partial+update. Account creation validates `settings` before creating the Account+directory. A later PATCH first merges the current explicit Account values, then+validates the complete effective configuration.++**Other Account Configuration Sections**++In addition to model and vector settings, the following `settings` objects are+dynamic and both ROOT and the target Account's ADMIN can read and write them:++| Path | Type and constraints | Meaning |+| --- | --- | --- |+| `acl.enabled` | Boolean, default `false` | Whether ACL is enabled for this Account |+| `agent_evolution.enabled` | Boolean, default `false` | Whether Agent Evolution is enabled; when the Account omits the whole section, the complete Cluster `agent_evolution` section is used for legacy compatibility |+| `github.token` | String, default empty string | GitHub access token; an empty string means the Account provides no token |+| `feishu.app_id` | String, optional | Account Feishu App ID |+| `feishu.app_secret` | String, optional | Account Feishu App Secret |+| `feishu.max_rows_per_sheet` | Integer, `> 0`, optional | Maximum rows read from one Sheet |+| `feishu.max_records_per_table` | Integer, `> 0`, optional | Maximum records read from one Base table |+| `feishu.download_images` | Boolean, optional | Whether to download images from Feishu documents |+| `feishu.request_timeout` | Number, `> 0`, optional | Feishu request timeout in seconds |++`feishu.domain` is not part of the Account API; Cluster always owns it. When+the Account omits the entire `feishu` section, it uses the complete Cluster+Feishu configuration. Once configured, the fields above use explicit Account+values or Feishu defaults, while only `domain` still comes from Cluster.+`github` and `acl` do not fall back to Cluster.++**Read explicit Account configuration**++```bash+curl http://localhost:1933/api/v1/admin/accounts/acme/configuration \+ -H "X-API-Key: <root-key>"+```++```json+{+ "status": "ok",+ "result": {+ "account_id": "acme",+ "settings": {+ "embedding": {+ "max_retries": 5+ }+ }+ }+}+```++The response does not expand Cluster values, defaults, or the effective+Embedding/VectorDB composition. For example, when the response above has no+Account model binding, actual calls still use the Cluster model binding.++**Update dynamic Account configuration**++This example assumes the Account declared a `dense` binding with `model` and+`dimension` at creation. The PATCH only rotates its credentials and updates+dynamic runtime values.++```bash+curl -X PATCH http://localhost:1933/api/v1/admin/accounts/acme/configuration \+ -H "Content-Type: application/json" \+ -H "X-API-Key: <root-key>" \+ -d '{+ "settings": {+ "embedding": {+ "max_retries": 5,+ "dense": {+ "credentials": [{+ "id": "primary",+ "provider": "openai",+ "model": "embed-deployment-v2",+ "api_key": "<new-api-key>",+ "api_base": "https://embedding.example/v1"+ }]+ }+ }+ }+ }'+```++```json+{+ "status": "ok",+ "result": {+ "account_id": "acme",+ "settings": {+ "embedding": {+ "max_retries": 5,+ "dense": {+ "model": "text-embedding-3-large",+ "dimension": 3072,+ "credentials": [{+ "id": "primary",+ "provider": "openai",+ "model": "embed-deployment-v2",+ "api_key": "<new-api-key>",+ "api_base": "https://embedding.example/v1"+ }]+ }+ }+ }+ }+}+```++Objects merge recursively and arrays replace wholesale. The example therefore+replaces the full `dense.credentials` failover chain rather than merging by+`id`. Set a dynamic leaf to `null` to remove its Account value, for example+`{"settings":{"embedding":{"max_retries":null}}}`. The vector resolver then+uses the corresponding Cluster value. An empty object does not clear an+existing object.++**Account VLM and Query Planner Fields**++`vlm` and `query_planner` use the same dynamic schema:++| Path | Type and constraints | Meaning |+| --- | --- | --- |+| `*.model` | Non-empty string, required | Default model name |+| `*.credentials` | Non-empty array, required; replaces as a whole | Provider/failover bindings in call order |+| `*.timeout` | Number, `> 0`, optional | Account request timeout in seconds; reset it to use Cluster timeout |+| `*.credentials[].id` | String, optional | Credential identifier |+| `*.credentials[].provider` | String, required | `volcengine`, `openai`, `azure`, `kimi`, `glm`, `litellm`, or `openai-codex` |+| `*.credentials[].model` | String, optional | Overrides the outer `model`; can be an endpoint/deployment ID |+| `*.credentials[].api_key` | String, optional | Provider API key; normally required except for `litellm`; `openai-codex` may use local Codex OAuth |+| `*.credentials[].api_base` | String, optional | API endpoint |+| `*.credentials[].api_version` | String, optional | API version for Azure and similar APIs |+| `*.credentials[].forward_api_key` | Boolean, optional | Whether to forward the API key to LiteLLM |+| `*.credentials[].extra_headers` | `map<string, string>`, optional | Additional HTTP request headers; map keys are header names and values are header values |+| `*.credentials[].extra_request_body` | `map<string, JSON value>`, optional | Provider extensions appended unchanged to an OpenAI-compatible completion request body; a top-level `stream` key is not allowed |+| `*.credentials[].reasoning_effort` | String, optional | OpenAI-compatible reasoning effort |+| `*.credentials[].keepalive_expiry` | Number, `>= 0`, optional | Idle HTTP connection lifetime in seconds |+| `*.credentials[].max_tokens` | Integer, `> 0`, optional | Overrides the outer completion token limit |++When an Account has no `vlm`, it uses the Cluster VLM. Once `vlm` is configured,+the model, provider, endpoint, and credentials come exclusively from Account+settings; Cluster provides only general runtime behavior not owned by the+Account. Query Planner precedence is Account `query_planner`, Account `vlm`,+Cluster `query_planner`, then Cluster `vlm`.++The keys inside `extra_headers` and `extra_request_body` are not enumerated by+OpenViking; they must follow the target provider's API contract. They belong+only to that credential and do not merge with a same-named Cluster object or+another credential. `extra_request_body` cannot set `stream` because+OpenViking VLM APIs return complete responses only.++**Account Embedding Fields**++Unset values are not persisted on the Account. At runtime, the vector resolver+uses the corresponding Cluster value. If Account creation declares `dense`,+`sparse`, or `hybrid`, that mode must be a complete Account binding. `hybrid`+cannot be combined with `dense` or `sparse`.++| Path | Lifecycle | Type and constraints | Meaning |+| --- | --- | --- | --- |+| `embedding.dense` / `sparse` / `hybrid` | Mode existence is create-only | Object/null | Three model output modes; cannot be added, removed, or switched after creation |+| `embedding.max_concurrent` | Dynamic | Integer, `>= 1` | Provider-call concurrency limit for this Account |+| `embedding.max_retries` | Dynamic | Integer, `>= 0` | Retry count for transient provider failures |+| `embedding.circuit_breaker.failure_threshold` | Dynamic | Integer, `>= 1` | Consecutive failures before opening the circuit |+| `embedding.circuit_breaker.reset_timeout` | Dynamic | Number, `> 0` | Base circuit recovery wait in seconds |+| `embedding.circuit_breaker.max_reset_timeout` | Dynamic | Number, `> 0` | Maximum circuit recovery wait in seconds |+| `embedding.text_source` | Create-only | `content_only` / `summary_first` | Text source used when writing vectors |+| `embedding.max_input_tokens` | Create-only | Integer, `>= 100` | Input token limit for one embedding call |+| `embedding.*.model` | Create-only | Non-empty string, required when first declaring a mode | Model identity |+| `embedding.*.dimension` | Create-only | Integer, `> 0`, required when first declaring a mode | Vector dimension; must match the effective VectorDB |+| `embedding.*.input` | Create-only | `text` / `multimodal`, optional | Input mode |+| `embedding.*.query_param` / `document_param` | Create-only | String, optional | Query/document parameters for asymmetric retrieval |+| `embedding.*.version` | Create-only | String, optional | Model version |+| `embedding.*.credentials` | Dynamic | Non-empty array; replaces as a whole | Account provider/failover binding |+| `embedding.*.failback_timeout_seconds` | Dynamic | Number, `> 0` | Wait before trying to fail back to the primary credential |+| `embedding.*.failback_request_count` | Dynamic | Integer, `>= 1` | Backup requests before attempting failback |++`embedding.*.credentials` is an ordered array. Its first item has priority;+later credentials are attempted in array order after a failure. Each item has+this schema:++| Field | Type and constraints | Meaning |+| --- | --- | --- |+| `id` | String, optional | Stable credential identifier; when omitted, runtime identifies it from its array index |+| `provider` | String, required | Lowercase provider name: `openai`, `azure`, `volcengine`, `vikingdb`, `jina`, `ollama`, `gemini`, `voyage`, `dashscope`, `minimax`, `cohere`, `litellm`, or `local` |+| `model` | Non-empty string, optional | Overrides the outer model for the mode; when absent, uses the outer model and is commonly an endpoint/deployment ID |+| `api_key` | String, optional | API key. Provider-specific requirements appear below |+| `api_base` | String, optional | OpenAI-compatible or Azure endpoint |+| `api_version` | String, optional | API version for Azure and similar APIs |+| `ak` | String, optional | Access Key for the VikingDB Embedding provider |+| `sk` | String, optional | Secret Key for the VikingDB Embedding provider |+| `region` | String, optional | Region for the VikingDB Embedding provider |+| `host` | String, optional | Provider endpoint or routing host |+| `extra_headers` | `map<string, string>`, optional | Additional HTTP headers sent to the provider |++Each credential must independently satisfy its provider's connection and+authentication requirements. It cannot borrow values from Cluster configuration+or another credential in the array:++| Provider | Required or alternative fields | Notes |+| --- | --- | --- |+| `openai` | `api_key` or `api_base` | `api_base` supports local OpenAI-compatible services that do not require an API key |+| `azure` | `api_key` and `api_base` | Add `api_version` when required by the Azure endpoint |+| `volcengine`, `jina`, `gemini`, `voyage`, `dashscope`, `minimax`, `cohere` | `api_key` | Other connection fields are provider-specific options |+| `vikingdb` | `ak`, `sk`, and `region` | All three are required together |+| `ollama`, `litellm`, `local` | No mandatory authentication field | An outer or credential `model` is still required; the provider handles endpoint, environment, or local-model requirements |++A credential may omit `model` to use the outer model for its mode. Once the+credential array is supplied, it does not compose with Cluster provider,+endpoint, credential, or provider-specific fields. `batch_size`,+`encoding_format`, `extra_body`, `model_path`, `cache_dir`, fusion/video+parameters, `allow_metadata_override`, and provider/auth fields outside+`credentials` are not on the Account API surface.++Existing Accounts can update dynamic runtime values, but cannot create a model+mode for the first time through PATCH because `model`, `dimension`, and the mode+combination are create-time contracts. `embedding: {}` is valid and means that+the Account has no Embedding override; submitted through PATCH, it only merges+and does not clear existing settings.++**Account VectorDB Fields**++Supply `vectordb` only as `settings.vectordb` in the Account creation request.+Every field is create-only. When omitted, the Account uses the Cluster+VectorDB. When supplied, Account connection and authentication completely+replace Cluster connection and authentication even if both choose the same+backend type.++| Path | Type and constraints | Meaning |+| --- | --- | --- |+| `vectordb.backend` | Required: `http`, `volcengine`, or `vikingdb` | Account supports remote backends only |+| `vectordb.name` | Non-empty string, required | Collection name |+| `vectordb.url` | String; required for `http` | HTTP backend endpoint |+| `vectordb.project` | Non-empty string, default `default` | Project name; `project_name` is the internal field name |+| `vectordb.index_name` | Non-empty string, required | Index name |+| `vectordb.distance_metric` | `cosine`, `l2`, or `ip`; default `cosine` | Distance metric |+| `vectordb.dimension` | Integer, `> 0`, required | Must equal the effective Embedding dimension |+| `vectordb.sparse_weight` | Number, `>= 0`; default `0` | Sparse/hybrid retrieval weight |++VectorDB subobjects are also entirely create-only:++| Path | Type and constraints | Meaning |+| --- | --- | --- |+| `vectordb.volcengine.ak` | String, optional | Access Key for AK/SK authentication; required in that mode |+| `vectordb.volcengine.sk` | String, optional | Secret Key for AK/SK authentication; required in that mode |+| `vectordb.volcengine.api_key` | String, optional | Data API key authentication; when set, AK/SK are not required |+| `vectordb.volcengine.session_token` | String, optional | Optional STS temporary-credential token for AK/SK authentication |+| `vectordb.volcengine.region` | String, optional | Required in AK/SK mode; API-key mode requires this or `host` |+| `vectordb.volcengine.host` | String, optional | Data-plane endpoint for API-key mode; API-key mode requires this or `region` |+| `vectordb.vikingdb.host` | Non-empty string; required for `vikingdb` | Private-deployment VikingDB endpoint |+| `vectordb.vikingdb.headers` | `map<string, string>`, optional | Private-deployment request headers; map keys are header names and values are header values |++Account `local`, `cuvs`, `path`, cuVS tuning, and `custom_params` are not+supported. External control-plane tooling must create remote collections,+indexes, schemas, and authorization before configuration. The API validates the+local Embedding/VectorDB contract but does not probe remote resources. After+configuration becomes effective, queries, indexing, queue writes, reindexing,+and OVPack route by the target Account. ROOT follows the same routing when+acting for an Account.++Every Embedding creation or update validates the effective+Embedding/VectorDB pair, including vector dimension, output mode, sparse+weight, distance metric, provider configuration, and credential completeness.+On validation failure, no new configuration is published. Runtime connection or+authentication errors, absent collections/indexes, and schema drift fail only+the current Account operation and never fall back to another Account or the+Cluster VectorDB. Dynamic credential or endpoint updates affect subsequent+calls; in-flight calls complete. OpenViking does not migrate or rebuild+historical vectors automatically, so callers must ensure semantic model+compatibility.+### user_settingsROOT can manage any User and ADMIN can manage Users in its own account. The@@ -533,10 +872,13 @@ Create a new workspace with its first admin user.| admin_user_id | str | Yes | - | First admin user ID || seed | str | No | `null` | Optional deterministic API key seed. When set, the key secret is `sha256(user_id + "\0" + seed)` || user_config | object | No | `null` | Initial config for the first admin user. Supports `add_targets.resource_uri`, `add_targets.skill_uri`, and `memory_policy` |+| settings | object | No | `null` | Initial Account runtime configuration. ROOT-only; supports `feishu`, `github`, `acl`, `agent_evolution`, `vlm`, `query_planner`, `embedding`, and `vectordb`. `vectordb` and Embedding create-only fields can only be set here |**Notes:**- In `trusted` mode, `user_key` is omitted from the response- Omit `seed` for the default random API key. Treat seed values as secret material; short seeds can make the key guessable.+- `settings` receives structural and effective Embedding/VectorDB pair validation before the Account and its directories are created. A failed validation leaves no Account, user, or configuration file.+- Account `vlm`, `query_planner`, `embedding`, and `vectordb` are ROOT-only. See [Account Configuration Reference](#account-configuration-reference) above for their schema, lifecycle, and validation. The current Python SDK, CLI, and other SDK Account-creation wrappers do not expose a `settings` argument; use the HTTP API for this capability.- Account-level namespace isolation settings are no longer supported. User memory uses user-scoped namespaces, and one-to-many external participants are represented with `peer_id`.- `user_config.add_targets.resource_uri` must be a writable resource directory URI: `viking://resources` or `viking://resources/...`, `viking://~/resources` or `viking://~/resources/...`, `viking://user/{user_id}/resources` or `viking://user/{user_id}/resources/...`, or `viking://user/{user_id}/peers/{peer_id}/resources` or `viking://user/{user_id}/peers/{peer_id}/resources/...`.- `user_config.add_targets.skill_uri` must be `viking://~/skills` or `viking://agent/skills`. Explicit `viking://user/{user_id}/skills` is not accepted in v1.@@ -561,6 +903,39 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \}'```+**Create an Account with dedicated Embedding and VectorDB**++```bash+curl -X POST http://localhost:1933/api/v1/admin/accounts \+ -H "Content-Type: application/json" \+ -H "X-API-Key: <root-key>" \+ -d '{+ "account_id": "acme-isolated",+ "admin_user_id": "alice",+ "settings": {+ "embedding": {+ "dense": {+ "model": "text-embedding-3-large",+ "dimension": 3072,+ "credentials": [{+ "provider": "openai",+ "api_key": "<embedding-api-key>"+ }]+ }+ },+ "vectordb": {+ "backend": "vikingdb",+ "name": "acme_context",+ "index_name": "default",+ "dimension": 3072,+ "vikingdb": {+ "host": "https://vikingdb.example"+ }+ }+ }+ }'+```+**Trusted mode (registered gateway user)**```bashdiff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex 7d746eea8..7d62f72ba 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -11,6 +11,27 @@ openviking-server doctor`openviking-server init` prompts for embedding and VLM settings separately. For API-based VLM choices such as `OpenAI`, `Volcengine`, `Kimi`, and `GLM`, enter the VLM API key when prompted. If you want to use Codex as the VLM provider, choose `OpenAI Codex`; the wizard can import existing Codex auth or guide you through login directly.+## Account Embedding and VectorDB++ROOT can configure `settings.embedding` and `settings.vectordb` when creating an+Account. These sections use Account-specific allowlist schemas. Account and+Cluster settings remain independent; the vector resolver applies Cluster defaults+for omitted Account values. Provider connections can only be supplied through a+complete `credentials` binding. Configuration reads return only Account values.++VectorDB is immutable after Account creation. Existing Accounts may rotate complete+Embedding credential/deployment bindings and update retry, concurrency, failback, and+circuit-breaker settings. Outer model identity and other vector-space fields remain+create-only. Compatible endpoint updates do not interrupt in-flight calls or rebuild+historical vectors.++Account-owned VectorDB configurations use remote backends only. Account+configuration cannot select local/cuvs backends, local paths, cuVS tuning, or+custom adapter parameters. Accounts with no VectorDB settings continue sharing+the Cluster connection with Account data filtering. Remote resources must+already exist.+See [Admin configuration API](../api/08-admin.md#runtime-configuration) for permissions and PATCH rules.+## Configuration FileCreate `~/.openviking/ov.conf` in your home configuration directory:@@ -52,17 +73,42 @@ For `provider: "openai-codex"`, `vlm.api_key` is optional when Codex OAuth is alOpenViking configuration has two layers:- **Startup configuration** is read from `ov.conf`. It defines the process baseline and the runtime configuration source. Changing it requires a service restart; the runtime configuration API never rewrites `ov.conf`.-- **Runtime overrides** are sparse values stored by the configured runtime configuration source. They can be read and updated through the Admin API at Cluster or Account scope.+- **Runtime settings** are stored independently at Cluster and Account scope by the configured runtime configuration source. They can be read and updated through the Admin API.Only fields explicitly declared as runtime fields are exposed by the runtime configuration API. The current update surface is:| Scope | Configuration | Lifecycle | Effective behavior || --- | --- | --- | --- || Cluster | `agent_evolution` | Dynamic | ROOT can update it through the Admin API; it is used as the cluster default. |-| Account | `feishu`, `agent_evolution` | Dynamic | ROOT or the Account ADMIN can update them. Agent Evolution falls back to the whole Cluster section. An unset Account Feishu section also uses the Cluster section; once set, only `domain` comes from Cluster and omitted Account fields use Feishu defaults. Both are consumed through the runtime manager. |+| Account | `feishu`, `agent_evolution` | Dynamic | ROOT or the Account ADMIN can update them. Agent Evolution retains deprecated whole-section Cluster fallback for compatibility. Feishu defaulting is implemented by its business resolver: an unset Account section uses Cluster, while a configured section takes only `domain` from Cluster. || Account | `github`, `acl` | Dynamic | ROOT or the Account ADMIN can update it. These sections have no Cluster fallback. |--Cluster `embedding`, Cluster `vlm`, `query_planner`, Cluster `memory`, `feishu`, storage, parser, retrieval, and other ordinary configuration sections remain startup-only. Account `vlm`, `memory`, `embedding`, and `vectordb` are not on the current Account configuration API surface; requests that contain them are rejected.+| Account | `vlm`, `query_planner` | Dynamic | ROOT-only. Each configured section requires `model` and a non-empty `credentials` array; `timeout` is optional. ADMIN callers cannot read or update these sections. |+| Account | `embedding` | Mixed | ROOT-only. Credentials, retries, concurrency, failback and circuit-breaker settings are dynamic; model identity, vector-space fields, text source and input token limit are create-only. |+| Account | `vectordb` | Create-only | ROOT-only. Supply it in Account creation `settings`; later additions, changes and resets are rejected. Only remote backends `http`, `volcengine` and `vikingdb` are supported for Account-owned connections. |++Cluster `embedding`, `vlm`, `query_planner`, `memory`, `feishu`, storage, parser, retrieval, and other ordinary configuration sections remain startup-only. Account `memory` is not on the current Account configuration API surface.++Account and Cluster configurations are independently stored and published.+Any use of Cluster settings when Account settings are absent is a business+default, not implicit configuration inheritance. The VLM resolver implements+that policy: without an Account VLM section it uses Cluster VLM; with an Account+section, model-service identity comes from Account while selected runtime+behavior is composed with Cluster. Account `timeout` overrides Cluster `timeout`+when set; omitting or resetting it uses Cluster `timeout`. Query Planner selection+is Account `query_planner`, Account `vlm`, Cluster `query_planner`, then Cluster `vlm`.++The vector resolver validates effective Embedding and VectorDB settings together.+Account `embedding: {}` is valid; without Account model modes, Cluster model+bindings are used. Account credentials and explicit VectorDB connections supply+their own connection and authentication fields. Remote collections, indexes and+authorization must be provisioned externally. Changing embedding credentials does+not migrate existing vectors; the caller must preserve model compatibility.++Account-owned business code must resolve model configuration through+`VLMResolver` and pass the resulting `VLMConfig` to lower-level helpers.+`ClusterVLMResolver` is restricted to startup, diagnostics, and offline+evaluation composition roots. A CI architecture test rejects new direct reads+of Cluster VLM or Query Planner configuration from other production modules.For runtime changes, use the following endpoints:@@ -74,7 +120,7 @@ GET /api/v1/admin/accounts/{account_id}/configurationPATCH /api/v1/admin/accounts/{account_id}/configuration```-The request body wraps a sparse patch in `settings`:+The request body wraps a PATCH document in `settings`:```json{@@ -86,7 +132,7 @@ The request body wraps a sparse patch in `settings`:}```-PATCH uses three states: an omitted field is unchanged, a concrete value sets or replaces the value, and `null` removes the override at that layer. Objects merge recursively and arrays replace as a whole. The response contains explicit values at the addressed layer, not inherited or effective values. See [Admin API - Runtime Configuration](../api/08-admin.md#runtime-configuration) for permissions, validation, fallback, and compatibility details. The implementation design is documented in [Runtime Configuration Design](../../design/runtime-configuration-design.md).+PATCH uses three states: an omitted field is unchanged, a concrete value sets or replaces the value, and `null` removes that value from the addressed scope. Objects merge recursively and arrays replace as a whole. The response contains settings from that scope, not a business-effective Account/Cluster composition. Declarative `fallback` is deprecated, supports only complete sections, and remains solely for compatibility; new features must implement Cluster defaults in their business resolver. See [Admin API - Runtime Configuration](../api/08-admin.md#runtime-configuration) for details.## Configuration Examplesdiff --git a/docs/zh/api/08-admin.md b/docs/zh/api/08-admin.mdindex 8c33c4a38..0cba1f5e2 100644--- a/docs/zh/api/08-admin.md+++ b/docs/zh/api/08-admin.md@@ -372,26 +372,328 @@ Content-Type: application/json`null` 表示删除当前层配置,具体值表示更新。当前 Cluster 运行时配置面仅包含 `agent_evolution`。Account 配置面包含-`feishu`、`agent_evolution`、`github` 和 `acl`,且均为动态字段。Account 的-`vlm`、`memory`、`embedding` 和 `vectordb` 不在当前 API 范围内,即使创建-Account 时提交也会被拒绝。Cluster 的 `embedding`、`vlm`、`query_planner`、+`feishu`、`agent_evolution`、`github`、`acl`、`vlm` 和 `query_planner`,+这些配置均可动态修改。Account 的+`vlm`、`query_planner`、`embedding` 和 `vectordb` 仅 ROOT 可读写,ADMIN 的读取+响应过滤这些配置,写入请求在读取配置前拒绝。每段已配置的 `vlm` 或+`query_planner` 都必须包含 `model` 和非空 `credentials` 数组,`timeout` 可选。+`memory` 不在当前 API 范围内。+`vectordb` 只能随 Account 创建时的 `settings` 提交,创建后包括 ROOT 在内均不可+新增、修改或重置。Cluster 的 `embedding`、`vlm`、`query_planner`、`memory`、`feishu`、存储、解析器和检索配置没有声明为运行时字段,因此仍然只能在启动配置中修改。-Account Agent Evolution 未设置时整段回落到 Cluster 配置。Account 未设置-Feishu 时也整段使用 Cluster 配置;一旦设置,`app_id`、`app_secret`、+Account `embedding` 和 `vectordb` 使用独立白名单模型。Account 与 Cluster+配置分别发布,向量配置解析器按业务规则应用 Cluster 默认值。模型服务的连接字段+只允许出现在 `credentials` 中,数组整体替换完整服务绑定,不能拼接 Cluster+连接或鉴权字段。每组凭证必须独立提供 `provider` 和必需的连接、鉴权参数;+凭证未设置 `model` 时可以使用有效外层 `model`。VectorDB 不开放本地路径、+cuVS 调优和自定义适配器参数。++存量 Account 可 PATCH 完整的模型凭证与部署绑定、重试、并发、故障回切和熔断参数。+将 `max_retries` 等可选运行参数设为 `null`,会从 Account 配置删除该值,+随后由向量配置解析器应用 Cluster 默认值;已配置模型模式中的必需凭证不能删除。+外层模型身份、模式、`dimension`、`input`、`query_param`、`document_param`、+`version`、`text_source` 和 `max_input_tokens` 为创建期字段。+`credentials` 之外的 provider 字段、`batch_size`、`encoding_format`、`extra_body`、+本地模型路径、融合/视频参数和 `allow_metadata_override` 不在 Account API 范围内。+每次更新都在持久化前联合校验有效 Embedding 和 VectorDB,失败保留原配置。++显式 `embedding: {}` 是合法配置,表示未声明 Account 模型模式或运行策略。+作为 PATCH 提交时,`{}` 会与现有配置合并,不会清空已有值。未配置 Account+模型模式时使用 Cluster 模型绑定。显式 Account VectorDB 配置会替换 Cluster+的连接与鉴权字段,即使后端类型相同也不会拼接;仅支持 `http`、`volcengine`、+`vikingdb` 远端后端。++```json+{"settings":{"embedding":{"dense":{"credentials":[{"provider":"openai","model":"compatible-deployment","api_base":"https://embedding.example/v1","api_key":"account-key"}]}}}}+```++查询、队列写入、Reindex 和 OVPack 都使用目标 Account 配置,ROOT 也遵守此规则。+服务端点更新作用于后续 Embedding 调用,在途调用安全完成。调用方负责保证模型空间兼容:+维度相同不能证明权重相同,本功能不会自动重建历史向量。远端集合、索引和授权由+外部控制面创建,运行失败不会切换到其他 Account 或 Cluster 向量库。++Account 与 Cluster 配置分别存储。Agent Evolution 仅为兼容旧行为保留已废弃的+Cluster 整段回退。Feishu 默认值由 Feishu 业务代码解析:Account 未设置+Feishu 时使用完整 Cluster 配置;一旦设置,`app_id`、`app_secret`、`max_rows_per_sheet`、`max_records_per_table`、`download_images` 和`request_timeout` 来自 Account 配置或 Feishu 默认值,只有 `domain` 仍由-Cluster 管理。GitHub 和 ACL 没有 Cluster fallback。+Cluster 管理。GitHub 和 ACL 不回退到 Cluster。++VLM 业务解析器在 Account 未配置 VLM 时使用 Cluster VLM。Account 已配置时,+模型身份、服务端点和凭证仅来自 Account,部分运行参数按业务规则使用 Cluster+配置。Account 设置 `timeout` 时覆盖 Cluster 的值,未设置或重置后使用 Cluster+的值。Query Planner 的选择顺序为 Account `query_planner`、Account `vlm`、+Cluster `query_planner`、Cluster `vlm`;这是 VLM 业务规则,不是配置框架的隐式继承。PATCH 会先做结构校验,再构造合并后的配置:未知路径和运行时配置面之外的字段会被拒绝。对象递归合并,数组整体替换;嵌套 null 只删除对应叶子。删除整个对象覆盖需要在父路径传 null,传空对象仍表示显式空对象。-两个 GET 接口只返回目标层持久化的显式值,不展开 fallback。配置持久化后会发布新配置并等待-匹配的进程内 Consumer;Consumer 失败会记录日志但不会回滚已持久化的覆盖,因此接口成功只表示+两个 GET 接口只返回目标作用域持久化的配置,不返回业务解析后的默认值。配置持久化后会发布新配置并等待+匹配的进程内 Consumer;Consumer 失败会记录日志但不会回滚已持久化的配置,因此接口成功只表示配置层更新成功,不保证所有派生客户端都已完成切换。当前业务接入状态见[运行时配置设计](../../design/runtime-configuration-design.md)。+#### Account Configuration 接口参考++Account 配置通过创建接口的 `settings` 初始化,并通过 configuration 接口读取和更新:++| 方法 | 路径 | 权限 | 返回值 |+| --- | --- | --- | --- |+| `POST` | `/api/v1/admin/accounts` | ROOT | 新 Account;可接受创建期 `settings` |+| `GET` | `/api/v1/admin/accounts/{account_id}/configuration` | ROOT;或目标 Account 的 ADMIN | 该 Account 显式持久化的 `settings` |+| `PATCH` | `/api/v1/admin/accounts/{account_id}/configuration` | ROOT;或目标 Account 的 ADMIN | 合并后的显式 `settings` |++`vlm`、`query_planner`、`embedding` 和 `vectordb` 是敏感基础设施配置:只有 ROOT+可以创建、读取或修改。ADMIN 对自己的 Account 调用 GET 时,响应会移除这四段;若+PATCH body 包含其中任一段,立即返回 `403 PERMISSION_DENIED`。ADMIN 也不能管理+其他 Account。所有结构或业务校验错误返回 `400 INVALID_ARGUMENT`,不存在的 Account+返回 `404 NOT_FOUND`。++创建期字段只能随 `POST /api/v1/admin/accounts` 的 `settings` 写入。创建后 PATCH+触及这些字段,包括把父对象设为 `null`,都会返回 `400 INVALID_ARGUMENT`,且不会+持久化任何部分更新。创建请求会在创建账号目录前校验 `settings`;后续 PATCH 则先合并+当前 Account 显式值,再校验完整有效配置。++**其他 Account 配置段**++除模型与向量配置外,以下 `settings` object 均为动态字段,ROOT 和目标 Account 的 ADMIN+都可读写:++| 路径 | 类型和约束 | 含义 |+| --- | --- | --- |+| `acl.enabled` | boolean,默认 `false` | 是否启用该 Account 的 ACL |+| `agent_evolution.enabled` | boolean,默认 `false` | 是否启用 Agent Evolution;Account 未设置整个 section 时,为兼容旧行为使用完整 Cluster `agent_evolution` section |+| `github.token` | string,默认空字符串 | GitHub 访问 token;空字符串表示该 Account 未提供 token |+| `feishu.app_id` | string,可选 | Account Feishu App ID |+| `feishu.app_secret` | string,可选 | Account Feishu App Secret |+| `feishu.max_rows_per_sheet` | integer,`> 0`,可选 | 单个 Sheet 读取的最大行数 |+| `feishu.max_records_per_table` | integer,`> 0`,可选 | 单个多维表格读取的最大记录数 |+| `feishu.download_images` | boolean,可选 | 是否下载 Feishu 文档中的图片 |+| `feishu.request_timeout` | number,`> 0`,可选 | Feishu 请求超时秒数 |++`feishu.domain` 不在 Account API;它始终由 Cluster 管理。Account 未设置整个 `feishu`+section 时使用完整 Cluster Feishu 配置;一旦设置,以上 Account 字段使用显式值或 Feishu+默认值,只有 `domain` 仍来自 Cluster。`github` 和 `acl` 不回退到 Cluster。++**读取 Account 显式配置**++```bash+curl http://localhost:1933/api/v1/admin/accounts/acme/configuration \+ -H "X-API-Key: <root-key>"+```++```json+{+ "status": "ok",+ "result": {+ "account_id": "acme",+ "settings": {+ "embedding": {+ "max_retries": 5+ }+ }+ }+}+```++响应不会展开 Cluster 值、默认值或最终生效的 Embedding/VectorDB 组合。例如上例没有+Account 模型 binding 时,实际调用仍会使用 Cluster 模型 binding。++**修改动态 Account 配置**++以下示例假定 Account 已在创建时声明了包含 `model` 与 `dimension` 的 `dense`+binding;PATCH 只轮换其 credentials 并更新动态运行参数。++```bash+curl -X PATCH http://localhost:1933/api/v1/admin/accounts/acme/configuration \+ -H "Content-Type: application/json" \+ -H "X-API-Key: <root-key>" \+ -d '{+ "settings": {+ "embedding": {+ "max_retries": 5,+ "dense": {+ "credentials": [{+ "id": "primary",+ "provider": "openai",+ "model": "embed-deployment-v2",+ "api_key": "<new-api-key>",+ "api_base": "https://embedding.example/v1"+ }]+ }+ }+ }+ }'+```++```json+{+ "status": "ok",+ "result": {+ "account_id": "acme",+ "settings": {+ "embedding": {+ "max_retries": 5,+ "dense": {+ "model": "text-embedding-3-large",+ "dimension": 3072,+ "credentials": [{+ "id": "primary",+ "provider": "openai",+ "model": "embed-deployment-v2",+ "api_key": "<new-api-key>",+ "api_base": "https://embedding.example/v1"+ }]+ }+ }+ }+ }+}+```++对象递归合并,数组整体替换。因此上例会替换 `dense.credentials` 的全部 failover+链,而不是按 `id` 合并。动态叶子设为 `null` 会删除该 Account 值,例如+`{"settings":{"embedding":{"max_retries":null}}}`;之后由向量解析器采用 Cluster+对应值。空对象不会清空已有对象。++**Account VLM 与 Query Planner 字段**++`vlm` 和 `query_planner` 使用相同 schema,均为动态段:++| 路径 | 类型和约束 | 含义 |+| --- | --- | --- |+| `*.model` | 非空 string,必填 | 默认模型名 |+| `*.credentials` | 非空 array,必填,整体替换 | 按数组顺序使用的 provider/failover binding |+| `*.timeout` | number,`> 0`,可选 | Account 请求超时秒数;删除后使用 Cluster timeout |+| `*.credentials[].id` | string,可选 | credential 标识 |+| `*.credentials[].provider` | string,必填 | `volcengine`、`openai`、`azure`、`kimi`、`glm`、`litellm` 或 `openai-codex` |+| `*.credentials[].model` | string,可选 | 覆盖外层 `model`,可用于 endpoint/deployment ID |+| `*.credentials[].api_key` | string,可选 | provider API Key;除 `litellm` 外通常必需,`openai-codex` 可使用本机 Codex OAuth |+| `*.credentials[].api_base` | string,可选 | API endpoint |+| `*.credentials[].api_version` | string,可选 | Azure 等 API 的版本 |+| `*.credentials[].forward_api_key` | boolean,可选 | 是否把 API Key 透传给 LiteLLM |+| `*.credentials[].extra_headers` | `map<string, string>`,可选 | 请求附加 HTTP headers;map key 为 header 名,value 为 header 值 |+| `*.credentials[].extra_request_body` | `map<string, JSON value>`,可选 | 原样追加到 OpenAI-compatible completion 请求 body 的 provider 扩展字段;顶层 `stream` 不允许 |+| `*.credentials[].reasoning_effort` | string,可选 | OpenAI-compatible reasoning 强度 |+| `*.credentials[].keepalive_expiry` | number,`>= 0`,可选 | HTTP 空闲连接存活秒数 |+| `*.credentials[].max_tokens` | integer,`> 0`,可选 | 覆盖外层输出 token 上限 |++Account 未配置 `vlm` 时使用 Cluster VLM。配置 Account `vlm` 后,模型、provider、+endpoint 与凭据只取 Account 值;Cluster 仅提供未归属 Account 的通用运行行为。+Query Planner 优先级为 Account `query_planner`、Account `vlm`、Cluster+`query_planner`、Cluster `vlm`。++`extra_headers` 与 `extra_request_body` 的 key 不由 OpenViking 枚举,必须遵循目标+provider 的 API 契约。它们仅属于该 credential,不会与 Cluster 同名 object 或其他+credential 合并;不能用 `extra_request_body` 设置 `stream`,因为 OpenViking VLM 接口+只返回完整响应。++**Account Embedding 字段**++未设置的字段不写入 Account;向量解析器在运行时按需使用 Cluster 的相应值。若 Account+创建时声明 `dense`、`sparse` 或 `hybrid`,该 mode 必须是完整的 Account binding。+`hybrid` 不能与 `dense` 或 `sparse` 同时出现。++| 路径 | 生命周期 | 类型和约束 | 含义 |+| --- | --- | --- | --- |+| `embedding.dense` / `sparse` / `hybrid` | mode 存在性创建期 | object/null | 三种模型输出模式;创建后不能新增、删除或切换 |+| `embedding.max_concurrent` | 动态 | integer,`>= 1` | 该 Account 的 provider 调用并发上限 |+| `embedding.max_retries` | 动态 | integer,`>= 0` | 瞬时 provider 错误重试次数 |+| `embedding.circuit_breaker.failure_threshold` | 动态 | integer,`>= 1` | 熔断前的连续失败次数 |+| `embedding.circuit_breaker.reset_timeout` | 动态 | number,`> 0` | 熔断恢复基础等待秒数 |+| `embedding.circuit_breaker.max_reset_timeout` | 动态 | number,`> 0` | 熔断恢复等待上限秒数 |+| `embedding.text_source` | 创建期 | `content_only` / `summary_first` | 写入向量使用的文本来源 |+| `embedding.max_input_tokens` | 创建期 | integer,`>= 100` | 单次向量化的输入 token 上限 |+| `embedding.*.model` | 创建期 | 非空 string,mode 首次声明时必填 | 模型身份 |+| `embedding.*.dimension` | 创建期 | integer,`> 0`,mode 首次声明时必填 | 向量维度;必须与有效 VectorDB 一致 |+| `embedding.*.input` | 创建期 | `text` / `multimodal`,可选 | 输入模式 |+| `embedding.*.query_param` / `document_param` | 创建期 | string,可选 | 非对称检索的 query/document 参数 |+| `embedding.*.version` | 创建期 | string,可选 | 模型版本 |+| `embedding.*.credentials` | 动态 | 非空 array,整体替换 | Account provider/failover binding |+| `embedding.*.failback_timeout_seconds` | 动态 | number,`> 0` | 回切主 credential 前的等待秒数 |+| `embedding.*.failback_request_count` | 动态 | integer,`>= 1` | 使用备用 credential 后尝试回切的请求数 |++`embedding.*.credentials` 是有序数组,数组首项优先;失败时按数组顺序尝试后续+credential。每个元素的 schema 如下:++| 字段 | 类型和约束 | 含义 |+| --- | --- | --- |+| `id` | string,可选 | credential 稳定标识;未设置时运行时生成按数组下标命名的标识 |+| `provider` | string,必填 | 小写 provider 名:`openai`、`azure`、`volcengine`、`vikingdb`、`jina`、`ollama`、`gemini`、`voyage`、`dashscope`、`minimax`、`cohere`、`litellm` 或 `local` |+| `model` | 非空 string,可选 | 覆盖该 mode 的外层 `model`;未设置时使用外层 `model`,常用于 endpoint/deployment ID |+| `api_key` | string,可选 | API Key。具体 provider 是否必填见下表 |+| `api_base` | string,可选 | OpenAI-compatible 或 Azure endpoint |+| `api_version` | string,可选 | Azure 等 API 的版本参数 |+| `ak` | string,可选 | VikingDB Embedding provider 的 Access Key |+| `sk` | string,可选 | VikingDB Embedding provider 的 Secret Key |+| `region` | string,可选 | VikingDB Embedding provider 的区域 |+| `host` | string,可选 | provider endpoint 或路由 host |+| `extra_headers` | `map<string, string>`,可选 | 发往 provider 的附加 HTTP headers |++每个 credential 都必须独立完成 provider 所需的连接与鉴权,不能从 Cluster 或同一数组+的其他 credential 借用字段:++| provider | 必填或可替代字段 | 说明 |+| --- | --- | --- |+| `openai` | `api_key` 或 `api_base` | `api_base` 可用于不要求 API Key 的本地 OpenAI-compatible 服务 |+| `azure` | `api_key` 和 `api_base` | `api_version` 可按 Azure endpoint 要求补充 |+| `volcengine`、`jina`、`gemini`、`voyage`、`dashscope`、`minimax`、`cohere` | `api_key` | 其他连接字段按对应 provider 的调用方式选填 |+| `vikingdb` | `ak`、`sk` 和 `region` | 三项必须同时提供 |+| `ollama`、`litellm`、`local` | 无强制鉴权字段 | 仍必须有外层或 credential `model`;实际 endpoint、环境变量或本地模型要求由对应 provider 处理 |++credential 的 `model` 可以省略并使用该 mode 的外层 `model`。凭据数组一旦提供,不会+拼接 Cluster 的 provider、endpoint、鉴权或 provider-specific 字段。`batch_size`、+`encoding_format`、`extra_body`、`model_path`、`cache_dir`、融合/视频参数、+`allow_metadata_override` 及 credentials 外层 provider/auth 字段均不在 Account API+范围内。++存量 Account 可以更新动态运行参数;但不能借 PATCH 首次创建 model mode,因为 `model`、+`dimension` 和 mode 组合都是创建期契约。`embedding: {}` 合法,表示没有 Account+Embedding 覆盖;作为 PATCH 提交时只会合并,不会清空已有设置。++**Account VectorDB 字段**++`vectordb` 只能作为 Account 创建请求的 `settings.vectordb` 提交,所有字段均为创建期。+未提交时该 Account 使用 Cluster VectorDB;已提交时 Account 连接与鉴权完整替换 Cluster+连接与鉴权,即使 backend 类型相同也不会合并。++| 路径 | 类型和约束 | 含义 |+| --- | --- | --- |+| `vectordb.backend` | 必填:`http`、`volcengine`、`vikingdb` | Account 仅支持远端 backend |+| `vectordb.name` | 非空 string,必填 | collection 名 |+| `vectordb.url` | string;`http` 时必填 | HTTP backend endpoint |+| `vectordb.project` | 非空 string,默认 `default` | project 名;`project_name` 为内部字段名 |+| `vectordb.index_name` | 非空 string,必填 | index 名 |+| `vectordb.distance_metric` | `cosine`、`l2`、`ip`,默认 `cosine` | 距离度量 |+| `vectordb.dimension` | integer,`> 0`,必填 | 必须与有效 Embedding dimension 一致 |+| `vectordb.sparse_weight` | number,`>= 0`,默认 `0` | sparse/hybrid 检索权重 |++VectorDB 子对象也全部为创建期字段:++| 路径 | 类型和约束 | 含义 |+| --- | --- | --- |+| `vectordb.volcengine.ak` | string,可选 | AK/SK 鉴权模式的 Access Key;该模式必填 |+| `vectordb.volcengine.sk` | string,可选 | AK/SK 鉴权模式的 Secret Key;该模式必填 |+| `vectordb.volcengine.api_key` | string,可选 | Data API Key 鉴权模式;设置后不再要求 AK/SK |+| `vectordb.volcengine.session_token` | string,可选 | AK/SK 模式可选的 STS 临时凭据 token |+| `vectordb.volcengine.region` | string,可选 | AK/SK 模式必填;API Key 模式与 `host` 至少提供一个 |+| `vectordb.volcengine.host` | string,可选 | API Key 模式的数据面 endpoint;API Key 模式与 `region` 至少提供一个 |+| `vectordb.vikingdb.host` | 非空 string;`vikingdb` 时必填 | 私有部署 VikingDB endpoint |+| `vectordb.vikingdb.headers` | `map<string, string>`,可选 | 私有部署请求 headers;map key 为 header 名,value 为 header 值 |++不支持 Account `local`、`cuvs`、`path`、cuVS 调优或 `custom_params`。远端 collection、+index、schema 和授权由外部控制面预先创建;接口只做本地配置与 Embedding/VectorDB 联合+校验,不探测远端资源。配置有效后,查询、导入、队列写入、Reindex 和 OVPack 都按目标+Account 路由,ROOT 代表某个 Account 执行业务时也遵守这一规则。++每次 Embedding 创建或更新都会校验有效 Embedding/VectorDB pair,包括向量维度、输出+模式、稀疏权重、distance metric、provider 配置与鉴权完整性。校验失败不会发布新配置;+运行时连接、鉴权、collection/index 不存在或 schema 漂移只会使当前 Account 操作失败,+不会回退到其他 Account 或 Cluster VectorDB。凭据或 endpoint 动态更新仅影响后续调用,+在途调用会完成;系统不会自动迁移或重建历史向量,调用方必须保证模型语义兼容。+### user_settingsROOT 可管理任意 User,ADMIN 仅可管理所属 account 内的 User。User 配置接口当前@@ -451,10 +753,13 @@ User override 并重新继承上述默认值,请 PATCH `{"memory_policy": null| admin_user_id | str | 是 | - | 首个管理员用户 ID || seed | str | 否 | `null` | 可选的确定性 API Key seed。传入后,key secret 为 `sha256(user_id + "\0" + seed)` || user_config | object | 否 | `null` | 首个管理员用户的初始配置。支持 `add_targets.resource_uri`、`add_targets.skill_uri` 和 `memory_policy` |+| settings | object | 否 | `null` | Account 运行时初始配置。仅 ROOT 可提交;支持 `feishu`、`github`、`acl`、`agent_evolution`、`vlm`、`query_planner`、`embedding` 和 `vectordb`。其中 `vectordb` 及 Embedding 创建期字段只能在这里设置 |**说明:**- 在 `trusted` 模式下,响应中不会包含 `user_key` 字段- 省略 `seed` 时使用默认随机 API Key。seed 应视为密钥材料;过短的 seed 会让 key 更容易被猜测。+- `settings` 在账号和目录创建前完成结构与有效 Embedding/VectorDB 联合校验。校验失败不会留下 Account、用户或配置文件。+- Account `vlm`、`query_planner`、`embedding` 和 `vectordb` 是 ROOT-only 配置;字段 schema、生命周期和校验见上文 [Account Configuration 接口参考](#account-configuration-接口参考)。当前 Python SDK、CLI 及其他 SDK 的创建账号封装尚未暴露 `settings` 参数,使用此能力请直接调用 HTTP API。- 不再支持 account 级 namespace 隔离配置。用户记忆使用 user-scoped namespace,一对多外部参与者通过 `peer_id` 表达。- `user_config.add_targets.resource_uri` 必须是可写资源目录 URI:`viking://resources` 或 `viking://resources/...`、`viking://~/resources` 或 `viking://~/resources/...`、`viking://user/{user_id}/resources` 或 `viking://user/{user_id}/resources/...`、`viking://user/{user_id}/peers/{peer_id}/resources` 或 `viking://user/{user_id}/peers/{peer_id}/resources/...`。- `user_config.add_targets.skill_uri` 只能是 `viking://~/skills` 或 `viking://agent/skills`。v1 不支持显式写成 `viking://user/{user_id}/skills`。@@ -479,6 +784,39 @@ curl -X POST http://localhost:1933/api/v1/admin/accounts \}'```+创建独立 Embedding 与 VectorDB 的 Account:++```bash+curl -X POST http://localhost:1933/api/v1/admin/accounts \+ -H "Content-Type: application/json" \+ -H "X-API-Key: <root-key>" \+ -d '{+ "account_id": "acme-isolated",+ "admin_user_id": "alice",+ "settings": {+ "embedding": {+ "dense": {+ "model": "text-embedding-3-large",+ "dimension": 3072,+ "credentials": [{+ "provider": "openai",+ "api_key": "<embedding-api-key>"+ }]+ }+ },+ "vectordb": {+ "backend": "vikingdb",+ "name": "acme_context",+ "index_name": "default",+ "dimension": 3072,+ "vikingdb": {+ "host": "https://vikingdb.example"+ }+ }+ }+ }'+```+`trusted` 模式示例:```bashdiff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex d70df743d..bd4702d9e 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -11,6 +11,24 @@ openviking-server doctor`openviking-server init` 会分别引导你填写 Embedding 和 VLM 的配置。对于 `OpenAI`、`Volcengine`、`Kimi`、`GLM` 这类 API 型 VLM,按提示填写对应的 VLM API Key;如果要使用 Codex 作为 VLM,请选择 `OpenAI Codex`,向导会自动帮你处理已有 Codex 鉴权的导入,或直接引导你完成登录。+## Account Embedding 与 VectorDB++ROOT 可在创建 Account 时配置 `settings.embedding` 和 `settings.vectordb`,+两者使用 Account 专用白名单模型。Account 与 Cluster 配置分别保存,向量业务+resolver 为 Account 未设置的值应用 Cluster 默认。Provider 连接只能通过完整+`credentials` binding 提交,不能跨 Account/Cluster 拼接。配置查询只返回+Account 配置。++VectorDB 创建后不可修改。新旧 Account 均可轮换完整 Embedding+credentials/deployment binding,并更新重试、并发、failback 和熔断参数;+外层 model 身份及其他向量空间字段仅创建时可设。兼容 endpoint 更新不打断+在途调用,也不会自动重建历史向量。++Account 独立配置的 VectorDB 仅支持远端 backend;Account 不能选择 local/cuvs,+也不能设置本地路径、cuVS 调优或自定义 adapter 参数。未设置 VectorDB 的+Account 复用 Cluster 连接并保留数据过滤。远端资源由外部控制面提前创建。权限与 PATCH 规则见+[Admin 配置 API](../api/08-admin.md#runtime-configuration)。+## 快速开始在用户配置目录 `~/.openviking/` 下创建 `ov.conf`:@@ -53,17 +71,38 @@ openviking-server doctorOpenViking 的配置分为两个层级:- **启动配置**从 `ov.conf` 读取,用于定义进程基线和运行时配置源。修改后需要重启服务;运行时配置接口不会改写 `ov.conf`。-- **运行时覆盖配置**由配置源持久化保存,可以通过 Admin API 在 Cluster 或 Account 层修改。+- **运行时配置**由配置源按 Cluster 和 Account 作用域分别持久化,可以通过 Admin API 修改。只有显式声明为运行时字段的配置,才会暴露在运行时配置 API 中。当前可修改范围如下:| 范围 | 配置 | 生命周期 | 生效说明 || --- | --- | --- | --- || Cluster | `agent_evolution` | 动态配置 | ROOT 可通过 Admin API 修改,作为集群默认值使用。 |-| Account | `feishu`、`agent_evolution` | 动态配置 | ROOT 或该 Account 的 ADMIN 可修改。Agent Evolution 整段回落到 Cluster 配置。Account 未设置 Feishu 时也整段使用 Cluster 配置;一旦设置,则仅 `domain` 来自 Cluster,省略的 Account 字段使用 Feishu 默认值。两者都已通过运行时管理器接入业务读取。 |-| Account | `github`、`acl` | 动态配置 | ROOT 或该 Account 的 ADMIN 可修改;没有 Cluster fallback。 |--Cluster 的 `embedding`、`vlm`、`query_planner`、`memory`、`feishu`、存储、解析器、检索等普通配置仍然是启动配置。Account 的 `vlm`、`memory`、`embedding` 和 `vectordb` 不在当前 Account 配置 API 范围内,包含这些字段的请求会被拒绝。+| Account | `feishu`、`agent_evolution` | 动态配置 | ROOT 或该 Account 的 ADMIN 可修改。Agent Evolution 为兼容旧行为保留已废弃的 Cluster 整段回退。Feishu 默认值由业务解析器处理:Account 未设置时使用 Cluster;设置后仅 `domain` 来自 Cluster。 |+| Account | `github`、`acl` | 动态配置 | ROOT 或该 Account 的 ADMIN 可修改;不回退到 Cluster。 |+| Account | `vlm`、`query_planner` | 动态配置 | 仅 ROOT 可读写。每段已配置的模型配置都必须包含 `model` 和非空 `credentials` 数组,`timeout` 可选;ADMIN 无法读取或修改这两段配置。 |+| Account | `embedding` | 部分动态 | 仅 ROOT 可读写。凭证、重试、并发、故障回切和熔断参数可动态修改;模型身份、向量空间字段、文本来源和输入 token 上限仅能在创建时设置。 |+| Account | `vectordb` | 仅创建时配置 | 仅 ROOT 可在 Account 创建请求的 `settings` 中设置,后续新增、修改和重置均被拒绝。Account 专属连接仅支持 `http`、`volcengine`、`vikingdb` 远端后端。 |++Cluster 的 `embedding`、`vlm`、`query_planner`、`memory`、`feishu`、存储、解析器、检索等普通配置仍然是启动配置。Account 的 `memory` 不在当前 Account 配置 API 范围内。++Account 与 Cluster 配置分别存储和发布。Account 未配置时是否使用 Cluster+属于业务默认行为,不是配置框架中的隐式继承。VLM 业务解析器负责这项策略:+Account 未配置 VLM 时使用 Cluster VLM;Account 已配置时,模型服务身份来自+Account,并按 VLM 业务规则组合部分 Cluster 运行参数。Account 设置 `timeout`+时覆盖 Cluster 的值,未设置或重置后使用 Cluster 的值。Query Planner 的选择顺序为+Account `query_planner`、Account `vlm`、Cluster `query_planner`、Cluster `vlm`。++向量配置解析器会联合校验有效的 Embedding 和 VectorDB 配置。Account+`embedding: {}` 是合法配置;未声明 Account 模型模式时使用 Cluster 模型绑定。+Account 凭证和显式 VectorDB 连接必须独立提供连接与鉴权字段。远端集合、索引和+访问授权需要由外部预先创建。修改 embedding 凭证不会迁移历史向量,调用方需要+保证模型兼容。++处理 Account 业务的代码必须通过 `VLMResolver` 解析模型配置,并把得到的+`VLMConfig` 显式传给下层函数。`ClusterVLMResolver` 仅限启动、诊断和离线评测+等依赖组装入口使用。CI 架构测试会拒绝其他生产模块新增对 Cluster VLM+或 Query Planner 配置的直接读取。修改运行时配置使用以下接口:@@ -75,7 +114,7 @@ GET /api/v1/admin/accounts/{account_id}/configurationPATCH /api/v1/admin/accounts/{account_id}/configuration```-请求体使用 `settings` 包装稀疏补丁:+请求体使用 `settings` 包装 PATCH 文档:```json{@@ -87,7 +126,11 @@ PATCH /api/v1/admin/accounts/{account_id}/configuration}```-PATCH 采用三态语义:字段缺失表示不修改,具体值表示设置或替换,`null` 表示删除当前层的覆盖。对象递归合并,数组整体替换。响应返回目标层的显式值,不返回继承值或最终生效值。权限、校验、fallback 和兼容接口详见 [Admin API - 运行时配置](../api/08-admin.md#runtime-configuration);实现设计见 [运行时配置设计](../../design/runtime-configuration-design.md)。+PATCH 采用三态语义:字段缺失表示不修改,具体值表示设置或替换,`null`+表示从当前作用域删除该值。对象递归合并,数组整体替换。响应只返回该作用域+的配置,不返回业务组合后的有效配置。声明式 `fallback` 已废弃,只支持整段+配置,且仅用于兼容旧行为;新功能需要在业务解析器中实现 Cluster 默认值。+详见 [Admin API - 运行时配置](../api/08-admin.md#runtime-configuration)。## 配置示例diff --git a/openviking/config/__init__.py b/openviking/config/__init__.pyindex 703db6882..729ee3f3a 100644--- a/openviking/config/__init__.py+++ b/openviking/config/__init__.py@@ -7,14 +7,16 @@ from configuration *merge/publish/invalidation* (:class:`RuntimeConfigManager`).Cluster and account are two independent Pydantic models: cluster fields live on``OpenVikingConfig`` and account fields on :class:`AccountConfig`. A field's-scope is decided by which model declares it. Account reads go through-``RuntimeConfigManager.get_account(account_id, field)``, which loads on demand-and resolves the field's declared cluster fallback.+scope is decided by which model declares it. Business code should resolve+defaults from the independently published models. The manager's declarative+whole-section fallback remains only for compatibility with existing fields."""from openviking.config.account_config import AccountConfigfrom openviking.config.assembly import build_config_source, resolve_config_source_settingsfrom openviking.config.manager import (+ AccountCandidateContext,+ AccountCandidateValidator,ConfigChangeConsumer,ConfigChangeEvent,ConfigChangeReason,@@ -36,6 +38,8 @@ from openviking_cli.utils.config.open_viking_config import RuntimeConfigSettings__all__ = ["AccountConfig",+ "AccountCandidateContext",+ "AccountCandidateValidator","ConfigChangeConsumer","ConfigChangeEvent","ConfigChangeReason",diff --git a/openviking/config/account_config.py b/openviking/config/account_config.pyindex 548bc9ed2..8a172927a 100644--- a/openviking/config/account_config.py+++ b/openviking/config/account_config.py@@ -2,21 +2,33 @@# SPDX-License-Identifier: AGPL-3.0"""Account-scoped runtime configuration model.-``AccountConfig`` declares account overrides; ``OpenVikingConfig`` declares-cluster configuration. ``RuntimeField`` specifies write permissions and optional-cluster fallback. The manager resolves fallback for a whole unset section,-without merging cluster values into an explicitly configured account section.+``AccountConfig`` contains Account-owned configuration; ``OpenVikingConfig``+contains Cluster-owned configuration. They are independent models.++Some existing fields still declare the deprecated ``RuntimeField.fallback``+compatibility behavior. It can only select a complete Cluster section when the+Account section is absent. New defaults and any field-level composition belong+in business resolvers, not in this model or the generic configuration manager.++Runtime Cluster fallback also remains necessary for Account documents created+before complete settings were materialized. It is a migration constraint, not+the target model for new configuration. New provisioning flows should copy+Cluster defaults into a complete Account-owned configuration at creation time;+later Cluster changes must not alter that Account implicitly."""from __future__ import annotations-from typing import Optional+from typing import ClassVar, List, Optional-from pydantic import BaseModel+from pydantic import BaseModel, model_validator+from openviking.config.account_vector import AccountEmbeddingConfig, AccountVectorDBConfig+from openviking.models.vlm.registry import is_valid_providerfrom openviking_cli.utils.config.agent_evolution_config import AgentEvolutionConfigfrom openviking_cli.utils.config.github_config import GitHubConfigfrom openviking_cli.utils.config.runtime_field import RuntimeField+from openviking_cli.utils.config.vlm_config import VLMConfig, VLMCredentialclass AccountAclSettings(BaseModel):@@ -26,7 +38,7 @@ class AccountAclSettings(BaseModel):class AccountFeishuConfig(BaseModel):- """Sparse account-level Feishu overrides.+ """Account-level Feishu settings.``domain`` intentionally does not exist here. It is a cluster deploymentsetting and is selected from the cluster configuration by the business@@ -41,16 +53,93 @@ class AccountFeishuConfig(BaseModel):request_timeout: Optional[float] = RuntimeField(default=None, gt=0)-class AccountConfig(BaseModel):- """Sparse per-account override model.+class AccountVLMConfig(BaseModel):+ """Account-owned VLM settings consumed by the VLM business resolver.- Every field is ``Optional`` and defaults to ``None`` (= "account did not- override this"). ``fallback`` fields resolve to the named cluster field when- unset.+ ``to_vlm_config`` explicitly composes selected Cluster runtime behavior+ with Account-owned model-service identity. This is a VLM rule, not generic+ configuration inheritance. New endpoint or credential fields must be added+ to the exclusion set when they are introduced.+ """++ _ACCOUNT_OWNED_MODEL_SERVICE_FIELDS: ClassVar[frozenset[str]] = frozenset(+ {+ "backup",+ "model",+ "api_key",+ "forward_api_key",+ "api_base",+ "provider",+ "backend",+ "providers",+ "default_provider",+ "api_version",+ "extra_headers",+ "extra_request_body",+ "credentials",+ }+ )++ model: str = RuntimeField(min_length=1)+ credentials: List[VLMCredential] = RuntimeField(min_length=1)+ timeout: Optional[float] = RuntimeField(default=None, gt=0)++ def to_vlm_config(self, cluster_vlm: Optional[VLMConfig] = None) -> VLMConfig:+ """Build an isolated VLM config with Cluster-owned runtime behavior."""+ values = {}+ if cluster_vlm is not None:+ values.update(+ cluster_vlm.model_dump(+ mode="python",+ exclude=self._ACCOUNT_OWNED_MODEL_SERVICE_FIELDS,+ )+ )+ values.update(self.model_dump(mode="python", exclude_none=True))+ return VLMConfig.model_validate(values)++ @model_validator(mode="after")+ def validate_model_service(self) -> "AccountVLMConfig":+ """Reject incomplete credentials without consulting Cluster config."""+ if not self.model.strip():+ raise ValueError("model is required for Account VLM")+ for index, credential in enumerate(self.credentials):+ provider = credential.provider.strip().lower() if credential.provider else ""+ if not provider:+ raise ValueError(+ f"credentials[{index}].provider is required for Account VLM"+ )+ if not is_valid_provider(provider):+ raise ValueError(+ f"credentials[{index}].provider '{credential.provider}' is not supported"+ )+ credential.provider = provider+ for field_name in ("model", "api_key", "api_base", "api_version"):+ value = getattr(credential, field_name)+ if value is not None and not value.strip():+ raise ValueError(+ f"credentials[{index}].{field_name} must not be blank"+ )+ self.to_vlm_config()+ return self+++class AccountConfig(BaseModel):+ """Configuration owned by one Account.++ Optional sections are simply not configured for that Account. When a+ section is present, its Pydantic model validates the smallest Account-owned+ configuration needed for that section; business resolvers may use Cluster+ configuration only when the corresponding Account section is absent.+ The few ``fallback`` declarations below are legacy whole-section+ compatibility behavior and should not be copied to new fields. New Account+ creation should materialize defaults instead of introducing new runtime+ dependencies on Cluster configuration."""# Account-level settings with active business consumers.feishu: Optional[AccountFeishuConfig] = RuntimeField(default=None)+ vlm: Optional[AccountVLMConfig] = RuntimeField(default=None)+ query_planner: Optional[AccountVLMConfig] = RuntimeField(default=None)github: Optional[GitHubConfig] = RuntimeField(default=None)agent_evolution: Optional[AgentEvolutionConfig] = RuntimeField(default=None,@@ -58,7 +147,11 @@ class AccountConfig(BaseModel):)acl: Optional[AccountAclSettings] = RuntimeField(default=None)- # Deferred account-level sections (vlm, memory, embedding, vectordb)- # have no active consumers. Ignore historical or newer persisted sections;- # validate_patch() still keeps API writes limited to the fields above.+ embedding: Optional[AccountEmbeddingConfig] = RuntimeField(default=None)+ vectordb: Optional[AccountVectorDBConfig] = RuntimeField(+ default=None,+ dynamic=False,+ )++ # Ignore sections persisted by newer binaries; API writes are still gated.model_config = {"arbitrary_types_allowed": True, "extra": "ignore"}diff --git a/openviking/config/account_vector.py b/openviking/config/account_vector.pynew file mode 100644index 000000000..9e1e460c5--- /dev/null+++ b/openviking/config/account_vector.py@@ -0,0 +1,188 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Account-owned vector configuration exposed by the runtime configuration API."""++from __future__ import annotations++from typing import Dict, List, Literal, Optional++from pydantic import BaseModel, model_validator++from openviking_cli.utils.config.runtime_field import RuntimeField+++class AccountEmbeddingCredential(BaseModel):+ """One Account-owned provider binding; credential arrays replace as a unit."""++ id: Optional[str] = RuntimeField(default=None)+ provider: str = RuntimeField(min_length=1)+ model: Optional[str] = RuntimeField(default=None, min_length=1)+ api_key: Optional[str] = RuntimeField(default=None)+ api_base: Optional[str] = RuntimeField(default=None)+ api_version: Optional[str] = RuntimeField(default=None)+ ak: Optional[str] = RuntimeField(default=None)+ sk: Optional[str] = RuntimeField(default=None)+ region: Optional[str] = RuntimeField(default=None)+ host: Optional[str] = RuntimeField(default=None)+ extra_headers: Optional[Dict[str, str]] = RuntimeField(default=None)+++class AccountEmbeddingModelConfig(BaseModel):+ """Account-selectable embedding deployment and immutable vector contract."""++ # True model identity and vector-space fields are fixed at Account creation.+ model: str = RuntimeField(dynamic=False, min_length=1)+ dimension: int = RuntimeField(dynamic=False, gt=0)+ input: Optional[Literal["text", "multimodal"]] = RuntimeField(+ default=None,+ dynamic=False,+ )+ query_param: Optional[str] = RuntimeField(default=None, dynamic=False)+ document_param: Optional[str] = RuntimeField(default=None, dynamic=False)+ version: Optional[str] = RuntimeField(default=None, dynamic=False)++ # Provider bindings may rotate without changing the declared vector space.+ credentials: List[AccountEmbeddingCredential] = RuntimeField(min_length=1)+ failback_timeout_seconds: Optional[float] = RuntimeField(default=None, gt=0)+ failback_request_count: Optional[int] = RuntimeField(default=None, ge=1)++ @model_validator(mode="after")+ def validate_credentials(self) -> "AccountEmbeddingModelConfig":+ """Validate each Account-owned provider binding without Cluster fallback."""+ from openviking_cli.utils.config.embedding_config import EmbeddingModelConfig++ for credential in self.credentials:+ values = {+ "model": credential.model or self.model,+ "dimension": self.dimension,+ "provider": credential.provider,+ "api_key": credential.api_key,+ "api_base": credential.api_base,+ "api_version": credential.api_version,+ "ak": credential.ak,+ "sk": credential.sk,+ "region": credential.region,+ "host": credential.host,+ }+ for field_name in ("input", "query_param", "document_param", "version"):+ value = getattr(self, field_name)+ if value is not None:+ values[field_name] = value+ EmbeddingModelConfig.model_validate(values)+ return self+++class AccountEmbeddingCircuitBreakerConfig(BaseModel):+ failure_threshold: Optional[int] = RuntimeField(default=None, ge=1)+ reset_timeout: Optional[float] = RuntimeField(default=None, gt=0)+ max_reset_timeout: Optional[float] = RuntimeField(default=None, gt=0)++ @model_validator(mode="after")+ def validate_section(self) -> "AccountEmbeddingCircuitBreakerConfig":+ if not self.model_fields_set:+ raise ValueError("circuit_breaker configuration must not be empty")+ return self+++class AccountEmbeddingConfig(BaseModel):+ """Embedding settings an Account may own.++ A section may contain only Account runtime policy, but every declared model+ mode is a complete Account-owned binding. Cluster binding is used only when+ no Account-owned model mode is declared.+ """++ dense: Optional[AccountEmbeddingModelConfig] = RuntimeField(default=None)+ sparse: Optional[AccountEmbeddingModelConfig] = RuntimeField(default=None)+ hybrid: Optional[AccountEmbeddingModelConfig] = RuntimeField(default=None)+ max_concurrent: Optional[int] = RuntimeField(default=None, ge=1)+ max_retries: Optional[int] = RuntimeField(default=None, ge=0)+ circuit_breaker: Optional[AccountEmbeddingCircuitBreakerConfig] = RuntimeField(+ default=None+ )+ text_source: Optional[Literal["content_only", "summary_first"]] = RuntimeField(+ default=None,+ dynamic=False,+ )+ max_input_tokens: Optional[int] = RuntimeField(default=None, dynamic=False, ge=100)++ @model_validator(mode="after")+ def validate_section(self) -> "AccountEmbeddingConfig":+ """Validate mode combinations; an empty section is an explicit no-op override."""+ if self.hybrid is not None and (self.dense is not None or self.sparse is not None):+ raise ValueError("embedding.hybrid cannot be combined with dense or sparse")+ return self+++class AccountVolcengineVectorConfig(BaseModel):+ ak: Optional[str] = RuntimeField(default=None, dynamic=False)+ sk: Optional[str] = RuntimeField(default=None, dynamic=False)+ api_key: Optional[str] = RuntimeField(default=None, dynamic=False)+ session_token: Optional[str] = RuntimeField(default=None, dynamic=False)+ region: Optional[str] = RuntimeField(default=None, dynamic=False)+ host: Optional[str] = RuntimeField(default=None, dynamic=False)+++class AccountVikingDBVectorConfig(BaseModel):+ host: Optional[str] = RuntimeField(default=None, dynamic=False)+ headers: Optional[Dict[str, str]] = RuntimeField(default=None, dynamic=False)+++class AccountVectorDBConfig(BaseModel):+ """Complete create-only Account VectorDB identity and schema contract.++ Local paths, cuVS tuning and custom adapter parameters are intentionally not+ exposed. Account-owned backends are remote only; local/cuvs remain Cluster+ backends.+ """++ backend: Literal["http", "volcengine", "vikingdb"] = RuntimeField(dynamic=False)+ name: str = RuntimeField(dynamic=False, min_length=1)+ url: Optional[str] = RuntimeField(default=None, dynamic=False)+ project_name: str = RuntimeField(+ default="default",+ alias="project",+ dynamic=False,+ min_length=1,+ )+ index_name: str = RuntimeField(dynamic=False, min_length=1)+ distance_metric: Literal["cosine", "l2", "ip"] = RuntimeField(+ default="cosine",+ dynamic=False,+ )+ dimension: int = RuntimeField(dynamic=False, gt=0)+ sparse_weight: float = RuntimeField(default=0.0, dynamic=False, ge=0)+ volcengine: Optional[AccountVolcengineVectorConfig] = RuntimeField(+ default=None,+ dynamic=False,+ )+ vikingdb: Optional[AccountVikingDBVectorConfig] = RuntimeField(+ default=None,+ dynamic=False,+ )++ model_config = {"populate_by_name": True}++ @model_validator(mode="after")+ def validate_connection(self) -> "AccountVectorDBConfig":+ """Require a complete connection block for the selected remote backend."""+ if self.backend == "http" and not self.url:+ raise ValueError("Account HTTP VectorDB requires url")+ if self.backend == "vikingdb":+ if self.vikingdb is None or not self.vikingdb.host:+ raise ValueError("Account VikingDB requires vikingdb.host")+ if self.backend == "volcengine":+ config = self.volcengine+ if config is None:+ raise ValueError("Account Volcengine VectorDB requires volcengine configuration")+ if config.api_key:+ if not (config.host or config.region):+ raise ValueError(+ "Account Volcengine api_key mode requires host or region"+ )+ elif not (config.ak and config.sk and config.region):+ raise ValueError(+ "Account Volcengine VectorDB requires ak, sk and region "+ "when api_key is not configured"+ )+ return selfdiff --git a/openviking/config/binding.py b/openviking/config/binding.pyindex 4f90e70fa..ce88e4662 100644--- a/openviking/config/binding.py+++ b/openviking/config/binding.py@@ -14,11 +14,17 @@ from typing import Optionalfrom openviking.config.account_config import AccountConfigfrom openviking.config.assembly import build_config_source, resolve_config_source_settings-from openviking.config.manager import RuntimeConfigManager+from openviking.config.manager import AccountCandidateValidator, RuntimeConfigManagerfrom openviking.config.merge import apply_three_state_patchfrom openviking.config.source.base import ConfigSourcefrom openviking.config.source.file_source import FileConfigSource-from openviking.config.validate import validate_patch+from openviking.config.validate import (+ filter_runtime_fields,+ validate_patch,+)+from openviking.config.vector import (+ validate_account_vector_candidate,+)from openviking.pyagfs import AsyncAGFSClientfrom openviking_cli.utils.config import get_openviking_config, set_openviking_configfrom openviking_cli.utils.config.config_utils import warn_unknown_config_fields@@ -27,7 +33,7 @@ from openviking_cli.utils.logger import get_loggerlogger = get_logger(__name__)-# The concrete manager type this module hands back.+# The concrete manager type this module hands back; business rules are hooks.OpenVikingRuntimeConfigManager = RuntimeConfigManager[OpenVikingConfig, AccountConfig]@@ -45,14 +51,15 @@ def _build_cluster(old: OpenVikingConfig, override: dict) -> OpenVikingConfig:stored override may contain top-level fields from a newer binary, so thatruntime-only rebuild intentionally ignores those fields."""+ runtime_override = filter_runtime_fields(OpenVikingConfig, override or {})merged = apply_three_state_patch(old.model_dump(by_alias=True, exclude_unset=True),- override or {},+ runtime_override,)return OpenVikingConfig.from_dict(merged)-def _build_account(override: Optional[dict]) -> AccountConfig:+def _build_account(settings: Optional[dict]) -> AccountConfig:"""Construct (and thereby validate) an account config from its sparse override.A persisted account override may carry fields this binary does not declare --@@ -60,14 +67,18 @@ def _build_account(override: Optional[dict]) -> AccountConfig:stay ignored so legacy settings keep loading, and the warning keeps the dropvisible. Only field names are logged, never values."""- sparse = override or {}+ sparse = settings or {}warn_unknown_config_fields(data=sparse, model=AccountConfig, logger=logger)- return AccountConfig.model_validate(sparse)+ return AccountConfig.model_validate(filter_runtime_fields(AccountConfig, settings))def _validate_request(patch: dict, is_account: bool, creating: bool) -> None:"""Structural gate: which model's RuntimeField surface a patch may touch."""model = AccountConfig if is_account else OpenVikingConfig+ if is_account and isinstance(patch, dict) and isinstance(patch.get("vectordb"), dict):+ patch = {**patch, "vectordb": dict(patch["vectordb"])}+ if "project" in patch["vectordb"]:+ patch["vectordb"]["project_name"] = patch["vectordb"].pop("project")validate_patch(model, patch, creating=creating)@@ -104,7 +115,7 @@ def manager_over_source(``base_config`` is captured from the current singleton at construction time."""base = base_config or get_openviking_config()- return RuntimeConfigManager(+ return OpenVikingRuntimeConfigManager(source,base_config=base,get_config=get_openviking_config,@@ -112,4 +123,10 @@ def manager_over_source(build_config=_build_cluster,build_account=_build_account,validate_request=_validate_request,+ account_candidate_validators=[+ AccountCandidateValidator(+ sections=frozenset({"embedding", "vectordb"}),+ validate=validate_account_vector_candidate,+ )+ ],)diff --git a/openviking/config/embedding.py b/openviking/config/embedding.pynew file mode 100644index 000000000..acc5dad2b--- /dev/null+++ b/openviking/config/embedding.py@@ -0,0 +1,301 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Account embedding resources with call-scoped borrowing and safe retirement."""++from __future__ import annotations++import asyncio+import hashlib+import threading+from dataclasses import dataclass, field++from openviking.concurrency import AsyncSemaphore+from openviking.config.scope import ScopeKind+from openviking.config.vector import AccountVectorConfigResolver, VectorRuntimeSettings+from openviking.models.embedder.base import EmbedderBase+from openviking.models.vlm.token_usage import TokenUsageTracker+from openviking.service.task_tracker_concurrency import KeyedAsyncLockPool+from openviking.utils.circuit_breaker import CircuitBreaker, CircuitBreakerOpen+from openviking.utils.model_retry import (+ ERROR_CLASS_AUTH,+ ERROR_CLASS_INPUT_TOO_LARGE,+ classify_api_error,+)+from openviking_cli.utils.logger import get_logger++logger = get_logger(__name__)++@dataclass(frozen=True)+class EmbeddingResourceStatus:+ """Read-only Account embedding state."""++ fingerprint: str+ dimension: int+ borrowers: int+ retired: bool+ closed: bool+++@dataclass(eq=False)+class _EmbeddingResource:+ fingerprint: str+ settings: VectorRuntimeSettings+ embedder: EmbedderBase+ breaker: CircuitBreaker+ borrowers: int = 0+ retired: bool = False+ closed: bool = False+ lock: threading.Lock = field(default_factory=threading.Lock, repr=False)++ def try_borrow(self) -> bool:+ with self.lock:+ if self.retired or self.closed:+ return False+ self.borrowers += 1+ return True++ def release(self) -> None:+ close = False+ with self.lock:+ self.borrowers -= 1+ if self.retired and not self.borrowers and not self.closed:+ self.closed = True+ close = True+ if close:+ self._close_embedder()++ def retire(self) -> None:+ close = False+ with self.lock:+ self.retired = True+ if not self.borrowers and not self.closed:+ self.closed = True+ close = True+ if close:+ self._close_embedder()++ def _close_embedder(self) -> None:+ try:+ self.embedder.close()+ except Exception:+ # Retirement must remain terminal even if a provider's best-effort+ # close path fails; otherwise AccountEmbeddingProvider.close() can+ # wait forever for this resource to leave _retired.+ logger.warning(+ "Failed to close retired embedding resource %s",+ self.fingerprint,+ exc_info=True,+ )++ def status(self) -> EmbeddingResourceStatus:+ with self.lock:+ return EmbeddingResourceStatus(+ fingerprint=self.fingerprint,+ dimension=self.settings.vectordb.dimension,+ borrowers=self.borrowers,+ retired=self.retired,+ closed=self.closed,+ )+++def _bind_account_state(+ embedder: EmbedderBase,+ semaphore: AsyncSemaphore,+ tracker: TokenUsageTracker,+ account_id: str,+) -> None:+ """Share isolation state only among clients owned by this Account."""+ embedder._account_semaphore = semaphore+ embedder._token_tracker = tracker+ embedder._account_id = account_id+ children = list(getattr(embedder, "_embedders", []))+ for name in ("dense_embedder", "sparse_embedder"):+ child = getattr(embedder, name, None)+ if child is not None:+ children.append(child)+ for child in children:+ _bind_account_state(child, semaphore, tracker, account_id)+++class AccountEmbeddingProvider:+ """Resolve, cache, execute and retire Account embedding resources."""++ def __init__(self, resolver: AccountVectorConfigResolver, config_events):+ self._resolver = resolver+ self._cache: dict[str, _EmbeddingResource] = {}+ self._retired: set[_EmbeddingResource] = set()+ self._account_locks = KeyedAsyncLockPool[str]()+ self._usage: dict[str, TokenUsageTracker] = {}+ self._lock = threading.RLock()+ self._closed = False+ config_events.add_update_consumer(+ scope=ScopeKind.ACCOUNT,+ sections={"embedding"},+ consumer=self._on_change,+ )++ async def _on_change(self, event) -> None:+ if event.scope.key:+ await self.invalidate(event.scope.key)++ async def invalidate(self, account_id: str) -> None:+ async with self._account_locks.acquire(account_id):+ with self._lock:+ resource = self._cache.pop(account_id, None)+ if resource is not None:+ self._retire(resource)++ def _retire(self, resource: _EmbeddingResource) -> None:+ with self._lock:+ self._retired.add(resource)+ resource.retire()+ if resource.status().closed:+ with self._lock:+ self._retired.discard(resource)++ async def get_status(self, account_id: str) -> EmbeddingResourceStatus:+ return (await self._resource_for(account_id)).status()++ async def _resource_for(self, account_id: str) -> _EmbeddingResource:+ if not account_id:+ raise ValueError("account_id is required")+ async with self._account_locks.acquire(account_id):+ with self._lock:+ if self._closed:+ raise RuntimeError("Account embedding provider is closed")++ settings = await self._resolver.resolve(account_id)+ fingerprint = hashlib.sha256(+ settings.embedding.model_dump_json().encode()+ ).hexdigest()+ with self._lock:+ if self._closed:+ raise RuntimeError("Account embedding provider is closed")+ cached = self._cache.get(account_id)+ if cached is not None and cached.fingerprint == fingerprint:+ return cached++ config = settings.embedding+ embedder = config.get_embedder()+ with self._lock:+ tracker = self._usage.setdefault(account_id, TokenUsageTracker())+ _bind_account_state(+ embedder,+ AsyncSemaphore(config.max_concurrent),+ tracker,+ account_id,+ )+ resource = _EmbeddingResource(+ fingerprint=fingerprint,+ settings=settings,+ embedder=embedder,+ breaker=CircuitBreaker(**config.circuit_breaker.model_dump()),+ )+ with self._lock:+ if self._closed:+ resource.retire()+ raise RuntimeError("Account embedding provider is closed")+ previous = self._cache.get(account_id)+ self._cache[account_id] = resource+ if previous is not None:+ self._retire(previous)+ return resource++ async def _borrow(self, account_id: str) -> _EmbeddingResource:+ while True:+ resource = await self._resource_for(account_id)+ if resource.try_borrow():+ return resource++ def bind(self, account_id: str) -> AccountBoundEmbedder:+ if not account_id:+ raise ValueError("account_id is required")+ return AccountBoundEmbedder(self, account_id)++ async def query_cache_key(self, account_id: str, content) -> tuple[str, str, str]:+ """Describe a query input without borrowing the account resource."""+ resource = await self._resource_for(account_id)+ prepared = resource.embedder.prepare_embedding_input(content)+ return account_id, resource.fingerprint, repr(prepared)++ async def embed(self, account_id: str, content, *, is_query: bool = False):+ resource = await self._borrow(account_id)+ try:+ prepared = resource.embedder.prepare_embedding_input(content)+ return await self._execute(resource, prepared, is_query)+ finally:+ resource.release()+ self._discard_retired(resource)++ def _discard_retired(self, resource: _EmbeddingResource) -> None:+ if resource.status().closed:+ with self._lock:+ self._retired.discard(resource)++ async def _execute(self, resource, content, is_query):+ from openviking.telemetry import bind_telemetry_stage++ try:+ resource.breaker.check()+ except CircuitBreakerOpen as exc:+ exc.retry_after = resource.breaker.retry_after+ raise+ try:+ with bind_telemetry_stage("embed_query" if is_query else "embed_resource"):+ result = await resource.embedder.embed_async(content, is_query=is_query)+ if result.dense_vector is not None:+ expected = resource.settings.vectordb.dimension+ if len(result.dense_vector) != expected:+ raise ValueError(+ f"Dense vector dimension mismatch: expected {expected}, "+ f"got {len(result.dense_vector)}"+ )+ except Exception as exc:+ if classify_api_error(exc) not in {ERROR_CLASS_AUTH, ERROR_CLASS_INPUT_TOO_LARGE}:+ resource.breaker.record_failure(exc)+ raise+ resource.breaker.record_success()+ return result++ def get_token_usage(self, account_id: str):+ with self._lock:+ tracker = self._usage.get(account_id, TokenUsageTracker())+ return tracker.to_dict()++ def get_total_token_usage(self):+ with self._lock:+ trackers = tuple(self._usage.values())+ return TokenUsageTracker.merge(*trackers).to_dict()++ async def close(self) -> None:+ with self._lock:+ self._closed = True+ resources = set(self._cache.values())+ self._cache.clear()+ for resource in resources:+ self._retire(resource)+ while True:+ with self._lock:+ if not self._retired:+ return+ await asyncio.sleep(0.01)+++class AccountBoundEmbedder:+ """Long-lived Account proxy that resolves the current resource per call."""++ def __init__(self, provider: AccountEmbeddingProvider, account_id: str):+ self.provider = provider+ self.account_id = account_id++ async def embed_compatible(self, content, *, is_query=False):+ return await self.provider.embed(self.account_id, content, is_query=is_query)++ async def query_embedding_cache_key(self, content):+ return await self.provider.query_cache_key(self.account_id, content)++ async def embed_async(self, content, is_query=False):+ return await self.embed_compatible(content, is_query=is_query)++ def get_token_usage(self):+ return self.provider.get_token_usage(self.account_id)diff --git a/openviking/config/manager.py b/openviking/config/manager.pyindex 22f47a41c..023f70569 100644--- a/openviking/config/manager.py+++ b/openviking/config/manager.py@@ -13,9 +13,10 @@ Two scopes are managed side by side, mirroring the two independent config models- **cluster** — a single process-wide config object, bridged through the``get_config`` / ``set_config`` / ``build_config`` hooks so the manager staysagnostic to the concrete cluster model.-- **account** — a per-account cache of ``(sparse override, constructed account- config, last-access time)``. ``get_account(account_id, field)`` loads the- account on demand and resolves the field's declared cluster fallback.+- **account** — a per-account cache of the constructed Account configuration+ and its last-access time. Account and Cluster configurations remain distinct.+ ``get_account(account_id, field)`` returns the Account value, except for the+ deprecated whole-section fallback retained for existing fields.Both models are built and validated by caller-supplied hooks, so the managerimports neither ``OpenVikingConfig`` nor ``AccountConfig`` directly.@@ -24,16 +25,17 @@ imports neither ``OpenVikingConfig`` nor ``AccountConfig`` directly.from __future__ import annotationsimport asyncio+import threadingimport time-import weakref+from concurrent.futures import Future as ConcurrentFuturefrom dataclasses import dataclassfrom enum import Enum-from typing import Any, Awaitable, Callable, Generic, Optional, TypeVar+from typing import Any, Awaitable, Callable, Generic, Iterable, Optional, TypeVarfrom openviking.config.merge import apply_three_state_patch, diff_sectionsfrom openviking.config.scope import ConfigScope, ScopeKindfrom openviking.config.source.base import ConfigSource-from openviking.service.task_tracker_concurrency import OwnerLoopDispatcher, run_to_completion+from openviking.service.task_tracker_concurrency import KeyedAsyncLockPool, run_to_completionfrom openviking_cli.utils.config.runtime_field import fallback_of, resolve_fallbackfrom openviking_cli.utils.logger import get_logger@@ -43,14 +45,16 @@ logger = get_logger(__name__)C = TypeVar("C")A = TypeVar("A")T = TypeVar("T")+_NO_OLD_SETTINGS = object()@dataclass(frozen=True)class AccountConfigView(Generic[C, A]):- """Resolve fields against a captured account/cluster publication pair.+ """Expose one atomically captured Account/Cluster publication pair.Used only by synchronous selectors, never as a request context. Returned- models are shared, read-only configuration values.+ models are shared, read-only configuration values. Business resolvers should+ combine them explicitly instead of adding generic framework fallback rules."""_account: A@@ -58,7 +62,7 @@ class AccountConfigView(Generic[C, A]):@propertydef account(self) -> A:- """Return the captured sparse account configuration."""+ """Return the captured Account configuration."""return self._account@property@@ -67,6 +71,11 @@ class AccountConfigView(Generic[C, A]):return self._clusterdef get(self, field: str) -> Any:+ """Return an Account field with legacy whole-section fallback.++ This compatibility API never merges nested values. New business+ resolvers should read ``account`` and ``cluster`` explicitly.+ """fields = getattr(type(self._account), "model_fields", {})if field not in fields:raise AttributeError(field)@@ -76,6 +85,37 @@ class AccountConfigView(Generic[C, A]):target = fallback_of(fields[field])return resolve_fallback(self._cluster, target) if target is not None else None++@dataclass(frozen=True)+class AccountCandidateContext(Generic[C, A]):+ """Read-only inputs for synchronous, side-effect-free domain validation.++ ``old_view`` is supplied only for an update PATCH, built from the latest+ document passed to the source's mutation callback (including absent settings+ on an existing Account). Both views share one captured Cluster publication.+ Creation, initial loading and refresh validate only the candidate; loading a+ persisted document is not a local update request. ``changed_sections`` names+ PATCH keys, or is ``None`` when all validators must run.+ """++ new_view: AccountConfigView[C, A]+ old_view: Optional[AccountConfigView[C, A]]+ changed_sections: Optional[frozenset[str]]+ creating: bool+++@dataclass(frozen=True)+class AccountCandidateValidator(Generic[C, A]):+ """Validate every candidate; sections describe the domain's dependencies.++ Validators may use context.changed_sections to scope PATCH transition+ rules, but must always validate the complete candidate's effective values.+ """++ sections: frozenset[str]+ validate: Callable[[AccountCandidateContext[C, A]], None]++REFRESH_INTERVAL_SECS = 30.0# Accounts unused for this long are evicted and stop being polled.ACCOUNT_IDLE_TTL_SECS = 24 * 60 * 60.0@@ -85,7 +125,8 @@ ACCOUNT_IDLE_TTL_SECS = 24 * 60 * 60.0class ConfigChangeEvent:"""Emitted after a new config is published.- ``scope`` names the changed override (cluster-wide or one account).+ ``scope`` names the changed persisted settings document (cluster-wide or+ one account).``old_config`` / ``new_config`` are the objects for that scope (the clusterconfig, or that account's :class:`AccountConfig`; ``None`` when the accountscope was cleared or evicted). ``reason`` distinguishes ordinary config@@ -116,7 +157,7 @@ class _ConsumerRegistration:@dataclassclass _AccountEntry(Generic[A]):- """One account's cached state under the manager's owner loop.+ """One account's cached state protected by the publication lock.``config`` is the constructed, already-validated account model;``last_access`` drives idle eviction.@@ -126,15 +167,32 @@ class _AccountEntry(Generic[A]):last_access: float+@dataclass(frozen=True)+class _PreparedPatch:+ """Candidate and persisted document prepared for one scope mutation."""++ persisted_settings: dict+ candidate: Any+++@dataclass(frozen=True)+class _PendingNotification:+ """One notification ordered after the previous event for its scope."""++ event: ConfigChangeEvent+ predecessor: Optional[ConcurrentFuture[None]]+ completion: ConcurrentFuture[None]++class RuntimeConfigManager(Generic[C, A]):- """Coordinate override merge/publish/invalidation over a :class:`ConfigSource`.+ """Coordinate scoped config patching/publication over a :class:`ConfigSource`.``base_config`` is the caller-owned immutable startup baseline.``get_config`` / ``set_config`` bridge to the process-wide cluster singleton;``build_config`` rebuilds the cluster model from the baseline plus a complete- cluster override; ``build_account`` constructs an account model from its- sparse override. Supplying these as hooks keeps the manager free of any- concrete config-model import.+ Cluster settings document; ``build_account`` constructs an Account model from+ its own settings document. Supplying these as hooks keeps the manager free of+ concrete config-model imports and business-specific defaulting rules."""def __init__(@@ -147,9 +205,9 @@ class RuntimeConfigManager(Generic[C, A]):build_config: Callable[[C, dict], C],build_account: Callable[[Optional[dict]], A],validate_request: Optional[Callable[[dict, bool, bool], None]] = None,+ account_candidate_validators: Iterable[AccountCandidateValidator[C, A]] = (),) -> None:self._source = source- self._dispatcher = OwnerLoopDispatcher()# Immutable startup baseline. Cluster overrides are always rebuilt from# this object, never from the previously published effective config.self._base_config = base_config@@ -157,26 +215,26 @@ class RuntimeConfigManager(Generic[C, A]):self._set_config = set_config# build_config(old_cluster, cluster_override) -> new validated cluster config.self._build_config = build_config- # build_account(sparse_override) -> constructed & validated account config.- # The manager persists and builds from the *sparse* override only; fallback- # is never materialized. AccountConfig's own @model_validator(after) runs at- # construction, but it only cross-checks fields the account set explicitly- # (see _check_embedding_vectordb_dim), so it never needs the cluster here.+ # build_account(account_settings) -> validated Account configuration.+ # Account/Cluster composition belongs to business resolvers. Existing+ # RuntimeField fallback remains a whole-section compatibility read only.self._build_account = build_account# validate_request(patch, is_account_scope, creating) -> None (structural gate).self._validate_request = validate_request- # Per-account cache; only touched on the owner loop.+ # Domain validators run before persistence and never mutate publications.+ self._account_candidate_validators = tuple(account_candidate_validators)+ # Per-account cache; publication_lock protects cross-loop snapshots.self._accounts: dict[str, _AccountEntry[A]] = {}- self._overrides: dict[ConfigScope, Optional[dict]] = {}+ self._persisted_settings: dict[ConfigScope, Optional[dict]] = {}self._consumers: list[_ConsumerRegistration] = []# Per-scope local locks serialize same-node concurrent PATCHes so two# requests mutating the same scope can't interleave read-merge-write.- self._scope_locks: weakref.WeakValueDictionary[tuple, asyncio.Lock] = (- weakref.WeakValueDictionary()- )- self._publish_lock = asyncio.Lock()- self._notification_lock = asyncio.Lock()+ self._scope_locks = KeyedAsyncLockPool[tuple]()+ self._publication_lock = threading.RLock()+ self._notification_tails: dict[ConfigScope, ConcurrentFuture[None]] = {}+ self._refresh_task_lock = threading.Lock()self._refresh_task: Optional[asyncio.Task] = None+ self._refresh_task_loop: Optional[asyncio.AbstractEventLoop] = None# -- consumers ------------------------------------------------------------@@ -202,56 +260,59 @@ class RuntimeConfigManager(Generic[C, A]):async def initialize(self) -> None:"""Load cluster defaults before serving requests."""- self._dispatcher.bind_current_loop()await self._refresh_scope(ConfigScope.cluster(), reason=ConfigChangeReason.UPDATE)async def replace_base_config(self, base_config: C) -> ConfigChangeEvent:- """Replace the startup baseline without persisting a runtime override."""- return await self._dispatcher.run(- lambda: run_to_completion(lambda: self._replace_base_config(base_config))- )+ """Replace the startup baseline without persisting runtime settings."""+ return await run_to_completion(lambda: self._replace_base_config(base_config))async def _replace_base_config(self, base_config: C) -> ConfigChangeEvent:scope = ConfigScope.cluster()async with self._lock_for(scope):- async with self._publish_lock:+ with self._publication_lock:self._base_config = base_config+ persisted_settings = self._persisted_settings.get(scope)+ candidate = self._build_candidate(scope, persisted_settings)event = self._publish(scope,- self._overrides.get(scope),+ persisted_settings,+ candidate,reason=ConfigChangeReason.UPDATE,)- await self._notify(event)+ notification = self._chain_notification(event)+ await self._notify_in_order(notification)return event# -- account loading -----------------------------------------------------async def _ensure_loaded(self, account_id: str) -> None:- """Load one account's override and construct its config, once.+ """Load and validate one Account configuration, once.- Idempotent and concurrency-safe per account. Absence of a file records- "loaded, no override"; a read/decrypt/validate failure raises and does- not fall back to another account's config.+ Idempotent and concurrency-safe per Account. Absence of a file records+ "loaded, no settings"; a read/decrypt/validate failure raises and does+ not fall back to another Account's configuration."""- entry = self._accounts.get(account_id)- if entry is not None:- entry.last_access = time.monotonic()- return+ with self._publication_lock:+ entry = self._accounts.get(account_id)+ if entry is not None:+ entry.last_access = time.monotonic()+ returnscope = ConfigScope.account(account_id)async with self._lock_for(scope):- if account_id in self._accounts:- self._accounts[account_id].last_access = time.monotonic()- return- override = await self._source.load(scope)- async with self._publish_lock:+ with self._publication_lock:+ if account_id in self._accounts:+ self._accounts[account_id].last_access = time.monotonic()+ return+ persisted_settings = await self._source.load(scope)+ with self._publication_lock:self._accounts[account_id] = _AccountEntry(- config=self._build_account(override),+ config=self._build_account_candidate(persisted_settings),last_access=time.monotonic(),)- self._overrides[scope] = override+ self._persisted_settings[scope] = persisted_settingsasync def get_account(self, account_id: str, field: str) -> Any:- """Load an account on demand and return one effective config field."""+ """Load an Account field, retaining deprecated whole-section fallback."""return await self.resolve_account(account_id, lambda view: view.get(field))async def resolve_account(@@ -262,16 +323,18 @@ class RuntimeConfigManager(Generic[C, A]):Selectors must be synchronous and perform no I/O or configurationmutations. Loading and cancellation have the same contract as get_account."""- return await self._dispatcher.run(- lambda: run_to_completion(lambda: self._resolve_account(account_id, resolver))- )+ return await run_to_completion(lambda: self._resolve_account(account_id, resolver))async def _resolve_account(self, account_id: str, resolver: Callable[[AccountConfigView[C, A]], T]) -> T:- await self._ensure_loaded(account_id)- # No await between capturing the publications and running the selector.- view = AccountConfigView(self._accounts[account_id].config, self._get_config())+ while True:+ await self._ensure_loaded(account_id)+ with self._publication_lock:+ entry = self._accounts.get(account_id)+ if entry is not None:+ view = AccountConfigView(entry.config, self._get_config())+ breakresult = resolver(view)import inspect@@ -282,82 +345,139 @@ class RuntimeConfigManager(Generic[C, A]):return resultasync def get_settings(self, scope: ConfigScope) -> dict:- """Read explicit overrides, never the merged configuration."""+ """Read the settings stored for exactly one scope."""import copy- return copy.deepcopy(await self._dispatcher.run(lambda: self._source.load(scope)) or {})+ return copy.deepcopy(await self._source.load(scope) or {})def validate_initial_settings(self, account_id: str, settings: dict) -> None:"""Validate creation-time settings without persisting them."""ConfigScope.account(account_id)if self._validate_request is not None:self._validate_request(settings, True, True)- # Construct-to-validate: section-internal and cross-section validators run.- self._build_account(settings)+ self._build_account_candidate(settings, creating=True)# -- PATCH ---------------------------------------------------------------async def patch_cluster(self, patch: dict) -> ConfigChangeEvent:- """Apply a three-state PATCH to the cluster override and publish."""+ """Apply a three-state PATCH to the Cluster settings and publish."""scope = ConfigScope.cluster()- return await self._dispatcher.run(- lambda: run_to_completion(lambda: self._patch(scope, patch))- )+ return await run_to_completion(lambda: self._patch(scope, patch))async def patch_account(self, account_id: str, patch: dict, *, creating: bool = False) -> ConfigChangeEvent:- """Apply a three-state PATCH to one account override and publish."""+ """Apply a three-state PATCH to one Account configuration and publish."""scope = ConfigScope.account(account_id)- return await self._dispatcher.run(- lambda: run_to_completion(lambda: self._patch(scope, patch, creating=creating))- )+ return await run_to_completion(lambda: self._patch(scope, patch, creating=creating))async def delete_account(self, account_id: str) -> ConfigChangeEvent:- """Delete one account override and evict all manager-owned state."""+ """Delete one Account configuration and evict all manager-owned state."""scope = ConfigScope.account(account_id)- return await self._dispatcher.run(- lambda: run_to_completion(lambda: self._delete_account(scope))- )+ return await run_to_completion(lambda: self._delete_account(scope))async def _delete_account(self, scope: ConfigScope) -> ConfigChangeEvent:assert scope.key is not Noneasync with self._lock_for(scope):await self._source.delete(scope)- async with self._publish_lock:- entry = self._accounts.pop(scope.key, None)- self._overrides.pop(scope, None)- event = self._account_event(- scope.key,- entry.config if entry is not None else None,+ with self._publication_lock:+ event = self._publish(+ scope,+ None,None,reason=ConfigChangeReason.EVICT,)- await self._notify(event)+ notification = self._chain_notification(event)+ await self._notify_in_order(notification)return eventasync def _patch(self, scope: ConfigScope, patch: dict, *, creating: bool = False) -> ConfigChangeEvent:- is_account = scope.kind is ScopeKind.ACCOUNT- if self._validate_request is not None:- self._validate_request(patch, is_account, creating)+ # Phase 1: validate only the request boundary. Candidate validation+ # happens after the current document has been merged.+ self._validate_patch_request(scope, patch, creating)++ # Phase 2: serialize the scope's read/merge/validate/write operation.async with self._lock_for(scope):+ prepared = await self._persist_validated_patch(scope, patch, creating=creating)- def mutate(current: Optional[dict]) -> dict:- override = apply_three_state_patch(current, patch)- if self._validate_request is not None and not creating:- self._validate_resets(current or {}, patch, is_account)- # Construct-to-validate before persisting.- self._build_candidate(scope, override)- return override-- override = await self._source.update(scope, mutate)- async with self._publish_lock:- event = self._publish(scope, override, reason=ConfigChangeReason.UPDATE)- await self._notify(event)+ # Phase 3: publish only the already-built candidate. Account and+ # Cluster publications are independent; a Cluster pointer change+ # never rebuilds the AccountConfig candidate.+ with self._publication_lock:+ event = self._publish(+ scope,+ prepared.persisted_settings,+ prepared.candidate,+ reason=ConfigChangeReason.UPDATE,+ )+ notification = self._chain_notification(event)++ # Phase 4: consumers run outside write locks, in publication order.+ await self._notify_in_order(notification)return event+ def _validate_patch_request(+ self,+ scope: ConfigScope,+ patch: dict,+ creating: bool,+ ) -> None:+ """Validate the request boundary before entering scope serialization."""+ if self._validate_request is not None:+ self._validate_request(patch, scope.kind is ScopeKind.ACCOUNT, creating)++ async def _persist_validated_patch(+ self,+ scope: ConfigScope,+ patch: dict,+ *,+ creating: bool,+ ) -> _PreparedPatch:+ """Prepare one candidate and persist its explicit scope document."""+ prepared: Optional[_PreparedPatch] = None++ def mutate(current: Optional[dict]) -> dict:+ nonlocal prepared+ prepared = self._prepare_patch(scope, current, patch, creating=creating)+ return prepared.persisted_settings++ persisted_settings = await self._source.update(scope, mutate)+ if prepared is None:+ raise RuntimeError("config source update did not invoke its mutate callback")+ if prepared.persisted_settings is not persisted_settings:+ prepared = _PreparedPatch(+ persisted_settings=persisted_settings,+ candidate=prepared.candidate,+ )+ return prepared++ def _prepare_patch(+ self,+ scope: ConfigScope,+ current: Optional[dict],+ patch: dict,+ *,+ creating: bool,+ ) -> _PreparedPatch:+ """Merge, transition-check, construct and validate one PATCH candidate."""+ persisted_settings = apply_three_state_patch(current, patch)+ if self._validate_request is not None and not creating:+ self._validate_resets(+ current or {},+ patch,+ scope.kind is ScopeKind.ACCOUNT,+ )+ candidate = self._build_candidate(+ scope,+ persisted_settings,+ changed_sections=frozenset(patch),+ old_settings=current,+ creating=creating,+ )+ return _PreparedPatch(persisted_settings=persisted_settings, candidate=candidate)+def _validate_resets(self, current: dict, patch: dict, is_account: bool) -> None:"""A parent reset must not erase creation-only overrides beneath it."""@@ -377,48 +497,92 @@ class RuntimeConfigManager(Generic[C, A]):# -- copy-on-write publish ------------------------------------------------ def _build_candidate(self, scope: ConfigScope, override: Optional[dict]) -> Any:- """Build (and thereby validate) the new object for a scope's override."""+ def _build_candidate(+ self,+ scope: ConfigScope,+ persisted_settings: Optional[dict],+ *,+ changed_sections: Optional[frozenset[str]] = None,+ old_settings: Any = _NO_OLD_SETTINGS,+ creating: bool = False,+ ) -> Any:+ """Build and validate the candidate publication for one scope."""if scope.kind is ScopeKind.CLUSTER:- return self._build_config(self._base_config, override or {})- return self._build_account(override)+ return self._build_config(self._base_config, persisted_settings or {})+ return self._build_account_candidate(+ persisted_settings,+ changed_sections=changed_sections,+ old_settings=old_settings,+ creating=creating,+ )++ def _build_account_candidate(+ self,+ settings: Optional[dict],+ *,+ changed_sections: Optional[frozenset[str]] = None,+ old_settings: Any = _NO_OLD_SETTINGS,+ creating: bool = False,+ ) -> A:+ """Build an Account model and run injected cross-publication checks."""+ account = self._build_account(settings)+ # The source may contain changes rejected by a previous refresh.+ # Validate the complete candidate; changed_sections only scopes+ # transition checks inside validators, never candidate validity.+ validators = self._account_candidate_validators+ if not validators:+ return account+ cluster = self._get_config()+ context = AccountCandidateContext(+ new_view=AccountConfigView(account, cluster),+ old_view=(+ AccountConfigView(self._build_account(old_settings), cluster)+ if not creating and old_settings is not _NO_OLD_SETTINGS+ else None+ ),+ changed_sections=changed_sections,+ creating=creating,+ )+ for validator in validators:+ validator.validate(context)+ return accountdef _publish(self,scope: ConfigScope,- override: Optional[dict],+ persisted_settings: Optional[dict],+ candidate: Any,*,reason: ConfigChangeReason,) -> ConfigChangeEvent:- """Swap in the new object for a scope and return the change event.-- Cluster publish swaps the singleton pointer; account publish replaces the- cache entry. Either way business code only ever sees a fully-built object,- never a partially-mutated one.- """+ """Swap an already-built candidate into publication state."""if scope.kind is ScopeKind.CLUSTER:+ if candidate is None:+ raise ValueError("cluster publication requires a candidate")old = self._get_config()- new = self._build_config(self._base_config, override or {})- self._set_config(new)- self._overrides[scope] = override+ self._set_config(candidate)+ self._persisted_settings[scope] = persisted_settingsreturn ConfigChangeEvent(scope=scope,- changed_sections=diff_sections(old, new),+ changed_sections=diff_sections(old, candidate),old_config=old,- new_config=new,+ new_config=candidate,reason=reason,)assert scope.key is not Noneaccount_id = scope.keyold_entry = self._accounts.get(account_id)old_config = old_entry.config if old_entry is not None else None- new_config = self._build_account(override)- self._accounts[account_id] = _AccountEntry(- config=new_config,- last_access=(old_entry.last_access if old_entry else time.monotonic()),- )- self._overrides[scope] = override- return self._account_event(account_id, old_config, new_config, reason=reason)+ if candidate is None:+ self._accounts.pop(account_id, None)+ self._persisted_settings.pop(scope, None)+ else:+ self._accounts[account_id] = _AccountEntry(+ config=candidate,+ last_access=(old_entry.last_access if old_entry else time.monotonic()),+ )+ self._persisted_settings[scope] = persisted_settings+ return self._account_event(account_id, old_config, candidate, reason=reason)def _account_event(self,@@ -436,46 +600,90 @@ class RuntimeConfigManager(Generic[C, A]):reason=reason,)+ def _chain_notification(+ self, event: ConfigChangeEvent+ ) -> Optional[_PendingNotification]:+ """Link an event to the preceding notification for the same scope."""+ is_evict = event.reason is ConfigChangeReason.EVICT+ if not event.changed_sections and not is_evict:+ return None+ completion: ConcurrentFuture[None] = ConcurrentFuture()+ pending = _PendingNotification(+ event=event,+ predecessor=self._notification_tails.get(event.scope),+ completion=completion,+ )+ self._notification_tails[event.scope] = completion+ return pending++ async def _notify_in_order(+ self, pending: Optional[_PendingNotification]+ ) -> None:+ """Deliver one event after its scope predecessor, without write locks."""+ if pending is None:+ return+ if pending.predecessor is not None:+ await asyncio.wrap_future(pending.predecessor)+ try:+ await self._notify(pending.event)+ finally:+ pending.completion.set_result(None)+ with self._publication_lock:+ if self._notification_tails.get(pending.event.scope) is pending.completion:+ self._notification_tails.pop(pending.event.scope, None)+async def _notify(self, event: ConfigChangeEvent) -> None:- """Await matching consumers in registration order after publication."""+ """Await matching consumers in registration order for one scope."""is_evict = event.reason is ConfigChangeReason.EVICTif not event.changed_sections and not is_evict:return- async with self._notification_lock:- for registration in self._consumers:- if registration.scope is not event.scope.kind:- continue- if not is_evict and registration.sections.isdisjoint(event.changed_sections):- continue- try:- await registration.consumer(event)- except Exception:- logger.exception("Config change consumer failed")-- def _lock_for(self, scope: ConfigScope) -> asyncio.Lock:+ for registration in self._consumers:+ if registration.scope is not event.scope.kind:+ continue+ if not is_evict and registration.sections.isdisjoint(event.changed_sections):+ continue+ try:+ await registration.consumer(event)+ except Exception:+ logger.exception("Config change consumer failed")++ def _lock_for(self, scope: ConfigScope):key = (scope.kind.value, scope.key)- lock = self._scope_locks.get(key)- if lock is None:- lock = asyncio.Lock()- self._scope_locks[key] = lock- return lock+ return self._scope_locks.acquire(key)# -- periodic refresh ----------------------------------------------------def start_refresh_loop(self, interval_secs: float = REFRESH_INTERVAL_SECS) -> None:- if self._refresh_task is None or self._refresh_task.done():- self._refresh_task = asyncio.create_task(self._refresh_loop(interval_secs))+ loop = asyncio.get_running_loop()+ with self._refresh_task_lock:+ if self._refresh_task is None or self._refresh_task.done():+ self._refresh_task = loop.create_task(self._refresh_loop(interval_secs))+ self._refresh_task_loop = loopasync def stop_refresh_loop(self) -> None:- task = self._refresh_task- self._refresh_task = None- if task is not None:+ with self._refresh_task_lock:+ task = self._refresh_task+ owner_loop = self._refresh_task_loop+ if task is None or owner_loop is None:+ return++ async def cancel_and_wait() -> None:task.cancel()try:await taskexcept asyncio.CancelledError:pass+ if asyncio.get_running_loop() is owner_loop:+ await cancel_and_wait()+ else:+ future = asyncio.run_coroutine_threadsafe(cancel_and_wait(), owner_loop)+ await asyncio.wrap_future(future)+ with self._refresh_task_lock:+ if self._refresh_task is task:+ self._refresh_task = None+ self._refresh_task_loop = None+async def _refresh_loop(self, interval_secs: float) -> None:while True:try:@@ -487,25 +695,26 @@ class RuntimeConfigManager(Generic[C, A]):logger.exception("Runtime config refresh iteration failed")async def refresh_once(self) -> None:- """Run one refresh on the configuration owner's loop."""- await self._dispatcher.run(self._refresh_once)+ """Reload all active configuration scopes once."""+ await run_to_completion(self._refresh_once)async def _refresh_once(self) -> None:"""Reload cluster + hot accounts once, publishing any observed change.Every active scope is reloaded and diffed against the last published- override (``_refresh_scope``); the manager owns change detection, so the+ settings document (``_refresh_scope``); the manager owns change detection, so thesource stays stateless. Cold accounts (idle > TTL) are evicted and stopbeing reloaded. On load or publish failure the last effective value iskept, and the next refresh retries the active scope."""- async with self._publish_lock:- evictions = self._evict_cold_accounts()- for event in evictions:- await self._notify(event)- scopes = [ConfigScope.cluster()] + [- ConfigScope.account(account_id) for account_id in list(self._accounts)- ]+ with self._publication_lock:+ account_ids = list(self._accounts)+ for account_id in account_ids:+ await self._evict_account_if_cold(account_id)+ with self._publication_lock:+ scopes = [ConfigScope.cluster()] + [+ ConfigScope.account(account_id) for account_id in self._accounts+ ]for scope in scopes:try:await self._refresh_scope(scope, reason=ConfigChangeReason.UPDATE)@@ -523,35 +732,46 @@ class RuntimeConfigManager(Generic[C, A]):reason: ConfigChangeReason,) -> None:async with self._lock_for(scope):- override = await self._source.load(scope)- if scope in self._overrides and self._overrides[scope] == override:- return- async with self._publish_lock:+ persisted_settings = await self._source.load(scope)+ with self._publication_lock:+ if (+ scope in self._persisted_settings+ and self._persisted_settings[scope] == persisted_settings+ ):+ return+ candidate = self._build_candidate(+ scope,+ persisted_settings,+ changed_sections=None,+ old_settings=_NO_OLD_SETTINGS,+ creating=False,+ )if scope.kind is ScopeKind.ACCOUNT:assert scope.key is not Noneif scope.key not in self._accounts:# A refresh must not resurrect an evicted/never-loaded account.return- event = self._publish(scope, override, reason=reason)- await self._notify(event)-- def _evict_cold_accounts(self) -> list[ConfigChangeEvent]:- now = time.monotonic()- cold = [- account_id- for account_id, entry in self._accounts.items()- if now - entry.last_access > ACCOUNT_IDLE_TTL_SECS- ]- events: list[ConfigChangeEvent] = []- for account_id in cold:- entry = self._accounts.pop(account_id)- self._overrides.pop(ConfigScope.account(account_id), None)- events.append(- self._account_event(+ event = self._publish(scope, persisted_settings, candidate, reason=reason)+ notification = self._chain_notification(event)+ await self._notify_in_order(notification)++ async def _evict_account_if_cold(self, account_id: str) -> None:+ scope = ConfigScope.account(account_id)+ async with self._lock_for(scope):+ with self._publication_lock:+ entry = self._accounts.get(account_id)+ if (+ entry is None+ or time.monotonic() - entry.last_access <= ACCOUNT_IDLE_TTL_SECS+ ):+ return+ self._accounts.pop(account_id)+ self._persisted_settings.pop(scope, None)+ event = self._account_event(account_id,entry.config,None,reason=ConfigChangeReason.EVICT,)- )- return events+ notification = self._chain_notification(event)+ await self._notify_in_order(notification)diff --git a/openviking/config/merge.py b/openviking/config/merge.pyindex b3020baad..dae0f8c67 100644--- a/openviking/config/merge.py+++ b/openviking/config/merge.py@@ -2,13 +2,18 @@# SPDX-License-Identifier: AGPL-3.0"""Three-state PATCH merge and copy-on-write helpers.-The same three-state semantics apply to every config layer (cluster and account):+The same three-state PATCH semantics apply to each independent config scope:- field absent: keep current value.- field is a concrete value: set/replace.-- field is ``None``: delete this layer's override, inheriting the next layer.+- field is ``None``: remove the value from this scope.Objects merge recursively, arrays replace wholesale.++What an absent value means is deliberately outside this helper. A business+resolver may supply a default, reject the operation, or consult Cluster+configuration. Legacy ``RuntimeField.fallback`` is a separate compatibility+mechanism and is not implemented by this merge function."""from __future__ import annotations@@ -18,7 +23,7 @@ from typing import Any, Optionaldef apply_three_state_patch(current: Optional[dict], patch: dict) -> dict:- """Return a new sparse override with ``patch`` applied to ``current``.+ """Return a new settings document with ``patch`` applied to ``current``.Never mutates the inputs (pure function; safe for conflict retries)."""@@ -30,7 +35,7 @@ def apply_three_state_patch(current: Optional[dict], patch: dict) -> dict:def _merge_into(base: dict, patch: dict) -> None:for key, value in patch.items():if value is None:- # Delete this layer's override, restoring inheritance.+ # Remove the value from this scope; consumers decide the default.base.pop(key, None)continueif isinstance(value, dict):diff --git a/openviking/config/scope.py b/openviking/config/scope.pyindex d39ffb637..b9bdcdf40 100644--- a/openviking/config/scope.py+++ b/openviking/config/scope.py@@ -1,10 +1,9 @@# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.# SPDX-License-Identifier: AGPL-3.0-"""Logical address of a single config override.+"""Logical address of one scoped configuration document.-``ConfigScope`` names *one* override (cluster-wide or one account). It does not-express inheritance layers and does not prescribe storage layout; that is a-``ConfigSource`` implementation detail.+``ConfigScope`` identifies Cluster configuration or one Account's configuration.+It does not express inheritance, fallback, precedence, or storage layout."""from __future__ import annotations@@ -23,7 +22,7 @@ class ScopeKind(str, Enum):@dataclass(frozen=True)class ConfigScope:- """A logical address for one override; validated on construction."""+ """A validated logical address for one scoped configuration."""kind: ScopeKindkey: Optional[str] = Nonediff --git a/openviking/config/source/__init__.py b/openviking/config/source/__init__.pyindex a8ea0ba1e..3c307d8b6 100644--- a/openviking/config/source/__init__.py+++ b/openviking/config/source/__init__.py@@ -2,7 +2,7 @@# SPDX-License-Identifier: AGPL-3.0"""Config source abstraction, registry, and built-in implementations.-A :class:`ConfigSource` owns *where an override comes from, how it is written+A :class:`ConfigSource` owns *where scoped settings come from, how they are writtenback, how change is detected, and whether/how it is encrypted*. The:class:`~openviking.config.manager.RuntimeConfigManager` owns merge, publish andinvalidation and depends only on this abstraction.diff --git a/openviking/config/source/base.py b/openviking/config/source/base.pyindex 60d707331..5f0b854be 100644--- a/openviking/config/source/base.py+++ b/openviking/config/source/base.py@@ -16,8 +16,8 @@ from openviking.config.scope import ConfigScope, ScopeKind__all__ = ["ConfigScope", "ScopeKind", "ConfigSource", "ConfigSourceContext", "Mutate"]-# A pure, repeatable function producing the full new override from the current-# one. It must have no side effects and must not send consumer notifications;+# A pure, repeatable function producing the complete new settings document from+# the current one. It must have no side effects or send consumer notifications;# a conflict retry may run it again.Mutate = Callable[[Optional[dict]], dict]@@ -36,27 +36,35 @@ class ConfigSourceContext:@runtime_checkableclass ConfigSource(Protocol):- """Storage/awareness of config overrides for individual scopes."""+ """Storage and change awareness for scoped configuration documents.++ A source instance may be called concurrently from different threads and+ event loops. Implementations must synchronize mutable state accordingly and+ must not rely on loop-affine clients or asyncio primitives unless they+ dispatch those operations to their owning loop internally.+ """async def load(self, scope: ConfigScope) -> Optional[dict]:- """Read the sparse override (plaintext dict) for one scope.+ """Read the explicitly stored settings for one scope.- Returns ``None`` when no override exists for the scope.+ Omitted model fields are not materialized in storage. This serialization+ detail does not make Account configuration an override of Cluster+ configuration. Returns ``None`` when the scope has no stored document."""...async def update(self, scope: ConfigScope, mutate: "Mutate") -> dict:"""Perform a read-modify-write within the source's own concurrency guard.- Reads the current override, calls ``mutate`` to get the full new- override, writes it back. ``mutate`` is guaranteed to run against the+ Reads the current settings, calls ``mutate`` to get the complete new+ document, and writes it back. ``mutate`` is guaranteed to run against thelatest value and the write must not drop updates; lock vs. CAS is animplementation choice."""...async def delete(self, scope: ConfigScope) -> None:- """Delete the persisted override for one scope.+ """Delete the persisted settings for one scope.Missing state is treated as success. Implementations must provide thesame concurrency guarantees as :meth:`update`.diff --git a/openviking/config/source/file_source.py b/openviking/config/source/file_source.pyindex 2687ebf92..3f16f9ade 100644--- a/openviking/config/source/file_source.py+++ b/openviking/config/source/file_source.py@@ -2,21 +2,22 @@# SPDX-License-Identifier: AGPL-3.0"""Built-in file-backed config source.-Paths are specific to this provider. The account override retains the legacy+Paths are specific to this provider. Account settings retain the legacy``setting.json`` location:============ ==========================================================-override path+scope path============ ==========================================================account ``/local/{account_id}/_system/setting.json``account backup ``/local/{account_id}/_system/setting.backup.json``cluster ``/local/_system/runtime_config/cluster.json``============ ==========================================================-Only sparse overrides are stored. This source exchanges JSON bytes with AGFS;-encryption at rest follows the mount's configuration. Backups preserve the-previous bytes returned by AGFS so readers can recover if the destination is-left truncated by an interrupted write.+Only explicitly configured fields are serialized. Account and Cluster documents+remain independent; this source does not apply fallback or inheritance. It+exchanges JSON bytes with AGFS, and encryption at rest follows the mount's+configuration. Backups preserve the previous bytes returned by AGFS so readers+can recover if the destination is left truncated by an interrupted write."""from __future__ import annotations@@ -39,7 +40,7 @@ CLUSTER_SETTINGS_PATH = "/local/_system/runtime_config/cluster.json"class FileConfigSource:- """Store sparse JSON overrides using AGFS locks, backups and rollback."""+ """Store scoped JSON settings using AGFS locks, backups and rollback."""def __init__(self,diff --git a/openviking/config/source/memory_source.py b/openviking/config/source/memory_source.pyindex 435da313a..9731fc671 100644--- a/openviking/config/source/memory_source.py+++ b/openviking/config/source/memory_source.py@@ -4,10 +4,10 @@from __future__ import annotations-import asyncioimport copyfrom typing import Optional+from openviking.concurrency import AsyncSemaphorefrom openviking.config.scope import ConfigScopefrom openviking.config.source.base import ConfigSourceContext, Mutatefrom openviking.config.source.registry import register_config_source@@ -19,7 +19,7 @@ class MemoryConfigSource:def __init__(self, ctx: Optional[ConfigSourceContext] = None) -> None:self._namespace = ctx.params.get("namespace", "") if ctx else ""self._store: dict[tuple, Optional[dict]] = {}- self._lock = asyncio.Lock()+ self._lock = AsyncSemaphore()def _key(self, scope: ConfigScope) -> tuple:return (self._namespace, scope.kind.value, scope.key)diff --git a/openviking/config/validate.py b/openviking/config/validate.pyindex efab237af..e44527e45 100644--- a/openviking/config/validate.py+++ b/openviking/config/validate.py@@ -14,7 +14,9 @@ branches:2. cluster-vs-account scope is confined by *which model is validated against*(``OpenVikingConfig`` for a cluster PATCH, ``AccountConfig`` for an accountPATCH) — there is no per-field scope flag;-3. objects merge recursively, arrays replace wholesale (a list value is a leaf);+3. objects merge recursively, arrays replace wholesale (indices are not+ independently patchable), while typed model list elements are checked against+ their own RuntimeField schema;4. ``None`` is the three-state "delete this override". Deleting a section isallowed only when its whole model subtree is writable for the operation.@@ -25,6 +27,7 @@ the request shape, not the semantic validity of individual values.from __future__ import annotations+import copyimport dataclassesimport typesimport typing@@ -35,6 +38,8 @@ from pydantic import BaseModelfrom openviking_cli.utils.config.runtime_field import (collect_frozen_paths,collect_runtime_field_paths,+ is_dynamic,+ is_runtime_field,)@@ -78,6 +83,42 @@ def validate_patch(_reject_frozen(patch, (), frozen)+def filter_runtime_fields(model: type[BaseModel], settings: dict[str, Any] | None) -> dict:+ """Build the effective runtime document from a persisted settings document.++ This is intentionally different from :func:`validate_patch`. A ConfigSource+ document is trusted persisted state, not a post-creation write request, so+ ``dynamic=False`` RuntimeFields must still be loaded on every node. The+ filter only prevents known ordinary ``Field`` values and fields unknown to+ this binary from becoming effective. The raw document remains in the+ source for forward-compatible round trips.+ """+ if not isinstance(settings, dict):+ return {}++ def walk(cls: type[Any], node: dict[str, Any]) -> dict:+ fields = _model_fields(cls)+ aliases = {+ field.alias: name+ for name, field in fields.items()+ if getattr(field, "alias", None)+ }+ result: dict = {}+ for key, value in node.items():+ name = key if key in fields else aliases.get(key)+ field = fields.get(name)+ if field is None or not is_runtime_field(field):+ continue+ nested = _unwrap_model(_field_annotation(field))+ if nested is not None and isinstance(value, dict):+ result[key] = walk(nested, value)+ else:+ result[key] = copy.deepcopy(value)+ return result++ return walk(model, settings)++def _reject_frozen(node: dict[str, Any],prefix: tuple[str, ...],@@ -115,12 +156,117 @@ def _walk(continue# Non-dict values (scalar / list-replace) are leaves.if not isinstance(value, dict):+ if isinstance(value, list):+ _validate_model_list(+ value,+ path,+ _field_at_path(root_model, path),+ creating=creating,+ )continuenested_model = _model_at_path(root_model, path)if nested_model is not None:_walk(value, path, allowed, frozen, root_model, creating)+def _validate_model_list(+ values: list[Any],+ path: tuple[str, ...],+ field: Any,+ *,+ creating: bool,+) -> None:+ """Validate RuntimeField elements inside a typed model list.++ Lists remain atomic PATCH values: callers replace the whole list rather than+ addressing an index. When the element type is a Pydantic model, however, its+ object shape is still part of the request contract and must not silently+ discard unknown or non-runtime fields.+ """+ element_model = _list_element_model(_field_annotation(field) if field is not None else None)+ if element_model is None:+ return++ fields = _model_fields(element_model)+ aliases = {+ item.alias: name+ for name, item in fields.items()+ if getattr(item, "alias", None)+ }+ for index, item in enumerate(values):+ if not isinstance(item, dict):+ # Pydantic will report the element type error when the merged+ # configuration is constructed. This layer only checks request+ # surface permissions.+ continue+ for key, value in item.items():+ if not isinstance(key, str):+ raise ConfigPatchError(+ "patch keys must be strings",+ path=path + (str(index),),+ )+ name = key if key in fields else aliases.get(key)+ child = fields.get(name)+ child_path = path + (str(index), key)+ if child is None or not is_runtime_field(child):+ raise ConfigPatchError(+ "field is not modifiable by the config API",+ path=child_path,+ )+ if not creating and not is_dynamic(child):+ raise ConfigPatchError(+ "field is create-only and cannot be changed after creation",+ path=child_path,+ )+ nested_model = _unwrap_model(_field_annotation(child))+ if nested_model is not None and isinstance(value, dict):+ _validate_model_object(value, nested_model, child_path, creating=creating)+ elif isinstance(value, list):+ _validate_model_list(+ value,+ child_path,+ child,+ creating=creating,+ )+++def _validate_model_object(+ node: dict[str, Any],+ model: type[Any],+ path: tuple[str, ...],+ *,+ creating: bool,+) -> None:+ """Validate a model nested inside a typed list element."""+ fields = _model_fields(model)+ aliases = {+ item.alias: name+ for name, item in fields.items()+ if getattr(item, "alias", None)+ }+ for key, value in node.items():+ if not isinstance(key, str):+ raise ConfigPatchError("patch keys must be strings", path=path)+ name = key if key in fields else aliases.get(key)+ child = fields.get(name)+ child_path = path + (key,)+ if child is None or not is_runtime_field(child):+ raise ConfigPatchError(+ "field is not modifiable by the config API",+ path=child_path,+ )+ if not creating and not is_dynamic(child):+ raise ConfigPatchError(+ "field is create-only and cannot be changed after creation",+ path=child_path,+ )+ nested_model = _unwrap_model(_field_annotation(child))+ if nested_model is not None and isinstance(value, dict):+ _validate_model_object(value, nested_model, child_path, creating=creating)+ elif isinstance(value, list):+ _validate_model_list(value, child_path, child, creating=creating)++def _validate_subtree_delete(path: tuple[str, ...],allowed: set[tuple[str, ...]],@@ -178,6 +324,44 @@ def _model_at_path(return model+def _field_at_path(+ root_model: type[BaseModel],+ path: tuple[str, ...],+) -> Any | None:+ """Return the declared field at a model-only path."""+ model = root_model+ for index, part in enumerate(path):+ field = _model_fields(model).get(part)+ if field is None:+ return None+ if index == len(path) - 1:+ return field+ nested = _unwrap_model(_field_annotation(field))+ if nested is None:+ return None+ model = nested+ return None+++def _list_element_model(annotation: Any) -> type[Any] | None:+ """Resolve a typed list's model element, including Optional wrappers."""+ origin = typing.get_origin(annotation)+ if origin in (typing.Union, types.UnionType):+ for arg in typing.get_args(annotation):+ if arg is type(None):+ continue+ element = _list_element_model(arg)+ if element is not None:+ return element+ return None+ if origin not in (list, tuple, set, frozenset):+ return None+ args = typing.get_args(annotation)+ if not args:+ return None+ return _unwrap_model(args[0])++def _model_fields(model: type[Any]) -> dict[str, Any]:if isinstance(model, type) and issubclass(model, BaseModel):return dict(model.model_fields)diff --git a/openviking/config/vector.py b/openviking/config/vector.pynew file mode 100644index 000000000..a13131947--- /dev/null+++ b/openviking/config/vector.py@@ -0,0 +1,248 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Pure account vector configuration resolution and compatibility checks."""++from __future__ import annotations++import copy+import hashlib+import json+from dataclasses import dataclass+from typing import Any++from openviking.config.account_vector import AccountEmbeddingConfig, AccountVectorDBConfig+from openviking.config.manager import AccountCandidateContext+from openviking.config.validate import ConfigPatchError+from openviking_cli.utils.config.embedding_config import EmbeddingConfig, EmbeddingModelConfig+from openviking_cli.utils.config.vectordb_config import VectorDBBackendConfig++MODEL_SECTIONS = ("dense", "sparse", "hybrid")+PROVIDER_BINDING = frozenset(+ {+ "credentials",+ "provider",+ "backend",+ "api_key",+ "api_base",+ "api_version",+ "ak",+ "sk",+ "region",+ "host",+ "extra_headers",+ }+)+# Provider-specific fields that must not leak from Cluster once an Account takes+# over the provider binding. ``extra_body`` can carry provider routing/selection+# and ``model_path`` is the local model identity, so both belong to the tenant+# binding. Cluster-maintained runtime switches (encoding_format, cache_dir,+# enable_fusion, res_level, max_video_frames) are intentionally not listed: they+# are behavior/infra defaults, not tenant routing or credentials.+PROVIDER_SPECIFIC_ISOLATED = frozenset({"extra_body", "model_path"})+BACKEND_CONNECTIONS = frozenset({"path", "url", "volcengine", "vikingdb", "cuvs", "custom_params"})+++def _account_values(section: Any) -> dict:+ if section is None:+ return {}+ if isinstance(section, dict):+ return copy.deepcopy(section)+ return section.model_dump(by_alias=True, exclude_unset=True, exclude_none=True)+++def _overlay(base: dict, override: dict) -> dict:+ result = copy.deepcopy(base)+ for key, value in override.items():+ if isinstance(value, dict) and isinstance(result.get(key), dict):+ result[key] = _overlay(result[key], value)+ else:+ result[key] = copy.deepcopy(value)+ return result+++def resolve_effective_embedding(cluster: EmbeddingConfig, account: Any) -> EmbeddingConfig:+ """Merge ordinary fields, replacing provider bindings as complete units."""+ if isinstance(account, dict):+ account = AccountEmbeddingConfig.model_validate(account)+ override = _account_values(account)+ base = cluster.model_dump(exclude_unset=True)+ # The default local section is synthesized by the model validator.+ account_modes = {+ mode for mode in MODEL_SECTIONS if isinstance(override.get(mode), dict)+ }+ if account_modes:+ # A declared Account mode replaces the Cluster mode set. Keeping an+ # unrelated Cluster mode would make valid hybrid/sparse overrides fail+ # the mutually-exclusive mode validation below.+ for mode in MODEL_SECTIONS:+ if mode not in account_modes:+ base.pop(mode, None)+ for mode in MODEL_SECTIONS:+ section = getattr(cluster, mode)+ if section is not None and (not account_modes or mode in account_modes):+ base[mode] = section.model_dump(exclude_unset=True)+ supplied = override.get(mode)+ if not isinstance(supplied, dict):+ continue+ if PROVIDER_BINDING.intersection(supplied):+ # Drop both the provider binding and provider-specific fields that+ # would otherwise carry Cluster routing/model identity into the+ # Account request. Cluster-maintained runtime switches remain.+ dropped = PROVIDER_BINDING | PROVIDER_SPECIFIC_ISOLATED+ base[mode] = {+ key: value+ for key, value in (base.get(mode) or {}).items()+ if key not in dropped+ }+ for index, credential in enumerate(supplied.get("credentials") or []):+ if not isinstance(credential, dict) or not credential.get("provider"):+ raise ValueError(f"embedding.{mode}.credentials[{index}].provider is required")+ # Validate without any outer connection/auth fallback. Only model+ # identity and vector-contract fields are intentionally shared.+ contract = _overlay(+ base[mode],+ {key: value for key, value in supplied.items() if key not in dropped},+ )+ independent = _overlay(contract, credential)+ independent.pop("id", None)+ independent["model"] = credential.get("model") or supplied.get(+ "model", independent.get("model")+ )+ EmbeddingModelConfig.model_validate(independent)+ return EmbeddingConfig.model_validate(_overlay(base, override))+++def resolve_effective_vectordb(+ cluster: VectorDBBackendConfig, account: Any+) -> VectorDBBackendConfig:+ """Keep index defaults; an Account owns its complete connection and auth."""+ if isinstance(account, dict):+ account = AccountVectorDBConfig.model_validate(account)+ base = cluster.model_dump(by_alias=True)+ override = _account_values(account)+ if "project_name" in override:+ override["project"] = override.pop("project_name")+ if account is not None:+ base = {key: value for key, value in base.items() if key not in BACKEND_CONNECTIONS}+ return VectorDBBackendConfig.model_validate(_overlay(base, override))+++def validate_vector_settings(+ embedding: EmbeddingConfig, vectordb: VectorDBBackendConfig+) -> VectorDBBackendConfig:+ """Validate a pair locally, returning a normalized copy of the DB config."""+ dimension = embedding.dimension+ if dimension <= 0:+ raise ValueError("embedding dimension must be positive")+ if vectordb.dimension not in (0, dimension):+ raise ValueError(+ f"embedding dimension {dimension} differs from vectordb dimension {vectordb.dimension}"+ )+ if not vectordb.name or not vectordb.index_name:+ raise ValueError("vectordb collection name and index_name must not be empty")+ if embedding.hybrid and (embedding.dense or embedding.sparse):+ raise ValueError("embedding.hybrid cannot be combined with dense or sparse sections")+ sparse = embedding.hybrid is not None or embedding.sparse is not None+ if vectordb.sparse_weight < 0 or (vectordb.sparse_weight > 0 and not sparse):+ raise ValueError("vectordb.sparse_weight requires a sparse or hybrid embedding")+ if vectordb.backend in {"local", "cuvs", "http", "volcengine", "vikingdb"}:+ if vectordb.distance_metric not in {"cosine", "l2", "ip"}:+ raise ValueError("vectordb.distance_metric must be cosine, l2 or ip")+ if sparse and vectordb.backend == "cuvs" and vectordb.cuvs:+ if not vectordb.cuvs.fallback_to_native:+ raise ValueError("sparse/hybrid embedding requires cuvs.fallback_to_native")+ for mode in MODEL_SECTIONS:+ model = getattr(embedding, mode)+ if model is None:+ continue+ if model.input not in {"text", "multimodal"}:+ raise ValueError(f"embedding.{mode}.input must be text or multimodal")+ providers = (+ [credential.provider or model.provider for credential in model.credentials]+ if model.credentials+ else [model.provider]+ )+ if mode != "dense" and any(+ provider not in {"volcengine", "vikingdb"} for provider in providers+ ):+ raise ValueError(f"embedding.{mode} requires a provider supporting {mode} output")+ return vectordb.model_copy(update={"dimension": dimension})+++@dataclass(frozen=True)+class VectorRuntimeSettings:+ embedding: EmbeddingConfig+ vectordb: VectorDBBackendConfig+ embedding_profile: str+ dedicated_vectordb: bool+++class AccountVectorConfigResolver:+ """Resolve effective vector settings from paired Account/Cluster publications."""++ def __init__(self, manager):+ self._manager = manager++ async def resolve(self, account_id: str) -> VectorRuntimeSettings:+ if not account_id:+ raise ValueError("account_id is required for vector configuration")+ return await self._manager.resolve_account(account_id, vector_settings_from_view)+++def resolve_account_vector_settings(account: Any, cluster: Any) -> VectorRuntimeSettings:+ # Account and Cluster remain independent publications. Choosing Cluster+ # when an Account section is absent is vector-domain behavior, not generic+ # RuntimeField fallback. This path also keeps pre-materialization Account+ # documents working; new Account provisioning should snapshot defaults into+ # Account-owned settings instead of adding further runtime Cluster coupling.+ embedding = resolve_effective_embedding(cluster.embedding, account.embedding)+ vectordb = resolve_effective_vectordb(cluster.storage.vectordb, account.vectordb)+ if account.vectordb is None:+ vectordb = validate_vector_settings(cluster.embedding, vectordb)+ vectordb = validate_vector_settings(embedding, vectordb)+ identity = {}+ for mode in MODEL_SECTIONS:+ section = getattr(embedding, mode)+ if section is not None:+ identity[mode] = {+ "provider": section._effective_provider(),+ "model": section.model,+ "credentials": [+ {+ "provider": credential.provider or section.provider,+ "model": credential.model or section.model,+ }+ for credential in section.credentials+ ],+ "dimension": section.get_effective_dimension(),+ "input": section.input,+ "query_param": section.query_param,+ "document_param": section.document_param,+ "version": section.version,+ "extra_body": section.extra_body,+ "model_path": section.model_path,+ "enable_fusion": section.enable_fusion,+ "res_level": section.res_level,+ "max_video_frames": section.max_video_frames,+ }+ profile = hashlib.sha256(json.dumps(identity, sort_keys=True).encode()).hexdigest()+ return VectorRuntimeSettings(embedding, vectordb, profile, account.vectordb is not None)+++def vector_settings_from_view(view) -> VectorRuntimeSettings:+ return resolve_account_vector_settings(view.account, view.cluster)+++def validate_account_vector_candidate(context: AccountCandidateContext) -> None:+ """Check the effective pair and preserve an existing Account's vector contract."""+ after = vector_settings_from_view(context.new_view).embedding+ if context.creating or context.old_view is None:+ return+ if context.changed_sections is not None and "embedding" not in context.changed_sections:+ return+ before = vector_settings_from_view(context.old_view).embedding+ for mode in MODEL_SECTIONS:+ if (getattr(before, mode) is None) != (getattr(after, mode) is None):+ raise ConfigPatchError("embedding mode is create-only", path=("embedding", mode))+ if before.dimension != after.dimension:+ raise ConfigPatchError("embedding dimension is create-only", path=("embedding",))diff --git a/openviking/config/vlm.py b/openviking/config/vlm.pynew file mode 100644index 000000000..21bb757a8--- /dev/null+++ b/openviking/config/vlm.py@@ -0,0 +1,432 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Account-aware VLM selection and call-scoped client lifecycle."""++from __future__ import annotations++import asyncio+import inspect+import threading+from dataclasses import dataclass+from typing import Any, Awaitable, Callable, Literal, Protocol++from openviking.config.account_config import AccountConfig+from openviking.config.manager import ConfigChangeEvent, RuntimeConfigManager+from openviking.config.scope import ScopeKind+from openviking.models.vlm.token_usage import TokenUsageTracker+from openviking_cli.utils.config import get_openviking_config+from openviking_cli.utils.config.open_viking_config import OpenVikingConfig+from openviking_cli.utils.config.vlm_config import VLMConfig++VLMRole = Literal["vlm", "query_planner"]+_RequestKey = tuple[str, VLMRole]+_ResourceKey = tuple[str, ...]+++class VLMHandle(Protocol):+ """Async model-call surface returned by a resolver."""++ model: str | None+ max_concurrent: int+ max_tokens: int | None+ thinking: bool+ token_tracker: TokenUsageTracker++ def is_available(self) -> bool: ...++ def supports_media(self, *args, **kwargs) -> bool | Awaitable[bool]: ...++ async def get_completion_async(self, *args, **kwargs): ...++ async def get_vision_completion_async(self, *args, **kwargs): ...++ async def get_media_completion_async(self, *args, **kwargs): ...+++class VLMResolver(Protocol):+ """Resolve a call-safe model handle for one Account."""++ async def get_vlm(self, account_id: str) -> VLMHandle: ...++ async def get_query_planner(self, account_id: str) -> VLMHandle: ...++ async def has_dedicated_query_planner(self, account_id: str) -> bool: ...+++@dataclass(frozen=True)+class _VLMView:+ account: AccountConfig+ cluster: OpenVikingConfig+++@dataclass(frozen=True)+class _VLMSelection:+ key: _ResourceKey+ config: VLMConfig+ tracker: TokenUsageTracker+++@dataclass(eq=False)+class _VLMResource:+ key: _ResourceKey+ config: VLMConfig+ tracker: TokenUsageTracker+ bindings: int = 0+ borrowers: int = 0+ retired: bool = False+ closed: bool = False++ def close_if_idle(self) -> None:+ if self.retired and not self.borrowers and not self.closed:+ self.closed = True+ self.config.close()+++class AccountBoundVLM:+ """Long-lived Account proxy; every model call uses the current resource."""++ def __init__(+ self,+ provider: "AccountVLMProvider",+ account_id: str,+ role: VLMRole,+ config: VLMConfig,+ tracker: TokenUsageTracker,+ ) -> None:+ self._provider = provider+ self._account_id = account_id+ self._role = role+ self._settings = self._copy_settings(config)+ self._tracker = tracker++ @staticmethod+ def _copy_settings(config: VLMConfig) -> VLMConfig:+ return VLMConfig.model_validate(config.model_dump(mode="python"))++ def _refresh(self, resource: _VLMResource) -> None:+ self._settings = self._copy_settings(resource.config)+ self._tracker = resource.tracker++ def __getattr__(self, name: str) -> Any:+ if name in VLMConfig.model_fields:+ return getattr(self._settings, name)+ raise AttributeError(name)++ @property+ def token_tracker(self) -> TokenUsageTracker:+ return self._tracker++ def get_token_usage(self) -> dict:+ return self._tracker.to_dict()++ def reset_token_usage(self) -> None:+ self._tracker.reset()++ def is_available(self) -> bool:+ return self._settings.is_available()++ async def supports_media(self, *args, **kwargs) -> bool:+ return await self._provider._invoke_maybe_async(+ self,+ "supports_media",+ *args,+ **kwargs,+ )++ async def get_completion_async(self, *args, **kwargs):+ return await self._provider._invoke(+ self,+ "get_completion_async",+ *args,+ **kwargs,+ )++ async def get_vision_completion_async(self, *args, **kwargs):+ return await self._provider._invoke(+ self,+ "get_vision_completion_async",+ *args,+ **kwargs,+ )++ async def get_media_completion_async(self, *args, **kwargs):+ return await self._provider._invoke(+ self,+ "get_media_completion_async",+ *args,+ **kwargs,+ )+++class AccountVLMProvider:+ """Select, cache, borrow and retire Account VLM resources.++ Cluster fallback keeps pre-materialization Account documents working.+ New provisioning should persist complete Account-owned model settings+ instead of introducing additional runtime dependencies on Cluster config.+ """++ def __init__(+ self,+ manager: RuntimeConfigManager[OpenVikingConfig, AccountConfig],+ ) -> None:+ self._manager = manager+ self._bindings: dict[_RequestKey, _VLMResource] = {}+ self._resources: dict[_ResourceKey, _VLMResource] = {}+ self._retired: set[_VLMResource] = set()+ self._usage: dict[str, TokenUsageTracker] = {}+ self._planner_usage: dict[str, TokenUsageTracker] = {}+ self._lock = threading.RLock()+ self._epoch = 0+ self._closed = False+ manager.add_update_consumer(+ scope=ScopeKind.ACCOUNT,+ sections={"vlm", "query_planner"},+ consumer=self._on_account_config_change,+ )+ manager.add_update_consumer(+ scope=ScopeKind.CLUSTER,+ sections={"vlm", "query_planner"},+ consumer=self._on_cluster_config_change,+ )++ async def get_vlm(self, account_id: str) -> AccountBoundVLM:+ return await self._new_handle(account_id, "vlm")++ async def get_query_planner(self, account_id: str) -> AccountBoundVLM:+ return await self._new_handle(account_id, "query_planner")++ async def _new_handle(self, account_id: str, role: VLMRole) -> AccountBoundVLM:+ resource = await self._resource_for(account_id, role)+ return AccountBoundVLM(self, account_id, role, resource.config, resource.tracker)++ async def _view(self, account_id: str) -> _VLMView:+ if not account_id:+ raise ValueError("account_id is required")+ return await self._manager.resolve_account(+ account_id,+ lambda view: _VLMView(account=view.account, cluster=view.cluster),+ )++ async def _select(self, account_id: str, role: VLMRole) -> _VLMSelection:+ view = await self._view(account_id)+ if role == "vlm":+ return self._select_vlm(account_id, view)+ return self._select_query_planner(account_id, view)++ def _account_tracker(+ self,+ trackers: dict[str, TokenUsageTracker],+ account_id: str,+ ) -> TokenUsageTracker:+ with self._lock:+ return trackers.setdefault(account_id, TokenUsageTracker())++ def _select_vlm(self, account_id: str, view: _VLMView) -> _VLMSelection:+ account_vlm = view.account.vlm+ if account_vlm is None:+ return _VLMSelection(+ ("account", account_id, "vlm"),+ view.cluster.vlm,+ self._account_tracker(self._usage, account_id),+ )+ return _VLMSelection(+ ("account", account_id, "vlm"),+ account_vlm.to_vlm_config(view.cluster.vlm),+ self._account_tracker(self._usage, account_id),+ )++ def _select_query_planner(+ self,+ account_id: str,+ view: _VLMView,+ ) -> _VLMSelection:+ if view.account.query_planner is not None:+ return _VLMSelection(+ ("account", account_id, "query_planner"),+ view.account.query_planner.to_vlm_config(view.cluster.get_query_planner()),+ self._account_tracker(self._planner_usage, account_id),+ )+ if view.account.vlm is not None:+ return self._select_vlm(account_id, view)+ if view.cluster.query_planner is not None and view.cluster.query_planner._has_any_config():+ return _VLMSelection(+ ("account", account_id, "query_planner"),+ view.cluster.query_planner,+ self._account_tracker(self._planner_usage, account_id),+ )+ return self._select_vlm(account_id, view)++ @staticmethod+ def _create_resource(selection: _VLMSelection) -> _VLMResource:+ config = VLMConfig.model_validate(selection.config.model_dump(mode="python"))+ config.set_token_usage_tracker(selection.tracker)+ return _VLMResource(selection.key, config, selection.tracker)++ async def _resource_for(self, account_id: str, role: VLMRole) -> _VLMResource:+ request_key = (account_id, role)+ while True:+ with self._lock:+ if self._closed:+ raise RuntimeError("Account VLM provider is closed")+ cached = self._bindings.get(request_key)+ if cached is not None:+ return cached+ epoch = self._epoch++ selection = await self._select(account_id, role)+ candidate = self._create_resource(selection)+ with self._lock:+ if self._closed:+ candidate.retired = True+ candidate.close_if_idle()+ raise RuntimeError("Account VLM provider is closed")+ if self._epoch != epoch:+ candidate.retired = True+ candidate.close_if_idle()+ continue+ resource = self._resources.get(selection.key)+ if resource is None:+ resource = candidate+ self._resources[selection.key] = resource+ else:+ candidate.retired = True+ candidate.close_if_idle()+ existing = self._bindings.get(request_key)+ if existing is not None:+ return existing+ self._bindings[request_key] = resource+ resource.bindings += 1+ return resource++ async def _borrow(self, account_id: str, role: VLMRole) -> _VLMResource:+ request_key = (account_id, role)+ while True:+ resource = await self._resource_for(account_id, role)+ with self._lock:+ if self._closed:+ raise RuntimeError("Account VLM provider is closed")+ if self._bindings.get(request_key) is not resource or resource.retired:+ continue+ resource.borrowers += 1+ return resource++ async def _invoke(+ self,+ handle: AccountBoundVLM,+ method: str,+ *args,+ **kwargs,+ ):+ resource = await self._borrow(handle._account_id, handle._role)+ handle._refresh(resource)+ try:+ return await getattr(resource.config, method)(*args, **kwargs)+ finally:+ self._release(resource)++ async def _invoke_maybe_async(+ self,+ handle: AccountBoundVLM,+ method: str,+ *args,+ **kwargs,+ ):+ resource = await self._borrow(handle._account_id, handle._role)+ handle._refresh(resource)+ try:+ result = getattr(resource.config, method)(*args, **kwargs)+ return await result if inspect.isawaitable(result) else result+ finally:+ self._release(resource)++ def _release(self, resource: _VLMResource) -> None:+ with self._lock:+ resource.borrowers -= 1+ resource.close_if_idle()+ if resource.closed:+ self._retired.discard(resource)++ async def _on_account_config_change(self, event: ConfigChangeEvent) -> None:+ account_id = event.scope.key+ if account_id is not None:+ self._invalidate(lambda key: key[0] == account_id)++ async def _on_cluster_config_change(self, event: ConfigChangeEvent) -> None:+ del event+ self._invalidate(lambda _key: True)++ def _invalidate(self, matches: Callable[[_RequestKey], bool]) -> None:+ with self._lock:+ self._epoch += 1+ removed = [+ self._bindings.pop(key)+ for key in list(self._bindings)+ if matches(key)+ ]+ for resource in removed:+ resource.bindings -= 1+ if resource.bindings:+ continue+ self._resources.pop(resource.key, None)+ resource.retired = True+ self._retired.add(resource)+ resource.close_if_idle()+ if resource.closed:+ self._retired.discard(resource)++ async def close(self) -> None:+ with self._lock:+ self._closed = True+ self._invalidate(lambda _key: True)+ while True:+ with self._lock:+ if not self._retired:+ return+ await asyncio.sleep(0.01)++ def get_token_usage(self, account_id: str) -> dict:+ with self._lock:+ tracker = self._usage.get(account_id, TokenUsageTracker())+ return tracker.to_dict()++ def get_node_token_usage(self) -> dict:+ with self._lock:+ trackers = (*self._usage.values(), *self._planner_usage.values())+ return TokenUsageTracker.merge(*trackers).to_dict()++ async def has_dedicated_query_planner(self, account_id: str) -> bool:+ view = await self._view(account_id)+ if view.account.query_planner is not None or view.account.vlm is not None:+ return True+ planner = view.cluster.query_planner+ return planner is not None and planner._has_any_config()+++class ClusterVLMResolver:+ """Resolve static Cluster model handles for offline and standalone flows."""++ def __init__(+ self,+ config_provider: Callable[[], OpenVikingConfig] = get_openviking_config,+ ) -> None:+ self._config_provider = config_provider++ def get_vlm_sync(self) -> VLMConfig:+ return self._config_provider().vlm++ def get_query_planner_sync(self) -> VLMConfig:+ return self._config_provider().get_query_planner()++ async def get_vlm(self, account_id: str) -> VLMConfig:+ del account_id+ return self.get_vlm_sync()++ async def get_query_planner(self, account_id: str) -> VLMConfig:+ del account_id+ return self.get_query_planner_sync()++ async def has_dedicated_query_planner(self, account_id: str) -> bool:+ del account_id+ planner = self._config_provider().query_planner+ return planner is not None and planner._has_any_config()diff --git a/openviking/eval/ragas/__init__.py b/openviking/eval/ragas/__init__.pyindex fb08122d1..771b6ff0c 100644--- a/openviking/eval/ragas/__init__.py+++ b/openviking/eval/ragas/__init__.py@@ -142,7 +142,9 @@ def _create_ragas_llm_from_config() -> Optional[Any]:logger.debug("OpenViking config file not found, skipping VLM config")return None- vlm_config = config.vlm+ from openviking.config.vlm import ClusterVLMResolver++ vlm_config = ClusterVLMResolver(lambda: config).get_vlm_sync()if not vlm_config.is_available():logger.warning(diff --git a/openviking/eval/ragas/pipeline.py b/openviking/eval/ragas/pipeline.pyindex 18ac658be..fb2cde55b 100644--- a/openviking/eval/ragas/pipeline.py+++ b/openviking/eval/ragas/pipeline.py@@ -52,10 +52,16 @@ class RAGQueryPipeline:def _get_llm(self):"""Lazy initialization of LLM for answer generation."""if self._llm is None:- from openviking_cli.utils.config import get_openviking_config+ from openviking.config.vlm import ClusterVLMResolver+ from openviking_cli.utils.config.open_viking_config import (+ OpenVikingConfigSingleton,+ )- config = get_openviking_config()- self._llm = config.vlm+ config_path = Path(self.config_path).expanduser()+ if not config_path.is_file():+ raise FileNotFoundError(f"VLM config file does not exist: {config_path}")+ config = OpenVikingConfigSingleton.initialize(config_path=str(config_path))+ self._llm = ClusterVLMResolver(lambda: config).get_vlm_sync()return self._llmdef add_documents(diff --git a/openviking/eval/ragas/playback.py b/openviking/eval/ragas/playback.pyindex f41725dd4..2821b1496 100644--- a/openviking/eval/ragas/playback.py+++ b/openviking/eval/ragas/playback.py@@ -213,6 +213,7 @@ class IOPlayback:os.environ[OPENVIKING_CONFIG_ENV] = self.config_file+ from openviking.config.vlm import ClusterVLMResolverfrom openviking.storage.viking_fs import init_viking_fsfrom openviking.storage.viking_vector_index_backend import VikingVectorIndexBackendfrom openviking.utils.agfs_utils import RagfsBindingConfig, create_agfs_client@@ -243,6 +244,7 @@ class IOPlayback:self._viking_fs = init_viking_fs(agfs=agfs_client,vector_store=vector_store,+ vlm_resolver=ClusterVLMResolver(lambda: config),)self._vector_store = vector_storediff --git a/openviking/metrics/datasources/model_usage.py b/openviking/metrics/datasources/model_usage.pyindex 3e16d4695..6ad8cbf9d 100644--- a/openviking/metrics/datasources/model_usage.py+++ b/openviking/metrics/datasources/model_usage.py@@ -8,11 +8,16 @@ This file provides two categories of DataSource APIs:1) DomainStats (pull): `ModelUsageDataSource.read_model_usage()` reads aggregated cumulativeusage from in-process model instances / shared token trackers. This is used by`ModelUsageCollector` which converts cumulative stats into Prometheus Counters via deltas.+ The Service-backed pull snapshot is node-scoped: Account and Cluster trackers are aggregated+ without adding an Account label. Standalone callers without a Service retain Cluster fallback.2) Event (push): `VLMEventDataSource`, `EmbeddingEventDataSource`, and`RerankEventDataSource` emit per-call events.These events are published to the shared observability event bus and consumed by metricscollectors and Usage/Audit subscribers.+Account attribution for VLM usage is provided by the event-based `openviking_vlm_*` metrics,+which carry the Account context on each call. The pull metrics intentionally remain aggregate.+Note: DataSources are not allowed to write into MetricRegistry directly in this architecture.They only emit events or expose read APIs. Collectors are the only writers."""@@ -80,19 +85,38 @@ class ModelUsageDataSource(DomainStatsMetricDataSource):}try:- vlm = config.vlm.get_vlm_instance()+ if self._service is None:+ from openviking.config.vlm import ClusterVLMResolver++ vlm = ClusterVLMResolver(lambda: config).get_vlm_sync().get_vlm_instance()+ usage = vlm.get_token_usage()+ else:+ resolver = getattr(self._service, "vlm_resolver", None)+ if resolver is None:+ raise RuntimeError("Account VLM resolver is not initialized")+ usage = resolver.get_node_token_usage()result["vlm"] = {"available": True,- "usage_by_model": _extract_usage_by_model(vlm.get_token_usage(), self),+ "usage_by_model": _extract_usage_by_model(usage, self),}except Exception:passtry:- embedder = config.embedding.get_embedder()+ from openviking.models.embedder.base import _get_token_tracker++ if self._service is None:+ # Keep the legacy aggregate tracker only for standalone callers+ # that do not provide a Service/AccountEmbeddingProvider.+ usage = _get_token_tracker().to_dict()+ else:+ provider = getattr(self._service, "embedding_provider", None)+ if provider is None:+ raise RuntimeError("Account embedding provider is not initialized")+ usage = provider.get_total_token_usage()result["embedding"] = {"available": True,- "usage_by_model": _extract_usage_by_model(embedder.get_token_usage(), self),+ "usage_by_model": _extract_usage_by_model(usage, self),}except Exception:passdiff --git a/openviking/metrics/datasources/probes.py b/openviking/metrics/datasources/probes.pyindex 972089ac9..8a749240b 100644--- a/openviking/metrics/datasources/probes.py+++ b/openviking/metrics/datasources/probes.py@@ -118,9 +118,11 @@ class ModelProviderProbeDataSource(ProbeMetricDataSource):"""def _probe() -> tuple[str, bool]:- config = self._config_provider()- provider = str(getattr(getattr(config, "vlm", None), "provider", "") or "unknown")- _ = config.vlm.get_vlm_instance()+ from openviking.config.vlm import ClusterVLMResolver++ vlm = ClusterVLMResolver(self._config_provider).get_vlm_sync()+ provider = str(getattr(vlm, "provider", "") or "unknown")+ _ = vlm.get_vlm_instance()return provider, Truereturn self.safe_tuple_probe("provider", _probe, default_name="unknown")diff --git a/openviking/models/embedder/base.py b/openviking/models/embedder/base.pyindex d036a1dba..12cfbe284 100644--- a/openviking/models/embedder/base.py+++ b/openviking/models/embedder/base.py@@ -7,10 +7,10 @@ import randomimport timeimport weakreffrom abc import ABC, abstractmethod-from contextlib import contextmanager+from contextlib import asynccontextmanagerfrom dataclasses import dataclassfrom threading import Lock-from typing import Any, Awaitable, Callable, Dict, Iterator, List, Optional, TypeVar, Union+from typing import Any, AsyncIterator, Awaitable, Callable, Dict, List, Optional, TypeVar, Unionfrom openviking.telemetry import get_current_telemetryfrom openviking.utils.embedding_input import (@@ -29,34 +29,80 @@ from openviking_cli.utils import get_loggerT = TypeVar("T")logger = get_logger(__name__)-# Request-scoped cache for query embeddings. A request handler installs the-# scope once by setting a fresh dict; every task spawned inside that request-# (the context assembler fans finds out via asyncio.gather) then shares the-# same dict object by reference, so repeated embeddings of the same query text-# within one request are served from the first in-flight embed.-# The dedup relies on the synchronous check-create-store block below running on-# a single event loop; if an embed path ever moves into a thread pool, that-# invariant breaks and the cache would need a lock.-query_embed_cache_var: contextvars.ContextVar[Optional[Dict[Any, "asyncio.Task"]]] = (++@dataclass+class _SharedQueryEmbedding:+ task: "asyncio.Task[EmbedResult]"+ waiters: int = 0+++class QueryEmbeddingCache(dict[Any, _SharedQueryEmbedding]):+ """Own in-flight query work for one request and track its waiters."""++ def __init__(self) -> None:+ super().__init__()+ self._pending_tasks: set[asyncio.Task] = set()++ async def run(+ self,+ key: Any,+ factory: Callable[[], Awaitable["EmbedResult"]],+ ) -> "EmbedResult":+ entry = self.get(key)+ if entry is None:+ entry = _SharedQueryEmbedding(asyncio.create_task(factory()))+ self[key] = entry+ entry.task.add_done_callback(lambda done: self._discard_unsuccessful(key, entry, done))++ entry.waiters += 1+ try:+ return await asyncio.shield(entry.task)+ finally:+ entry.waiters -= 1+ if entry.waiters == 0 and not entry.task.done():+ if self.get(key) is entry:+ self.pop(key, None)+ self._pending_tasks.add(entry.task)+ entry.task.cancel()++ def _discard_unsuccessful(+ self,+ key: Any,+ entry: _SharedQueryEmbedding,+ done: "asyncio.Task[EmbedResult]",+ ) -> None:+ self._pending_tasks.discard(done)+ if (done.cancelled() or done.exception() is not None) and self.get(key) is entry:+ self.pop(key, None)++ async def close(self) -> None:+ pending = {+ entry.task for entry in self.values() if not entry.task.done()+ } | {task for task in self._pending_tasks if not task.done()}+ for task in pending:+ task.cancel()+ if pending:+ await asyncio.gather(*pending, return_exceptions=True)+ self.clear()+ self._pending_tasks.clear()+++# Request handlers install one cache around the fan-out that issues sibling+# finds. Context copying gives every child task the same cache instance.+query_embed_cache_var: contextvars.ContextVar[Optional[QueryEmbeddingCache]] = (contextvars.ContextVar("ov_query_embed_cache", default=None))-@contextmanager-def query_embed_cache_scope() -> Iterator[None]:- """Install the request-scoped query embedding cache for one request body.-- The scope must wrap the fan-out that spawns the sibling find tasks, not- the shared find chokepoint below it: asyncio.gather copies the current- context when it wraps each sibling in a task, so a scope installed by the- first find to run would stay invisible to its siblings and the dedup would- collapse. Callers that fan finds out should wrap that fan-out; callers- with no fan-out need no scope.- """- token = query_embed_cache_var.set({})+@asynccontextmanager+async def query_embed_cache_scope() -> AsyncIterator[None]:+ """Install and clean up the request-scoped query embedding cache."""+ cache = QueryEmbeddingCache()+ token = query_embed_cache_var.set(cache)try:yieldfinally:+ await cache.close()query_embed_cache_var.reset(token)@@ -132,67 +178,45 @@ async def embed_compat(embedders that do not support images, so all embedders can be called the sameway."""+ from openviking.config.embedding import AccountBoundEmbedderfrom openviking.telemetry import bind_telemetry_stage+ if isinstance(embedder, AccountBoundEmbedder):+ if is_query:+ key = await embedder.query_embedding_cache_key(content)+ return await _embed_from_request_cache(+ key,+ lambda: embedder.embed_compatible(content, is_query=True),+ )+ return await embedder.embed_compatible(content, is_query=is_query)stage = "embed_query" if is_query else "embed_resource"embedding_input = embedder.prepare_embedding_input(content)if is_query:- cached = await _embed_from_request_cache(embedder, embedding_input, stage)- if cached is not None:- return cached+ return await _embed_from_request_cache(+ _query_cache_key(embedder, embedding_input),+ lambda: _embed_with_stage(embedder, embedding_input, stage),+ )with bind_telemetry_stage(stage):return await embedder.embed_async(embedding_input, is_query=is_query)async def _embed_from_request_cache(- embedder: "EmbedderBase", embedding_input: "EmbeddingInput", stage: str-) -> Optional["EmbedResult"]:- """Serve a query embed from the request-scoped cache, deduplicating in-flight embeds.+ key: Any, factory: Callable[[], Awaitable["EmbedResult"]]+) -> "EmbedResult":+ """Run a query embed directly or through the current request cache."""+ cache = query_embed_cache_var.get()+ if cache is None:+ return await factory()+ return await cache.run(key, factory)- Returns None when the request scope is not installed, so the caller falls back- to the plain embed path.- """++async def _embed_with_stage(+ embedder: "EmbedderBase", embedding_input: "EmbeddingInput", stage: str+) -> "EmbedResult":from openviking.telemetry import bind_telemetry_stage- cache = query_embed_cache_var.get()- if cache is None:- return None- key = _query_cache_key(embedder, embedding_input)- pending = cache.get(key)- if pending is None:- # Create the task synchronously and store it before the first await:- # sibling tasks of the same request then see this entry and await the- # same in-flight embed instead of starting their own.- with bind_telemetry_stage(stage):- pending = asyncio.create_task(embedder.embed_async(embedding_input, is_query=True))- cache[key] = pending- try:- # Shield the shared task: cancelling a waiter propagates to the future- # it is blocked on (Task.cancel cancels its _fut_waiter), so without- # the shield a cancelled waiter would kill the embed every sibling is- # waiting for and leave the key pointing at a cancelled task.- return await asyncio.shield(pending)- except asyncio.CancelledError:- if pending.cancelled():- # The shared embed itself was cancelled: evict the dead entry so- # the next find of this text starts a fresh embed instead of- # awaiting the cancelled task.- cache.pop(key, None)- else:- # Only this waiter was cancelled; the shared embed lives on. If it- # then fails with nobody left waiting on it, evict the stale entry- # and consume the exception so asyncio does not log- # "Task exception was never retrieved".- def _evict_if_failed(done: "asyncio.Task") -> None:- if not done.cancelled() and done.exception() is not None:- cache.pop(key, None)-- pending.add_done_callback(_evict_if_failed)- raise- except Exception:- # A failed embed must not poison the rest of the request.- cache.pop(key, None)- raise+ with bind_telemetry_stage(stage):+ return await embedder.embed_async(embedding_input, is_query=True)def truncate_and_normalize(embedding: List[float], dimension: Optional[int]) -> List[float]:@@ -364,7 +388,9 @@ class EmbedderBase(ABC):operation_name: str,) -> T:async def _wrapped() -> T:- semaphore = _get_async_embed_semaphore(self.max_concurrent)+ semaphore = getattr(self, "_account_semaphore", None)+ if semaphore is None:+ semaphore = _get_async_embed_semaphore(self.max_concurrent)wait_started = time.monotonic()await semaphore.acquire()wait_elapsed = time.monotonic() - wait_started@@ -461,7 +487,8 @@ class EmbedderBase(ABC):duration_seconds=self._resolve_metrics_duration_seconds(duration_seconds),prompt_tokens=int(prompt_tokens),completion_tokens=int(completion_tokens),- account_id=root_context.account_id if root_context is not None else None,+ account_id=getattr(self, "_account_id", None)+ or (root_context.account_id if root_context is not None else None),)except Exception as e:# Metrics must never break embedding execution.@@ -645,10 +672,20 @@ class CompositeHybridEmbedder(HybridEmbedderBase):async def embed_async(self, content: "EmbeddingInput", is_query: bool = False) -> EmbedResult:dense_input = self.dense_embedder.prepare_embedding_input(content)sparse_input = self.sparse_embedder.prepare_embedding_input(content)- dense_res, sparse_res = await asyncio.gather(+ calls = asyncio.gather(self.dense_embedder.embed_async(dense_input, is_query=is_query),self.sparse_embedder.embed_async(sparse_input, is_query=is_query),+ return_exceptions=True,)+ # Keep the parent borrow alive until every child has stopped. Shielding+ # also lets cancellation wait for providers with asynchronous cleanup.+ from openviking.service.task_tracker_concurrency import run_to_completion++ results = await run_to_completion(lambda: calls)+ for result in results:+ if isinstance(result, BaseException):+ raise result+ dense_res, sparse_res = resultsreturn EmbedResult(dense_vector=dense_res.dense_vector, sparse_vector=sparse_res.sparse_vector)diff --git a/openviking/models/vlm/base.py b/openviking/models/vlm/base.pyindex fa7bd1b72..ec52d012d 100644--- a/openviking/models/vlm/base.py+++ b/openviking/models/vlm/base.py@@ -755,8 +755,12 @@ class FailoverVLM(VLMBase):"""Get combined token usage from both primary and backup instances."""from openviking.models.vlm.token_usage import TokenUsageTracker+ primary_tracker = self.primary.token_tracker+ backup_tracker = self.backup.token_tracker+ if primary_tracker is backup_tracker:+ return primary_tracker.to_dict()merged_tracker = TokenUsageTracker.merge(- self.primary.token_tracker, self.backup.token_tracker+ primary_tracker, backup_tracker)return merged_tracker.to_dict()@@ -801,11 +805,24 @@ class MultiCredentialVLM(VLMBase):if len(vlm_instances) != len(credential_ids):raise ValueError("vlm_instances and credential_ids must have the same length")- # Use the first instance's config as base+ # Expose the common runtime behavior expected by callers that inspect+ # the wrapper as a VLMBase. Provider-specific identity remains on each+ # credential instance.first = vlm_instances[0]+ configured_token_limits = [+ instance.max_tokens+ for instance in vlm_instances+ if isinstance(instance.max_tokens, int)+ ]config = {"model": first.model,"provider": first.provider,+ "temperature": first.temperature,+ "max_retries": first.max_retries,+ "timeout": first.timeout,+ "max_tokens": (+ min(configured_token_limits) if configured_token_limits else None+ ),"thinking": first.thinking,}super().__init__(config)@@ -1126,9 +1143,11 @@ class MultiCredentialVLM(VLMBase):if not self._vlm_instances:return {}- merged_tracker = self._vlm_instances[0].token_tracker- for instance in self._vlm_instances[1:]:- merged_tracker = TokenUsageTracker.merge(merged_tracker, instance.token_tracker)+ trackers = [instance.token_tracker for instance in self._vlm_instances]+ if all(tracker is trackers[0] for tracker in trackers[1:]):+ return trackers[0].to_dict()++ merged_tracker = TokenUsageTracker.merge(*trackers)return merged_tracker.to_dict()diff --git a/openviking/models/vlm/token_usage.py b/openviking/models/vlm/token_usage.pyindex 44efcc7f1..359475f21 100644--- a/openviking/models/vlm/token_usage.py+++ b/openviking/models/vlm/token_usage.py@@ -2,11 +2,13 @@# SPDX-License-Identifier: AGPL-3.0"""VLM Token usage monitoring data structures"""+import threadingfrom dataclasses import dataclass, fieldfrom datetime import datetime+from functools import wrapsfrom typing import Dict, Optional-from openviking.utils.time_utils import format_iso8601+from openviking.utils.time_utils import format_iso8601, parse_iso_datetime@dataclass@@ -126,12 +128,33 @@ class ModelTokenUsage:return f"ModelTokenUsage(model={self.model_name}, total={self.total_usage.total_tokens}, providers=[{providers}])"+def _locked(method):+ @wraps(method)+ def call(self, *args, **kwargs):+ with self._lock:+ return method(self, *args, **kwargs)++ return call+++def _add_usage(total: TokenUsage, usage: TokenUsage) -> None:+ total.last_updated = (+ max(total.last_updated, usage.last_updated) if total.call_count else usage.last_updated+ )+ total.prompt_tokens += usage.prompt_tokens+ total.completion_tokens += usage.completion_tokens+ total.total_tokens += usage.total_tokens+ total.call_count += usage.call_count++class TokenUsageTracker:"""Token usage tracker"""def __init__(self):self._usage_by_model: Dict[str, ModelTokenUsage] = {}+ self._lock = threading.RLock()+ @_lockeddef update(self, model_name: str, provider: str, prompt_tokens: int, completion_tokens: int) -> None:@@ -148,6 +171,7 @@ class TokenUsageTracker:self._usage_by_model[model_name].update(provider, prompt_tokens, completion_tokens)+ @_lockeddef get_model_usage(self, model_name: str) -> Optional[ModelTokenUsage]:"""Get token usage for specified model@@ -159,6 +183,7 @@ class TokenUsageTracker:"""return self._usage_by_model.get(model_name)+ @_lockeddef get_all_usage(self) -> Dict[str, ModelTokenUsage]:"""Get token usage for all models@@ -167,6 +192,7 @@ class TokenUsageTracker:"""return self._usage_by_model.copy()+ @_lockeddef get_total_usage(self) -> TokenUsage:"""Get total token usage@@ -175,17 +201,16 @@ class TokenUsageTracker:"""total = TokenUsage()for model_usage in self._usage_by_model.values():- total.prompt_tokens += model_usage.total_usage.prompt_tokens- total.completion_tokens += model_usage.total_usage.completion_tokens-- total.total_tokens += model_usage.total_usage.total_tokens+ _add_usage(total, model_usage.total_usage)return total+ @_lockeddef reset(self) -> None:"""Reset all token usage statistics"""self._usage_by_model.clear()+ @_lockeddef to_dict(self) -> Dict:"""Convert to dictionary format@@ -202,6 +227,7 @@ class TokenUsageTracker:return result+ @_lockeddef __str__(self) -> str:models = ", ".join([@@ -225,20 +251,20 @@ class TokenUsageTracker:merged = TokenUsageTracker()for tracker in trackers:- for model_name, model_usage in tracker._usage_by_model.items():- for provider_name, provider_usage in model_usage.usage_by_provider.items():- merged.update(- model_name=model_name,- provider=provider_name,- prompt_tokens=provider_usage.prompt_tokens,- completion_tokens=provider_usage.completion_tokens,+ # Snapshot under the writer's lock; never iterate a live model map.+ for model_name, model_usage in tracker.to_dict()["usage_by_model"].items():+ model = merged._usage_by_model.setdefault(model_name, ModelTokenUsage(model_name))+ for provider_name, counts in model_usage["usage_by_provider"].items():+ usage = TokenUsage(+ **{+ **counts,+ "last_updated": parse_iso_datetime(counts["last_updated"]).replace(+ tzinfo=None+ ),+ })- # Update call count (update() only increments by 1)- if provider_usage.call_count > 1:- merged_model = merged._usage_by_model[model_name]- merged_provider = merged_model.usage_by_provider[provider_name]- merged_provider.call_count = provider_usage.call_count- # Update last_updated- merged_provider.last_updated = provider_usage.last_updated+ provider = model.usage_by_provider.setdefault(provider_name, TokenUsage())+ _add_usage(provider, usage)+ _add_usage(model.total_usage, usage)return mergeddiff --git a/openviking/parse/parsers/media/utils.py b/openviking/parse/parsers/media/utils.pyindex 3f85f9075..d77808116 100644--- a/openviking/parse/parsers/media/utils.py+++ b/openviking/parse/parsers/media/utils.py@@ -3,6 +3,7 @@"""Media-related utilities for OpenViking."""import asyncio+import inspectimport reimport tempfilefrom pathlib import Path@@ -18,6 +19,7 @@ from openviking_cli.utils.config import get_openviking_configfrom openviking_cli.utils.logger import get_loggerif TYPE_CHECKING:+ from openviking.config.vlm import VLMHandlefrom openviking.server.identity import RequestContextfrom .constants import (@@ -251,6 +253,8 @@ async def generate_image_summary(original_filename: str,llm_sem: Optional[asyncio.Semaphore] = None,ctx: Optional["RequestContext"] = None,+ *,+ vlm: "VLMHandle",) -> Dict[str, Any]:"""Generate summary for an image file using VLM.@@ -264,9 +268,10 @@ async def generate_image_summary(Returns:Dictionary with "name" and "summary" keys"""+ if vlm is None:+ raise ValueError("Image summary requires an explicitly resolved VLM")viking_fs = get_viking_fs()config = get_openviking_config()- vlm = config.vlmfile_name = original_filenametry:@@ -330,6 +335,8 @@ async def generate_audio_summary(original_filename: str,llm_sem: Optional[asyncio.Semaphore] = None,ctx: Optional["RequestContext"] = None,+ *,+ vlm: "VLMHandle",) -> Dict[str, Any]:"""Generate a normalized semantic summary for an audio file.@@ -348,6 +355,7 @@ async def generate_audio_summary("audio",llm_sem=llm_sem,ctx=ctx,+ vlm=vlm,)@@ -356,6 +364,8 @@ async def generate_video_summary(original_filename: str,llm_sem: Optional[asyncio.Semaphore] = None,ctx: Optional["RequestContext"] = None,+ *,+ vlm: "VLMHandle",) -> Dict[str, Any]:"""Generate a normalized semantic summary for a video file.@@ -374,6 +384,7 @@ async def generate_video_summary("video",llm_sem=llm_sem,ctx=ctx,+ vlm=vlm,)@@ -413,19 +424,25 @@ async def _generate_media_summary(media_type: str,llm_sem: Optional[asyncio.Semaphore] = None,ctx: Optional["RequestContext"] = None,+ *,+ vlm: "VLMHandle",) -> Dict[str, Any]:+ if vlm is None:+ raise ValueError(f"{media_type.title()} summary requires an explicitly resolved VLM")config = get_openviking_config()- vlm = config.vlmresult = {"name": original_filename, "summary": ""}viking_fs = get_viking_fs()stat = await viking_fs.stat(media_uri, ctx=ctx, skip_count=True)size_bytes = int((stat or {}).get("size", 0))- if not vlm.supports_media(+ supports_media = vlm.supports_media(media_type=media_type,filename=original_filename,size_bytes=size_bytes,- ):+ )+ if inspect.isawaitable(supports_media):+ supports_media = await supports_media+ if not supports_media:logger.info("Skipping unsupported or disabled %s understanding input: %s",media_type,diff --git a/openviking/parse/vlm.py b/openviking/parse/vlm.pyindex 589e81eb9..b4dca87c1 100644--- a/openviking/parse/vlm.py+++ b/openviking/parse/vlm.py@@ -6,6 +6,7 @@ from dataclasses import dataclassfrom pathlib import Pathfrom typing import Any, Dict, List, Union+from openviking.config.vlm import VLMHandlefrom openviking.prompts import render_promptfrom openviking_cli.utils.extractor import ImageInfo, TableInfofrom openviking_cli.utils.llm import parse_json_from_response@@ -43,18 +44,23 @@ class VLMProcessor:def __init__(self,+ *,+ vlm: VLMHandle,max_images_per_call: int = 10,max_sections_per_call: int = 20,):"""Initialize VLM processor."""+ if vlm is None:+ raise ValueError("VLMProcessor requires an explicitly resolved VLM")self.max_images_per_call = max_images_per_callself.max_sections_per_call = max_sections_per_call+ self._vlm = vlmdef _get_vlm(self):- """Get VLM singleton."""- from openviking_cli.utils.config import get_openviking_config-- return get_openviking_config().vlm+ """Return the explicitly resolved VLM configuration."""+ if self._vlm is None:+ raise RuntimeError("VLMProcessor requires an explicitly resolved VLM")+ return self._vlmasync def understand_image(self,diff --git a/openviking/privacy/skill_extractor.py b/openviking/privacy/skill_extractor.pyindex fe04647a6..c1d56bf34 100644--- a/openviking/privacy/skill_extractor.py+++ b/openviking/privacy/skill_extractor.py@@ -4,9 +4,9 @@from dataclasses import dataclass, field+from openviking.config.vlm import VLMHandlefrom openviking.privacy.skill_placeholder import placeholderize_skill_content_with_blocksfrom openviking.prompts import render_prompt-from openviking_cli.utils.config import get_openviking_configfrom openviking_cli.utils.llm import parse_json_from_response@@ -24,7 +24,10 @@ async def extract_skill_privacy_values(skill_name: str,skill_description: str,content: str,+ vlm: VLMHandle,) -> SkillPrivacyExtractionResult:+ if vlm is None:+ raise ValueError("Skill privacy extraction requires an explicitly resolved VLM")prompt = render_prompt("skill.privacy_extraction",{@@ -33,7 +36,7 @@ async def extract_skill_privacy_values("skill_content": content,},)- response = await get_openviking_config().vlm.get_completion_async(prompt)+ response = await vlm.get_completion_async(prompt)data = parse_json_from_response(response) or {}values: dict[str, str] = {}diff --git a/openviking/retrieve/context_assembler/expansion.py b/openviking/retrieve/context_assembler/expansion.pyindex 191d7f442..779400c89 100644--- a/openviking/retrieve/context_assembler/expansion.py+++ b/openviking/retrieve/context_assembler/expansion.py@@ -12,6 +12,7 @@ from __future__ import annotationsimport asynciofrom typing import Any, List, Tuple+from openviking.config.vlm import VLMHandlefrom openviking.retrieve.context_assembler.params import MAX_PLANNED_QUERIESfrom openviking.retrieve.intent_analyzer import IntentAnalyzerfrom openviking_cli.utils.config import get_openviking_config@@ -28,6 +29,7 @@ async def expand_queries(session: Any,mode: str = "auto",timeout_s: float | None = None,+ planner: VLMHandle | None = None,) -> Tuple[List[str], str]:"""Return ``(queries, status)`` with the original query always first."""if mode != "auto" or session is None:@@ -46,7 +48,12 @@ async def expand_queries(timeout = timeout_s or get_openviking_config().retrieval.recall_intent_timeout_stry:- analyzer = IntentAnalyzer(max_recent_messages=RECENT_MESSAGES)+ if planner is None:+ raise RuntimeError("Query expansion requires an explicitly resolved query planner")+ analyzer = IntentAnalyzer(+ max_recent_messages=RECENT_MESSAGES,+ query_planner=planner,+ )plan = await asyncio.wait_for(analyzer.analyze(compression_summary=summary,diff --git a/openviking/retrieve/context_assembler/pipeline.py b/openviking/retrieve/context_assembler/pipeline.pyindex 6fce2db04..1c98bc180 100644--- a/openviking/retrieve/context_assembler/pipeline.py+++ b/openviking/retrieve/context_assembler/pipeline.py@@ -65,12 +65,31 @@ async def assemble_context(expansion_mode = params.query_expansion if intent_enabled else "off"needs_session = bool(params.session_id) and (expansion_mode == "auto" or params.dedup_turns > 0)session = await _load_session(service, ctx, params.session_id) if needs_session else None+ resolver = getattr(service, "vlm_resolver", None)- queries, expansion_status = await expand_queries(- query=params.query,- session=session,- mode=expansion_mode,- )+ if expansion_mode == "auto" and session is not None:+ if resolver is None:+ raise RuntimeError(+ "Context assembly requires a VLM resolver for account-owned expansion"+ )+ try:+ expansion_planner = await resolver.get_query_planner(ctx.account_id)+ except Exception as exc:+ logger.warning("Account expansion planner unavailable: %s", exc)+ queries, expansion_status = [params.query], "failed"+ else:+ queries, expansion_status = await expand_queries(+ query=params.query,+ session=session,+ mode=expansion_mode,+ planner=expansion_planner,+ )+ else:+ queries, expansion_status = await expand_queries(+ query=params.query,+ session=session,+ mode=expansion_mode,+ )ledger = await RecallLedger.load(service=service,@@ -84,7 +103,7 @@ async def assemble_context(# The fan-out below embeds each planned query once per (query, target)# find, so wrap it in the request-scoped query embedding cache: sibling# finds share the first in-flight embed of each distinct query text.- with query_embed_cache_scope():+ async with query_embed_cache_scope():candidates, gather_stats = await gather_candidates(service=service,ctx=ctx,@@ -124,13 +143,32 @@ async def assemble_context(digest = ""rewrite_status = "off"rewrite_usage: Optional[Dict[str, int]] = None- if plan.entries and server_rewrite_enabled(params.rewrite):- digest, rewrite_status, rewrite_usage = await rewrite_context(- query=params.query,- rendered=rendered or render_context(plan.entries),- max_bullets=params.rewrite_max_bullets,- valid_uris=[entry.uri for entry in plan.entries],- )+ rewrite_enabled = server_rewrite_enabled(params.rewrite)+ if params.rewrite == "auto" and resolver is not None:+ try:+ rewrite_enabled = await resolver.has_dedicated_query_planner(ctx.account_id)+ except Exception as exc:+ logger.warning("Account rewrite planner unavailable: %s", exc)+ rewrite_enabled = False+ rewrite_status = "failed"+ if plan.entries and rewrite_enabled:+ if resolver is None:+ raise RuntimeError(+ "Context assembly requires a VLM resolver for account-owned rewrite"+ )+ try:+ planner = await resolver.get_query_planner(ctx.account_id)+ except Exception as exc:+ logger.warning("Account rewrite planner unavailable: %s", exc)+ rewrite_status = "failed"+ else:+ digest, rewrite_status, rewrite_usage = await rewrite_context(+ query=params.query,+ rendered=rendered or render_context(plan.entries),+ max_bullets=params.rewrite_max_bullets,+ valid_uris=[entry.uri for entry in plan.entries],+ planner=planner,+ )if rewrite_status == "no_relevant":rendered = ""diff --git a/openviking/retrieve/context_assembler/rewrite.py b/openviking/retrieve/context_assembler/rewrite.pyindex 06b623657..968e246a1 100644--- a/openviking/retrieve/context_assembler/rewrite.py+++ b/openviking/retrieve/context_assembler/rewrite.py@@ -12,6 +12,7 @@ import asyncioimport refrom typing import Any, Collection, Dict, Literal, Optional, Tuple+from openviking.config.vlm import VLMHandlefrom openviking.prompts import render_promptfrom openviking_cli.utils.config import get_openviking_configfrom openviking_cli.utils.logger import get_logger@@ -24,13 +25,11 @@ URI_PATTERN = re.compile(r"""viking://[^\s<>"')\]]+""")def server_rewrite_enabled(mode: bool | Literal["auto"]) -> bool:- """Resolve the API mode without constructing a model client."""- if mode is True:- return True- if mode != "auto":- return False- planner = get_openviking_config().query_planner- return planner is not None and planner._has_any_config()+ """Return whether rewrite was explicitly enabled.++ Account-aware ``auto`` resolution belongs to the caller's VLM resolver.+ """+ return mode is Truedef normalize_digest(@@ -66,10 +65,10 @@ def normalize_digest(return f"{DIGEST_HEADER}\n" + "\n".join(bullets)-def _usage_snapshot(planner: Any) -> Optional[Tuple[int, int, int]]:+def _usage_snapshot(planner: VLMHandle) -> Optional[Tuple[int, int, int]]:"""``(prompt, completion, calls)`` from the model instance's usage tracker."""try:- total = planner.get_vlm_instance().token_tracker.get_total_usage()+ total = planner.token_tracker.get_total_usage()return int(total.prompt_tokens), int(total.completion_tokens), int(total.call_count)except Exception:return None@@ -82,6 +81,7 @@ async def rewrite_context(max_bullets: int = 6,timeout_s: Optional[float] = None,valid_uris: Optional[Collection[str]] = None,+ planner: VLMHandle,) -> Tuple[str, str, Optional[Dict[str, int]]]:"""Return ``(digest, status, usage)`` while containing every model failure."""if not rendered.strip():@@ -97,12 +97,6 @@ async def rewrite_context("max_bullets": max(1, max_bullets),},)- try:- planner = config.get_query_planner()- except Exception as exc:- logger.warning("Rewrite planner unavailable: %s", exc)- return "", "failed", None-before = _usage_snapshot(planner)try:response = await asyncio.wait_for(diff --git a/openviking/retrieve/intent_analyzer.py b/openviking/retrieve/intent_analyzer.pyindex 9af4e6276..6ab305d61 100644--- a/openviking/retrieve/intent_analyzer.py+++ b/openviking/retrieve/intent_analyzer.py@@ -6,12 +6,12 @@ Intent analyzer for OpenViking retrieval.Analyzes session context to generate query plans."""-from typing import Any, List, Optional+from typing import List, Optional+from openviking.config.vlm import VLMHandlefrom openviking.message import Messagefrom openviking.prompts import render_promptfrom openviking_cli.retrieve.types import ContextType, QueryPlan, TypedQuery-from openviking_cli.utils.config import get_openviking_configfrom openviking_cli.utils.llm import parse_json_from_responsefrom openviking_cli.utils.logger import get_logger@@ -27,7 +27,7 @@ QUERY_PLANNER_PROMPT_BY_MODEL: dict[str, str] = {}-def resolve_intent_analysis_prompt_id(query_planner: Any) -> str:+def resolve_intent_analysis_prompt_id(query_planner: VLMHandle) -> str:"""Return the prompt id expected by the configured query-planner model."""model = getattr(query_planner, "model", None)if not isinstance(model, str):@@ -48,9 +48,12 @@ class IntentAnalyzer:# Limit content length (about 10000 tokens)MAX_COMPRESSION_SUMMARY_CHARS = 30000- def __init__(self, max_recent_messages: int = 5):+ def __init__(self, max_recent_messages: int = 5, *, query_planner: VLMHandle):"""Initialize intent analyzer."""+ if query_planner is None:+ raise ValueError("IntentAnalyzer requires an explicitly resolved query planner")self.max_recent_messages = max_recent_messages+ self.query_planner = query_plannerasync def analyze(self,@@ -69,9 +72,7 @@ class IntentAnalyzer:context_type: Constrained context type (only generate queries for this type)target_abstract: Target directory abstract for more precise queries"""- # Call the lightweight query planner when configured; otherwise keep using VLM.- config = get_openviking_config()- query_planner = config.get_query_planner()+ query_planner = self.query_planner# Build context prompt. Some fine-tuned planner models expect a compact# prompt/output contract, selected by exact model mapping above.diff --git a/openviking/server/routers/admin.py b/openviking/server/routers/admin.pyindex c0d6dec83..5b779c165 100644--- a/openviking/server/routers/admin.py+++ b/openviking/server/routers/admin.py@@ -3,6 +3,7 @@"""Admin endpoints for OpenViking multi-tenant HTTP Server."""import asyncio+from collections.abc import Mappingfrom typing import Any, Optionalfrom fastapi import APIRouter, Body, Depends, Path, Query, Request@@ -137,6 +138,34 @@ class ConfigPatchRequest(BaseModel):settings: dict[str, Any] = Field(default_factory=dict)+_ROOT_ONLY_ACCOUNT_CONFIG_SECTIONS = frozenset({"vlm", "query_planner", "embedding", "vectordb"})+++def _authorize_account_config_patch(+ ctx: RequestContext,+ settings: Mapping[str, object],+) -> None:+ restricted = _ROOT_ONLY_ACCOUNT_CONFIG_SECTIONS.intersection(settings)+ if restricted and ctx.role != Role.ROOT:+ fields = ", ".join(sorted(restricted))+ raise PermissionDeniedError(+ f"Only ROOT can modify account configuration fields: {fields}"+ )+++def _visible_account_config(+ ctx: RequestContext,+ settings: Mapping[str, object],+) -> dict[str, object]:+ if ctx.role == Role.ROOT:+ return dict(settings)+ return {+ key: value+ for key, value in settings.items()+ if key not in _ROOT_ONLY_ACCOUNT_CONFIG_SECTIONS+ }++class UserSettingsPatch(BaseModel):memory_policy: Optional[dict]@@ -338,6 +367,11 @@ async def _rollback_account_creation(returnrollback_errors: list[Exception] = []+ try:+ await service.release_account_vector_resources(account_id)+ except Exception as exc:+ rollback_errors.append(exc)+ logger.exception("Failed to release vector resources for account %s", account_id)if runtime_config is not None:try:await runtime_config.delete_account(account_id)@@ -441,14 +475,12 @@ async def create_account(await _validate_initial_user_config(service, account_ctx, body.user_config)# Reject bad initial config before any storage is created, so a failed# create leaves nothing behind. This validates the active account runtime- # field surface without persisting. Only needed when initial settings exist.- runtime_config = None- if body.settings:- runtime_config = _get_runtime_config_manager()- try:- runtime_config.validate_initial_settings(body.account_id, body.settings)- except (ConfigPatchError, ValueError) as exc:- raise InvalidArgumentError(str(exc)) from exc+ # field surface and inherited vector configuration without persisting.+ runtime_config = _get_runtime_config_manager()+ try:+ runtime_config.validate_initial_settings(body.account_id, body.settings or {})+ except (ConfigPatchError, ValueError) as exc:+ raise InvalidArgumentError(str(exc)) from excmanager = _get_api_key_manager(request)user_key = await manager.create_account(body.account_id,@@ -456,8 +488,6 @@ async def create_account(seed=body.seed,)try:- await service.initialize_account_workspace(account_ctx)- await _write_initial_user_config(service, account_ctx, body.user_config)if body.settings and runtime_config is not None:# Persist the pre-validated override.await runtime_config.patch_account(@@ -465,6 +495,8 @@ async def create_account(body.settings,creating=True,)+ await service.initialize_account_workspace(account_ctx)+ await _write_initial_user_config(service, account_ctx, body.user_config)except BaseException:await _rollback_account_creation(service,@@ -637,7 +669,10 @@ async def get_account_configuration()return Response(status="ok",- result={"account_id": account_id, "settings": settings},+ result={+ "account_id": account_id,+ "settings": _visible_account_config(ctx, settings),+ },)@@ -759,6 +794,7 @@ async def patch_account_configuration("""Apply a three-state PATCH to the account configuration layer."""_check_account_access(ctx, account_id)await _check_account_exists(request, account_id)+ _authorize_account_config_patch(ctx, body.settings)try:await _get_runtime_config_manager().patch_account(account_id, body.settings)except (ConfigPatchError, ValueError) as exc:@@ -768,7 +804,10 @@ async def patch_account_configuration()return Response(status="ok",- result={"account_id": account_id, "settings": settings},+ result={+ "account_id": account_id,+ "settings": _visible_account_config(ctx, settings),+ },)diff --git a/openviking/server/routers/debug.py b/openviking/server/routers/debug.pyindex 6f8114359..d42e1b099 100644--- a/openviking/server/routers/debug.py+++ b/openviking/server/routers/debug.py@@ -26,12 +26,19 @@ router = APIRouter(prefix="/api/v1/debug", tags=["debug"])@router.get("/health")async def debug_health(- _ctx: RequestContext = Depends(get_request_context),+ ctx: RequestContext = Depends(get_request_context),):- """Quick health check."""+ """Account-scoped health check."""service = get_service()- is_healthy = service.debug.is_healthy()- return Response(status="ok", result={"healthy": is_healthy})+ try:+ status = await service.debug.observer.account_system(ctx)+ is_healthy = status.is_healthy+ except Exception:+ is_healthy = False+ return Response(+ status="ok",+ result={"healthy": is_healthy, "account_id": ctx.account_id},+ )@router.get("/vector/scroll")diff --git a/openviking/server/routers/observer.py b/openviking/server/routers/observer.pyindex 31d40cf11..fdab4762b 100644--- a/openviking/server/routers/observer.py+++ b/openviking/server/routers/observer.py@@ -53,7 +53,7 @@ async def observer_queue():"""Get queue system status."""service = get_service()- component = service.debug.observer.get_queue_status(format=format)+ component = await service.debug.observer.get_queue_status_async(format=format)return Response(status="ok", result=_component_to_dict(component))@@ -66,20 +66,20 @@ async def observer_vikingdb():"""Get VikingDB status."""service = get_service()- component = service.debug.observer.get_vikingdb_status(ctx=ctx, format=format)+ component = await service.debug.observer.account_vikingdb(ctx, format=format)return Response(status="ok", result=_component_to_dict(component))@router.get("/models")async def observer_models(- _ctx: RequestContext = Depends(get_request_context),+ ctx: RequestContext = Depends(get_request_context),format: Literal["table", "json"] = Query("table", description="Observer status representation format"),):"""Get models status (VLM, Embedding, Rerank)."""service = get_service()- component = service.debug.observer.get_models_status(format=format)+ component = await service.debug.observer.account_models(ctx, format=format)return Response(status="ok", result=_component_to_dict(component))@@ -92,7 +92,7 @@ async def observer_lock():"""Get lock system status."""service = get_service()- component = service.debug.observer.get_lock_status(format=format)+ component = await service.debug.observer.get_lock_status_async(format=format)return Response(status="ok", result=_component_to_dict(component))@@ -118,7 +118,7 @@ async def observer_filesystem():"""Get filesystem operation metrics."""service = get_service()- component = service.debug.observer.get_filesystem_status(format=format)+ component = await service.debug.observer.get_filesystem_status_async(format=format)return Response(status="ok", result=_component_to_dict(component))@@ -131,5 +131,5 @@ async def observer_system():"""Get system overall status (includes all components)."""service = get_service()- status = service.debug.observer.system(ctx=ctx, format=format)+ status = await service.debug.observer.account_system(ctx, format=format)return Response(status="ok", result=_system_to_dict(status))diff --git a/openviking/server/routers/skills.py b/openviking/server/routers/skills.pyindex 25add93de..efb02702c 100644--- a/openviking/server/routers/skills.py+++ b/openviking/server/routers/skills.py@@ -632,7 +632,7 @@ async def find_skills(# Both finds embed the same query text, so wrap the fan-out in the# request-scoped cache to reuse the first in-flight embed.- with query_embed_cache_scope():+ async with query_embed_cache_scope():user_execution, agent_execution = await asyncio.gather(run_operation(operation="skills.find",diff --git a/openviking/server/routers/system.py b/openviking/server/routers/system.pyindex 8bc19c8d0..f21539152 100644--- a/openviking/server/routers/system.py+++ b/openviking/server/routers/system.py@@ -2,7 +2,6 @@# SPDX-License-Identifier: AGPL-3.0"""System endpoints for OpenViking HTTP Server."""-import asynciofrom typing import Optionalfrom fastapi import APIRouter, Depends, Request@@ -54,19 +53,6 @@ async def _probe_agfs_readiness() -> dict[str, object]:return {"status": "ok", "checks": checks}-async def _embedding_probe(embedder) -> str:- """Quick embedding probe: embed a single token and check for errors."""- from openviking.models.embedder.base import embed_compat-- try:- await embed_compat(embedder, "ok", is_query=True)- return "ok"- except Exception as e:- provider = getattr(embedder, "provider", "unknown")- model = getattr(embedder, "model_name", "unknown")- return f"error: provider={provider} model={model}: {e}"--@router.get("/health", tags=["system"])async def health_check(request: Request):"""Health check endpoint (no authentication required)."""@@ -163,19 +149,12 @@ async def readiness_check(request: Request):except Exception as e:checks["api_key_manager"] = f"error: {e}"- # 4. Embedding: quick probe to verify the provider is reachable+ # 4. Embedding: the provider is initialized by the service startup path.+ # There is no Account context on an unauthenticated readiness probe, so do+ # not create or probe a Cluster-scoped embedder here.try:- from openviking_cli.utils.config.open_viking_config import OpenVikingConfigSingleton-- ov_config = OpenVikingConfigSingleton.get_instance()- embedder = ov_config.embedding.get_embedder()- if embedder is not None:- probe_result = await asyncio.wait_for(_embedding_probe(embedder), timeout=10.0)- checks["embedding"] = probe_result- else:- checks["embedding"] = "not_configured"- except asyncio.TimeoutError:- checks["embedding"] = "error: probe timed out (provider unreachable)"+ embedding_provider = getattr(service, "embedding_provider", None)+ checks["embedding"] = "ok" if embedding_provider is not None else "not_initialized"except Exception as e:checks["embedding"] = f"error: {e}"diff --git a/openviking/service/core.py b/openviking/service/core.pyindex 2a62a80f9..78632b79f 100644--- a/openviking/service/core.py+++ b/openviking/service/core.py@@ -7,6 +7,7 @@ Main service class that composes all sub-services and manages infrastructure lif"""import asyncio+import inspectimport osfrom typing import TYPE_CHECKING, Any, Optional@@ -57,6 +58,7 @@ from openviking_cli.utils.config.storage_config import StorageConfiglogger = get_logger(__name__)if TYPE_CHECKING:+ from openviking.config.vlm import VLMResolverfrom openviking.session.compressor_v3 import SessionCompressorV3@@ -103,6 +105,9 @@ class OpenVikingService:self._encryptor: Optional[Any] = Noneself._privacy_config_service: Optional[UserPrivacyConfigService] = Noneself._runtime_config_manager: Optional[Any] = None+ self._vlm_resolver: Optional["VLMResolver"] = None+ self._vector_config_resolver: Optional[Any] = None+ self._embedding_provider: Optional[Any] = Noneself._data_dir_lock_acquired = Falseself._data_dir_lock_path: Optional[str] = None@@ -137,10 +142,13 @@ class OpenVikingService:binding_config = self._build_ragfs_binding_config()# Initialize storage+ from openviking.config.vlm import ClusterVLMResolver++ cluster_vlm = ClusterVLMResolver(lambda: config).get_vlm_sync()self._init_storage(config.storage,max_concurrent_embedding=config.embedding.max_concurrent,- max_concurrent_semantic=config.vlm.max_concurrent,+ max_concurrent_semantic=cluster_vlm.max_concurrent,max_concurrent_external_parse=config.queue_workers.external_parse.max_concurrent,max_concurrent_add_resource=config.queue_workers.add_resource.max_concurrent,max_concurrent_session_commit=config.queue_workers.session_commit.max_concurrent,@@ -149,12 +157,6 @@ class OpenVikingService:git_config=config.git,)- # Initialize embedder- self._embedder = config.embedding.get_embedder()- logger.info(- f"Initialized embedder (dim {config.embedding.dimension}, sparse {self._embedder.is_sparse})"- )-def _init_storage(self,config: StorageConfig,@@ -198,12 +200,6 @@ class OpenVikingService:)self._vikingdb_manager.acl_manager = AclManager(self._vikingdb_manager)- # Configure queues if QueueManager is available.- # Workers are NOT started here — start() is called after VikingFS is initialized- # in initialize(), so that recovered tasks don't race against VikingFS init.- if self._queue_manager:- self._queue_manager.setup_standard_queues(self._vikingdb_manager, start=False)-# PathLock has been moved to Rust ragfs; Python-layer LockManager is no longer needed.set_task_tracker(config.build_task_tracker(self._agfs_client))@@ -217,6 +213,41 @@ class OpenVikingService:"""The runtime config manager bound to the cluster + account models."""return self._runtime_config_manager+ @property+ def vector_config_resolver(self) -> Optional[Any]:+ """The account-aware vector configuration resolver."""+ return self._vector_config_resolver++ @property+ def embedding_provider(self) -> Optional[Any]:+ """The account-aware embedding resource provider."""+ return self._embedding_provider++ async def release_account_vector_resources(self, account_id: str) -> None:+ """Release derived vector resources without deleting remote collections."""+ if self._vikingdb_manager is not None:+ await self._vikingdb_manager.release_account(account_id)+ if self._embedding_provider is not None:+ await self._embedding_provider.invalidate(account_id)++ async def _on_account_vector_config_change(self, event: Any) -> None:+ """Retire cached resources after eviction or a VectorDB source refresh."""+ from openviking.config.manager import ConfigChangeReason++ if (+ event.reason is not ConfigChangeReason.EVICT+ and "vectordb" not in event.changed_sections+ ):+ return+ account_id = event.scope.key+ if account_id:+ await self.release_account_vector_resources(account_id)++ @property+ def vlm_resolver(self) -> Optional["VLMResolver"]:+ """The account-aware VLM resolver owned by this service instance."""+ return self._vlm_resolver+def set_agent_evolution_config(self, config: AgentEvolutionConfig) -> None:"""Set the legacy server value used as the cluster startup baseline."""self._agent_evolution_base_config = config.model_copy(deep=True)@@ -245,6 +276,10 @@ class OpenVikingService:per account and loaded on demand by field."""from openviking.config.binding import build_runtime_config_manager+ from openviking.config.embedding import AccountEmbeddingProvider+ from openviking.config.scope import ScopeKind+ from openviking.config.vector import AccountVectorConfigResolver+ from openviking.config.vlm import AccountVLMProviderfrom openviking.pyagfs import AsyncAGFSClientif self._agfs_client is None:@@ -266,7 +301,30 @@ class OpenVikingService:if self._vikingdb_manager is None or self._vikingdb_manager.acl_manager is None:raise NotInitializedError("ACL")self._vikingdb_manager.acl_manager.set_runtime_config_manager(manager)+ self._vector_config_resolver = AccountVectorConfigResolver(manager)+ self._embedding_provider = AccountEmbeddingProvider(+ self._vector_config_resolver,+ manager,+ )+ self._vikingdb_manager.set_vector_config_resolver(self._vector_config_resolver)+ # Release the account's derived VectorDB backend when its config+ # publication is evicted (idle TTL) or deleted, so a cold account does+ # not keep its adapter/collection handles alive until process exit and a+ # later access re-resolves through the resolver instead of a stale cache.+ manager.add_update_consumer(+ scope=ScopeKind.ACCOUNT,+ sections={"vectordb", "embedding"},+ consumer=self._on_account_vector_config_change,+ )self._session_service.set_runtime_config_manager(manager)+ self._vlm_resolver = AccountVLMProvider(manager)+ if self._queue_manager is not None:+ self._queue_manager.set_vlm_resolver(self._vlm_resolver)+ self._queue_manager.setup_standard_queues(+ self._vikingdb_manager,+ start=False,+ embedding_provider=self._embedding_provider,+ )def _ensure_data_dir_lock_acquired(self) -> None:"""Protect embedded vector storage from concurrent processes in one workspace."""@@ -403,9 +461,6 @@ class OpenVikingService:git_config=self._config.git,)- if self._embedder is None:- self._embedder = self._config.embedding.get_embedder()-config = get_openviking_config()if self._encryptor:@@ -423,12 +478,12 @@ class OpenVikingService:if self._agfs_client is None:raise RuntimeError("AGFS client not initialized")- if self._embedder is None:- raise RuntimeError("Embedder not initialized")-+ await self._init_runtime_config_manager()+ if self._vlm_resolver is None:+ raise RuntimeError("VLM resolver not initialized")self._viking_fs = init_viking_fs(agfs=self._agfs_client,- query_embedder=self._embedder,+ query_embedder=None,rerank_config=config.rerank,vector_store=self._vikingdb_manager,acl_manager=self._vikingdb_manager.acl_manager,@@ -437,14 +492,16 @@ class OpenVikingService:glob_config=config.glob,enable_recorder=enable_recorder,encryptor=self._encryptor,+ vlm_resolver=self._vlm_resolver,+ embedding_provider=self._embedding_provider,+ vector_config_resolver=self._vector_config_resolver,)if enable_recorder:logger.info("VikingFS IO Recorder enabled")- await self._init_runtime_config_manager()-self._resource_processor = ResourceProcessor(vikingdb=self._vikingdb_manager,runtime_config_manager=self._runtime_config_manager,+ vlm_resolver=self._vlm_resolver,)# Initialize directories@@ -468,10 +525,12 @@ class OpenVikingService:self._skill_processor = SkillProcessor(vikingdb=self._vikingdb_manager,privacy_config_service=self._privacy_config_service,+ vlm_resolver=self._vlm_resolver,)self._session_compressor = create_session_compressor(vikingdb=self._vikingdb_manager,skill_processor=self._skill_processor,+ vlm_resolver=self._vlm_resolver,)self._watch_scheduler = WatchScheduler(@@ -493,6 +552,7 @@ class OpenVikingService:self._pack_service.set_dependencies(viking_fs=self._viking_fs,vector_store=self._vikingdb_manager,+ vector_config_resolver=self._vector_config_resolver,)self._search_service.set_viking_fs(self._viking_fs)self._resource_service.set_dependencies(@@ -508,6 +568,7 @@ class OpenVikingService:vikingdb=self._vikingdb_manager,viking_fs=self._viking_fs,session_compressor=self._session_compressor,+ vlm_resolver=self._vlm_resolver,)self._resource_memory_link_service.set_dependencies(vikingdb=self._vikingdb_manager,@@ -532,6 +593,8 @@ class OpenVikingService:vikingdb=self._vikingdb_manager,config=self._config,agfs_client=self._agfs_client,+ embedding_provider=self._embedding_provider,+ vlm_resolver=self._vlm_resolver,)self._agent_evolution_service.set_dependencies(vikingdb=self._vikingdb_manager,@@ -610,6 +673,7 @@ class OpenVikingService:async def close(self) -> None:"""Close OpenViking and release resources."""await self._resource_service.close_background_tasks()+ vlm_resolver = getattr(self, "_vlm_resolver", None)if self._runtime_config_manager:await self._runtime_config_manager.stop_refresh_loop()@@ -631,15 +695,27 @@ class OpenVikingService:self._queue_manager = Nonelogger.info("Queue manager stopped")+ close_vlm_resolver = getattr(vlm_resolver, "close", None)+ if callable(close_vlm_resolver):+ result = close_vlm_resolver()+ if inspect.isawaitable(result):+ await result+ self._vlm_resolver = Noneself._config.vlm.close()await asyncio.sleep(0)if self._vikingdb_manager:self._vikingdb_manager.mark_closing()+ embedding_provider = getattr(self, "_embedding_provider", None)+ if embedding_provider:+ await embedding_provider.close()+ self._embedding_provider = None+if self._vikingdb_manager:await self._vikingdb_manager.close()self._vikingdb_manager = None+ self._vector_config_resolver = Noneif self._agfs_client:close_agfs = getattr(self._agfs_client, "close", None)@@ -692,8 +768,12 @@ class OpenVikingService:await self.initialize()effective_ctx = ctx or RequestContext(user=self.user, role=Role.ROOT)- from openviking.service.reindex_executor import get_reindex_executor+ from openviking.service.reindex_executor import ReindexExecutor+ executor = ReindexExecutor(+ vlm_resolver=self._vlm_resolver,+ vector_config_resolver=self._vector_config_resolver,+ )execute_kwargs = {"uri": uri,"mode": mode,@@ -706,7 +786,7 @@ class OpenVikingService:if tags is not None or tag_mode == "clear":execute_kwargs["tags"] = tagsexecute_kwargs["tag_mode"] = tag_mode- return await get_reindex_executor().execute(**execute_kwargs)+ return await executor.execute(**execute_kwargs)async def check_consistency(self,diff --git a/openviking/service/debug_service.py b/openviking/service/debug_service.pyindex 94ffa1c67..947c6368c 100644--- a/openviking/service/debug_service.py+++ b/openviking/service/debug_service.py@@ -3,12 +3,11 @@"""Debug Service - provides system status query and health check."""-+import asynciofrom dataclasses import dataclassfrom typing import Any, Dict, List, Optionalfrom openviking.server.identity import RequestContext-from openviking.storage.vikingdb_manager import VikingDBManagerfrom openviking.storage.observers import (FilesystemObserver,ModelsObserver,@@ -18,6 +17,7 @@ from openviking.storage.observers import ()from openviking.storage.queuefs import get_queue_managerfrom openviking.storage.viking_fs import get_viking_fs+from openviking.storage.vikingdb_manager import VikingDBManagerfrom openviking_cli.utils import run_asyncfrom openviking_cli.utils.config import OpenVikingConfigfrom openviking_cli.utils.logger import get_logger@@ -121,29 +121,37 @@ class ObserverService:vikingdb: Optional[VikingDBManager] = None,config: Optional[OpenVikingConfig] = None,agfs_client: Optional[Any] = None,+ embedding_provider: Optional[Any] = None,+ vlm_resolver: Optional[Any] = None,):self._vikingdb = vikingdbself._config = configself._agfs_client = agfs_client+ self._embedding_provider = embedding_provider+ self._vlm_resolver = vlm_resolverdef set_dependencies(self,vikingdb: VikingDBManager,config: OpenVikingConfig,agfs_client: Optional[Any] = None,+ embedding_provider: Optional[Any] = None,+ vlm_resolver: Optional[Any] = None,) -> None:"""Set dependencies after initialization."""self._vikingdb = vikingdbself._config = configif agfs_client is not None:self._agfs_client = agfs_client+ self._embedding_provider = embedding_provider+ self._vlm_resolver = vlm_resolver@propertydef _dependencies_ready(self) -> bool:"""Check if both vikingdb and config dependencies are set."""return self._vikingdb is not None and self._config is not None- def get_queue_status(self, *, format: str = "table") -> ComponentStatus:+ async def get_queue_status_async(self, *, format: str = "table") -> ComponentStatus:"""Get queue status."""try:qm = get_queue_manager()@@ -156,9 +164,13 @@ class ObserverService:)observer = QueueObserver(qm)try:- status = observer.get_status_json() if format == "json" else observer.get_status_table()- is_healthy = observer.is_healthy()- has_errors = observer.has_errors()+ status = (+ await observer.get_status_json_async()+ if format == "json"+ else await observer.get_status_table_async()+ )+ has_errors = await observer.has_active_errors_async()+ is_healthy = not has_errorsexcept Exception as exc:logger.warning("Queue observer status unavailable: %s", exc)if format == "json":@@ -185,6 +197,10 @@ class ObserverService:status=status,)+ def get_queue_status(self, *, format: str = "table") -> ComponentStatus:+ """Synchronous compatibility wrapper for non-async callers."""+ return run_async(self.get_queue_status_async(format=format))+@propertydef queue(self) -> ComponentStatus:"""Get queue status."""@@ -213,6 +229,8 @@ class ObserverService:def vikingdb(self, ctx: Optional[RequestContext] = None) -> ComponentStatus:"""Get VikingDB status."""+ if ctx is not None:+ return run_async(self.account_vikingdb(ctx))return self.get_vikingdb_status(ctx=ctx)@property@@ -230,15 +248,36 @@ class ObserverService:status=_models_not_initialized_status(format),)- vlm_instance = self._config.vlm.get_vlm_instance()+ from types import SimpleNamespace++ vlm_instance = Noneembedding_instance = None+ scope = "Node aggregate"+ if self._vlm_resolver is not None and hasattr(+ self._vlm_resolver, "get_node_token_usage"+ ):+ vlm_instance = SimpleNamespace(+ model="node-aggregate",+ provider="aggregate",+ get_token_usage=self._vlm_resolver.get_node_token_usage,+ )+ if self._embedding_provider is not None:+ embedding_instance = SimpleNamespace(+ get_token_usage=self._embedding_provider.get_total_token_usage,+ )++ # Standalone ObserverService instances have no Account providers.+ if vlm_instance is None:+ scope = "Cluster"+ vlm_instance = self._config.vlm.get_vlm_instance()+ if embedding_instance is None and self._embedding_provider is None:+ from openviking.models.embedder.base import _get_token_tracker++ embedding_instance = SimpleNamespace(get_token_usage=_get_token_tracker().to_dict)+rerank_instance = None- embedding_config = getattr(self._config, "embedding", None)rerank_config = getattr(self._config, "rerank", None)- if embedding_config:- embedding_instance = embedding_config.get_embedder()-if rerank_config and rerank_config.is_available():from openviking.models.rerank import RerankClient@@ -249,49 +288,167 @@ class ObserverService:embedding_instance=embedding_instance,rerank_instance=rerank_instance,)+ status = observer.get_status_json() if format == "json" else observer.get_status_table()+ if format == "json":+ status = {"scope": scope, **status}+ else:+ status = f"Scope: {scope}\n{status}"return ComponentStatus(name="models",is_healthy=observer.is_healthy(),has_errors=observer.has_errors(),- status=observer.get_status_json() if format == "json" else observer.get_status_table(),+ status=status,)- @property- def lock(self) -> ComponentStatus:- """Get lock system status via pathlock_observe snapshot."""+ async def account_models(+ self, ctx: RequestContext, *, format: str = "table"+ ) -> ComponentStatus:+ embedding_dimension = Nonetry:- viking_fs = get_viking_fs()- snapshot = run_async(viking_fs._async_agfs.pathlock_observe())- except Exception:+ if self._embedding_provider is None:+ raise RuntimeError("Account embedding provider is not initialized")+ embedding_status = await self._embedding_provider.get_status(ctx.account_id)+ embedding_dimension = embedding_status.dimension+ if self._vlm_resolver is None:+ raise RuntimeError("Account VLM resolver is not initialized")+ vlm = await self._vlm_resolver.get_vlm(ctx.account_id)+ observer = ModelsObserver(+ vlm_instance=vlm,+ embedding_instance=self._embedding_provider.bind(ctx.account_id),+ )+ status = observer.get_status_json() if format == "json" else observer.get_status_table()+ if format == "json":+ status = {+ "account_id": ctx.account_id,+ "embedding_dimension": embedding_status.dimension,+ **status,+ }+ else:+ status = (+ f"Account: {ctx.account_id}\n"+ f"Embedding dimension: {embedding_status.dimension}\n{status}"+ )return ComponentStatus(- name="lock",+ name="models",+ is_healthy=True,+ has_errors=False,+ status=status,+ )+ except Exception as exc:+ logger.warning(+ "Account model observer failed for account %s: %s",+ ctx.account_id,+ exc,+ exc_info=True,+ )+ return ComponentStatus(+ name="models",is_healthy=False,has_errors=True,- status=_lock_not_initialized_status(format),+ status=(+ {+ "account_id": ctx.account_id,+ "embedding_dimension": embedding_dimension,+ "vlm": [],+ "embedding": [],+ "rerank": [],+ "error": str(exc),+ }+ if format == "json"+ else f"Account: {ctx.account_id}\nModels unavailable: {exc}"+ ),)- active = snapshot.get("active_locks", 0)- waiting = snapshot.get("waiting_locks", 0)- stale = snapshot.get("stale_locks_removed", 0)- conflicts = snapshot.get("conflicts", [])- lines = [- f"Active locks: {active}",- f"Waiting locks: {waiting}",- f"Stale locks removed: {stale}",- f"Conflicts: {len(conflicts)}",- ]- # Conflicts and stale removals are retained diagnostics, not current failures.- return ComponentStatus(- name="lock",- is_healthy=True,- has_errors=False,- status="\n".join(lines),++ async def account_vikingdb(+ self, ctx: RequestContext, *, format: str = "table"+ ) -> ComponentStatus:+ try:+ backend = await self._vikingdb.get_account_backend(ctx.account_id)+ healthy = await backend.health_check()+ count = await backend.count() if healthy else 0+ status = (+ {+ "backend": backend._mode,+ "collection": backend._collection_name,+ "index": backend._index_name,+ "dimension": backend.vector_dim,+ "vector_count": count,+ }+ if format == "json"+ else f"Account: {ctx.account_id}\nBackend: {backend._mode}\n"+ f"Collection: {backend._collection_name}\nIndex: {backend._index_name}\n"+ f"Dimension: {backend.vector_dim}\nVector count: {count}"+ )+ return ComponentStatus(+ name="vikingdb",+ is_healthy=healthy,+ has_errors=not healthy,+ status=status,+ )+ except Exception as exc:+ logger.warning(+ "Account VectorDB observer failed for account %s: %s",+ ctx.account_id,+ exc,+ exc_info=True,+ )+ return ComponentStatus(+ name="vikingdb",+ is_healthy=False,+ has_errors=True,+ status=(+ {+ "account_id": ctx.account_id,+ "backend": None,+ "collection": None,+ "index": None,+ "dimension": None,+ "vector_count": 0,+ "error": str(exc),+ }+ if format == "json"+ else f"Account: {ctx.account_id}\nVectorDB unavailable: {exc}"+ ),+ )++ async def account_system(+ self, ctx: RequestContext, *, format: str = "table"+ ) -> SystemStatus:+ queue, vikingdb, models, lock, filesystem = await asyncio.gather(+ self.get_queue_status_async(format=format),+ self.account_vikingdb(ctx, format=format),+ self.account_models(ctx, format=format),+ self.get_lock_status_async(format=format),+ self.get_filesystem_status_async(format=format),+ )+ components = {+ "queue": queue,+ "vikingdb": vikingdb,+ "models": models,+ "lock": lock,+ "retrieval": self.get_retrieval_status(format=format),+ "filesystem": filesystem,+ }+ return SystemStatus(+ is_healthy=all(component.is_healthy for component in components.values()),+ components=components,+ errors=[+ f"{component.name} has errors"+ for component in components.values()+ if component.has_errors+ ],)- def get_lock_status(self, *, format: str = "table") -> ComponentStatus:+ @property+ def lock(self) -> ComponentStatus:+ """Get lock system status via pathlock_observe snapshot."""+ return self.get_lock_status()++ async def get_lock_status_async(self, *, format: str = "table") -> ComponentStatus:"""Get lock system status via pathlock_observe snapshot."""try:viking_fs = get_viking_fs()- snapshot = run_async(viking_fs._async_agfs.pathlock_observe())+ snapshot = await viking_fs._async_agfs.pathlock_observe()except Exception:return ComponentStatus(name="lock",@@ -326,6 +483,10 @@ class ObserverService:status=status,)+ def get_lock_status(self, *, format: str = "table") -> ComponentStatus:+ """Synchronous compatibility wrapper for non-async callers."""+ return run_async(self.get_lock_status_async(format=format))+@propertydef retrieval(self) -> ComponentStatus:"""Get retrieval quality status."""@@ -350,24 +511,27 @@ class ObserverService:@propertydef filesystem(self) -> ComponentStatus:"""Get filesystem operation status."""- observer = FilesystemObserver()- return ComponentStatus(- name="filesystem",- is_healthy=observer.is_healthy(),- has_errors=observer.has_errors(),- status=observer.get_status_table(),- )+ return self.get_filesystem_status()- def get_filesystem_status(self, *, format: str = "table") -> ComponentStatus:+ async def get_filesystem_status_async(self, *, format: str = "table") -> ComponentStatus:"""Get filesystem operation status."""observer = FilesystemObserver()+ status = (+ await observer.get_status_json_async()+ if format == "json"+ else await observer.get_status_table_async()+ )return ComponentStatus(name="filesystem",is_healthy=observer.is_healthy(),has_errors=observer.has_errors(),- status=observer.get_status_json() if format == "json" else observer.get_status_table(),+ status=status,)+ def get_filesystem_status(self, *, format: str = "table") -> ComponentStatus:+ """Synchronous compatibility wrapper for non-async callers."""+ return run_async(self.get_filesystem_status_async(format=format))+async def get_filesystem_stats(self, mount_path: Optional[str] = None) -> dict:"""Get filesystem statistics from RAGFS.@@ -394,6 +558,8 @@ class ObserverService:def system(self, ctx: Optional[RequestContext] = None, *, format: str = "table") -> SystemStatus:"""Get system overall status."""+ if ctx is not None:+ return run_async(self.account_system(ctx, format=format))components = {"queue": self.get_queue_status(format=format),"vikingdb": self.get_vikingdb_status(ctx=ctx, format=format),@@ -424,17 +590,33 @@ class DebugService:vikingdb: Optional[VikingDBManager] = None,config: Optional[OpenVikingConfig] = None,agfs_client: Optional[Any] = None,+ embedding_provider: Optional[Any] = None,+ vlm_resolver: Optional[Any] = None,):- self._observer = ObserverService(vikingdb, config, agfs_client)+ self._observer = ObserverService(+ vikingdb,+ config,+ agfs_client,+ embedding_provider,+ vlm_resolver,+ )def set_dependencies(self,vikingdb: VikingDBManager,config: OpenVikingConfig,agfs_client: Optional[Any] = None,+ embedding_provider: Optional[Any] = None,+ vlm_resolver: Optional[Any] = None,) -> None:"""Set dependencies after initialization."""- self._observer.set_dependencies(vikingdb, config, agfs_client)+ self._observer.set_dependencies(+ vikingdb,+ config,+ agfs_client,+ embedding_provider,+ vlm_resolver,+ )@propertydef observer(self) -> ObserverService:diff --git a/openviking/service/deletion.py b/openviking/service/deletion.pyindex bedc449fb..eebfbbf46 100644--- a/openviking/service/deletion.py+++ b/openviking/service/deletion.py@@ -332,6 +332,9 @@ class DeletionService:))if user_id is None:+ await run_to_completion(+ lambda: self._service.release_account_vector_resources(account_id)+ )runtime_config = self._service.runtime_config_managerif runtime_config is not None:await run_to_completion(lambda: runtime_config.delete_account(account_id))diff --git a/openviking/service/pack_service.py b/openviking/service/pack_service.pyindex 3f3fc5a82..632e61778 100644--- a/openviking/service/pack_service.py+++ b/openviking/service/pack_service.py@@ -23,18 +23,30 @@ logger = get_logger(__name__)class PackService:"""OVPack export/import and backup/restore service."""- def __init__(self, viking_fs: Optional[VikingFS] = None, vector_store=None):+ def __init__(+ self,+ viking_fs: Optional[VikingFS] = None,+ vector_store=None,+ vector_config_resolver=None,+ ):self._viking_fs = viking_fsself._vector_store = vector_store+ self._vector_config_resolver = vector_config_resolverdef set_viking_fs(self, viking_fs: VikingFS) -> None:"""Set VikingFS instance (for deferred initialization)."""self._viking_fs = viking_fs- def set_dependencies(self, viking_fs: VikingFS, vector_store=None) -> None:+ def set_dependencies(+ self,+ viking_fs: VikingFS,+ vector_store=None,+ vector_config_resolver=None,+ ) -> None:"""Set pack service dependencies."""self._viking_fs = viking_fsself._vector_store = vector_store+ self._vector_config_resolver = vector_config_resolverdef _ensure_initialized(self) -> VikingFS:"""Ensure VikingFS is initialized."""@@ -79,6 +91,7 @@ class PackService:to,ctx=ctx,vector_store=self._vector_store,+ vector_config_resolver=self._vector_config_resolver,include_vectors=include_vectors,)@@ -96,6 +109,7 @@ class PackService:to,ctx=maintenance_ctx,vector_store=self._vector_store,+ vector_config_resolver=self._vector_config_resolver,include_vectors=include_vectors,)@@ -125,6 +139,7 @@ class PackService:on_conflict=on_conflict,vector_mode=vector_mode,vector_store=self._vector_store,+ vector_config_resolver=self._vector_config_resolver,ctx=ctx,)@@ -145,4 +160,5 @@ class PackService:on_conflict=on_conflict,vector_mode=vector_mode,vector_store=self._vector_store,+ vector_config_resolver=self._vector_config_resolver,)diff --git a/openviking/service/reindex_executor.py b/openviking/service/reindex_executor.pyindex f487d8799..4860dd5a9 100644--- a/openviking/service/reindex_executor.py+++ b/openviking/service/reindex_executor.py@@ -10,6 +10,7 @@ import timefrom dataclasses import dataclass, fieldfrom typing import Any, Iterable, Optional+from openviking.config.vlm import VLMResolverfrom openviking.core.context import (Context,ContextLevel,@@ -146,6 +147,25 @@ class ReindexExecutor:"memory": {"vectors_only", "semantic_and_vectors", "prune_orphans"},}+ def __init__(+ self,+ vlm_resolver: VLMResolver | None = None,+ vector_config_resolver=None,+ ) -> None:+ self.vlm_resolver = vlm_resolver+ self.vector_config_resolver = vector_config_resolver++ async def _semantic_processor_for(self, ctx: RequestContext) -> SemanticProcessor:+ if self.vlm_resolver is None:+ raise RuntimeError(+ "ReindexExecutor requires a VLM resolver for semantic reindexing"+ )+ vlm = await self.vlm_resolver.get_vlm(ctx.account_id)+ return SemanticProcessor(+ max_concurrent_llm=vlm.max_concurrent,+ vlm_resolver=self.vlm_resolver,+ )+@staticmethoddef _effective_file_vectorization_concurrency() -> int:config = get_openviking_config().reindex@@ -988,9 +1008,6 @@ class ReindexExecutor:counters = run.countersctx = run.ctxif mode == "semantic_and_vectors":- processor = SemanticProcessor(- max_concurrent_llm=get_openviking_config().vlm.max_concurrent- )if not recursive:await self._regenerate_skill_semantics(uri=uri, ctx=ctx, lock=run.lock)await self._reindex_skill_vectors(@@ -1001,11 +1018,13 @@ class ReindexExecutor:ingest_options=run.ingest_options,)return+ owner_ctx = self._content_owner_ctx(uri, ctx)+ processor = await self._semantic_processor_for(owner_ctx)executor = SemanticTreeExecutor(processor=processor,context_type="skill",max_concurrent_llm=processor.max_concurrent_llm,- ctx=self._content_owner_ctx(uri, ctx),+ ctx=owner_ctx,lock=run.lock,generation_trigger="reindex",ingest_options=run.ingest_options,@@ -1084,10 +1103,8 @@ class ReindexExecutor:lock: dict | None = None,recursive: bool = True,) -> None:- processor = SemanticProcessor(- max_concurrent_llm=get_openviking_config().vlm.max_concurrent,- )owner_ctx = self._content_owner_ctx(uri, ctx)+ processor = await self._semantic_processor_for(owner_ctx)msg = SemanticMsg(uri=uri,context_type=context_type,@@ -1799,7 +1816,13 @@ class ReindexExecutor:async def _regenerate_skill_semantics(self, *, uri: str, ctx: RequestContext, lock: dict | None = None) -> None:- await SemanticProcessor()._skill_root_semantics(uri, ctx=ctx, regenerate=True, lock=lock)+ processor = await self._semantic_processor_for(ctx)+ await processor._skill_root_semantics(+ uri,+ ctx=ctx,+ regenerate=True,+ lock=lock,+ )async def _read_directory_abstract(self, uri: str, *, ctx: RequestContext) -> str:try:@@ -1846,7 +1869,11 @@ class ReindexExecutor:content_type = get_resource_content_type(uri.rsplit("/", 1)[-1])if content_type == ResourceContentType.TEXT:- embedding_config = get_openviking_config().embedding+ if self.vector_config_resolver is None:+ raise RuntimeError("ReindexExecutor requires a vector config resolver")+ embedding_config = (+ await self.vector_config_resolver.resolve(ctx.account_id)+ ).embeddingtext_source = embedding_config.text_sourceif text_source in SUMMARY_TEXT_SOURCES and summary:return summarydiff --git a/openviking/service/search_service.py b/openviking/service/search_service.pyindex 4dabb67cd..536d2cbdf 100644--- a/openviking/service/search_service.py+++ b/openviking/service/search_service.py@@ -196,7 +196,7 @@ class SearchService:targets = resolve_retrieval_targets(target_uri, ctx).target_directoriesfor target in targets:await fs._ensure_retrieval_scope(target, ctx)- storage, embedder = fs._get_vector_store(), fs._get_embedder()+ storage, embedder = fs._get_vector_store(), fs._get_embedder(ctx)if not storage:raise RuntimeError("Vector store not initialized. Call OpenViking.initialize() first.")if not embedder:diff --git a/openviking/service/session_service.py b/openviking/service/session_service.pyindex 161a40be9..60b5c3ce9 100644--- a/openviking/service/session_service.py+++ b/openviking/service/session_service.py@@ -47,6 +47,7 @@ from openviking_cli.utils.config.memory_config import SessionAutoCommitConfiglogger = get_logger(__name__)if TYPE_CHECKING:+ from openviking.config.vlm import VLMResolverfrom openviking.session.compressor_v3 import SessionCompressorV3from openviking.usage_reporter import UsageReporter@@ -66,6 +67,7 @@ class SessionService:self._tool_output_externalization_config = ToolOutputExternalizationConfig()self._agent_evolution_default_enabled = AgentEvolutionConfig().enabledself._runtime_config_manager: Optional[Any] = None+ self._vlm_resolver: Optional["VLMResolver"] = Noneself._default_user_memory_policy: Optional[Dict[str, Any]] = Noneself._default_user_auto_commit_policy: Optional[Dict[str, Any]] = Noneself._usage_reporter: Optional["UsageReporter"] = None@@ -83,11 +85,13 @@ class SessionService:vikingdb: VikingDBManager,viking_fs: VikingFS,session_compressor: "SessionCompressorV3",+ vlm_resolver: Optional["VLMResolver"] = None,) -> None:"""Set dependencies (for deferred initialization)."""self._vikingdb = vikingdbself._viking_fs = viking_fsself._session_compressor = session_compressor+ self._vlm_resolver = vlm_resolverdef set_tool_output_externalization_config(self, config: ToolOutputExternalizationConfig@@ -213,6 +217,7 @@ class SessionService:),memory_policy_provider=lambda: self._get_user_memory_policy(ctx),usage_reporter=self._usage_reporter,+ vlm_resolver=self._vlm_resolver,)async def _get_user_memory_policy(self, ctx: RequestContext) -> Optional[Dict[str, Any]]:diff --git a/openviking/session/__init__.py b/openviking/session/__init__.pyindex 7e0aff65c..25475fc79 100644--- a/openviking/session/__init__.py+++ b/openviking/session/__init__.py@@ -11,6 +11,7 @@ from openviking_cli.utils import get_loggerlogger = get_logger(__name__)if TYPE_CHECKING:+ from openviking.config.vlm import VLMResolverfrom openviking.session.compressor_v3 import SessionCompressorV3@@ -18,6 +19,7 @@ def create_session_compressor(vikingdb: VikingDBManager,memory_version: Optional[str] = None,skill_processor=None,+ vlm_resolver: Optional["VLMResolver"] = None,) -> "SessionCompressorV3":"""Create the session compressor.@@ -37,7 +39,11 @@ def create_session_compressor(logger.info("Using v3 memory compressor (v2 + commit streaming train)")from openviking.session.compressor_v3 import SessionCompressorV3- return SessionCompressorV3(vikingdb=vikingdb, skill_processor=skill_processor)+ return SessionCompressorV3(+ vikingdb=vikingdb,+ skill_processor=skill_processor,+ vlm_resolver=vlm_resolver,+ )__all__ = [diff --git a/openviking/session/compressor_v3.py b/openviking/session/compressor_v3.pyindex b28113b4e..0a4f2c5b6 100644--- a/openviking/session/compressor_v3.py+++ b/openviking/session/compressor_v3.py@@ -16,7 +16,7 @@ import jsonimport refrom dataclasses import dataclass, fieldfrom datetime import datetime, timezone-from typing import Any, List, Optional+from typing import TYPE_CHECKING, Any, List, Optionalfrom uuid import uuid4from openviking.core.context import Context@@ -87,6 +87,9 @@ from openviking.telemetry import get_current_telemetry, tracerfrom openviking_cli.utils import get_loggerfrom openviking_cli.utils.config import get_openviking_config+if TYPE_CHECKING:+ from openviking.config.vlm import VLMHandle, VLMResolver+logger = get_logger(__name__)_CASES_MEMORY_TYPE = CASE_MEMORY_TYPE@@ -253,12 +256,15 @@ class SessionCompressorV3:rollout_analyzer: TrajectoryRolloutAnalyzer | Any | None = None,streaming_trainer_config: StreamingPolicyTrainerConfig | None = None,streaming_memory_updater_config: StreamingMemoryUpdaterConfig | None = None,+ vlm_resolver: VLMResolver | None = None,):self.vikingdb = vikingdbself.skill_processor = skill_processor+ self.vlm_resolver = vlm_resolverself.rollout_analyzer = rollout_analyzer or TrajectoryRolloutAnalyzer(viking_fs=get_viking_fs(),vikingdb=vikingdb,+ vlm_resolver=vlm_resolver,)self.streaming_trainer_config = streaming_trainer_config or StreamingPolicyTrainerConfig()self.streaming_memory_updater_config = (@@ -273,9 +279,13 @@ class SessionCompressorV3:isolation_handler: Optional[MemoryIsolationHandler] = None,transaction_handle=None,context_provider: Optional[SessionExtractContextProvider] = None,+ vlm_config: VLMHandle | None = None,) -> ExtractLoop:- config = get_openviking_config()- vlm = config.vlm.get_vlm_instance()+ if vlm_config is None:+ raise RuntimeError(+ "SessionCompressorV3 requires an explicitly resolved VLM config"+ )+ vlm = vlm_configviking_fs = get_viking_fs()if context_provider is None:context_provider = SessionExtractContextProvider(@@ -285,6 +295,7 @@ class SessionCompressorV3:ctx=ctx,viking_fs=viking_fs,transaction_handle=transaction_handle,+ vlm_config=vlm_config,)return ExtractLoop(vlm=vlm,@@ -689,6 +700,11 @@ class SessionCompressorV3:allowed_memory_types=allowed_memory_types,)+ if self.vlm_resolver is None:+ raise RuntimeError(+ "SessionCompressorV3 requires a VLM resolver for account-owned work"+ )+ vlm_config = await self.vlm_resolver.get_vlm(ctx.account_id)context_provider = SessionExtractContextProvider(messages=messages,latest_archive_overview=latest_archive_overview,@@ -697,6 +713,7 @@ class SessionCompressorV3:viking_fs=viking_fs,transaction_handle=None,memory_registry=registry,+ vlm_config=vlm_config,)await context_provider.prepare_extraction_messages()extract_context = context_provider.get_extract_context()@@ -718,6 +735,7 @@ class SessionCompressorV3:isolation_handler=isolation_handler,transaction_handle=None,context_provider=context_provider,+ vlm_config=vlm_config,)operations, _tools_used = await orchestrator.run()if operations is None:@@ -736,6 +754,7 @@ class SessionCompressorV3:registry=registry,vikingdb=self.vikingdb,config=self.streaming_memory_updater_config,+ vlm_resolver=self.vlm_resolver,)update_result = await updater.submit(MemoryUpdateRequest(@@ -895,6 +914,7 @@ class SessionCompressorV3:viking_fs=viking_fs,memory_type=SESSION_SKILL_MEMORY_TYPE,memory_registry=load_skill_extract_registry(),+ vlm_resolver=self.vlm_resolver,),policy_updater=SkillPolicyUpdater(skill_processor=self.skill_processor,@@ -978,10 +998,12 @@ class SessionCompressorV3:rollout_analyzer=self.rollout_analyzer,gradient_estimator=ExperienceGradientEstimator(viking_fs=viking_fs,+ vlm_resolver=self.vlm_resolver,),policy_optimizer=PatchMergePolicyOptimizer(viking_fs=viking_fs,memory_type="experiences",+ vlm_resolver=self.vlm_resolver,),policy_updater=MemoryFilePolicyUpdater(viking_fs=viking_fs, vikingdb=self.vikingdb),context=PipelineContext(@@ -1031,6 +1053,7 @@ class SessionCompressorV3:if experiences_allowed:exp_gradients = await ExperienceGradientEstimator(viking_fs=viking_fs,+ vlm_resolver=self.vlm_resolver,).estimate(analysis, exp_trainer.policy_set, gradient_context)exp_training_result = _trajectory_only_training_result(analysis=analysis,diff --git a/openviking/session/memory/agent_experience_context_provider.py b/openviking/session/memory/agent_experience_context_provider.pyindex c27239487..b570a5b6c 100644--- a/openviking/session/memory/agent_experience_context_provider.py+++ b/openviking/session/memory/agent_experience_context_provider.py@@ -10,7 +10,7 @@ No tool calls — all context is prefetched. Top-3 candidates also include theirsource_trajectories as grounding material."""-from typing import Any, Dict, List, Optional+from typing import TYPE_CHECKING, Any, Dict, List, Optionalfrom openviking.pyagfs.exceptions import AGFSNotFoundErrorfrom openviking.server.identity import RequestContext@@ -25,6 +25,9 @@ from openviking.storage.viking_fs import VikingFSfrom openviking.telemetry import tracerfrom openviking_cli.utils import get_logger+if TYPE_CHECKING:+ from openviking.config.vlm import VLMHandle+logger = get_logger(__name__)@@ -50,8 +53,13 @@ class AgentExperienceContextProvider(SessionExtractContextProvider):trajectory_summary: str,trajectory_uri: str,latest_archive_overview: str = "",+ vlm_config: Optional["VLMHandle"] = None,):- super().__init__(messages=messages, latest_archive_overview=latest_archive_overview)+ super().__init__(+ messages=messages,+ latest_archive_overview=latest_archive_overview,+ vlm_config=vlm_config,+ )self.trajectory_summary = trajectory_summaryself.trajectory_uri = trajectory_uriself.prefetched_uris: List[str] = []diff --git a/openviking/session/memory/extract_loop.py b/openviking/session/memory/extract_loop.pyindex d7288fa6d..189923d84 100644--- a/openviking/session/memory/extract_loop.py+++ b/openviking/session/memory/extract_loop.py@@ -229,7 +229,7 @@ class ExtractLoop:config = get_openviking_config()self._link_enabled = config.memory.link_enabled if config.memory else False- self._resolve_effective_max_output_tokens(config)+ self._resolve_effective_max_output_tokens()# 获取 ExtractContext(整个流程复用)self._extract_context = self.context_provider.get_extract_context()@@ -458,20 +458,18 @@ class ExtractLoop:return final_operations, tools_used- def _resolve_effective_max_output_tokens(self, config: Any = None) -> None:+ def _resolve_effective_max_output_tokens(self) -> None:"""Resolve the extraction output cap.- Priority: explicit per-loop value > configured vlm.max_tokens >+ Priority: explicit per-loop value > resolved VLM max_tokens >_DEFAULT_EXTRACTION_MAX_OUTPUT_TOKENS. The default is a functional floorthat suits the primary Doubao models; a model with a lower max output(e.g. gpt-4o-mini) must set vlm.max_tokens in ov.conf to override it."""- if config is None:- config = get_openviking_config()if self.max_output_tokens is not None:self._effective_max_output_tokens = self.max_output_tokensreturn- configured = getattr(getattr(config, "vlm", None), "max_tokens", None)+ configured = getattr(self.vlm, "max_tokens", None)self._effective_max_output_tokens = (configured if configured is not None else _DEFAULT_EXTRACTION_MAX_OUTPUT_TOKENS)diff --git a/openviking/session/memory/patch_merge_context_provider.py b/openviking/session/memory/patch_merge_context_provider.pyindex aa9ed99ee..1972ff1fa 100644--- a/openviking/session/memory/patch_merge_context_provider.py+++ b/openviking/session/memory/patch_merge_context_provider.py@@ -6,7 +6,7 @@ from __future__ import annotationsimport difflibfrom dataclasses import dataclass, field-from typing import Any+from typing import TYPE_CHECKING, Anyfrom openviking.server.identity import RequestContextfrom openviking.session.memory.dataclass import MemoryFile, MemoryTypeSchema@@ -17,6 +17,9 @@ from openviking.session.memory.session_extract_context_provider import ()from openviking.session.memory.utils.language import resolve_output_language_from_text+if TYPE_CHECKING:+ from openviking.config.vlm import VLMHandle+_SYSTEM_HIDDEN_FIELDS = {"source_extraction_id","source_extraction_ids",@@ -124,8 +127,9 @@ class PatchMergeContextProvider(SessionExtractContextProvider):required_file_uris: list[str] | None = None,output_language: str | None = None,memory_registry: MemoryTypeRegistry | None = None,+ vlm_config: VLMHandle | None = None,):- super().__init__(messages=[])+ super().__init__(messages=[], vlm_config=vlm_config)self.memory_type = memory_typeself._registry = memory_registryself.required_file_uris = list(required_file_uris or [])diff --git a/openviking/session/memory/session_extract_context_provider.py b/openviking/session/memory/session_extract_context_provider.pyindex d9073007a..8fa4f2612 100644--- a/openviking/session/memory/session_extract_context_provider.py+++ b/openviking/session/memory/session_extract_context_provider.py@@ -39,6 +39,7 @@ from openviking_cli.utils import get_loggerfrom openviking_cli.utils.config import get_openviking_configif TYPE_CHECKING:+ from openviking.config.vlm import VLMHandlefrom openviking.session.memory.memory_updater import ExtractContextlogger = get_logger(__name__)@@ -67,6 +68,7 @@ class SessionExtractContextProvider(ExtractContextProvider):viking_fs: VikingFS = None,transaction_handle=None,memory_registry: MemoryTypeRegistry | None = None,+ vlm_config: Optional["VLMHandle"] = None,):self.messages = list(messages) if isinstance(messages, list) else messagesself.latest_archive_overview = latest_archive_overview@@ -83,6 +85,7 @@ class SessionExtractContextProvider(ExtractContextProvider):self._ctx = ctxself._viking_fs = viking_fsself._transaction_handle = transaction_handle+ self._vlm_config = vlm_configself._link_enabled = config.memory.link_enabled if config.memory else Falseself._vision_messages_prepared = Falseself._vision_vlm = None@@ -132,10 +135,15 @@ class SessionExtractContextProvider(ExtractContextProvider):def _get_vision_vlm(self):if self._vision_vlm is not None:return self._vision_vlm- vlm_config = get_openviking_config().vlm+ vlm_config = self._vlm_config+ if vlm_config is None:+ raise RuntimeError(+ "SessionExtractContextProvider requires an explicitly resolved "+ "VLM for vision processing"+ )if not (vlm_config and vlm_config.is_available()):return None- self._vision_vlm = vlm_config.get_vlm_instance()+ self._vision_vlm = vlm_configreturn self._vision_vlmdef _detect_language(self) -> str:diff --git a/openviking/session/memory/streaming_memory_updater.py b/openviking/session/memory/streaming_memory_updater.pyindex 6ca48d5c9..698281e71 100644--- a/openviking/session/memory/streaming_memory_updater.py+++ b/openviking/session/memory/streaming_memory_updater.py@@ -17,6 +17,7 @@ from collections.abc import Iterablefrom dataclasses import dataclass, fieldfrom typing import Any, Hashable+from openviking.config.vlm import VLMResolverfrom openviking.core.peer_id import safe_peer_idfrom openviking.message import Messagefrom openviking.server.identity import RequestContext@@ -58,7 +59,6 @@ from openviking.telemetry import tracerfrom openviking.telemetry.tracer import get_trace_idfrom openviking_cli.exceptions import ConflictError, NotFoundErrorfrom openviking_cli.utils import get_logger-from openviking_cli.utils.config import get_openviking_configlogger = get_logger(__name__)@@ -130,6 +130,7 @@ class StreamingMemoryUpdater:registry: MemoryTypeRegistry | None = Nonevikingdb: Any = Noneconfig: StreamingMemoryUpdaterConfig = field(default_factory=StreamingMemoryUpdaterConfig)+ vlm_resolver: VLMResolver | None = None_group_batchers: dict[MemoryMergeGroupKey,StreamingBatcher[MemoryUpdateRequest, StreamingMemoryUpdateResult],@@ -586,6 +587,7 @@ class StreamingMemoryUpdater:),trace_console=self.config.trace_console,force_merge=True,+ vlm_resolver=self.vlm_resolver,)kind_batches = [@@ -755,6 +757,7 @@ async def merge_memory_operations(strict_extract_errors: bool = False,trace_console: bool = False,force_merge: bool = False,+ vlm_resolver: VLMResolver | None = None,) -> ResolvedOperations:"""Merge resolved memory operations by memory type/URI using patch context."""@@ -818,6 +821,7 @@ async def merge_memory_operations(peer_id=peer_id,trace_console=trace_console,force_merge=force_merge,+ vlm_resolver=vlm_resolver,)for (peer_id, memory_type) in all_group_keys],@@ -910,6 +914,7 @@ async def merge_one_memory_type_operations(peer_id: str | None = None,trace_console: bool = False,force_merge: bool = False,+ vlm_resolver: VLMResolver | None = None,) -> ResolvedOperations:registry = registry or get_default_registry()schema = registry.get(memory_type)@@ -1020,12 +1025,19 @@ async def merge_one_memory_type_operations(memory_file_to_delete_patch(df, schema=schema, extract_context=extract_context)for df in delete_files)+ if vlm_resolver is None:+ raise RuntimeError(+ "merge_one_memory_type_operations requires a VLM resolver "+ "for account-owned work"+ )+ vlm_config = await vlm_resolver.get_vlm(ctx.account_id)provider = PatchMergeContextProvider(memory_type=memory_type,required_file_uris=required_file_uris,patches=patches,output_language=merge_output_language_from_messages(messages),memory_registry=registry,+ vlm_config=vlm_config,)provider._ctx = ctxprovider._viking_fs = safe_get_viking_fs()@@ -1060,7 +1072,7 @@ async def merge_one_memory_type_operations(return list(prefetch_messages)provider.prefetch = _prefetch- vlm = get_openviking_config().vlm.get_vlm_instance()+ vlm = vlm_configtracer.info("[streaming_memory_updater] llm merge input "f"memory_type={memory_type} required_file_count={len(required_file_uris)} "@@ -2219,6 +2231,7 @@ async def get_streaming_memory_updater(registry: MemoryTypeRegistry | None = None,vikingdb: Any = None,config: StreamingMemoryUpdaterConfig | None = None,+ vlm_resolver: VLMResolver | None = None,) -> StreamingMemoryUpdater:"""Get or create the process-global streaming updater for one user key."""@@ -2231,11 +2244,14 @@ async def get_streaming_memory_updater(# vectorization for later normal commits with the same user key.if vikingdb is not None and existing.vikingdb is not vikingdb:existing.vikingdb = vikingdb+ if vlm_resolver is not None:+ existing.vlm_resolver = vlm_resolverreturn existingupdater = StreamingMemoryUpdater(registry=registry,vikingdb=vikingdb,config=config or StreamingMemoryUpdaterConfig(),+ vlm_resolver=vlm_resolver,)_streaming_memory_updater_registry[key] = updaterreturn updaterdiff --git a/openviking/session/session.py b/openviking/session/session.pyindex 44d810ba2..612502242 100644--- a/openviking/session/session.py+++ b/openviking/session/session.py@@ -67,6 +67,7 @@ from openviking_cli.utils import get_logger, run_asyncfrom openviking_cli.utils.config import get_openviking_configif TYPE_CHECKING:+ from openviking.config.vlm import VLMResolverfrom openviking.session.compressor_v3 import SessionCompressorV3 as SessionCompressorfrom openviking.storage import VikingDBManagerfrom openviking.storage.queuefs.session_commit_msg import SessionCommitMsg@@ -647,6 +648,7 @@ class Session:usage_reporter: Optional["UsageReporter"] = None,agent_evolution_enabled_provider: Optional[Callable[[], bool | Awaitable[bool]]] = None,memory_policy_provider: Optional[MemoryPolicyProvider] = None,+ vlm_resolver: Optional["VLMResolver"] = None,):self._viking_fs = viking_fsself._vikingdb_manager = vikingdb_manager@@ -680,6 +682,12 @@ class Session:self._agent_evolution_enabled_provider = agent_evolution_enabled_providerself._memory_policy_provider = memory_policy_providerself._usage_reporter = usage_reporter+ self._vlm_resolver = vlm_resolver++ async def _get_vlm_config(self):+ if self._vlm_resolver is None:+ raise RuntimeError("Session requires a VLM resolver for account-owned work")+ return await self._vlm_resolver.get_vlm(self.ctx.account_id)async def _resolve_memory_policy(self, override: Optional[Dict[str, Any]] = None@@ -4312,7 +4320,7 @@ class Session:limits: ExtractionBatchLimits,) -> str:messages = [message for batch in batches for message in batch.messages]- vlm = get_openviking_config().vlm+ vlm = await self._get_vlm_config()if not (vlm and vlm.is_available()):return await self._generate_archive_summary_async(messages,@@ -4390,7 +4398,7 @@ class Session:)checkpoint_instructions = self._checkpoint_prompt_instructions(len(checkpoint_requests))- vlm = get_openviking_config().vlm+ vlm = await self._get_vlm_config()if not (vlm and vlm.is_available()):if checkpoint_requests:raise ValueError("A configured VLM is required to generate checkpoint summaries")@@ -4667,7 +4675,8 @@ class Session:"output_language": output_language,},)- return await get_openviking_config().vlm.get_completion_async(prompt)+ vlm = await self._get_vlm_config()+ return await vlm.get_completion_async(prompt)except Exception as e:logger.warning(f"WM creation fallback failed: {e}")turn_count = len([m for m in messages if is_user_query(m)])diff --git a/openviking/session/train/components/gradient_estimator.py b/openviking/session/train/components/gradient_estimator.pyindex 80de733ff..d3e45ab5e 100644--- a/openviking/session/train/components/gradient_estimator.py+++ b/openviking/session/train/components/gradient_estimator.py@@ -8,6 +8,7 @@ import asynciofrom dataclasses import dataclass, fieldfrom typing import Any+from openviking.config.vlm import VLMResolverfrom openviking.message import Messagefrom openviking.server.identity import RequestContextfrom openviking.session.memory.agent_experience_context_provider import (@@ -22,7 +23,6 @@ from openviking.session.train.utils import first_uri, safe_intfrom openviking.storage.viking_fs import get_viking_fsfrom openviking.telemetry import tracerfrom openviking_cli.utils import get_logger-from openviking_cli.utils.config import get_openviking_configlogger = get_logger(__name__)@@ -48,6 +48,7 @@ class ExperienceGradientEstimator:viking_fs: Any = Nonevlm: Any = None+ vlm_resolver: VLMResolver | None = None@tracer("train.gradient_estimator.experience.estimate",@@ -97,17 +98,36 @@ class ExperienceGradientEstimator:trajectory: Trajectory,context: ExperienceGradientContext,):- config = get_openviking_config()- vlm = self.vlm or config.vlm.get_vlm_instance()+ vlm_config = None+ if self.vlm is None:+ if self.vlm_resolver is None:+ raise RuntimeError(+ "ExperienceGradientEstimator requires a VLM resolver "+ "for account-owned work"+ )+ vlm_config = await self.vlm_resolver.get_vlm(+ context.request_context.account_id+ )+ vlm = vlm_config+ else:+ vlm = self.vlmviking_fs = self.viking_fs or get_viking_fs()if viking_fs is None:raise RuntimeError("VikingFS is required for experience gradient estimation")- provider = AgentExperienceContextProvider(- messages=context.messages,- trajectory_summary=trajectory.content,- trajectory_uri=trajectory.uri,- )+ if vlm_config is None:+ provider = AgentExperienceContextProvider(+ messages=context.messages,+ trajectory_summary=trajectory.content,+ trajectory_uri=trajectory.uri,+ )+ else:+ provider = AgentExperienceContextProvider(+ messages=context.messages,+ trajectory_summary=trajectory.content,+ trajectory_uri=trajectory.uri,+ vlm_config=vlm_config,+ )if hasattr(provider, "get_extract_context"):extract_context = provider.get_extract_context()else:diff --git a/openviking/session/train/components/policy_optimizer.py b/openviking/session/train/components/policy_optimizer.pyindex df5c90ae1..ec2f3397b 100644--- a/openviking/session/train/components/policy_optimizer.py+++ b/openviking/session/train/components/policy_optimizer.py@@ -8,6 +8,7 @@ from collections import defaultdictfrom dataclasses import dataclass, fieldfrom typing import Any+from openviking.config.vlm import VLMResolverfrom openviking.message import Messagefrom openviking.server.identity import RequestContextfrom openviking.session.memory.dataclass import MemoryFile, StoredLink@@ -29,7 +30,6 @@ from openviking.session.train.interfaces import SemanticGradientfrom openviking.session.train.utils import first_uri, safe_intfrom openviking.telemetry import tracerfrom openviking_cli.utils import get_logger-from openviking_cli.utils.config import get_openviking_configlogger = get_logger(__name__)@@ -50,6 +50,7 @@ class PatchMergePolicyOptimizer:vlm: Any = Nonememory_type: str = "experiences"memory_registry: MemoryTypeRegistry | None = None+ vlm_resolver: VLMResolver | None = None@tracer("train.policy_optimizer.patch_merge.plan",@@ -121,19 +122,37 @@ class PatchMergePolicyOptimizer:policy_set: PolicySet,context: PatchMergePolicyOptimizerContext,):- config = get_openviking_config()- vlm = self.vlm or config.vlm.get_vlm_instance()+ vlm_config = None+ if self.vlm is None:+ if self.vlm_resolver is None:+ raise RuntimeError(+ "PatchMergePolicyOptimizer requires a VLM resolver "+ "for account-owned work"+ )+ vlm_config = await self.vlm_resolver.get_vlm(+ context.request_context.account_id+ )+ vlm = vlm_config+ else:+ vlm = self.vlmviking_fs = self.viking_fs or policy_set.viking_fsif viking_fs is None:raise RuntimeError("VikingFS is required for patch-merge policy optimization")extract_context = ExtractContext(list(context.messages or []))- provider = PatchMergeContextProvider(- memory_type=self.memory_type,- memory_registry=self.memory_registry,- required_file_uris=_required_file_uris(gradients, policy_set),- patches=[_gradient_to_merge_patch(gradient) for gradient in gradients],- )+ provider_kwargs = {+ "memory_type": self.memory_type,+ "memory_registry": self.memory_registry,+ "required_file_uris": _required_file_uris(gradients, policy_set),+ "patches": [_gradient_to_merge_patch(gradient) for gradient in gradients],+ }+ if vlm_config is None:+ provider = PatchMergeContextProvider(**provider_kwargs)+ else:+ provider = PatchMergeContextProvider(+ **provider_kwargs,+ vlm_config=vlm_config,+ )provider._ctx = context.request_contextprovider._viking_fs = viking_fsprovider._extract_context = extract_contextdiff --git a/openviking/session/train/components/rollout_executor.py b/openviking/session/train/components/rollout_executor.pyindex a2b5ce2a4..df3080336 100644--- a/openviking/session/train/components/rollout_executor.py+++ b/openviking/session/train/components/rollout_executor.py@@ -10,11 +10,11 @@ from dataclasses import dataclassfrom typing import Anyfrom uuid import uuid4+from openviking.config.vlm import VLMResolverfrom openviking.message import Message, TextPartfrom openviking.session.train.context import ExecutionContextfrom openviking.session.train.domain import Case, ExperienceSet, Rolloutfrom openviking.telemetry import tracer-from openviking_cli.utils.config import get_openviking_configPromptBuilder = Callable[[Case, ExperienceSet, ExecutionContext], str]@@ -31,6 +31,7 @@ class SingleTurnLLMRolloutExecutor:vlm: Any = Noneprompt_builder: PromptBuilder | None = Nonethinking: bool | None = None+ vlm_resolver: VLMResolver | None = None@tracer("train.rollout_executor.single_turn.execute", ignore_result=True, ignore_args=True)async def execute(@@ -39,7 +40,28 @@ class SingleTurnLLMRolloutExecutor:policy_set: ExperienceSet,context: ExecutionContext,) -> list[Rollout]:- vlm = self.vlm or get_openviking_config().vlm+ vlm = self.vlm+ if vlm is None:+ from openviking.service.task_work_index import get_task_context++ task_context = get_task_context()+ policy_context = getattr(policy_set, "request_context", None)+ account_id = (+ getattr(policy_context, "account_id", None)+ or context.metadata.get("account_id")+ or (task_context.account_id if task_context is not None else None)+ )+ if self.vlm_resolver is None:+ raise RuntimeError(+ "SingleTurnLLMRolloutExecutor requires an explicitly resolved "+ "VLM or VLM resolver"+ )+ if not account_id:+ raise RuntimeError(+ "SingleTurnLLMRolloutExecutor requires account_id when using "+ "a VLM resolver"+ )+ vlm = await self.vlm_resolver.get_vlm(str(account_id))rollouts: list[Rollout] = []for case in cases:prompt = self._build_prompt(case, policy_set, context)diff --git a/openviking/session/train/components/trajectory_analyzer.py b/openviking/session/train/components/trajectory_analyzer.pyindex 8ada2093e..a758d5e14 100644--- a/openviking/session/train/components/trajectory_analyzer.py+++ b/openviking/session/train/components/trajectory_analyzer.py@@ -7,6 +7,7 @@ from __future__ import annotationsfrom dataclasses import dataclassfrom typing import Any+from openviking.config.vlm import VLMResolverfrom openviking.core.context import Contextfrom openviking.message import Message, TextPartfrom openviking.server.identity import RequestContext@@ -42,7 +43,6 @@ from openviking.session.train.interfaces import RolloutEvaluatorfrom openviking.storage.viking_fs import get_viking_fsfrom openviking.telemetry import tracerfrom openviking_cli.utils import get_logger-from openviking_cli.utils.config import get_openviking_configlogger = get_logger(__name__)@@ -75,6 +75,7 @@ class TrajectoryRolloutAnalyzer:vikingdb: Any = Nonevlm: Any = Noneevaluator: RolloutEvaluator | None = None+ vlm_resolver: VLMResolver | None = None@tracer("train.rollout_analyzer.trajectory.analyze", ignore_result=True, ignore_args=True)async def analyze(@@ -163,11 +164,21 @@ class TrajectoryRolloutAnalyzer:if not messages or ctx is None:return empty_result+ vlm_config = None+ if self.vlm is None:+ if self.vlm_resolver is None:+ raise RuntimeError(+ "TrajectoryRolloutAnalyzer requires a VLM resolver "+ "for account-owned work"+ )+ vlm_config = await self.vlm_resolver.get_vlm(ctx.account_id)+provider = AgentTrajectoryContextProvider(messages=messages,latest_archive_overview=latest_archive_overview,include_trajectories=include_trajectories,include_session_skills=include_session_skills,+ vlm_config=vlm_config,)consumed_experience_uris = collect_read_experience_uris(messages, ctx=ctx)phase_result = await self._run_trajectory_extract_phase(@@ -200,8 +211,13 @@ class TrajectoryRolloutAnalyzer:source_archive_uri: str = "",consumed_experience_uris: list[str] | None = None,) -> tuple[list[str], list[str], list[Context], list[PatchSemanticGradient]] | None:- config = get_openviking_config()- vlm = self.vlm or config.vlm.get_vlm_instance()+ if self.vlm is None:+ vlm_config = provider._vlm_config+ if vlm_config is None:+ raise RuntimeError("Trajectory provider is missing its resolved VLM config")+ vlm = vlm_config+ else:+ vlm = self.vlmviking_fs = self.viking_fs or get_viking_fs()if viking_fs is None:raise RuntimeError("VikingFS is required to extract trajectory memories")diff --git a/openviking/storage/collection_schemas.py b/openviking/storage/collection_schemas.pyindex 62a1fefe9..b440fe64a 100644--- a/openviking/storage/collection_schemas.py+++ b/openviking/storage/collection_schemas.py@@ -44,7 +44,6 @@ from openviking.storage.viking_vector_index_backend import (from openviking.telemetry import bind_telemetry, resolve_telemetryfrom openviking.telemetry.request_wait_tracker import get_request_wait_trackerfrom openviking.utils.circuit_breaker import (- CircuitBreaker,CircuitBreakerOpen,classify_api_error,)@@ -338,6 +337,19 @@ async def init_context_collection(storage) -> bool:"Existing collection metadata is unavailable; cannot validate embedding compatibility")+ actual_dimension = next(+ (+ field.get("Dim")+ for field in existing_meta.get("Fields", [])+ if field.get("FieldName") == "vector"+ ),+ None,+ )+ if actual_dimension is not None and actual_dimension != vector_dim:+ raise EmbeddingRebuildRequiredError(+ f"Existing collection dimension {actual_dimension} differs from {vector_dim}"+ )+expected_fields = {field.get("FieldName") for field in schema["Fields"]}existing_fields = {field.get("FieldName") for field in existing_meta.get("Fields", [])}missing_fields = sorted(expected_fields - existing_fields)@@ -483,47 +495,27 @@ class TextEmbeddingHandler(DequeueHandlerBase):_request_stats_order: List[str] = []_max_cached_stats = 1024- def __init__(self, vikingdb: VikingVectorIndexBackend):+ def __init__(self, vikingdb: VikingVectorIndexBackend, embedding_provider=None):"""Initialize the text embedding handler.Args:vikingdb: VikingVectorIndexBackend instance for writing to vector database"""- from openviking_cli.utils.config import get_openviking_config-self._vikingdb = vikingdb- self._embedder = None- config = get_openviking_config()- self._collection_name = config.storage.vectordb.name- self._vector_dim = config.embedding.dimension- breaker_cfg = config.embedding.circuit_breaker- self._circuit_breaker = CircuitBreaker(- failure_threshold=breaker_cfg.failure_threshold,- reset_timeout=breaker_cfg.reset_timeout,- max_reset_timeout=breaker_cfg.max_reset_timeout,- )- self._breaker_open_last_log_at = 0.0- self._breaker_open_suppressed_count = 0+ self._embedding_provider = embedding_provider+ self._breaker_open_last_log_at: Dict[str, float] = {}self._breaker_open_log_interval = 30.0- def _initialize_embedder(self, config: "OpenVikingConfig"):- """Initialize the embedder instance from config."""- self._embedder = config.embedding.get_embedder()-- def _log_breaker_open_reenqueue_summary(self) -> None:+ def _log_breaker_open_reenqueue_summary(self, account_id: str) -> None:"""Log a throttled warning when embeddings are re-enqueued due to an open circuit breaker."""now = time.monotonic()- if self._breaker_open_last_log_at == 0.0:- logger.warning("Embedding circuit breaker is open; re-enqueueing messages")- self._breaker_open_last_log_at = now- self._breaker_open_suppressed_count = 0- return-- self._breaker_open_suppressed_count += 1- if now - self._breaker_open_last_log_at >= self._breaker_open_log_interval:- logger.warning("Embedding circuit breaker is open; re-enqueueing messages")- self._breaker_open_last_log_at = now- self._breaker_open_suppressed_count = 0+ last = self._breaker_open_last_log_at.get(account_id)+ if last is None or now - last >= self._breaker_open_log_interval:+ logger.warning(+ "Embedding circuit breaker is open; re-enqueueing messages account=%s",+ account_id,+ )+ self._breaker_open_last_log_at[account_id] = now@classmethoddef _merge_request_stats(@@ -698,7 +690,9 @@ class TextEmbeddingHandler(DequeueHandlerBase):self._embedding_delivery_log_context(embedding_msg),embedding_msg.action.value,)- account_id = inserted_data.get("account_id", "default")+ account_id = inserted_data.get("account_id")+ if not isinstance(account_id, str) or not account_id.strip():+ raise ValueError("Embedding message requires account_id")context_user = inserted_data.get("user") or {}user_id = context_user.get("user_id") or inserted_data.get("owner_user_id") or "default"user = UserIdentifier(account_id=account_id, user_id=user_id)@@ -734,53 +728,23 @@ class TextEmbeddingHandler(DequeueHandlerBase):return ProcessResult.success(data)# Circuit breaker: if API is known-broken, re-enqueue and wait- try:- self._circuit_breaker.check()- self._breaker_open_last_log_at = 0.0- self._breaker_open_suppressed_count = 0- except CircuitBreakerOpen:- self._log_breaker_open_reenqueue_summary()- if self._vikingdb.has_queue_manager:- execute_status = "requeued"- wait = self._circuit_breaker.retry_after- if wait > 0:- await asyncio.sleep(wait)- await self._reenqueue_embedding_msg(embedding_msg)- self._merge_request_stats(- embedding_msg.telemetry_id,- requeue_count=1,- )- get_request_wait_tracker().record_embedding_requeue(- embedding_msg.telemetry_id- )- return ProcessResult.requeued()- # No queue manager — cannot re-enqueue, drop with error- execute_status = "error"- error_msg = self._embedding_error_msg(- embedding_msg,- "Circuit breaker open and no queue manager",- )- request_failed_message = error_msg- return ProcessResult.failed(error_msg)-- # Initialize embedder if not already initialized- if not self._embedder:- from openviking_cli.utils.config import get_openviking_config-- config = get_openviking_config()- self._initialize_embedder(config)+ provider = self._embedding_provider+ if provider is None:+ raise RuntimeError("Account embedding provider is not initialized")+ embedder = provider.bind(account_id)# Generate embedding vector(s)- if self._embedder:+ if embedder:try:import time as _time_embed_t0 = _time.monotonic()result = await embed_compat(- self._embedder,+ embedder,embedding_msg.message,is_query=False,)+ self._breaker_open_last_log_at.pop(account_id, None)_embed_elapsed = _time.monotonic() - _embed_t0try:from openviking.metrics.datasources import EmbeddingEventDataSource@@ -791,6 +755,24 @@ class TextEmbeddingHandler(DequeueHandlerBase):)except Exception:pass+ except CircuitBreakerOpen as embed_err:+ self._log_breaker_open_reenqueue_summary(account_id)+ if self._vikingdb.has_queue_manager:+ execute_status = "requeued"+ wait = getattr(embed_err, "retry_after", 0)+ if wait > 0:+ await asyncio.sleep(wait)+ await self._reenqueue_embedding_msg(embedding_msg)+ self._merge_request_stats(embedding_msg.telemetry_id, requeue_count=1)+ get_request_wait_tracker().record_embedding_requeue(+ embedding_msg.telemetry_id+ )+ return ProcessResult.requeued()+ execute_status = "error"+ request_failed_message = self._embedding_error_msg(+ embedding_msg, "Circuit breaker open and no queue manager"+ )+ return ProcessResult.failed(request_failed_message)except Exception as embed_err:error_msg = self._embedding_error_msg(embedding_msg,@@ -817,7 +799,6 @@ class TextEmbeddingHandler(DequeueHandlerBase):if error_class == ERROR_CLASS_PERMANENT:execute_status = "error"self._log_embedding_error(logging.CRITICAL, error_msg, embedding_msg)- self._circuit_breaker.record_failure(embed_err)self._merge_request_stats(embedding_msg.telemetry_id, error_count=1)request_failed_message = error_msgreturn ProcessResult.failed(error_msg)@@ -838,7 +819,6 @@ class TextEmbeddingHandler(DequeueHandlerBase):# Transient or unknown — re-enqueue for retryself._log_embedding_error(logging.WARNING, error_msg, embedding_msg)execute_status = "requeued"- self._circuit_breaker.record_failure(embed_err)if self._vikingdb.has_queue_manager:try:await self._reenqueue_embedding_msg(embedding_msg)@@ -870,18 +850,6 @@ class TextEmbeddingHandler(DequeueHandlerBase):# Add dense vectorif result.dense_vector:inserted_data["vector"] = result.dense_vector- # Validate vector dimension- if len(result.dense_vector) != self._vector_dim:- execute_status = "error"- error_msg = self._embedding_error_msg(- embedding_msg,- "Dense vector dimension mismatch: "- f"expected {self._vector_dim}, got {len(result.dense_vector)}",- )- self._log_embedding_error(logging.ERROR, error_msg, embedding_msg)- self._merge_request_stats(embedding_msg.telemetry_id, error_count=1)- request_failed_message = error_msg- return ProcessResult.failed(error_msg)# Add sparse vector if presentif result.sparse_vector:@@ -921,7 +889,7 @@ class TextEmbeddingHandler(DequeueHandlerBase):account_id, uri, inserted_data.get("level", 2))- if self._vikingdb.uses_content_field:+ if await self._vikingdb.account_uses_content_field(account_id):inserted_data["content"] = await self._materialize_content(embedding_msg,ctx,@@ -1025,7 +993,6 @@ class TextEmbeddingHandler(DequeueHandlerBase):embedding_msg,vector_written=bool(record_id),)- self._circuit_breaker.record_success()return ProcessResult.success(inserted_data)except asyncio.CancelledError:diff --git a/openviking/storage/observers/filesystem_observer.py b/openviking/storage/observers/filesystem_observer.pyindex 68636dd81..2839d475e 100644--- a/openviking/storage/observers/filesystem_observer.py+++ b/openviking/storage/observers/filesystem_observer.py@@ -125,7 +125,7 @@ class FilesystemObserver(BaseObserver):return "\n".join(result)- def get_status_table(self) -> str:+ async def get_status_table_async(self) -> str:"""Format filesystem statistics as a string table.@@ -134,21 +134,29 @@ class FilesystemObserver(BaseObserver):"""try:observer_service = self._get_collector()- stats_data = run_async(observer_service.get_filesystem_stats(self.mount_path))+ stats_data = await observer_service.get_filesystem_stats(self.mount_path)return self._format_stats_table(stats_data)except Exception as e:logger.error(f"Error getting filesystem stats: {e}")return f"Error retrieving filesystem statistics: {e}"- def get_status_json(self) -> dict:+ async def get_status_json_async(self) -> dict:"""Return filesystem statistics as structured JSON."""try:observer_service = self._get_collector()- return run_async(observer_service.get_filesystem_stats(self.mount_path))+ return await observer_service.get_filesystem_stats(self.mount_path)except Exception as e:logger.error(f"Error getting filesystem stats: {e}")return {"error": str(e), "mounts": []}+ def get_status_table(self) -> str:+ """Synchronous compatibility wrapper for non-async callers."""+ return run_async(self.get_status_table_async())++ def get_status_json(self) -> dict:+ """Synchronous compatibility wrapper for non-async callers."""+ return run_async(self.get_status_json_async())+def __str__(self) -> str:return self.get_status_table()diff --git a/openviking/storage/observers/vikingdb_observer.py b/openviking/storage/observers/vikingdb_observer.pyindex d3a72b4a6..99ab4e77a 100644--- a/openviking/storage/observers/vikingdb_observer.py+++ b/openviking/storage/observers/vikingdb_observer.py@@ -31,11 +31,15 @@ class VikingDBObserver(BaseObserver):if not self._vikingdb_manager:return "VikingDB manager not initialized."- if not await self._vikingdb_manager.collection_exists():+ backend = (+ await self._vikingdb_manager.get_account_backend(ctx.account_id)+ if ctx is not None else self._vikingdb_manager+ )+ if not await backend.collection_exists():return "No collections found."statuses = await self._get_collection_statuses(- [self._vikingdb_manager.collection_name], ctx=ctx+ [backend.collection_name], ctx=ctx)return self._format_status_as_table(statuses)@@ -101,10 +105,14 @@ class VikingDBObserver(BaseObserver):self, collection_names: list, *, ctx: Optional[RequestContext] = None) -> Dict[str, Dict]:statuses = {}+ backend = (+ await self._vikingdb_manager.get_account_backend(ctx.account_id)+ if ctx is not None else self._vikingdb_manager+ )for name in collection_names:try:- if not await self._vikingdb_manager.collection_exists():+ if not await backend.collection_exists():continue# Current OpenViking flow uses one managed default index per collection.diff --git a/openviking/storage/ovpack/operations.py b/openviking/storage/ovpack/operations.pyindex 47ff28ebf..3e5c0c731 100644--- a/openviking/storage/ovpack/operations.py+++ b/openviking/storage/ovpack/operations.py@@ -267,6 +267,7 @@ async def import_ovpack(on_conflict: Optional[str] = None,vector_mode: Optional[str] = None,vector_store=None,+ vector_config_resolver=None,) -> str:"""Import .ovpack file to the specified parent path.@@ -323,12 +324,14 @@ async def import_ovpack()if not is_session_uri(root_uri):- vector_action = choose_vector_restore_action(+ vector_action = await choose_vector_restore_action(manifest,index_records,dense_vectors,vector_store=vector_store,+ vector_config_resolver=vector_config_resolver,vector_mode=vector_action_mode,+ ctx=ctx,)if parent != "viking://":@@ -422,6 +425,8 @@ async def _write_ovpack_archive(index_records: list[dict[str, Any]],dense_values: list[float],ctx: RequestContext,+ vector_store,+ vector_config_resolver,) -> str:ensure_dir_exists(to)manifest_entries = manifest_entries_by_path(manifest)@@ -469,7 +474,14 @@ async def _write_ovpack_archive(zf.writestr(f"{base_name}/{OVPACK_INTERNAL_DIR}/", "")zf.writestr(internal_zip_path(base_name, OVPACK_INDEX_RECORDS_PATH), index_bytes)- dense_snapshot = build_dense_snapshot_manifest(index_records, dense_values)+ dense_snapshot = None+ if dense_values:+ if vector_config_resolver is None:+ raise RuntimeError("OVPack requires a vector config resolver")+ settings = await vector_config_resolver.resolve(ctx.account_id)+ dense_snapshot = build_dense_snapshot_manifest(+ index_records, dense_values, settings.embedding+ )if dense_snapshot is not None:dense_bytes, dense_manifest = dense_snapshotmanifest["index"]["dense"] = dense_manifest@@ -488,6 +500,7 @@ async def export_ovpack(to: str,ctx: RequestContext,vector_store=None,+ vector_config_resolver=None,include_vectors: bool = False,) -> str:"""@@ -525,7 +538,7 @@ async def export_ovpack()entries = await _filter_existing_optional_sidecars(viking_fs, uri, entries, ctx)if include_vectors:- ensure_dense_snapshot_supported(vector_store)+ await ensure_dense_snapshot_supported(vector_store, vector_config_resolver, ctx)report = await check_index_consistency(viking_fs,vector_store,@@ -557,6 +570,8 @@ async def export_ovpack(index_records,dense_values,ctx,+ vector_store,+ vector_config_resolver,)logger.info(f"[ovpack] Exported {uri} to {to}")@@ -568,6 +583,7 @@ async def backup_ovpack(to: str,ctx: RequestContext,vector_store=None,+ vector_config_resolver=None,include_vectors: bool = False,) -> str:"""Export all public OpenViking scopes as a restore-only backup package."""@@ -580,7 +596,7 @@ async def backup_ovpack(entries = await _backup_entries(viking_fs, ctx)entries = await _filter_existing_optional_sidecars(viking_fs, "viking://", entries, ctx)if include_vectors:- ensure_dense_snapshot_supported(vector_store)+ await ensure_dense_snapshot_supported(vector_store, vector_config_resolver, ctx)report = await check_index_consistency(viking_fs,vector_store,@@ -614,6 +630,8 @@ async def backup_ovpack(index_records,dense_values,ctx,+ vector_store,+ vector_config_resolver,)logger.info(f"[ovpack] Backed up OpenViking public scopes to {to}")@@ -627,6 +645,7 @@ async def restore_ovpack(on_conflict: Optional[str] = None,vector_mode: Optional[str] = None,vector_store=None,+ vector_config_resolver=None,) -> str:"""Restore a backup package to its original public scope roots."""if not os.path.exists(file_path):@@ -679,12 +698,14 @@ async def restore_ovpack(resource=resource,)- vector_action = choose_vector_restore_action(+ vector_action = await choose_vector_restore_action(manifest,index_records,dense_vectors,vector_store=vector_store,+ vector_config_resolver=vector_config_resolver,vector_mode=vector_action_mode,+ ctx=ctx,)content_members = [diff --git a/openviking/storage/ovpack/vectors.py b/openviking/storage/ovpack/vectors.pyindex 84d8e5e02..2a4f887c6 100644--- a/openviking/storage/ovpack/vectors.py+++ b/openviking/storage/ovpack/vectors.py@@ -22,8 +22,8 @@ from openviking.storage.ovpack.format import (sha256_hex,)from openviking.storage.ovpack.manifest import manifest_dense_info, manifest_entry_target_uri-from openviking.storage.vector_ids import vector_record_idfrom openviking.storage.ovpack.validation import dense_record_count, record_dense_ref+from openviking.storage.vector_ids import vector_record_idfrom openviking.utils.time_utils import get_current_timestampfrom openviking_cli.exceptions import InvalidArgumentErrorfrom openviking_cli.utils.logger import get_logger@@ -41,34 +41,36 @@ def _index_meta_is_hybrid(index_meta: Any) -> bool:return "hybrid" in index_type-def _vector_store_index_meta_is_hybrid(vector_store: Any) -> bool:- candidates = [vector_store, getattr(vector_store, "_manager", None)]- for candidate in candidates:- if candidate is None:- continue- index_name = getattr(candidate, "_index_name", None)- try:- backend = candidate._get_default_backend()- index_name = index_name or getattr(backend, "_index_name", None)- collection = backend._get_collection()- if index_name and hasattr(collection, "get_index_meta_data"):- if _index_meta_is_hybrid(collection.get_index_meta_data(index_name)):- return True- except Exception:- continue- return False---def dense_snapshot_unsupported_reason(vector_store=None) -> str | None:+async def dense_snapshot_unsupported_reason(+ vector_store,+ vector_config_resolver,+ ctx: RequestContext,+) -> str | None:"""Return why dense vector snapshots are unsupported in the current runtime."""- if _vector_store_index_meta_is_hybrid(vector_store):+ if vector_store is None:+ return None+ if vector_config_resolver is None:+ raise RuntimeError("OVPack requires a vector config resolver")+ settings = await vector_config_resolver.resolve(ctx.account_id)+ if settings.embedding.sparse or settings.embedding.hybrid or settings.vectordb.sparse_weight:+ return "current vector index type is hybrid"+ backend = await vector_store.get_account_backend(ctx.account_id)+ meta = await backend.get_collection_meta()+ if _index_meta_is_hybrid(meta):return "current vector index type is hybrid"-return None-def ensure_dense_snapshot_supported(vector_store=None) -> None:- reason = dense_snapshot_unsupported_reason(vector_store)+async def ensure_dense_snapshot_supported(+ vector_store,+ vector_config_resolver,+ ctx: RequestContext,+) -> None:+ reason = await dense_snapshot_unsupported_reason(+ vector_store,+ vector_config_resolver,+ ctx,+ )if reason:raise InvalidArgumentError("ovpack vector snapshots only support pure dense vector indexes",@@ -76,25 +78,19 @@ def ensure_dense_snapshot_supported(vector_store=None) -> None:)-def embedding_snapshot_metadata(dimensions: int | None) -> dict[str, Any]:+def embedding_snapshot_metadata(dimensions: int | None, embedding_cfg) -> dict[str, Any]:metadata: dict[str, Any] = {}- try:- from openviking_cli.utils.config import get_openviking_config-- embedding_cfg = get_openviking_config().embedding- model_cfg = embedding_cfg.hybrid or embedding_cfg.dense- if model_cfg:- metadata = {- "provider": model_cfg.provider,- "model": model_cfg.model,- "input": model_cfg.input,- "query_param": model_cfg.query_param,- "document_param": model_cfg.document_param,- }- if dimensions is None:- dimensions = model_cfg.get_effective_dimension()- except Exception:- pass+ model_cfg = embedding_cfg.hybrid or embedding_cfg.dense+ if model_cfg:+ metadata = {+ "provider": model_cfg._effective_provider(),+ "model": model_cfg._effective_model(),+ "input": model_cfg.input,+ "query_param": model_cfg.query_param,+ "document_param": model_cfg.document_param,+ }+ if dimensions is None:+ dimensions = model_cfg.get_effective_dimension()if dimensions is not None:metadata["dimensions"] = dimensions@@ -104,6 +100,7 @@ def embedding_snapshot_metadata(dimensions: int | None) -> dict[str, Any]:def build_dense_snapshot_manifest(index_records: list[dict[str, Any]],dense_values: list[float],+ embedding_cfg,) -> tuple[bytes, dict[str, Any]] | None:if not dense_values:return None@@ -130,7 +127,7 @@ def build_dense_snapshot_manifest("byte_order": "little","dimensions": dense_dimensions,"sha256": sha256_hex(dense_bytes),- "embedding": embedding_snapshot_metadata(dense_dimensions),+ "embedding": embedding_snapshot_metadata(dense_dimensions, embedding_cfg),}@@ -157,27 +154,11 @@ def read_dense_vectors(return vectors-def current_embedding_metadata() -> dict[str, Any]:- try:- from openviking_cli.utils.config import get_openviking_config-- embedding_cfg = get_openviking_config().embedding- model_cfg = embedding_cfg.hybrid or embedding_cfg.dense- if not model_cfg:- return {}- return {- "provider": model_cfg.provider,- "model": model_cfg.model,- "input": model_cfg.input,- "query_param": model_cfg.query_param,- "document_param": model_cfg.document_param,- "dimensions": model_cfg.get_effective_dimension(),- }- except Exception:- return {}+def current_embedding_metadata(embedding_cfg) -> dict[str, Any]:+ return embedding_snapshot_metadata(None, embedding_cfg)-def _embedding_snapshot_compatible(manifest: dict[str, Any]) -> tuple[bool, str]:+def _embedding_snapshot_compatible(manifest: dict[str, Any], embedding_cfg) -> tuple[bool, str]:dense_info = manifest_dense_info(manifest)if dense_info is None:return False, "missing dense vector snapshot"@@ -186,7 +167,7 @@ def _embedding_snapshot_compatible(manifest: dict[str, Any]) -> tuple[bool, str]if not isinstance(package_embedding, dict):return False, "missing embedding metadata"- current_embedding = current_embedding_metadata()+ current_embedding = current_embedding_metadata(embedding_cfg)if not current_embedding:return False, "current embedding metadata is unavailable"@@ -199,30 +180,19 @@ def _embedding_snapshot_compatible(manifest: dict[str, Any]) -> tuple[bool, str]return True, ""-def choose_vector_restore_action(+async def choose_vector_restore_action(manifest: dict[str, Any],index_records: list[dict[str, Any]],dense_vectors: dict[str, list[float]],*,vector_store,+ vector_config_resolver,vector_mode: str,+ ctx: RequestContext,) -> str:if vector_mode == "recompute":return "recompute"- unsupported_reason = dense_snapshot_unsupported_reason(vector_store)- if unsupported_reason:- if vector_mode == "require":- raise InvalidArgumentError(- "ovpack dense vector snapshot cannot be restored into a sparse or hybrid index",- details={"reason": unsupported_reason},- )- logger.info(- "[ovpack] Recomputing vectors because dense snapshot restore is unsupported: "- f"{unsupported_reason}"- )- return "recompute"-dense_count = dense_record_count(index_records)if dense_count == 0 or not dense_vectors:if vector_mode == "require":@@ -242,7 +212,25 @@ def choose_vector_restore_action(raise InvalidArgumentError("Vector restore requires a writable vector store")return "recompute"- compatible, reason = _embedding_snapshot_compatible(manifest)+ unsupported_reason = await dense_snapshot_unsupported_reason(+ vector_store,+ vector_config_resolver,+ ctx,+ )+ if unsupported_reason:+ if vector_mode == "require":+ raise InvalidArgumentError(+ "ovpack dense vector snapshot cannot be restored into a sparse or hybrid index",+ details={"reason": unsupported_reason},+ )+ logger.info(+ "[ovpack] Recomputing vectors because dense snapshot restore is unsupported: "+ f"{unsupported_reason}"+ )+ return "recompute"++ settings = await vector_config_resolver.resolve(ctx.account_id)+ compatible, reason = _embedding_snapshot_compatible(manifest, settings.embedding)if not compatible:if vector_mode == "require":raise InvalidArgumentError(diff --git a/openviking/storage/queuefs/add_resource_msg.py b/openviking/storage/queuefs/add_resource_msg.pyindex 42f7a90fa..fcd5b64af 100644--- a/openviking/storage/queuefs/add_resource_msg.py+++ b/openviking/storage/queuefs/add_resource_msg.py@@ -110,6 +110,7 @@ class AddResourceMsg:task_id = data.get("task_id")path = data.get("path")root_uri = data.get("root_uri")+ account_id = data.get("account_id")prepared = data.get("prepared") if isinstance(data.get("prepared"), dict) else Nonestaged_source = Noneif data.get("staged_source") is not None:@@ -139,7 +140,13 @@ class AddResourceMsg:if prepared is not None:args.clear()has_source_payload = bool(prepared or staged_source or shared_source)- if not task_id or (not path and not has_source_payload) or not root_uri:+ if (+ not task_id+ or (not path and not has_source_payload)+ or not root_uri+ or not isinstance(account_id, str)+ or not account_id.strip()+ ):missing = []if not task_id:missing.append("task_id")@@ -147,6 +154,8 @@ class AddResourceMsg:missing.append("path, prepared, staged_source, or shared_source")if not root_uri:missing.append("root_uri")+ if not isinstance(account_id, str) or not account_id.strip():+ missing.append("account_id")raise ValueError(f"Missing required fields: {missing}")return cls(@@ -154,7 +163,7 @@ class AddResourceMsg:path=str(path or ""),source_path=str(data.get("source_path") or path or ""),root_uri=str(root_uri),- account_id=str(data.get("account_id", "default")),+ account_id=account_id,user_id=str(data.get("user_id", "default")),group_ids=([str(group_id) for group_id in data["group_ids"]]diff --git a/openviking/storage/queuefs/embedding_msg.py b/openviking/storage/queuefs/embedding_msg.pyindex af8aba7a7..6aff26c9f 100644--- a/openviking/storage/queuefs/embedding_msg.py+++ b/openviking/storage/queuefs/embedding_msg.py@@ -144,6 +144,13 @@ class EmbeddingMsg:initial_fields=dict(initial_fields or {}),)self._validate_payload()+ self._validate_account_context()++ def _validate_account_context(self) -> None:+ context_data = getattr(self.payload, "context_data", {})+ account_id = context_data.get("account_id") if isinstance(context_data, dict) else None+ if not isinstance(account_id, str) or not account_id.strip():+ raise ValueError("Embedding message requires account_id")def _legacy_payload(self,diff --git a/openviking/storage/queuefs/embedding_msg_converter.py b/openviking/storage/queuefs/embedding_msg_converter.pyindex f44e4d12d..b3b5869d6 100644--- a/openviking/storage/queuefs/embedding_msg_converter.py+++ b/openviking/storage/queuefs/embedding_msg_converter.py@@ -43,10 +43,12 @@ class EmbeddingMsgConverter:context_data = context.to_dict()- # Backfill tenant fields for legacy writers that only set user/uri.- if not context_data.get("account_id"):- user = context_data.get("user") or {}- context_data["account_id"] = user.get("account_id", "default")+ # Account identity is required at the queue boundary. Do not silently+ # route a malformed or legacy message to the default Account.+ if not isinstance(context_data.get("account_id"), str) or not context_data[+ "account_id"+ ].strip():+ raise ValueError("Embedding context requires account_id")uri = context_data.get("uri", "")owner_fields = Noneif uri:diff --git a/openviking/storage/queuefs/queue_manager.py b/openviking/storage/queuefs/queue_manager.pyindex cd55d3fee..43a78b537 100644--- a/openviking/storage/queuefs/queue_manager.py+++ b/openviking/storage/queuefs/queue_manager.py@@ -10,7 +10,7 @@ import atexitimport threadingimport timeimport traceback-from typing import Any, Dict, Optional, Sequence, Set, Union+from typing import TYPE_CHECKING, Any, Dict, Optional, Sequence, Set, Unionfrom openviking.service.task_work_index import TaskWorkIndexfrom openviking_cli.utils.logger import get_logger@@ -20,6 +20,9 @@ from .named_queue import DequeueHandlerBase, NamedQueue, QueueStatusfrom .queue_middleware import QueueMiddlewarefrom .semantic_queue import SemanticQueue+if TYPE_CHECKING:+ from openviking.config.vlm import VLMResolver+logger = get_logger(__name__)DEFAULT_MAX_CONCURRENT_SESSION_COMMIT = 8@@ -128,6 +131,7 @@ class QueueManager:self._embedding_worker_stopped = threading.Event()self._poll_interval = 0.2self._task_work_index = TaskWorkIndex()+ self._vlm_resolver: Optional["VLMResolver"] = None# Import at composition time to avoid a service <-> queue package cycle.from openviking.service.task_queue_middleware import TaskWorkQueueMiddleware@@ -145,6 +149,10 @@ class QueueManager:"""Start QueueManager workers."""if self._started:return+ if self.SEMANTIC in self._queues and self._vlm_resolver is None:+ raise RuntimeError(+ "QueueManager requires a VLM resolver before semantic workers start"+ )self._started = True@@ -161,23 +169,29 @@ class QueueManager:tracker.attach_work_index(self._task_work_index)return await tracker.restore_work_tasks(owners)- def setup_standard_queues(self, vector_store: Any, start: bool = True) -> None:+ def setup_standard_queues(+ self,+ vector_store: Any,+ start: bool = True,+ *,+ embedding_provider: Any = None,+ ) -> None:"""Setup standard queues (Embedding and Semantic) with their handlers.Args:vector_store: Vector store instance for handlers to write results.start: Whether to start worker threads immediately (default True).- Pass False when the consumer depends on resources that are- not yet initialized (e.g. VikingFS); call start() manually- after those resources are ready.+ Pass False when the consumer depends on resources that are not+ yet initialized.+ embedding_provider: Account-aware embedding provider for the handler."""# Import handlers here to avoid circular dependenciesfrom openviking.storage.collection_schemas import TextEmbeddingHandlerfrom openviking.storage.queuefs import SemanticProcessor# Embedding Queue- embedding_handler = TextEmbeddingHandler(vector_store)+ embedding_handler = TextEmbeddingHandler(vector_store, embedding_provider)self.get_queue(self.EMBEDDING,dequeue_handler=embedding_handler,@@ -189,6 +203,7 @@ class QueueManager:semantic_processor = SemanticProcessor(max_concurrent_llm=self._max_concurrent_semantic,embedding_worker_stopped=self._embedding_worker_stopped.is_set,+ vlm_resolver=self._vlm_resolver,)self.get_queue(self.SEMANTIC,@@ -200,6 +215,23 @@ class QueueManager:if start:self.start()+ def set_vlm_resolver(self, resolver: "VLMResolver") -> None:+ """Bind the owning service's resolver before queue workers start."""+ from openviking.storage.queuefs import SemanticProcessor++ if self._started:+ raise RuntimeError("Cannot replace the VLM resolver after queue workers start")+ self._vlm_resolver = resolver+ queue = self._queues.get(self.SEMANTIC)+ if queue is not None:+ queue.set_dequeue_handler(+ SemanticProcessor(+ max_concurrent_llm=self._max_concurrent_semantic,+ embedding_worker_stopped=self._embedding_worker_stopped.is_set,+ vlm_resolver=resolver,+ )+ )+def _start_queue_worker(self, queue: NamedQueue) -> None:"""Start a dedicated worker thread for a queue if not already running."""if queue.name in self._queue_threads:diff --git a/openviking/storage/queuefs/semantic_executor.py b/openviking/storage/queuefs/semantic_executor.pyindex b3099f67d..77ac836cb 100644--- a/openviking/storage/queuefs/semantic_executor.py+++ b/openviking/storage/queuefs/semantic_executor.py@@ -1435,6 +1435,7 @@ class SemanticTreeExecutor:children_abstracts,total_files=len(node.file_paths),total_children=len(node.children_dirs),+ ctx=self._ctx,)overview, abstract = self._processor._normalize_overview_generation(overview)diff --git a/openviking/storage/queuefs/semantic_msg.py b/openviking/storage/queuefs/semantic_msg.pyindex d29d324bd..48c31e73c 100644--- a/openviking/storage/queuefs/semantic_msg.py+++ b/openviking/storage/queuefs/semantic_msg.py@@ -173,6 +173,7 @@ class SemanticMsg:uri = data.get("uri")context_type = data.get("context_type")+ account_id = data.get("account_id")if not uri or not context_type:missing = []@@ -181,12 +182,14 @@ class SemanticMsg:if not context_type:missing.append("context_type")raise ValueError(f"Missing required fields: {missing}")+ if not isinstance(account_id, str) or not account_id.strip():+ raise ValueError("Missing required fields: ['account_id']")obj = cls(uri=uri,context_type=context_type,recursive=data.get("recursive", True),- account_id=data.get("account_id", "default"),+ account_id=account_id,user_id=data.get("user_id", "default"),group_ids=data.get("group_ids") if isinstance(data.get("group_ids"), list) else None,peer_id=data.get("peer_id", "default"),diff --git a/openviking/storage/queuefs/semantic_processor.py b/openviking/storage/queuefs/semantic_processor.pyindex 71a5922b5..60e358227 100644--- a/openviking/storage/queuefs/semantic_processor.py+++ b/openviking/storage/queuefs/semantic_processor.py@@ -7,7 +7,7 @@ import reimport threadingimport timefrom contextlib import nullcontext-from typing import Any, Awaitable, Callable, Dict, List, Optional, Set, Tuple+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List, Optional, Set, Tuplefrom urllib.parse import unquote, urlsplitfrom openviking.core.namespace import classify_uri@@ -77,8 +77,10 @@ from openviking_cli.utils import VikingURIfrom openviking_cli.utils.config import get_openviking_configfrom openviking_cli.utils.logger import get_logger-logger = get_logger(__name__)+if TYPE_CHECKING:+ from openviking.config.vlm import VLMHandle, VLMResolver+logger = get_logger(__name__)class RequestQueueStats:processed: int = 0@@ -126,6 +128,7 @@ class SemanticProcessor(DequeueHandlerBase):max_concurrent_llm: int = 32,*,embedding_worker_stopped: Optional[Callable[[], bool]] = None,+ vlm_resolver: Optional["VLMResolver"] = None,):"""Initialize SemanticProcessor.@@ -135,8 +138,24 @@ class SemanticProcessor(DequeueHandlerBase):"""self.max_concurrent_llm = max_concurrent_llmself._default_ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)- self._circuit_breaker = CircuitBreaker()+ self._circuit_breakers: Dict[str, CircuitBreaker] = {}+ self._breaker_lock = threading.Lock()self._embedding_worker_stopped = embedding_worker_stopped+ self._vlm_resolver = vlm_resolver++ def _account_breaker(self, account_id: str) -> CircuitBreaker:+ with self._breaker_lock:+ breaker = self._circuit_breakers.get(account_id)+ if breaker is None:+ breaker = self._circuit_breakers[account_id] = CircuitBreaker()+ return breaker++ async def _get_vlm_config(self, ctx: RequestContext) -> "VLMHandle":+ if self._vlm_resolver is None:+ raise RuntimeError(+ "SemanticProcessor requires a VLM resolver for account-owned work"+ )+ return await self._vlm_resolver.get_vlm(ctx.account_id)@classmethoddef _cache_tree_stats(cls, telemetry_id: str, uri: str, stats: SemanticTreeStats) -> None:@@ -251,7 +270,7 @@ class SemanticProcessor(DequeueHandlerBase):from openviking.storage.queuefs import get_queue_manager# Throttle to prevent re-enqueue storm during OPEN window- wait = self._circuit_breaker.retry_after+ wait = self._account_breaker(msg.account_id).retry_afterif wait > 0:with pause_task_processing():await asyncio.sleep(wait)@@ -414,6 +433,7 @@ class SemanticProcessor(DequeueHandlerBase):execute_started_at: float | None = Nonequeue_wait_ms = 0.0execute_status = "ok"+ breaker = Nonetry:import json@@ -425,6 +445,7 @@ class SemanticProcessor(DequeueHandlerBase):assert data is not Nonemsg = SemanticMsg.from_dict(data)+ breaker = self._account_breaker(msg.account_id)work = self._message_work(msg, lock)work.start()execute_started_at = time.perf_counter()@@ -468,7 +489,7 @@ class SemanticProcessor(DequeueHandlerBase):return ProcessResult.success()# Circuit breaker: if API is known-broken, re-enqueue and waittry:- self._circuit_breaker.check()+ breaker.check()except CircuitBreakerOpen:logger.warning(f"Circuit breaker is open, re-enqueueing semantic message: {msg.uri}"@@ -506,6 +527,11 @@ class SemanticProcessor(DequeueHandlerBase):get_request_wait_tracker().mark_semantic_done(msg.telemetry_id, msg.id)return ProcessResult.success()+ if self._vlm_resolver is None:+ raise RuntimeError(+ "SemanticProcessor requires a VLM resolver "+ "for account-owned work"+ )if not await work.acquire_lock(current_ctx):get_request_wait_tracker().mark_semantic_done(msg.telemetry_id, msg.id)return ProcessResult.success()@@ -682,7 +708,7 @@ class SemanticProcessor(DequeueHandlerBase):get_request_wait_tracker().mark_semantic_done(msg.telemetry_id, msg.id)self._merge_request_stats(msg.telemetry_id, processed=1)logger.info(f"Completed semantic generation for: {msg.uri}")- self._circuit_breaker.record_success()+ breaker.record_success()await self._cleanup_local_artifact(msg)return ProcessResult.success()finally:@@ -731,8 +757,10 @@ class SemanticProcessor(DequeueHandlerBase):exc_info=True,)# A malformed filesystem target does not indicate an API outage.- if not any(isinstance(exc, AGFSNotADirectoryError) for exc in (e, e.__cause__)):- self._circuit_breaker.record_failure(e)+ if breaker is not None and not any(+ isinstance(exc, AGFSNotADirectoryError) for exc in (e, e.__cause__)+ ):+ breaker.record_failure(e)if msg is not None:self._merge_request_stats(msg.telemetry_id, error_count=1)get_request_wait_tracker().mark_semantic_failed(@@ -748,7 +776,8 @@ class SemanticProcessor(DequeueHandlerBase):f"Transient API error processing semantic message, re-enqueueing: {e}",exc_info=True,)- self._circuit_breaker.record_failure(e)+ if breaker is not None:+ breaker.record_failure(e)if msg is not None and work is not None:return await self._requeue_semantic_msg_after_error(msg,@@ -993,6 +1022,7 @@ class SemanticProcessor(DequeueHandlerBase):[],llm_sem=llm_sem,total_files=len(file_paths),+ ctx=ctx,)overview, abstract = self._normalize_overview_generation(generated_content)@@ -1205,7 +1235,6 @@ class SemanticProcessor(DequeueHandlerBase):) -> Dict[str, Any]:"""Generate summary for a single text file (code, documentation, or other text)."""viking_fs = get_viking_fs()- vlm = get_openviking_config().vlmactive_ctx = ctx or self._default_ctxcontent = (@@ -1241,34 +1270,23 @@ class SemanticProcessor(DequeueHandlerBase):if len(skeleton_text) > max_skeleton_chars:skeleton_text = skeleton_text[:max_skeleton_chars]return result(skeleton_text)- if not vlm.is_available():- logger.warning("VLM not available for code summary fallback: %s", file_path)- return result("")-- from openviking.session.memory.utils.language import resolve_output_language-- output_language = resolve_output_language(content, config=config)- prompt = render_prompt(- "semantic.code_summary",- {"file_name": file_name, "content": content, "output_language": output_language},- )- async with llm_sem:- with bind_telemetry_stage("semantic_execute"):- summary = await vlm.get_completion_async(prompt)- return result(summary.strip())+ prompt_id = "semantic.code_summary"+ elif file_type == FILE_TYPE_DOCUMENTATION:+ prompt_id = "semantic.document_summary"+ else:+ prompt_id = "semantic.file_summary"+ vlm = await self._get_vlm_config(active_ctx)if not vlm.is_available():- logger.warning("VLM not available, using empty summary")+ if file_type == FILE_TYPE_CODE:+ logger.warning("VLM not available for code summary fallback: %s", file_path)+ else:+ logger.warning("VLM not available, using empty summary")return result("")from openviking.session.memory.utils.language import resolve_output_languageoutput_language = resolve_output_language(content, config=config)- if file_type == FILE_TYPE_DOCUMENTATION:- prompt_id = "semantic.document_summary"- else:- prompt_id = "semantic.file_summary"-prompt = render_prompt(prompt_id,{"file_name": file_name, "content": content, "output_language": output_language},@@ -1312,16 +1330,34 @@ class SemanticProcessor(DequeueHandlerBase):except Exception:prefix = Nonemedia_type = get_media_type(file_name, None, content=prefix)- if media_type == "image":- return await generate_image_summary(file_path, file_name, llm_sem, ctx=ctx)- elif media_type == "audio":- return await generate_audio_summary(file_path, file_name, llm_sem, ctx=ctx)- elif media_type == "video":- return await generate_video_summary(file_path, file_name, llm_sem, ctx=ctx)- else:- return await self._generate_text_summary(- file_path, file_name, llm_sem, ctx=ctx, file_content=file_content+ if media_type in {"image", "audio", "video"}:+ vlm = await self._get_vlm_config(ctx or self._default_ctx)+ if media_type == "image":+ return await generate_image_summary(+ file_path,+ file_name,+ llm_sem,+ ctx=ctx,+ vlm=vlm,+ )+ if media_type == "audio":+ return await generate_audio_summary(+ file_path,+ file_name,+ llm_sem,+ ctx=ctx,+ vlm=vlm,+ )+ return await generate_video_summary(+ file_path,+ file_name,+ llm_sem,+ ctx=ctx,+ vlm=vlm,)+ return await self._generate_text_summary(+ file_path, file_name, llm_sem, ctx=ctx, file_content=file_content+ )def _child_summary_line(self,@@ -1503,6 +1539,7 @@ class SemanticProcessor(DequeueHandlerBase):llm_sem: Optional[asyncio.Semaphore] = None,total_files: Optional[int] = None,total_children: Optional[int] = None,+ ctx: Optional[RequestContext] = None,) -> str:"""Generate raw directory overview model output.@@ -1526,7 +1563,8 @@ class SemanticProcessor(DequeueHandlerBase):"""config = get_openviking_config()- vlm = config.vlm+ active_ctx = ctx or self._default_ctx+ vlm = await self._get_vlm_config(active_ctx)semantic = config.semanticif not vlm.is_available():@@ -1612,6 +1650,7 @@ class SemanticProcessor(DequeueHandlerBase):llm_sem=llm_sem,output_language=output_language,directory_coverage=directory_coverage,+ vlm=vlm,)elif over_budget:# Few files but long summaries → truncate summaries to fit budget@@ -1637,6 +1676,7 @@ class SemanticProcessor(DequeueHandlerBase):link_map,output_language=output_language,directory_coverage=directory_coverage,+ vlm=vlm,)else:overview = await self._single_generate_overview(@@ -1646,6 +1686,7 @@ class SemanticProcessor(DequeueHandlerBase):link_map,output_language=output_language,directory_coverage=directory_coverage,+ vlm=vlm,)return overview@@ -1658,10 +1699,10 @@ class SemanticProcessor(DequeueHandlerBase):link_map: Dict[str, str],output_language: str = "en",directory_coverage: str = "",+ *,+ vlm: "VLMHandle",) -> str:"""Generate overview from a single prompt (small directories)."""- config = get_openviking_config()- vlm = config.vlmtry:prompt = render_prompt(@@ -1698,6 +1739,8 @@ class SemanticProcessor(DequeueHandlerBase):llm_sem: Optional[asyncio.Semaphore] = None,output_language: str = "en",directory_coverage: str = "",+ *,+ vlm: "VLMHandle",) -> str:"""Generate overview by batching file and subdirectory summaries.@@ -1705,7 +1748,6 @@ class SemanticProcessor(DequeueHandlerBase):batch, then merges the partials without repeating the raw inputs."""config = get_openviking_config()- vlm = config.vlmsemantic = config.semanticbatch_size = semantic.overview_batch_sizedir_name = dir_uri.split("/")[-1]@@ -1828,9 +1870,12 @@ class SemanticProcessor(DequeueHandlerBase):if isinstance(content, bytes):content = content.decode("utf-8")definition = SkillLoader.parse(content)- processor = SkillProcessor(vikingdb=None)+ processor = SkillProcessor(vikingdb=None, vlm_resolver=self._vlm_resolver)abstract = processor._build_skill_abstract(definition)- overview = await processor._generate_overview(definition, get_openviking_config())+ overview = await processor._generate_overview(+ definition,+ await self._get_vlm_config(ctx),+ )await run_to_completion(lambda: write_abstract_overview(viking_fs=viking_fs,diff --git a/openviking/storage/vectordb_adapters/base.py b/openviking/storage/vectordb_adapters/base.pyindex 0701ef5b3..d305ba4e2 100644--- a/openviking/storage/vectordb_adapters/base.py+++ b/openviking/storage/vectordb_adapters/base.py@@ -29,7 +29,6 @@ from openviking.storage.expr import (from openviking.storage.vectordb.collection.collection import Collectionfrom openviking.storage.vectordb.collection.result import FetchDataInCollectionResultfrom openviking_cli.utils import get_logger-from openviking_cli.utils.config import get_openviking_configfrom openviking_cli.utils.config.vectordb_config import DEFAULT_INDEX_NAMElogger = get_logger(__name__)@@ -125,6 +124,7 @@ class CollectionAdapter(ABC):self._collection_name = collection_nameself._index_name = index_nameself._collection: Optional[Collection] = None+ self._dimension = 0@propertydef collection_name(self) -> str:@@ -511,7 +511,18 @@ class CollectionAdapter(ABC):else:# Approximate random sampling with a client-generated random# vector so every backend behaves consistently.- dim = get_openviking_config().embedding.dimension+ dim = self._dimension+ if dim <= 0:+ dim = next(+ (+ field["Dim"]+ for field in coll.get_meta_data().get("Fields", [])+ if field.get("FieldName") == "vector"+ ),+ 0,+ )+ if dim <= 0:+ raise ValueError("Vector collection dimension is unavailable")random_vector = [random.uniform(-1, 1) for _ in range(dim)]result = coll.search_by_vector(index_name=self._index_name,diff --git a/openviking/storage/vectordb_adapters/factory.py b/openviking/storage/vectordb_adapters/factory.pyindex bc3c13c31..0a344b690 100644--- a/openviking/storage/vectordb_adapters/factory.py+++ b/openviking/storage/vectordb_adapters/factory.py@@ -45,4 +45,6 @@ def create_collection_adapter(config) -> CollectionAdapter:f"Vector backend {backend} is not supported. "f"Available backends: {sorted(_ADAPTER_REGISTRY)}")- return adapter_cls.from_config(config)+ adapter = adapter_cls.from_config(config)+ adapter._dimension = config.dimension+ return adapterdiff --git a/openviking/storage/viking_fs/__init__.py b/openviking/storage/viking_fs/__init__.pyindex 5118395d6..cb2321cd5 100644--- a/openviking/storage/viking_fs/__init__.py+++ b/openviking/storage/viking_fs/__init__.py@@ -98,6 +98,7 @@ from openviking_cli.utils.logger import get_loggerfrom openviking_cli.utils.uri import VikingURIif TYPE_CHECKING:+ from openviking.config.vlm import VLMResolverfrom openviking.storage.acl import AclManagerfrom openviking.storage.viking_vector_index_backend import VikingVectorIndexBackendfrom openviking_cli.utils.config import GlobConfig, GrepConfig, RerankConfig, RetrievalConfig@@ -136,6 +137,9 @@ class VikingFS(glob_config: Optional["GlobConfig"] = None,timeout: int = 10,encryptor: Optional[Any] = None,+ vlm_resolver: Optional["VLMResolver"] = None,+ embedding_provider: Optional[Any] = None,+ vector_config_resolver: Optional[Any] = None,):self.agfs = agfsself._async_agfs = AsyncAGFSClient(agfs)@@ -147,15 +151,22 @@ class VikingFS(self.grep_config = grep_configself.glob_config = glob_configself._encryptor = encryptor+ self._vlm_resolver = vlm_resolver+ self._embedding_provider = embedding_provider+ self._vector_config_resolver = vector_config_resolverself._count_cache: Dict[str, tuple] = {} # cache_key → (count, timestamp)self._count_cache_max_size = 1024- self._fulltext_available: Optional[bool] = None # cached result of _collection_has_fulltext+ self._fulltext_available: Dict[tuple[str, str, str, str], bool] = {}self._bound_ctx: contextvars.ContextVar[Optional[RequestContext]] = contextvars.ContextVar("vikingfs_bound_ctx", default=None)self._background_tasks: set = set()self._deletion_guard: Optional[Callable[[str, str], bool]] = None+ def set_vlm_resolver(self, resolver: "VLMResolver") -> None:+ """Set the VLM resolver supplied by the owning service."""+ self._vlm_resolver = resolver+VikingFS.__module__ = __name__diff --git a/openviking/storage/viking_fs/_access.py b/openviking/storage/viking_fs/_access.pyindex 8dbeea1a0..86606428a 100644--- a/openviking/storage/viking_fs/_access.py+++ b/openviking/storage/viking_fs/_access.py@@ -99,6 +99,14 @@ class _AccessMixin:bound = self._bound_ctx.get()return bound or self._default_ctx()+ def _require_request_context(self, ctx: Optional[RequestContext]) -> RequestContext:+ """Resolve an account context without inventing the default account."""+ if ctx is None and self._bound_ctx.get() is None:+ raise RuntimeError(+ "Account request context is required for account-scoped operations"+ )+ return self._ctx_or_default(ctx)+@contextmanagerdef bind_request_context(self, ctx: RequestContext):"""Temporarily bind ctx for legacy internal call paths without explicit ctx param."""diff --git a/openviking/storage/viking_fs/_base.py b/openviking/storage/viking_fs/_base.pyindex 9def2bf1b..f8513da52 100644--- a/openviking/storage/viking_fs/_base.py+++ b/openviking/storage/viking_fs/_base.py@@ -12,6 +12,7 @@ from openviking_cli.exceptions import (from openviking_cli.utils.logger import get_loggerif TYPE_CHECKING:+ from openviking.config.vlm import VLMResolverfrom openviking.storage.acl import AclManagerfrom openviking.storage.viking_vector_index_backend import VikingVectorIndexBackendfrom openviking_cli.utils.config import GlobConfig, GrepConfig, RerankConfig, RetrievalConfig@@ -204,6 +205,9 @@ def init_viking_fs(timeout: int = 10,enable_recorder: bool = False,encryptor: Optional[Any] = None,+ vlm_resolver: Optional["VLMResolver"] = None,+ embedding_provider: Optional[Any] = None,+ vector_config_resolver: Optional[Any] = None,):"""Initialize VikingFS singleton.@@ -232,6 +236,9 @@ def init_viking_fs(grep_config=grep_config,glob_config=glob_config,encryptor=encryptor,+ vlm_resolver=vlm_resolver,+ embedding_provider=embedding_provider,+ vector_config_resolver=vector_config_resolver,)if enable_recorder:diff --git a/openviking/storage/viking_fs/_grep.py b/openviking/storage/viking_fs/_grep.pyindex ba8f503f3..f9c31f3dc 100644--- a/openviking/storage/viking_fs/_grep.py+++ b/openviking/storage/viking_fs/_grep.py@@ -154,7 +154,11 @@ class _GrepMixin:if not vector_store:return "fs"- backend_type = getattr(vector_store, "_backend_type", "unknown")+ account_id = getattr(ctx, "account_id", None) if ctx is not None else None+ if account_id and hasattr(vector_store, "get_account_backend"):+ backend_type = (await vector_store.get_account_backend(account_id))._mode+ else:+ backend_type = getattr(vector_store, "_backend_type", "unknown")# Keep this set consistent with ``CollectionAdapter.USE_CONTENT_FIELD``:# only these backends store the ``content`` field required for full-text grep.if backend_type not in ("volcengine", "vikingdb"):@@ -184,17 +188,29 @@ class _GrepMixin:async def _collection_has_fulltext(self, vector_store, ctx) -> bool:"""Check if collection has content field and FullText config.- Result is cached on the VikingFS instance since collection schema- does not change at runtime.+ The cache is scoped by Account and collection identity because one+ VikingFS instance can serve dedicated Account VectorDB collections."""- if self._fulltext_available is not None:- return self._fulltext_available+ account_id = getattr(ctx, "account_id", "") if ctx is not None else ""+ backend = None+ if account_id and hasattr(vector_store, "get_account_backend"):+ backend = await vector_store.get_account_backend(account_id)+ elif not account_id:+ backend = vector_store+ cache_key = (+ account_id,+ str(getattr(backend, "_mode", "")),+ str(getattr(backend, "collection_name", getattr(backend, "_collection_name", ""))),+ str(getattr(backend, "index_name", getattr(backend, "_index_name", ""))),+ )+ if cache_key in self._fulltext_available:+ return self._fulltext_available[cache_key]try:meta = Noneif hasattr(vector_store, "get_collection_meta"):meta = await vector_store.get_collection_meta(ctx=ctx)if not meta:- self._fulltext_available = False+ self._fulltext_available[cache_key] = Falsereturn Falsefields = meta.get("Fields", [])has_content = any(@@ -203,7 +219,7 @@ class _GrepMixin:fulltext = meta.get("FullText") or []has_content_fulltext = any(ft.get("Field") == "content" for ft in fulltext)result = has_content and has_content_fulltext- self._fulltext_available = result+ self._fulltext_available[cache_key] = resultreturn resultexcept Exception:logger.debug(diff --git a/openviking/storage/viking_fs/_ops.py b/openviking/storage/viking_fs/_ops.pyindex 5b4d48ad7..656c662c4 100644--- a/openviking/storage/viking_fs/_ops.py+++ b/openviking/storage/viking_fs/_ops.py@@ -1409,7 +1409,7 @@ class _OpsMixin:if vector_store is None:return False- backend_type = getattr(vector_store, "_backend_type", "unknown")+ backend_type = (await vector_store.get_account_backend(ctx.account_id))._modeif backend_type not in ("volcengine", "vikingdb"):return Falsediff --git a/openviking/storage/viking_fs/_semantic.py b/openviking/storage/viking_fs/_semantic.pyindex 205def709..5fa48d82d 100644--- a/openviking/storage/viking_fs/_semantic.py+++ b/openviking/storage/viking_fs/_semantic.py@@ -237,7 +237,7 @@ class _SemanticMixin:TypedQuery,)- real_ctx = self._ctx_or_default(ctx)+ real_ctx = self._require_request_context(ctx)retrieval_targets = resolve_retrieval_targets(target_uri, real_ctx)if filter_only:@@ -250,13 +250,13 @@ class _SemanticMixin:)for target_dir in retrieval_targets.target_directories:- await self._ensure_retrieval_scope(target_dir, ctx)+ await self._ensure_retrieval_scope(target_dir, real_ctx)storage = self._get_vector_store()if not storage:raise RuntimeError("Vector store not initialized. Call OpenViking.initialize() first.")- embedder = self._get_embedder()+ embedder = self._get_embedder(real_ctx)if not embedder:raise RuntimeError("Embedder not configured.")@@ -406,7 +406,7 @@ class _SemanticMixin:TypedQuery,)- real_ctx = self._ctx_or_default(ctx)+ real_ctx = self._require_request_context(ctx)retrieval_targets = resolve_retrieval_targets(target_uri, real_ctx)primary_target_uri = retrieval_targets.first_explicit_directory@@ -417,14 +417,14 @@ class _SemanticMixin:query_plan: Optional[QueryPlan] = Nonefor target_dir in retrieval_targets.target_directories:- await self._ensure_retrieval_scope(target_dir, ctx)+ await self._ensure_retrieval_scope(target_dir, real_ctx)# When target_uri exists, read its abstract as optional query-planning context.target_abstract = ""if primary_target_uri:try:with telemetry.measure("search.target_abstract"):- target_abstract = await self.abstract(primary_target_uri, ctx=ctx)+ target_abstract = await self.abstract(primary_target_uri, ctx=real_ctx)except Exception:target_abstract = ""@@ -446,7 +446,16 @@ class _SemanticMixin:)]elif intent_enabled and (session_summary or current_messages):- analyzer = IntentAnalyzer(max_recent_messages=5)+ if self._vlm_resolver is None:+ raise RuntimeError(+ "VikingFS requires a VLM resolver for account-owned intent analysis"+ )+ analyzer = IntentAnalyzer(+ max_recent_messages=5,+ query_planner=await self._vlm_resolver.get_query_planner(+ real_ctx.account_id+ ),+ )with telemetry.measure("search.intent_analysis"):query_plan = await analyzer.analyze(compression_summary=session_summary or "",@@ -472,7 +481,7 @@ class _SemanticMixin:# Concurrent executionstorage = self._get_vector_store()- embedder = self._get_embedder()+ embedder = self._get_embedder(real_ctx)retriever = HierarchicalRetriever(storage=storage,embedder=embedder,@@ -481,7 +490,6 @@ class _SemanticMixin:)async def _execute(tq: TypedQuery):- real_ctx = self._ctx_or_default(ctx)logger.debug("[VikingFS.search._execute] Calling retriever.retrieve with "f"ctx.account_id={real_ctx.account_id}, ctx.user={real_ctx.user}"diff --git a/openviking/storage/viking_fs/_snapshot.py b/openviking/storage/viking_fs/_snapshot.pyindex 736b61a1b..92dc4df79 100644--- a/openviking/storage/viking_fs/_snapshot.py+++ b/openviking/storage/viking_fs/_snapshot.py@@ -830,7 +830,7 @@ class _SnapshotMixin:Failures are logged and never propagate."""try:- from openviking.service.reindex_executor import get_reindex_executor+ from openviking.service.reindex_executor import ReindexExecutorexcept Exception:logger.exception("[VikingFS] ReindexExecutor import failed; skipping rebuild")return@@ -845,7 +845,10 @@ class _SnapshotMixin:if not tasks:return- executor = get_reindex_executor()+ executor = ReindexExecutor(+ vlm_resolver=self._vlm_resolver,+ vector_config_resolver=self._vector_config_resolver,+ )for op, uri, level in tasks:loop.create_task(self._run_vector_rebuild(executor, op, uri, level, ctx),@@ -865,6 +868,7 @@ class _SnapshotMixin:swallowed (and logged) inside :py:meth:`_run_vector_rebuild`, preservingthe "failures do not block" semantics."""+ from openviking.service.reindex_executor import ReindexExecutorfrom openviking.service.task_tracker import get_task_trackerfrom openviking.service.task_work_index import bind_task_context@@ -877,9 +881,10 @@ class _SnapshotMixin:user_id=ctx.user.user_id,stage="reindexing",)- from openviking.service.reindex_executor import get_reindex_executor-- executor = get_reindex_executor()+ executor = ReindexExecutor(+ vlm_resolver=self._vlm_resolver,+ vector_config_resolver=self._vector_config_resolver,+ )reindex_ctx = self._restore_reindex_context(ctx)with bind_task_context(task_id, ctx.account_id, ctx.user.user_id):await asyncio.gather(diff --git a/openviking/storage/viking_fs/_vector.py b/openviking/storage/viking_fs/_vector.pyindex e4ce41418..532dc27a3 100644--- a/openviking/storage/viking_fs/_vector.py+++ b/openviking/storage/viking_fs/_vector.py@@ -86,6 +86,16 @@ class _VectorMixin:"""Get vector store instance."""return self.vector_store- def _get_embedder(self) -> Any:- """Get embedder instance."""- return self.query_embedder+ def _get_embedder(self, ctx=None) -> Any:+ """Bind query calls to the account, resolving settings at each call.++ Fails closed: a request that already carries an account_id must never+ fall back to a process-wide startup embedder. When the account embedding+ provider is absent the caller gets an explicit initialization error+ instead of a Cluster-scoped embedder.+ """+ ctx = self._require_request_context(ctx)+ provider = self._embedding_provider+ if provider is None:+ raise RuntimeError("Account embedding provider is not initialized")+ return provider.bind(ctx.account_id)diff --git a/openviking/storage/viking_vector_index_backend.py b/openviking/storage/viking_vector_index_backend.pyindex 415211521..0dc884add 100644--- a/openviking/storage/viking_vector_index_backend.py+++ b/openviking/storage/viking_vector_index_backend.py@@ -5,9 +5,11 @@from __future__ import annotationsimport asyncio+import threadingimport uuidfrom contextlib import asynccontextmanagerfrom dataclasses import dataclass+from functools import wrapsfrom typing import Any, AsyncIterator, Awaitable, Callable, Container, Dict, List, Mapping, Optionalfrom openviking.core.namespace import (@@ -16,7 +18,7 @@ from openviking.core.namespace import (visible_roots,)from openviking.server.identity import RequestContext, Role-from openviking.service.task_tracker_concurrency import run_to_completion+from openviking.service.task_tracker_concurrency import KeyedAsyncLockPool, run_to_completionfrom openviking.storage.acl import (ACL_CONTEXT_FIELDS,ACL_GRANT_FIELDS,@@ -190,14 +192,36 @@ class _AsyncVectorAdapter:def __init__(self, adapter: Any):self._adapter = adapter+ self._condition = threading.Condition()+ self._active = 0+ self._closing = False+ self._closed = Falseasync def call(self, method_name: str, /, *args: Any, **kwargs: Any) -> Any:- return await run_to_completion(- lambda: asyncio.to_thread(getattr(self._adapter, method_name), *args, **kwargs)- )+ if method_name == "close":+ return await run_to_completion(lambda: asyncio.to_thread(self._close))+ return await self.run(getattr(self._adapter, method_name), *args, **kwargs)async def run(self, func: Any, /, *args: Any, **kwargs: Any) -> Any:- return await asyncio.to_thread(func, *args, **kwargs)+ with self._condition:+ if self._closing:+ raise RuntimeError("Vector adapter is closing")+ self._active += 1+ try:+ return await run_to_completion(lambda: asyncio.to_thread(func, *args, **kwargs))+ finally:+ with self._condition:+ self._active -= 1+ self._condition.notify_all()++ def _close(self) -> None:+ with self._condition:+ self._closing = True+ while self._active:+ self._condition.wait()+ if not self._closed:+ self._closed = True+ self._adapter.close()async def collection_meta(self, index_name: str) -> Dict[str, Any]:def _get() -> Dict[str, Any]:@@ -209,12 +233,10 @@ class _AsyncVectorAdapter:meta["ScalarIndex"] = index_meta["ScalarIndex"]return meta- return await asyncio.to_thread(_get)+ return await self.run(_get)async def update_collection_description(self, description: str) -> None:- await asyncio.to_thread(- lambda: self._adapter.get_collection().update(description=description)- )+ await self.run(lambda: self._adapter.get_collection().update(description=description))async def update_collection_schema(self, fields: List[Dict[str, Any]], scalar_index: List[str], index_name: str@@ -240,7 +262,16 @@ class _AsyncVectorAdapter:scalar_index=[*current_scalar_index, *missing_scalar_fields],)- await asyncio.to_thread(_update)+ await self.run(_update)+++def _backend_operation(method):+ @wraps(method)+ async def call(self, *args, **kwargs):+ async with self.operation():+ return await method(self, *args, **kwargs)++ return callclass _SingleAccountBackend:@@ -265,14 +296,18 @@ class _SingleAccountBackend:to the same storage path."""self._bound_account_id = bound_account_id+ self._operation_condition = threading.Condition()+ self._operations: dict[asyncio.Task, int] = {}+ self._retired = False+ self.vector_dim = config.dimensionself._adapter = shared_adapter or create_collection_adapter(config)self._async_adapter = _AsyncVectorAdapter(self._adapter)self._collection_config: Dict[str, Any] = {}self._meta_data_cache: Dict[str, Any] = {}self._mode = self._adapter.mode- self._distance_metric = "cosine"- self._sparse_weight = 0.0- self._collection_name = "context"+ self._distance_metric = config.distance_metric+ self._sparse_weight = config.sparse_weight+ self._collection_name = config.name or "context"self._index_name = config.index_name or DEFAULT_INDEX_NAMElogger.info(@@ -281,9 +316,35 @@ class _SingleAccountBackend:self._mode,)+ @asynccontextmanager+ async def operation(self):+ """Borrow across every I/O step, including nested backend operations."""+ task = asyncio.current_task()+ with self._operation_condition:+ if self._retired and task not in self._operations:+ raise RuntimeError("Account vector backend is closing")+ self._operations[task] = self._operations.get(task, 0) + 1+ try:+ yield+ finally:+ with self._operation_condition:+ self._operations[task] -= 1+ if not self._operations[task]:+ del self._operations[task]+ self._operation_condition.notify_all()++ def _wait_for_operations(self):+ with self._operation_condition:+ while self._operations:+ self._operation_condition.wait()+def _get_collection(self) -> Collection:return self._adapter.get_collection()+ @property+ def collection_name(self) -> str:+ return self._collection_name+def _get_meta_data(self, coll: Collection) -> Dict[str, Any]:if not self._meta_data_cache:self._meta_data_cache = coll.get_meta_data() or {}@@ -300,6 +361,7 @@ class _SingleAccountBackend:def _prepare_upsert_payload(self, data: Dict[str, Any]) -> Dict[str, Any]:"""Drop runtime-only or stale legacy fields before writing back to the current schema."""+ self._validate_vector_dimension(data.get("vector"))payload = {k: v for k, v in data.items() if v is not None}filtered = self._filter_known_fields(payload)result = {k: v for k, v in filtered.items() if v is not None}@@ -335,6 +397,7 @@ class _SingleAccountBackend:def _prepare_update_payload(self, data: Dict[str, Any]) -> Dict[str, Any]:"""Prepare a strict partial update without inventing omitted fields."""+ self._validate_vector_dimension(data.get("vector"))payload = self._filter_known_fields({key: value for key, value in data.items() if value is not None})@@ -346,6 +409,12 @@ class _SingleAccountBackend:payload.pop("content", None)return payload+ def _validate_vector_dimension(self, vector) -> None:+ if vector is not None and self.vector_dim and len(vector) != self.vector_dim:+ raise ValueError(+ f"Dense vector dimension mismatch: expected {self.vector_dim}, got {len(vector)}"+ )+def _bind_upsert_payload(self, data: Dict[str, Any]) -> Dict[str, Any]:"""Copy a record, enforce its bound account, and apply write defaults."""payload = dict(data)@@ -380,6 +449,7 @@ class _SingleAccountBackend:# Collection Management# =========================================================================+ @_backend_operationasync def create_collection(self, name: str, schema: Dict[str, Any]) -> bool:try:collection_meta = dict(schema)@@ -412,6 +482,7 @@ class _SingleAccountBackend:logger.error("Error creating collection %s: %s", name, e)return False+ @_backend_operationasync def drop_collection(self) -> bool:try:dropped = await self._async_adapter.call("drop_collection")@@ -423,9 +494,11 @@ class _SingleAccountBackend:logger.error("Error dropping collection: %s", e)return False+ @_backend_operationasync def collection_exists(self) -> bool:return await self._async_adapter.call("collection_exists")+ @_backend_operationasync def get_collection_info(self) -> Optional[Dict[str, Any]]:if not await self.collection_exists():return None@@ -437,11 +510,13 @@ class _SingleAccountBackend:"status": "active",}+ @_backend_operationasync def get_collection_meta(self) -> Optional[Dict[str, Any]]:if not await self.collection_exists():return Nonereturn await self._async_adapter.collection_meta(self._index_name)+ @_backend_operationasync def update_collection_description(self, description: str) -> bool:if not await self.collection_exists():return False@@ -449,6 +524,7 @@ class _SingleAccountBackend:await self._refresh_meta_data_async()return True+ @_backend_operationasync def update_collection_schema(self, fields: List[Dict[str, Any]], scalar_index: List[str]) -> None:@@ -459,6 +535,7 @@ class _SingleAccountBackend:# Data Operations (with tenant enforcement)# =========================================================================+ @_backend_operationasync def upsert(self,data: Dict[str, Any],@@ -498,6 +575,7 @@ class _SingleAccountBackend:ids = await self._async_adapter.call("upsert", payload)return ids[0] if ids else ""+ @_backend_operationasync def upsert_many(self, data_list: List[Dict[str, Any]]) -> List[str]:"""Bulk full-record upsert through one adapter call.@@ -541,6 +619,7 @@ class _SingleAccountBackend:async def end_bulk_ingest(self) -> None:await self._async_adapter.call("end_bulk_ingest")+ @_backend_operationasync def update(self, data: Dict[str, Any]) -> UpdateResult:"""Strict update path. The target record must already exist."""try:@@ -592,6 +671,7 @@ class _SingleAccountBackend:error_message=str(e),)+ @_backend_operationasync def get(self, ids: List[str]) -> List[Dict[str, Any]]:try:records = await self._async_adapter.call("get", ids)@@ -600,7 +680,7 @@ class _SingleAccountBackend:return recordsexcept Exception as e:logger.error("Error getting records: %s", e)- return []+ raisedef _with_account_filter(self, filter: Optional[Dict[str, Any] | FilterExpr]@@ -616,6 +696,7 @@ class _SingleAccountBackend:filter = RawDSL(filter)return And([account_filter, filter])+ @_backend_operationasync def get_strict(self, ids: List[str]) -> List[Dict[str, Any]]:"""Fetch records without converting backend errors to misses."""records = await self._async_adapter.call("get", ids)@@ -623,10 +704,12 @@ class _SingleAccountBackend:records = [r for r in records if r.get("account_id") == self._bound_account_id]return records+ @_backend_operationasync def strict_get(self, ids: List[str]) -> List[Dict[str, Any]]:"""Transaction alias for strict record reads."""return await self.get_strict(ids)+ @_backend_operationasync def strict_delete(self, ids: List[str]) -> int:"""Delete transaction records and propagate every backend failure."""if self._bound_account_id:@@ -637,6 +720,7 @@ class _SingleAccountBackend:return 0return int(await self._async_adapter.call("delete", ids=ids) or 0)+ @_backend_operationasync def strict_query(self,*,@@ -660,12 +744,14 @@ class _SingleAccountBackend:order_desc=order_desc,)+ @_backend_operationasync def strict_count(self, filter: Optional[Dict[str, Any] | FilterExpr] = None) -> int:"""Count transaction records without converting backend errors to zero."""return int(await self._async_adapter.call("strict_count", filter=self._with_account_filter(filter)))+ @_backend_operationasync def delete(self, ids: List[str]) -> int:try:if self._bound_account_id:@@ -678,8 +764,9 @@ class _SingleAccountBackend:return await self._async_adapter.call("delete", ids=ids)except Exception as e:logger.error("Error deleting records: %s", e)- return 0+ raise+ @_backend_operationasync def delete_by_filter(self, filter: FilterExpr) -> int:"""Root-only: 直接通过 filter 删除"""try:@@ -688,12 +775,11 @@ class _SingleAccountBackend:logger.error("Error deleting by filter: %s", e)raise+ @_backend_operationasync def exists(self, id: str) -> bool:- try:- return len(await self.get([id])) > 0- except Exception:- return False+ return len(await self.get([id])) > 0+ @_backend_operationasync def fetch_by_uri(self, uri: str) -> Optional[Dict[str, Any]]:try:records = await self.query(@@ -706,8 +792,9 @@ class _SingleAccountBackend:return Noneexcept Exception as e:logger.error("Error fetching record by URI %s: %s", uri, e)- return None+ raise+ @_backend_operationasync def query(self,query_vector: Optional[List[float]] = None,@@ -719,6 +806,7 @@ class _SingleAccountBackend:order_by: Optional[str] = None,order_desc: bool = False,) -> List[Dict[str, Any]]:+ self._validate_vector_dimension(query_vector)try:logger.debug(f"[_SingleAccountBackend.query] Called with bound_account_id={self._bound_account_id}, filter={filter}"@@ -748,8 +836,9 @@ class _SingleAccountBackend:)except Exception as e:logger.error("Error querying collection: %s", e, exc_info=True)- return []+ raise+ @_backend_operationasync def search_by_random(self,filter: Optional[Dict[str, Any] | FilterExpr] = None,@@ -771,6 +860,7 @@ class _SingleAccountBackend:logger.error("Error searching collection by random: %s", e, exc_info=True)raise+ @_backend_operationasync def search(self,query_vector: Optional[List[float]] = None,@@ -789,6 +879,7 @@ class _SingleAccountBackend:output_fields=output_fields,)+ @_backend_operationasync def filter(self,filter: Dict[str, Any] | FilterExpr,@@ -807,6 +898,7 @@ class _SingleAccountBackend:order_desc=order_desc,)+ @_backend_operationasync def remove_by_uri(self, uri: str) -> int:try:target_records = await self.filter(@@ -827,7 +919,7 @@ class _SingleAccountBackend:return total_deletedexcept Exception as e:logger.error("Error removing URI %s: %s", uri, e)- return 0+ raiseasync def _remove_descendants(self, parent_uri: str) -> int:total_deleted = 0@@ -847,6 +939,7 @@ class _SingleAccountBackend:total_deleted += 1return total_deleted+ @_backend_operationasync def scroll(self,filter: Optional[Dict[str, Any] | FilterExpr] = None,@@ -870,6 +963,7 @@ class _SingleAccountBackend:next_cursor = str(offset + len(records)) if len(records) == limit else Nonereturn records, next_cursor+ @_backend_operationasync def count(self, filter: Optional[Dict[str, Any] | FilterExpr] = None) -> int:try:if self._bound_account_id:@@ -886,6 +980,7 @@ class _SingleAccountBackend:logger.error("Error counting records: %s", e)raise+ @_backend_operationasync def clear(self) -> bool:try:if self._bound_account_id:@@ -893,12 +988,14 @@ class _SingleAccountBackend:return await self._async_adapter.call("clear")except Exception as e:logger.error("Error clearing collection: %s", e)- return False+ raise+ @_backend_operationasync def optimize(self) -> bool:logger.info("Optimization requested")return True+ @_backend_operationasync def search_by_keywords(self,keywords: Optional[List[str]] = None,@@ -918,7 +1015,7 @@ class _SingleAccountBackend:else:filter = account_filter- return await asyncio.to_thread(+ return await self._async_adapter.run(self._adapter.search_by_keywords,keywords=keywords,query=query,@@ -932,7 +1029,13 @@ class _SingleAccountBackend:raiseasync def close(self) -> None:+ with self._operation_condition:+ self._retired = True+ await run_to_completion(self._close_after_operations)++ async def _close_after_operations(self) -> None:try:+ await asyncio.to_thread(self._wait_for_operations)await self._async_adapter.call("close")self._collection_config = {}self._meta_data_cache = {}@@ -940,6 +1043,7 @@ class _SingleAccountBackend:except Exception as e:logger.error("Error closing backend: %s", e)+ @_backend_operationasync def health_check(self) -> bool:try:await self.collection_exists()@@ -947,6 +1051,7 @@ class _SingleAccountBackend:except Exception:return False+ @_backend_operationasync def get_stats(self) -> Dict[str, Any]:try:exists = await self.collection_exists()@@ -969,7 +1074,7 @@ class _SingleAccountBackend:@propertydef is_closing(self) -> bool:- return False+ return self._retiredclass VikingVectorIndexBackend:@@ -993,10 +1098,17 @@ class VikingVectorIndexBackend:self.acl_manager: Optional[AclManager] = Noneself._account_backends: Dict[str, _SingleAccountBackend] = {}+ self._vector_config_resolver = None+ self._account_backend_locks = KeyedAsyncLockPool[str]()+ self._resolved_backends: Dict[str, _SingleAccountBackend] = {}+ self._retiring_backends: set[_SingleAccountBackend] = set()+ self._initializing_accounts: set[str] = set()self._root_backend: Optional[_SingleAccountBackend] = None# Share a single adapter (and its underlying PersistStore/RocksDB instance)# across all account backends to avoid LOCK contention.self._shared_adapter = create_collection_adapter(config)+ self._shared_async_adapter = _AsyncVectorAdapter(self._shared_adapter)+ self._closing = Falselogger.info("VikingVectorIndexBackend facade initialized",@@ -1032,12 +1144,65 @@ class VikingVectorIndexBackend:backend._sparse_weight = self.sparse_weightbackend._collection_name = self._collection_namebackend._index_name = self._index_name+ backend._async_adapter = self._shared_async_adapterself._account_backends[account_id] = backendreturn self._account_backends[account_id]- def _get_backend_for_context(self, ctx: RequestContext) -> _SingleAccountBackend:+ async def _get_backend_for_context(self, ctx: RequestContext) -> _SingleAccountBackend:"""根据上下文获取 backend"""- return self._get_backend_for_account(ctx.account_id)+ return await self.get_account_backend(ctx.account_id)++ def set_vector_config_resolver(self, resolver) -> None:+ self._vector_config_resolver = resolver++ async def _resolve_vector_settings(self, account_id: str):+ if self._vector_config_resolver is None:+ raise RuntimeError("Account vector configuration resolver is not initialized")+ return await self._vector_config_resolver.resolve(account_id)++ async def get_account_backend(self, account_id: str) -> _SingleAccountBackend:+ if not account_id:+ raise ValueError("account_id is required")+ if self._vector_config_resolver is None:+ raise RuntimeError("Account vector configuration resolver is not initialized")+ async with self._account_backend_locks.acquire(account_id):+ if self._closing:+ raise RuntimeError("Vector backend is closing")+ self._initializing_accounts.add(account_id)+ try:+ return await self._load_account_backend(account_id)+ finally:+ self._initializing_accounts.discard(account_id)++ async def _load_account_backend(self, account_id: str) -> _SingleAccountBackend:+ if account_id in self._resolved_backends:+ return self._resolved_backends[account_id]+ settings = await self._resolve_vector_settings(account_id)+ if not settings.dedicated_vectordb:+ backend = self._get_backend_for_account(account_id)+ backend.vector_dim = settings.vectordb.dimension+ else:+ backend = _SingleAccountBackend(+ settings.vectordb.model_copy(deep=True),+ bound_account_id=account_id,+ )+ self._resolved_backends[account_id] = backend+ return backend++ async def account_uses_content_field(self, account_id: str) -> bool:+ return (await self.get_account_backend(account_id))._adapter.USE_CONTENT_FIELD++ async def release_account(self, account_id: str) -> None:+ """Release derived resources after account data cleanup; never drop a collection."""+ async with self._account_backend_locks.acquire(account_id):+ backend = self._resolved_backends.pop(account_id, None)+ self._account_backends.pop(account_id, None)+ if backend and backend._adapter is not self._shared_adapter:+ self._retiring_backends.add(backend)+ try:+ await backend.close()+ finally:+ self._retiring_backends.discard(backend)def _get_root_backend(self) -> _SingleAccountBackend:"""获取 root 特权 backend"""@@ -1049,6 +1214,7 @@ class VikingVectorIndexBackend:self._root_backend._sparse_weight = self.sparse_weightself._root_backend._collection_name = self._collection_nameself._root_backend._index_name = self._index_name+ self._root_backend._async_adapter = self._shared_async_adapterreturn self._root_backenddef _check_root_role(self, ctx: RequestContext) -> None:@@ -1081,7 +1247,7 @@ class VikingVectorIndexBackend:ctx: Optional[RequestContext] = None,) -> Optional[Dict[str, Any]]:if ctx:- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)else:backend = self._get_default_backend()return await backend.get_collection_meta()@@ -1124,8 +1290,14 @@ class VikingVectorIndexBackend:options.search_tag_mode,)data = {key: value for key, value in data.items() if key not in ACL_CONTEXT_FIELDS}- data = (await self._materialize_acl_fields([data], ctx, update=options.acl_update))[0]- backend = self._get_backend_for_context(ctx)+ data = (+ await self._materialize_acl_fields(+ [data],+ ctx,+ update=options.acl_update,+ )+ )[0]+ backend = await self._get_backend_for_context(ctx)logger.debug("[VikingVectorIndexBackend.upsert] Using backend for account_id=%s",ctx.account_id,@@ -1181,7 +1353,7 @@ class VikingVectorIndexBackend:self, data_list: List[Dict[str, Any]], *, ctx: RequestContext) -> List[str]:"""Write records whose ACL fields have already been materialized."""- return await self._get_backend_for_context(ctx).upsert_many(data_list)+ return await (await self._get_backend_for_context(ctx)).upsert_many(data_list)async def _materialize_acl_fields(self,@@ -1201,7 +1373,7 @@ class VikingVectorIndexBackend:"[VikingVectorIndexBackend.update] uri=%s",data.get("uri", ""),)- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)logger.debug(f"[VikingVectorIndexBackend.update] Using backend for account_id={ctx.account_id}")@@ -1217,7 +1389,13 @@ class VikingVectorIndexBackend:writes transactional or atomic, and adapters that do not maintain aderived local index treat it as a no-op."""- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)+ async with backend.operation():+ async with self._bulk_ingest_backend(backend):+ yield++ @asynccontextmanager+ async def _bulk_ingest_backend(self, backend) -> AsyncIterator[None]:begin_task = asyncio.create_task(backend.begin_bulk_ingest())entry_cancellation = await _wait_for_task_completion_despite_cancellation(begin_task)# A failed or self-cancelled begin did not acquire the scope, so it@@ -1240,26 +1418,26 @@ class VikingVectorIndexBackend:raise exit_cancellationasync def get(self, ids: List[str], *, ctx: RequestContext) -> List[Dict[str, Any]]:- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)return await backend.get(ids)async def get_strict(self, ids: List[str], *, ctx: RequestContext) -> List[Dict[str, Any]]:- return await self._get_backend_for_context(ctx).get_strict(ids)+ return await (await self._get_backend_for_context(ctx)).get_strict(ids)async def delete(self, ids: List[str], *, ctx: RequestContext) -> int:- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)return await backend.delete(ids)async def strict_delete(self, ids: List[str], *, ctx: RequestContext) -> int:"""Delete exact record IDs without converting backend failures to success."""- return await self._get_backend_for_context(ctx).strict_delete(ids)+ return await (await self._get_backend_for_context(ctx)).strict_delete(ids)async def exists(self, id: str, *, ctx: RequestContext) -> bool:- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)return await backend.exists(id)async def fetch_by_uri(self, uri: str, *, ctx: RequestContext) -> Optional[Dict[str, Any]]:- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)return await backend.fetch_by_uri(uri)async def update_search_tags(@@ -1384,7 +1562,7 @@ class VikingVectorIndexBackend:*,ctx: RequestContext,) -> List[Dict[str, Any]]:- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)return await backend.query(query_vector=query_vector,sparse_query_vector=sparse_query_vector,@@ -1406,7 +1584,7 @@ class VikingVectorIndexBackend:*,ctx: RequestContext,) -> List[Dict[str, Any]]:- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)acl_enabled = await self._acl_enabled(ctx)filter = self._merge_filters(filter,@@ -1463,7 +1641,7 @@ class VikingVectorIndexBackend:)async def remove_by_uri(self, uri: str, *, ctx: RequestContext) -> int:- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)return await backend.remove_by_uri(uri)async def scroll(@@ -1475,7 +1653,7 @@ class VikingVectorIndexBackend:*,ctx: RequestContext,) -> tuple[List[Dict[str, Any]], Optional[str]]:- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)return await backend.scroll(filter=filter,limit=limit,@@ -1492,7 +1670,7 @@ class VikingVectorIndexBackend:cursor: Optional[str],output_fields: List[str],) -> tuple[List[Dict[str, Any]], Optional[str]]:- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)return await backend.scroll(filter=filter,limit=limit,@@ -1501,7 +1679,7 @@ class VikingVectorIndexBackend:)async def _strict_transfer_count(self, ctx: RequestContext, filter: FilterExpr) -> int:- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)return await backend.strict_count(filter=filter)async def _strict_scan(@@ -1561,11 +1739,11 @@ class VikingVectorIndexBackend:async def _strict_transfer_get(self, ctx: RequestContext, ids: List[str]) -> List[Dict[str, Any]]:- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)return await backend.strict_get(ids)async def _strict_transfer_delete(self, ctx: RequestContext, ids: List[str]) -> int:- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)return await backend.strict_delete(ids)async def count(@@ -1575,7 +1753,7 @@ class VikingVectorIndexBackend:ctx: Optional[RequestContext] = None,) -> int:if ctx:- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)else:backend = self._get_default_backend()return await backend.count(filter=filter)@@ -1592,7 +1770,7 @@ class VikingVectorIndexBackend:ctx: Optional[RequestContext] = None,) -> List[Dict[str, Any]]:if ctx:- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)acl_enabled = await self._acl_enabled(ctx)filter = self._merge_filters(filter,@@ -1611,7 +1789,7 @@ class VikingVectorIndexBackend:async def clear(self, *, ctx: Optional[RequestContext] = None) -> bool:if ctx:- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)else:backend = self._get_default_backend()return await backend.clear()@@ -1620,16 +1798,44 @@ class VikingVectorIndexBackend:return await self._get_default_backend().optimize()async def close(self) -> None:+ self._closing = True+ await run_to_completion(self._close_backends)++ async def _close_backends(self) -> None:+ adapters: dict[int, _AsyncVectorAdapter] = {+ id(self._shared_adapter): self._shared_async_adapter+ }+ backends: set[_SingleAccountBackend] = set()try:- for backend in self._account_backends.values():- await backend.close()- if self._root_backend:- await self._root_backend.close()+ backends.update(self._account_backends.values())+ backends.update(self._retiring_backends)+ if self._root_backend is not None:+ backends.add(self._root_backend)+ for account_id in set(self._resolved_backends) | self._initializing_accounts:+ async with self._account_backend_locks.acquire(account_id):+ backend = self._resolved_backends.get(account_id)+ if backend is not None:+ backends.add(backend)+ for backend in backends:+ with backend._operation_condition:+ backend._retired = True+ adapters[id(backend._adapter)] = backend._async_adapter+ for backend in backends:+ await asyncio.to_thread(backend._wait_for_operations)+ except Exception as e:+ logger.error("Error preparing vector facade close: %s", e)+ finally:+ for adapter in adapters.values():+ try:+ await adapter.call("close")+ except Exception as e:+ logger.error("Error closing vector adapter: %s", e)self._account_backends.clear()+ self._resolved_backends.clear()+ self._retiring_backends.clear()+ self._initializing_accounts.clear()self._root_backend = Nonelogger.info("VikingVectorIndexBackend facade closed")- except Exception as e:- logger.error("Error closing facade: %s", e)async def health_check(self) -> bool:return await self._get_default_backend().health_check()@@ -1639,7 +1845,7 @@ class VikingVectorIndexBackend:@propertydef is_closing(self) -> bool:- return False+ return self._closing@propertydef has_queue_manager(self) -> bool:@@ -1785,7 +1991,7 @@ class VikingVectorIndexBackend:if level is not None:conds.append(Eq("level", level))- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)return await backend.filter(filter=And(conds),limit=limit,@@ -2094,7 +2300,7 @@ class VikingVectorIndexBackend:async def delete_account_data(self, account_id: str, *, ctx: RequestContext) -> int:"""删除指定 account 的所有数据(仅限,root 角色操作)"""self._check_root_role(ctx)- root_backend = self._get_root_backend()+ root_backend = await self.get_account_backend(account_id)return await root_backend.delete_by_filter(Eq("account_id", account_id))async def delete_user_data(@@ -2106,7 +2312,7 @@ class VikingVectorIndexBackend:) -> int:"""Delete every vector record owned by one user as ROOT."""self._check_root_role(ctx)- root_backend = self._get_root_backend()+ root_backend = await self.get_account_backend(account_id)return await root_backend.delete_by_filter(And([Eq("account_id", account_id), Eq("owner_user_id", user_id)]))@@ -2118,7 +2324,7 @@ class VikingVectorIndexBackend:Or([Eq("uri", uri), In("uri", [f"{uri}/"])]),]- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)await backend.delete_by_filter(And(conds))def _uri_transfer_filter(self, ctx: RequestContext, uri: str, *, recursive: bool) -> FilterExpr:@@ -2142,7 +2348,7 @@ class VikingVectorIndexBackend:sort: separate aggregate and search requests need not share a snapshot.Backend failures still propagate, unlike the legacy fail-open query API."""- backend = self._get_backend_for_context(ctx)+ backend = await self._get_backend_for_context(ctx)records: Dict[str, Dict[str, Any]] = {}entries = sorted(set(entry_uris))for uri in entries:diff --git a/openviking/storage/vikingdb_manager.py b/openviking/storage/vikingdb_manager.pyindex dd6401be7..db9b170cc 100644--- a/openviking/storage/vikingdb_manager.py+++ b/openviking/storage/vikingdb_manager.py@@ -158,23 +158,6 @@ class VikingDBManager(VikingVectorIndexBackend):logger.error(f"Error getting embedding queue size: {e}")return 0- def get_embedder(self):- """- Get the embedder instance from configuration.-- Returns:- Embedder instance or None if not configured- """- try:- from openviking_cli.utils.config import get_openviking_config-- config = get_openviking_config()- return config.embedding.get_embedder()- except Exception as e:- logger.warning(f"Failed to get embedder from configuration: {e}")- return None--class VikingDBManagerProxy:"""租户绑定的 VikingDBManager 代理。@@ -259,33 +242,35 @@ class VikingDBManagerProxy:async def get_embedding_queue_size(self) -> int:return await self._manager.get_embedding_queue_size()- def get_embedder(self):- return self._manager.get_embedder()-# =========================================================================# Collection Management(透传)# =========================================================================async def create_collection(self, name: str, schema: Dict[str, Any]) -> bool:- return await self._manager.create_collection(name, schema)+ backend = await self._manager.get_account_backend(self._ctx.account_id)+ return await backend.create_collection(name, schema)async def drop_collection(self) -> bool:- return await self._manager.drop_collection()+ backend = await self._manager.get_account_backend(self._ctx.account_id)+ return await backend.drop_collection()async def collection_exists(self) -> bool:- return await self._manager.collection_exists()+ backend = await self._manager.get_account_backend(self._ctx.account_id)+ return await backend.collection_exists()async def collection_exists_bound(self) -> bool:- return await self._manager.collection_exists_bound()+ return await self.collection_exists()async def get_collection_info(self) -> Optional[Dict[str, Any]]:- return await self._manager.get_collection_info()+ backend = await self._manager.get_account_backend(self._ctx.account_id)+ return await backend.get_collection_info()async def get_collection_meta(self) -> Optional[Dict[str, Any]]:- return await self._manager.get_collection_meta()+ return await self._manager.get_collection_meta(ctx=self._ctx)async def update_collection_description(self, description: str) -> bool:- return await self._manager.update_collection_description(description)+ backend = await self._manager.get_account_backend(self._ctx.account_id)+ return await backend.update_collection_description(description)# =========================================================================# 数据操作 API(自动携带 ctx)@@ -420,16 +405,19 @@ class VikingDBManagerProxy:return await self._manager.clear(ctx=self._ctx)async def optimize(self) -> bool:- return await self._manager.optimize()+ backend = await self._manager.get_account_backend(self._ctx.account_id)+ return await backend.optimize()async def close(self) -> None:return await self._manager.close()async def health_check(self) -> bool:- return await self._manager.health_check()+ backend = await self._manager.get_account_backend(self._ctx.account_id)+ return await backend.health_check()async def get_stats(self) -> Dict[str, Any]:- return await self._manager.get_stats()+ backend = await self._manager.get_account_backend(self._ctx.account_id)+ return await backend.get_stats()# =========================================================================# Tenant-Aware 方法(自动携带 ctx)diff --git a/openviking/utils/embedding_utils.py b/openviking/utils/embedding_utils.pyindex a4e2dc86d..6c58194ff 100644--- a/openviking/utils/embedding_utils.py+++ b/openviking/utils/embedding_utils.py@@ -636,7 +636,10 @@ async def vectorize_file(content_type = await _resolve_resource_content_type(file_path, file_name, viking_fs, ctx, file_content=file_content)- embedding_cfg = get_openviking_config().embedding+ resolver = getattr(viking_fs, "_vector_config_resolver", None)+ if resolver is None:+ raise RuntimeError("Vectorization requires a vector config resolver")+ embedding_cfg = (await resolver.resolve(ctx.account_id)).embeddingconfigured_text_source = embedding_cfg.text_sourceeffective_text_source = TEXT_SOURCE_SUMMARY_FIRST if use_summary else configured_text_sourceembed_summary = bool(summary and effective_text_source in SUMMARY_TEXT_SOURCES)diff --git a/openviking/utils/media_processor.py b/openviking/utils/media_processor.pyindex 2912ec136..227ad21c1 100644--- a/openviking/utils/media_processor.py+++ b/openviking/utils/media_processor.py@@ -92,9 +92,9 @@ class UnifiedResourceProcessor:def _get_vlm_processor(self) -> Optional["VLMProcessor"]:if self._vlm_processor is None:- from openviking.parse.vlm import VLMProcessor-- self._vlm_processor = VLMProcessor()+ raise RuntimeError(+ "UnifiedResourceProcessor requires an explicitly configured VLMProcessor"+ )return self._vlm_processordef _get_accessor_registry(self):diff --git a/openviking/utils/resource_processor.py b/openviking/utils/resource_processor.pyindex fc5da9c86..5ce437ca4 100644--- a/openviking/utils/resource_processor.py+++ b/openviking/utils/resource_processor.py@@ -49,6 +49,7 @@ from openviking_cli.utils.config import get_openviking_configfrom openviking_cli.utils.storage import StoragePathif TYPE_CHECKING:+ from openviking.config.vlm import VLMResolverfrom openviking.parse.accessors.base import LocalResourcefrom openviking.parse.vlm import VLMProcessor@@ -99,12 +100,13 @@ class ResourceProcessor:max_context_size: int = 2000,max_split_depth: int = 3,runtime_config_manager: Optional[Any] = None,+ vlm_resolver: Optional["VLMResolver"] = None,):"""Initialize coordinated writer."""self.vikingdb = vikingdb- self.embedder = vikingdb.get_embedder()self.media_storage = media_storageself.runtime_config_manager = runtime_config_manager+ self.vlm_resolver = vlm_resolverself.tree_builder = TreeBuilder()self._vlm_processor = Noneself._media_processor = None@@ -170,30 +172,60 @@ class ResourceProcessor:return resultdef _get_summarizer(self) -> "Summarizer":- """Lazy initialization of Summarizer."""+ """Lazy initialization of the standalone Summarizer."""if self._summarizer is None:self._summarizer = Summarizer(self._get_vlm_processor())return self._summarizer+ async def _summarizer_for(self, ctx: RequestContext) -> "Summarizer":+ """Build a lightweight account-bound summarizer."""+ if self._summarizer is not None:+ return self._summarizer+ if self.vlm_resolver is None:+ raise RuntimeError(+ "ResourceProcessor requires a VLM resolver for account-owned work"+ )+ return Summarizer(await self._vlm_processor_for(ctx))+def _get_vlm_processor(self) -> "VLMProcessor":- """Lazy initialization of VLM processor."""+ """Return an explicitly configured standalone VLM processor."""if self._vlm_processor is None:- from openviking.parse.vlm import VLMProcessor-- self._vlm_processor = VLMProcessor()+ raise RuntimeError(+ "ResourceProcessor requires an explicitly configured VLMProcessor"+ )return self._vlm_processor+ async def _vlm_processor_for(self, ctx: RequestContext) -> "VLMProcessor":+ from openviking.parse.vlm import VLMProcessor++ if self.vlm_resolver is None:+ raise RuntimeError(+ "ResourceProcessor requires a VLM resolver for account-owned work"+ )+ return VLMProcessor(vlm=await self.vlm_resolver.get_vlm(ctx.account_id))+def _get_media_processor(self):"""Lazy initialization of unified media processor."""if self._media_processor is None:from openviking.utils.media_processor import UnifiedResourceProcessorself._media_processor = UnifiedResourceProcessor(- vlm_processor=self._get_vlm_processor(),storage=self.media_storage,)return self._media_processor+ async def _media_processor_for(self, ctx: RequestContext):+ from openviking.utils.media_processor import UnifiedResourceProcessor++ if self.vlm_resolver is None and self._media_processor is not None:+ return self._media_processor+ if self.vlm_resolver is None:+ return self._get_media_processor()+ return UnifiedResourceProcessor(+ vlm_processor=await self._vlm_processor_for(ctx),+ storage=self.media_storage,+ )+def _build_parse_output_store(self):"""Return the configured parse output store, or None for AGFS mode.@@ -591,7 +623,7 @@ class ResourceProcessor:**kwargs,) -> Optional["LocalResource"]:"""Freeze a source when durable routing cannot safely defer access."""- media_processor = self._get_media_processor()+ media_processor = await self._media_processor_for(ctx)if not snapshot_required and not media_processor.durable_route_requires_preparation(path, **kwargs):@@ -641,7 +673,7 @@ class ResourceProcessor:self, resource_uris: List[str], ctx: RequestContext, **kwargs) -> Dict[str, Any]:"""Expose summarization as a standalone method."""- return await self._get_summarizer().summarize(resource_uris, ctx, **kwargs)+ return await (await self._summarizer_for(ctx)).summarize(resource_uris, ctx, **kwargs)async def process_resource(self,@@ -697,7 +729,7 @@ class ResourceProcessor:ResourceIngestionEventDataSource,)- media_processor = self._get_media_processor()+ media_processor = await self._media_processor_for(ctx)viking_fs = get_viking_fs()# Use reason as instruction fallback so it influences L0/L1# generation and improves search relevance as documented.@@ -1166,7 +1198,7 @@ class ResourceProcessor:if should_summarize:try:- summary_result = await self._get_summarizer().summarize(+ summary_result = await (await self._summarizer_for(ctx)).summarize(resource_uris=[root_uri],ctx=ctx,skip_vectorization=not build_index,@@ -1223,7 +1255,9 @@ class ResourceProcessor:if not should_summarize and temp_uri and not source_committed:viking_fs = get_viking_fs()if vectors_only and target_preexisting and not root_is_file:- diff = await SemanticProcessor()._sync_topdown_recursive(+ diff = await SemanticProcessor(+ vlm_resolver=self.vlm_resolver+ )._sync_topdown_recursive(temp_uri, root_uri, ctx=ctx, lock=resource_lock)sync_deleted_files = list(getattr(diff, "deleted_files", []))@@ -1249,7 +1283,7 @@ class ResourceProcessor:files=sync_deleted_files, dirs=sync_deleted_dirs, ctx=ctx)if should_refresh_file_parent:- await self._get_summarizer().refresh_file_parent(+ await (await self._summarizer_for(ctx)).refresh_file_parent(file_uri=file_refresh.file_uri,ctx=ctx,skip_vectorization=not build_index,@@ -1277,7 +1311,7 @@ class ResourceProcessor:await get_viking_fs()._async_agfs.pathlock_release(resource_lock)elif should_refresh_file_parent:try:- await self._get_summarizer().refresh_file_parent(+ await (await self._summarizer_for(ctx)).refresh_file_parent(file_uri=file_refresh.file_uri,ctx=ctx,skip_vectorization=not build_index,diff --git a/openviking/utils/skill_processor.py b/openviking/utils/skill_processor.pyindex 515098f9c..d7bd4eb03 100644--- a/openviking/utils/skill_processor.py+++ b/openviking/utils/skill_processor.py@@ -17,6 +17,7 @@ from typing import Any, Dict, List, Optionalimport yaml+from openviking.config.vlm import VLMHandle, VLMResolverfrom openviking.core.mcp_converter import is_mcp_format, mcp_to_skillfrom openviking.core.namespace import canonical_user_rootfrom openviking.core.skill_loader import SkillLoader@@ -102,10 +103,16 @@ class SkillProcessor:self,vikingdb: VikingDBManager,privacy_config_service: Optional[UserPrivacyConfigService] = None,+ vlm_resolver: Optional[VLMResolver] = None,):"""Initialize skill processor."""+ if privacy_config_service is not None and vlm_resolver is None:+ raise ValueError(+ "SkillProcessor requires a VLM resolver when privacy extraction is enabled"+ )self.vikingdb = vikingdbself._privacy_config_service = privacy_config_service+ self._vlm_resolver = vlm_resolverasync def process_skill(self,@@ -474,16 +481,21 @@ class SkillProcessor:async def prepare_skill_privacy(self, skill_dict: Dict[str, Any], ctx: RequestContext) -> tuple[Dict[str, Any], Dict[str, str]]:- del ctxif not self._privacy_config_service:return skill_dict, {}content = skill_dict.get("content", "")- extraction_result = await extract_skill_privacy_values(- skill_name=skill_dict.get("name", ""),- skill_description=skill_dict.get("description", ""),- content=content,- )+ extraction_kwargs = {+ "skill_name": skill_dict.get("name", ""),+ "skill_description": skill_dict.get("description", ""),+ "content": content,+ }+ if self._vlm_resolver is None:+ raise RuntimeError(+ "SkillProcessor requires a VLM resolver for account-owned work"+ )+ extraction_kwargs["vlm"] = await self._vlm_resolver.get_vlm(ctx.account_id)+ extraction_result = await extract_skill_privacy_values(**extraction_kwargs)if not extraction_result.values:return skill_dict, {}@@ -547,7 +559,7 @@ class SkillProcessor:delete_if_empty=delete_if_empty,)- async def _generate_overview(self, skill_dict: Dict[str, Any], config) -> str:+ async def _generate_overview(self, skill_dict: Dict[str, Any], vlm: VLMHandle) -> str:"""Generate L1 overview using VLM."""from openviking.prompts import render_prompt@@ -559,7 +571,7 @@ class SkillProcessor:"skill_content": skill_dict.get("content", ""),},)- return await config.vlm.get_completion_async(prompt)+ return await vlm.get_completion_async(prompt)async def _write_skill_content(self,diff --git a/openviking_cli/utils/config/embedding_config.py b/openviking_cli/utils/config/embedding_config.pyindex 3e1687e39..f4f278c82 100644--- a/openviking_cli/utils/config/embedding_config.py+++ b/openviking_cli/utils/config/embedding_config.py@@ -1039,6 +1039,9 @@ class EmbeddingConfig(BaseModel):if self.dense:return self._create_single_or_failover_embedder("dense", self.dense)+ if self.sparse:+ return self._create_single_or_failover_embedder("sparse", self.sparse)+raise ValueError("No embedding configuration found (dense, sparse, or hybrid)")def _create_single_or_failover_embedder(@@ -1112,6 +1115,8 @@ class EmbeddingConfig(BaseModel):return self.hybrid.get_effective_dimension()if self.dense:return self.dense.get_effective_dimension()+ if self.sparse:+ return self.sparse.get_effective_dimension()return 2048@staticmethoddiff --git a/openviking_cli/utils/config/runtime_field.py b/openviking_cli/utils/config/runtime_field.pyindex 85e089343..aeccef2cc 100644--- a/openviking_cli/utils/config/runtime_field.py+++ b/openviking_cli/utils/config/runtime_field.py@@ -5,24 +5,24 @@A plain Pydantic ``Field`` is not on the config API surface: PATCH requeststargeting it are rejected. Every component of a writable nested path must use:func:`RuntimeField`; marking a section does not grant access to its ordinary-``Field`` descendants. ``RuntimeField`` records two orthogonal attributes so-generic code can decide what the API may do without per-field branching:+``Field`` descendants. ``RuntimeField`` records lifecycle metadata so generic+code can decide what the API may write without per-field branching:- ``dynamic`` — the field's writable lifecycle, a single boolean covering allmutability. ``True`` (default): writable both at creation and by later PATCH.``False``: writable only when the owning object is first created (account orcluster config); any later PATCH that touches it is rejected. When a``dynamic=False`` field is not given at creation it is fixed to its default- (which may be a ``fallback``, resolved at read time — never materialized).-- ``fallback`` — when an account leaves this field unset, which cluster-level- field supplies the value. The value may be a dotted path (``storage.vectordb``)- to reach a nested cluster field.+ (which may use the deprecated compatibility ``fallback`` behavior).+- ``fallback`` — deprecated compatibility metadata for legacy whole-section+ fallback. It selects one complete Cluster field when the corresponding+ top-level Account field is unset; it never recursively merges fields.These attributes are stored on the field's ``json_schema_extra`` under the-``x-runtime-config`` key and read back through the helpers below. ``dynamic`` and-``fallback`` are orthogonal: a ``dynamic=False`` field may still carry a-``fallback`` (meaning "if not given at creation, fall back to the cluster default-forever").+``x-runtime-config`` key and read back through the helpers below. New Account+configuration should not use ``fallback``. When business behavior needs an+unset Account setting to use Cluster configuration, the business resolver+should combine the independently published Account and Cluster models.Whether a field is cluster-wide or per-account is *not* one of these attributes:it is decided by which model declares the field. Fields on ``OpenVikingConfig``@@ -62,12 +62,11 @@ def RuntimeField( # noqa: N802PATCH that touches it (or ``null``-deletes it via a parent) isrejected. A field declared with a plain ``Field`` — i.e. without``RuntimeField`` — is never on the config surface at all.- fallback: name of a cluster-level field, optionally dotted to reach a- nested field (``storage.vectordb``). When an account has not set this- field, its effective value is read from ``OpenVikingConfig.<fallback>``.- ``None`` (default) means there is no cluster fallback; the manager- returns ``None`` for an unset account field and the caller supplies- any business default. Only meaningful on ``AccountConfig``.+ fallback: Deprecated compatibility-only Cluster field path. It applies+ only when a top-level Account section is entirely unset and returns+ that complete Cluster section; it does not merge nested fields.+ New code should leave this as ``None`` and implement defaults in its+ business resolver. Only meaningful on ``AccountConfig``."""from pydantic import Field@@ -75,6 +74,7 @@ def RuntimeField( # noqa: N802extra[RUNTIME_CONFIG_KEY] = {"dynamic": dynamic,"fallback": fallback,+ "fallback_deprecated": fallback is not None,}return Field(json_schema_extra=extra, **kwargs)@@ -103,9 +103,11 @@ def is_dynamic(field: FieldInfo) -> bool:def fallback_of(field: FieldInfo) -> Optional[str]:- """Return the cluster field path this account field falls back to, else ``None``.+ """Return a legacy whole-section Cluster fallback path, else ``None``.- The result may be dotted (``storage.vectordb``); resolution walks the path.+ Deprecated: this helper exists for compatibility with fields that already+ declare ``fallback``. New business code should resolve Account and Cluster+ configuration explicitly."""meta = _runtime_meta(field)return meta.get("fallback") if meta else Nonediff --git a/openviking_cli/utils/config/vlm_config.py b/openviking_cli/utils/config/vlm_config.pyindex cf92cc307..832d9a53e 100644--- a/openviking_cli/utils/config/vlm_config.py+++ b/openviking_cli/utils/config/vlm_config.py@@ -9,6 +9,8 @@ from typing import Any, Awaitable, Callable, Dict, List, Optional, Unionfrom pydantic import BaseModel, Field, PrivateAttr, ValidationInfo, model_validator+from openviking_cli.utils.config.runtime_field import RuntimeField+def _load_codex_auth_module():importlib.import_module("openviking.models.vlm")@@ -37,12 +39,28 @@ def _reject_stream_config(data: Any, location: str) -> None:)+def _bind_token_usage_tracker(instance: Any, tracker: Any) -> None:+ """Bind one Account tracker to all concrete VLM instances in a wrapper."""+ if instance is None:+ return+ if hasattr(instance, "_token_tracker"):+ instance._token_tracker = tracker+ if hasattr(instance, "_vlm_instances"):+ for child in instance._vlm_instances:+ _bind_token_usage_tracker(child, tracker)+ else:+ for name in ("primary", "backup"):+ child = getattr(instance, name, None)+ if child is not None:+ _bind_token_usage_tracker(child, tracker)++class VLMCredential(BaseModel):"""Single VLM credential configuration for multi-credential failover."""- id: Optional[str] = Field(default=None, description="Unique identifier for this credential")- provider: Optional[str] = Field(default=None, description="Provider type")- model: Optional[str] = Field(+ id: Optional[str] = RuntimeField(default=None, description="Unique identifier for this credential")+ provider: Optional[str] = RuntimeField(default=None, description="Provider type")+ model: Optional[str] = RuntimeField(default=None,description=("Model name (or endpoint id) for this credential. "@@ -50,26 +68,28 @@ class VLMCredential(BaseModel):"to point to a different deployment / endpoint."),)- api_key: Optional[str] = Field(default=None, description="API key")- api_base: Optional[str] = Field(default=None, description="API base URL")- api_version: Optional[str] = Field(default=None, description="API version")- forward_api_key: Optional[bool] = Field(+ api_key: Optional[str] = RuntimeField(default=None, description="API key")+ api_base: Optional[str] = RuntimeField(default=None, description="API base URL")+ api_version: Optional[str] = RuntimeField(default=None, description="API version")+ forward_api_key: Optional[bool] = RuntimeField(default=None, description="Whether to pass api_key through to LiteLLM")- extra_headers: Optional[Dict[str, str]] = Field(default=None, description="Extra HTTP headers")- extra_request_body: Optional[Dict[str, Any]] = Field(+ extra_headers: Optional[Dict[str, str]] = RuntimeField(+ default=None, description="Extra HTTP headers"+ )+ extra_request_body: Optional[Dict[str, Any]] = RuntimeField(default=None, description="Extra JSON body fields")- reasoning_effort: Optional[str] = Field(+ reasoning_effort: Optional[str] = RuntimeField(default=None,description="Reasoning effort for OpenAI-compatible reasoning models",)- keepalive_expiry: Optional[float] = Field(+ keepalive_expiry: Optional[float] = RuntimeField(default=None,ge=0.0,description="Idle HTTP connection lifetime for OpenAI-compatible providers",)- max_tokens: Optional[int] = Field(+ max_tokens: Optional[int] = RuntimeField(default=None,gt=0,description=(@@ -113,7 +133,15 @@ class VLMMediaConfig(BaseModel):class VLMConfig(BaseModel):- """VLM configuration, supports multiple provider backends and multi-credential failover."""+ """VLM configuration with multi-provider and multi-credential failover.++ Compatibility contract: top-level fields added here must describe common+ runtime behavior that is safe for Account VLM configurations to inherit+ from Cluster configuration. Fields that select a model service, credential,+ endpoint, or provider-specific request identity must instead be represented+ by ``AccountVLMConfig`` (normally ``model`` or ``VLMCredential``) and excluded by+ ``AccountVLMConfig._ACCOUNT_OWNED_MODEL_SERVICE_FIELDS``.+ """backup: Optional["VLMConfig"] = Field(default=None, description="Backup VLM configuration for failover (legacy)"@@ -211,6 +239,7 @@ class VLMConfig(BaseModel):)_vlm_instance: Optional[Any] = None+ _token_usage_tracker: Any = PrivateAttr(default=None)_media_semaphores: weakref.WeakKeyDictionary[asyncio.AbstractEventLoop,weakref.ReferenceType[asyncio.Semaphore],@@ -665,8 +694,19 @@ class VLMConfig(BaseModel):else:self._vlm_instance = primary+ if self._token_usage_tracker is not None:+ _bind_token_usage_tracker(self._vlm_instance, self._token_usage_tracker)+return self._vlm_instance+ def set_token_usage_tracker(self, tracker: Any) -> None:+ """Bind an externally owned tracker without eagerly creating a client."""+ if self._token_usage_tracker is tracker:+ return+ self._token_usage_tracker = tracker+ if self._vlm_instance is not None:+ _bind_token_usage_tracker(self._vlm_instance, tracker)+def close(self) -> None:"""Close and clear the cached VLM instance."""instance = self._vlm_instance@@ -674,6 +714,13 @@ class VLMConfig(BaseModel):if instance is not None:instance.close()+ def __del__(self) -> None:+ """Release a lazily-created client when the config is no longer referenced."""+ try:+ self.close()+ except Exception:+ pass+def _build_vlm_config_dict_for_credential(self, credential: VLMCredential) -> Dict[str, Any]:"""Build VLM instance config dict for a specific credential."""result = {@@ -748,6 +795,7 @@ class VLMConfig(BaseModel):prompt: str = "",thinking: Optional[bool] = None,tools: Optional[List[Dict[str, Any]]] = None,+ tool_choice: Optional[Any] = None,messages: Optional[List[Dict[str, Any]]] = None,) -> Union[str, Any]:"""Get LLM completion."""@@ -756,6 +804,7 @@ class VLMConfig(BaseModel):prompt=prompt,thinking=effective_thinking,tools=tools,+ tool_choice=tool_choice,messages=messages,)@@ -766,6 +815,7 @@ class VLMConfig(BaseModel):tools: Optional[List[Dict[str, Any]]] = None,tool_choice: Optional[Any] = None,messages: Optional[List[Dict[str, Any]]] = None,+ max_tokens: Optional[int] = None,) -> Union[str, Any]:"""Get LLM completion asynchronously."""effective_thinking = self.thinking if thinking is None else thinking@@ -775,6 +825,7 @@ class VLMConfig(BaseModel):tools=tools,tool_choice=tool_choice,messages=messages,+ max_tokens=max_tokens,)def is_available(self) -> bool:@@ -793,6 +844,7 @@ class VLMConfig(BaseModel):images: Optional[list] = None,thinking: Optional[bool] = None,tools: Optional[List[Dict[str, Any]]] = None,+ tool_choice: Optional[Any] = None,messages: Optional[List[Dict[str, Any]]] = None,) -> Union[str, Any]:"""Get LLM completion with images."""@@ -802,6 +854,7 @@ class VLMConfig(BaseModel):images=images,thinking=effective_thinking,tools=tools,+ tool_choice=tool_choice,messages=messages,)@@ -864,6 +917,7 @@ class VLMConfig(BaseModel):images: Optional[list] = None,thinking: Optional[bool] = None,tools: Optional[List[Dict[str, Any]]] = None,+ tool_choice: Optional[Any] = None,messages: Optional[List[Dict[str, Any]]] = None,) -> Union[str, Any]:"""Get LLM completion with images asynchronously."""@@ -873,6 +927,7 @@ class VLMConfig(BaseModel):images=images,thinking=effective_thinking,tools=tools,+ tool_choice=tool_choice,messages=messages,)diff --git a/tests/agfs/test_viking_fs_git.py b/tests/agfs/test_viking_fs_git.pyindex e0edb7674..5eeacac5c 100644--- a/tests/agfs/test_viking_fs_git.py+++ b/tests/agfs/test_viking_fs_git.py@@ -626,6 +626,21 @@ class _SpyExecutor:return 0+def _patch_reindex_executor(monkeypatch, vfs, spy):+ import openviking.service.reindex_executor as reindex_mod++ vlm_resolver, vector_resolver = object(), object()+ monkeypatch.setattr(vfs, "_vlm_resolver", vlm_resolver)+ monkeypatch.setattr(vfs, "_vector_config_resolver", vector_resolver)++ def factory(*, vlm_resolver, vector_config_resolver):+ assert vlm_resolver is vfs._vlm_resolver+ assert vector_config_resolver is vfs._vector_config_resolver+ return spy++ monkeypatch.setattr(reindex_mod, "ReindexExecutor", factory)++@pytest.mark.asyncioasync def test_restore_schedules_reindex_for_derived_only_change(vfs, monkeypatch):"""When a restore only changes a directory `.abstract.md` (source file@@ -634,9 +649,7 @@ async def test_restore_schedules_reindex_for_derived_only_change(vfs, monkeypatc"""spy = _SpyExecutor()- import openviking.service.reindex_executor as reindex_mod-- monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: spy)+ _patch_reindex_executor(monkeypatch, vfs, spy)ctx = _make_ctx(account="acct_derived_only")await vfs.write_file("viking://resources/proj/x.md", b"body", ctx=ctx)@@ -677,9 +690,7 @@ async def test_restore_schedules_marker_and_files_independently(vfs, monkeypatch"""spy = _SpyExecutor()- import openviking.service.reindex_executor as reindex_mod-- monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: spy)+ _patch_reindex_executor(monkeypatch, vfs, spy)ctx = _make_ctx(account="acct_dedup")await vfs.write_file("viking://resources/proj/x.md", b"v1", ctx=ctx)@@ -717,9 +728,7 @@ async def test_restore_schedules_siblings_independently(vfs, monkeypatch):"""spy = _SpyExecutor()- import openviking.service.reindex_executor as reindex_mod-- monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: spy)+ _patch_reindex_executor(monkeypatch, vfs, spy)ctx = _make_ctx(account="acct_subsume_sibling")# proj_a: source file + directory marker@@ -760,9 +769,7 @@ async def test_restore_deletes_marker_and_source_vectors(vfs, monkeypatch):"""spy = _SpyExecutor()- import openviking.service.reindex_executor as reindex_mod-- monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: spy)+ _patch_reindex_executor(monkeypatch, vfs, spy)ctx = _make_ctx(account="acct_del_marker")await vfs.write_file("viking://resources/keep/k.md", b"keep", ctx=ctx)@@ -798,9 +805,7 @@ async def test_restore_relations_json_has_no_vector_side_effect(vfs, monkeypatch"""spy = _SpyExecutor()- import openviking.service.reindex_executor as reindex_mod-- monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: spy)+ _patch_reindex_executor(monkeypatch, vfs, spy)ctx = _make_ctx(account="acct_relations")await vfs.write_file("viking://resources/proj/.relations.json", b'{"v":1}', ctx=ctx)@@ -835,9 +840,7 @@ async def test_restore_returns_pollable_task_id(vfs, monkeypatch):"""spy = _SpyExecutor()- import openviking.service.reindex_executor as reindex_mod-- monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: spy)+ _patch_reindex_executor(monkeypatch, vfs, spy)from openviking.service.task_tracker import (TaskTracker,@@ -907,9 +910,8 @@ async def test_restore_concurrent_same_dir_is_rejected(vfs, monkeypatch):from openviking.storage.errors import ResourceBusyErrorspy = _SpyExecutor()- import openviking.service.reindex_executor as reindex_mod- monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: spy)+ _patch_reindex_executor(monkeypatch, vfs, spy)ctx = _make_ctx(account="acct_lock_same")await vfs.write_file("viking://resources/proj/a.md", b"v1", ctx=ctx)@@ -968,9 +970,8 @@ async def test_restore_concurrent_sibling_dirs_do_not_block(vfs, monkeypatch):concurrently — neither blocks the other."""spy = _SpyExecutor()- import openviking.service.reindex_executor as reindex_mod- monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: spy)+ _patch_reindex_executor(monkeypatch, vfs, spy)ctx = _make_ctx(account="acct_lock_sibling")await vfs.write_file("viking://resources/proj_a/x.md", b"v1", ctx=ctx)diff --git a/tests/config/test_runtime_config.py b/tests/config/test_runtime_config.pyindex 8108fa1b7..4bf3d2983 100644--- a/tests/config/test_runtime_config.py+++ b/tests/config/test_runtime_config.py@@ -411,11 +411,29 @@ def test_get_account_rejects_unknown_field():def test_account_patch_sets_override_and_publishes():+ source = MemoryConfigSource()+ manager, holder = _make_manager(source)+ asyncio.run(manager.initialize())+async def run():- manager, _ = _make_manager(MemoryConfigSource())- event = await manager.patch_account("ov-a", {"vlm": {"model": "account-model"}})- assert event.scope.key == "ov-a"- assert (await manager.get_account("ov-a", "vlm")).model == "account-model"+ await asyncio.gather(+ asyncio.to_thread(+ lambda: asyncio.run(manager.patch_account("ov-a", {"vlm": {"model": "account"}}))+ ),+ asyncio.to_thread(+ lambda: asyncio.run(+ manager.patch_account("ov-a", {"memory": {"extraction_enabled": False}})+ )+ ),+ )+ assert await source.load(ConfigScope.account("ov-a")) == {+ "vlm": {"model": "account"},+ "memory": {"extraction_enabled": False},+ }+ assert (await manager.get_account("ov-a", "vlm")).model == "account"+ assert (await manager.get_account("ov-a", "memory")).extraction_enabled is False+ assert (await manager.get_account("ov-b", "vlm")).model is None+ assert holder["config"].vlm.model is Noneasyncio.run(run())@@ -496,9 +514,9 @@ def test_patch_waits_for_matching_consumers_and_filters_registration():seen = []async def matching(event):+ seen.append(event.new_config.vlm.model)started.set()await release.wait()- seen.append(event.new_config.vlm.model)async def wrong_scope(event):seen.append("wrong-scope")@@ -523,10 +541,16 @@ def test_patch_waits_for_matching_consumers_and_filters_registration():)patch_task = asyncio.create_task(manager.patch_cluster({"vlm": {"model": "first"}}))await started.wait()- assert not patch_task.done()- release.set()- await patch_task+ later = asyncio.create_task(manager.patch_cluster({"vlm": {"model": "second"}}))+ while (await manager.get_settings(ConfigScope.cluster())).get("vlm", {}).get(+ "model"+ ) != "second":+ await asyncio.sleep(0)+ assert not patch_task.done() and not later.done()assert seen == ["first"]+ release.set()+ await asyncio.gather(patch_task, later)+ assert seen == ["first", "second"]asyncio.run(run())@@ -660,31 +684,86 @@ def test_refresh_does_not_resurrect_evicted_account():# -- AccountConfig field attributes + manager fallback -------------------------def test_account_config_field_attributes():- fields = AccountConfig.model_fields- assert set(fields) == {"acl", "agent_evolution", "feishu", "github"}- assert collect_runtime_field_paths(AccountConfig) == {- ("acl",),- ("acl", "enabled"),- ("agent_evolution",),- ("agent_evolution", "enabled"),- ("feishu",),- ("feishu", "app_id"),- ("feishu", "app_secret"),- ("feishu", "download_images"),- ("feishu", "max_records_per_table"),- ("feishu", "max_rows_per_sheet"),- ("feishu", "request_timeout"),- ("github",),- ("github", "token"),+async def test_account_runtime_binding_and_updates_are_isolated():+ from openviking.config.binding import manager_over_source+ from openviking.config.vector import AccountVectorConfigResolver+ from openviking_cli.utils.config import set_openviking_config+ from openviking_cli.utils.config.open_viking_config import (+ OpenVikingConfig,+ OpenVikingConfigSingleton,+ )++ cluster = OpenVikingConfig.from_dict(+ {+ "embedding": {+ "dense": {+ "provider": "openai",+ "model": "cluster",+ "dimension": 4,+ "api_key": "cluster-secret",+ "api_base": "https://cluster.invalid/v1",+ }+ },+ "vlm": {"provider": "openai", "model": "cluster-vlm", "api_key": "cluster-secret"},+ }+ )+ set_openviking_config(cluster)+ source = MemoryConfigSource()+ manager = manager_over_source(source, base_config=cluster)+ resolver = AccountVectorConfigResolver(manager)+ credential = {+ "provider": "openai",+ "api_key": "account-secret",+ "api_base": "https://account.invalid/v1",}- assert is_dynamic(fields["feishu"])- assert fallback_of(fields["feishu"]) is None- assert is_dynamic(fields["github"])- assert fallback_of(fields["github"]) is None- assert is_dynamic(fields["agent_evolution"])- assert fallback_of(fields["agent_evolution"]) == "agent_evolution"- assert collect_frozen_paths(AccountConfig) == set()+ settings = {+ "embedding": {"dense": {"model": "account", "dimension": 8, "credentials": [credential]}},+ "vectordb": {+ "backend": "http",+ "url": "http://account-vectors.invalid",+ "name": "account",+ "index_name": "default",+ "dimension": 8,+ },+ "vlm": {"model": "account-vlm", "credentials": [credential]},+ }+ try:+ await manager.initialize()+ with pytest.raises(ValueError, match="dimension"):+ await manager.patch_account(+ "a",+ {**settings, "vectordb": {**settings["vectordb"], "dimension": 4}},+ creating=True,+ )+ assert await source.load(ConfigScope.account("a")) is None+ await manager.patch_account("a", settings, creating=True)+ account, default = await resolver.resolve("a"), await resolver.resolve("b")+ assert account.dedicated_vectordb and account.vectordb.dimension == 8+ assert account.embedding.dense.credentials[0].api_key == "account-secret"+ assert account.embedding.dense.api_key is None+ assert default.embedding.dense.api_key == "cluster-secret"+ assert default.vectordb.dimension == 4 and not default.dedicated_vectordb+ vlm = (await manager.get_account("a", "vlm")).to_vlm_config(cluster.vlm)+ assert vlm.model == "account-vlm" and vlm.credentials[0].api_key == "account-secret"+ assert vlm.api_key is None++ before = await source.load(ConfigScope.account("a"))+ with pytest.raises(ConfigPatchError, match="create-only"):+ await manager.patch_account(+ "a", {"embedding": {"max_retries": 9, "dense": {"dimension": 4}}}+ )+ with pytest.raises(ConfigPatchError, match="api_ky"):+ await manager.patch_account(+ "a", {"vlm": {"credentials": [{"provider": "openai", "api_ky": "typo"}]}}+ )+ assert await source.load(ConfigScope.account("a")) == before+ await manager.patch_account(+ "a", {"embedding": {"dense": {"credentials": [{**credential, "api_key": "rotated"}]}}}+ )+ assert (await resolver.resolve("a")).embedding.dense.credentials[0].api_key == "rotated"+ assert (await resolver.resolve("b")).embedding.dense.api_key == "cluster-secret"+ finally:+ OpenVikingConfigSingleton.reset_instance()def test_account_config_ignores_inactive_sections_during_known_patch():@@ -698,8 +777,8 @@ def test_account_config_ignores_inactive_sections_during_known_patch():source = MemoryConfigSource()scope = ConfigScope.account("ov-a")- inactive_section = {"model": "unused"}- await source.update(scope, lambda _: {"vlm": inactive_section})+ inactive_section = {"extraction_enabled": False}+ await source.update(scope, lambda _: {"memory": inactive_section})base = OpenVikingConfig.from_dict({})set_openviking_config(base)@@ -709,7 +788,7 @@ def test_account_config_ignores_inactive_sections_during_known_patch():assert await manager.get_account("ov-a", "acl") is Noneawait manager.patch_account("ov-a", {"acl": {"enabled": True}})assert await source.load(scope) == {- "vlm": inactive_section,+ "memory": inactive_section,"acl": {"enabled": True},}finally:@@ -732,10 +811,13 @@ def test_account_patch_rejects_inactive_fields_and_allows_active_fields():validate_patch(AccountConfig, {"feishu": {"domain": "https://custom.example"}})validate_patch(AccountConfig, {"feishu": {"request_timeout": 60}})validate_patch(AccountConfig, {"feishu": None})- with pytest.raises(ConfigPatchError):- validate_patch(AccountConfig, {"vlm": {"model": "m"}})- with pytest.raises(ConfigPatchError):- validate_patch(AccountConfig, {"embedding": {"dense": {"model": "m"}}}, creating=True)+ validate_patch(AccountConfig, {"vlm": {"model": "m"}})+ validate_patch(AccountConfig, {"query_planner": {"timeout": 30}})+ with pytest.raises(ConfigPatchError, match="max_concurrent"):+ validate_patch(AccountConfig, {"vlm": {"max_concurrent": 2}})+ validate_patch(AccountConfig, {"embedding": {"dense": {"model": "m"}}}, creating=True)+ with pytest.raises(ConfigPatchError, match="create-only"):+ validate_patch(AccountConfig, {"embedding": {"dense": {"model": "m"}}})def test_feishu_cluster_patch_rejects_unknown_fields():diff --git a/tests/conftest.py b/tests/conftest.pyindex 862a02ba5..aca5eacc4 100644--- a/tests/conftest.py+++ b/tests/conftest.py@@ -110,6 +110,25 @@ def test_data_dir(temp_dir: Path) -> Path:return data_dir+def vector_backend_factory():+ """Construct local storage with an explicit account configuration boundary."""+ from types import SimpleNamespace+ from unittest.mock import AsyncMock++ from openviking.storage.viking_vector_index_backend import VikingVectorIndexBackend++ def create(config):+ backend = VikingVectorIndexBackend(config)+ settings = SimpleNamespace(vectordb=config, dedicated_vectordb=False)+ backend.set_vector_config_resolver(+ SimpleNamespace(resolve=AsyncMock(return_value=settings))+ )+ return backend++ return create++# ============ Service Fixtures ============diff --git a/tests/eval/test_ragas_basic.py b/tests/eval/test_ragas_basic.pyindex 69f6fc0f3..27cebf79e 100644--- a/tests/eval/test_ragas_basic.py+++ b/tests/eval/test_ragas_basic.py@@ -59,7 +59,7 @@ def test_async_record_writer_drains_records_before_stop_sentinel():def test_pipeline_query_consumes_http_result_and_generates_answer():class Client:- def search(self, **kwargs):+ def search(self, query, **kwargs):return {"memories": [{diff --git a/tests/misc/test_debug_service.py b/tests/misc/test_debug_service.pyindex 2a1ceb4e8..f5a5f7e36 100644--- a/tests/misc/test_debug_service.py+++ b/tests/misc/test_debug_service.py@@ -4,7 +4,8 @@Tests for DebugService and ObserverService."""-from unittest.mock import MagicMock, patch+import asyncio+from unittest.mock import ANY, AsyncMock, MagicMock, patchfrom openviking.service.debug_service import (ComponentStatus,@@ -140,9 +141,8 @@ class TestObserverService:mock_get_queue_manager.return_value = mock_queue_managermock_observer = MagicMock()- mock_observer.is_healthy.return_value = True- mock_observer.has_errors.return_value = False- mock_observer.get_status_table.return_value = "Queue Status Table"+ mock_observer.get_status_table_async = AsyncMock(return_value="Queue Status Table")+ mock_observer.has_active_errors_async = AsyncMock(return_value=False)mock_observer_cls.return_value = mock_observerservice = ObserverService()@@ -195,10 +195,10 @@ class TestObserverService:assert status.name == "models"assert status.is_healthy is Trueassert status.has_errors is False- assert status.status == "Models Status Table"+ assert status.status == "Scope: Cluster\nModels Status Table"mock_observer_cls.assert_called_once_with(vlm_instance=mock_vlm_instance,- embedding_instance=None,+ embedding_instance=ANY,rerank_instance=None,)@@ -232,16 +232,21 @@ class TestObserverService:mock_observer.has_errors.return_value = Falsemock_observer.get_status_table.return_value = "OK"mock_cls.return_value = mock_observer+ mock_queue_cls.return_value.get_status_table_async = AsyncMock(return_value="OK")+ mock_queue_cls.return_value.has_active_errors_async = AsyncMock(return_value=False)# Mock get_viking_fs to return a viking_fs with pathlock_observemock_viking_fs = MagicMock()+ mock_viking_fs._async_agfs.pathlock_observe = AsyncMock(+ return_value={+ "active_locks": 0,+ "waiting_locks": 0,+ "stale_locks_removed": 0,+ "conflicts": [],+ }+ )mock_get_viking_fs.return_value = mock_viking_fs- mock_run_async.return_value = {- "active_locks": 0,- "waiting_locks": 0,- "stale_locks_removed": 0,- "conflicts": [],- }+ mock_run_async.side_effect = asyncio.runmock_config = MagicMock(spec=["vlm"]) # Only allow vlm attributemock_config.vlm.get_vlm_instance.return_value = MagicMock()@@ -277,6 +282,8 @@ class TestObserverService:mock_queue.is_healthy.return_value = Falsemock_queue.has_errors.return_value = Truemock_queue.get_status_table.return_value = "Error"+ mock_queue.get_status_table_async = AsyncMock(return_value="Error")+ mock_queue.has_active_errors_async = AsyncMock(return_value=True)mock_queue_cls.return_value = mock_queue# VikingDB is healthy@@ -302,13 +309,16 @@ class TestObserverService:# Mock lock (pathlock_observe) as healthymock_viking_fs = MagicMock()+ mock_viking_fs._async_agfs.pathlock_observe = AsyncMock(+ return_value={+ "active_locks": 0,+ "waiting_locks": 0,+ "stale_locks_removed": 0,+ "conflicts": [],+ }+ )mock_get_viking_fs.return_value = mock_viking_fs- mock_run_async.return_value = {- "active_locks": 0,- "waiting_locks": 0,- "stale_locks_removed": 0,- "conflicts": [],- }+ mock_run_async.side_effect = asyncio.runmock_config = MagicMock(spec=["vlm"]) # Only allow vlm attributemock_config.vlm.get_vlm_instance.return_value = MagicMock()@@ -344,15 +354,20 @@ class TestObserverService:mock_observer.has_errors.return_value = Falsemock_observer.get_status_table.return_value = "OK"mock_cls.return_value = mock_observer+ mock_queue_cls.return_value.get_status_table_async = AsyncMock(return_value="OK")+ mock_queue_cls.return_value.has_active_errors_async = AsyncMock(return_value=False)mock_viking_fs = MagicMock()+ mock_viking_fs._async_agfs.pathlock_observe = AsyncMock(+ return_value={+ "active_locks": 0,+ "waiting_locks": 0,+ "stale_locks_removed": 0,+ "conflicts": [],+ }+ )mock_get_viking_fs.return_value = mock_viking_fs- mock_run_async.return_value = {- "active_locks": 0,- "waiting_locks": 0,- "stale_locks_removed": 0,- "conflicts": [],- }+ mock_run_async.side_effect = asyncio.runmock_config = MagicMock(spec=["vlm"])mock_config.vlm.get_vlm_instance.return_value = MagicMock()@@ -456,7 +471,8 @@ class TestObserverService:assert status is expectedmock_get_status.assert_called_once_with()- def test_lock_json_status_without_dependency_is_structured(self):+ @patch("openviking.service.debug_service.get_viking_fs", side_effect=RuntimeError())+ def test_lock_json_status_without_dependency_is_structured(self, _mock_get_viking_fs):"""Test lock json format returns a structured payload when uninitialized."""service = ObserverService()status = service.get_lock_status(format="json")@@ -492,6 +508,8 @@ class TestObserverService:mock_queue.is_healthy.return_value = Falsemock_queue.has_errors.return_value = Truemock_queue.get_status_table.return_value = "Error"+ mock_queue.get_status_table_async = AsyncMock(return_value="Error")+ mock_queue.has_active_errors_async = AsyncMock(return_value=True)mock_queue_cls.return_value = mock_queue# Others are healthydiff --git a/tests/misc/test_ovpack_import_policy.py b/tests/misc/test_ovpack_import_policy.pyindex 9b2df3b77..abce4b9e7 100644--- a/tests/misc/test_ovpack_import_policy.py+++ b/tests/misc/test_ovpack_import_policy.py@@ -10,6 +10,7 @@ import osimport tempfileimport zipfilefrom pathlib import Path+from types import SimpleNamespacefrom unittest.mock import AsyncMockimport pytest@@ -316,6 +317,21 @@ class FakeVectorStore:def __init__(self) -> None:self.upserts: list[dict[str, object]] = []+ async def resolve(self, account_id):+ from openviking_cli.utils.config.embedding_config import EmbeddingConfig+ return SimpleNamespace(+ embedding=EmbeddingConfig(dense={+ "provider": "openai", "model": "test", "dimension": 3, "api_key": "test"+ }),+ vectordb=SimpleNamespace(sparse_weight=0),+ )++ async def get_account_backend(self, account_id):+ return self++ async def get_collection_meta(self):+ return {}+async def filter(self, **kwargs):uri = kwargs["filter"].valueif uri == "viking://resources/demo":@@ -390,6 +406,9 @@ class HybridIndexVectorStore(FakeVectorStore):assert index_name == self._index_namereturn {"VectorIndex": {"IndexType": "flat_hybrid"}}+ async def get_collection_meta(self):+ return self.get_index_meta_data(self._index_name)+@pytest.fixturedef request_ctx() -> RequestContext:@@ -793,7 +812,8 @@ async def test_export_include_vectors_rejects_missing_index_records("viking://resources/demo",str(temp_ovpack_path),ctx=request_ctx,- vector_store=IncompleteVectorStore(),+ vector_store=(vector_store := IncompleteVectorStore()),+ vector_config_resolver=vector_store,include_vectors=True,)@@ -812,7 +832,8 @@ async def test_export_include_vectors_allows_overview_without_abstract("viking://resources/demo",str(temp_ovpack_path),ctx=request_ctx,- vector_store=OverviewOnlyVectorStore(),+ vector_store=(vector_store := OverviewOnlyVectorStore()),+ vector_config_resolver=vector_store,include_vectors=True,)@@ -880,7 +901,8 @@ async def test_export_include_vectors_rejects_hybrid_index_snapshot("viking://resources/demo",str(temp_ovpack_path),ctx=request_ctx,- vector_store=HybridIndexVectorStore(),+ vector_store=(vector_store := HybridIndexVectorStore()),+ vector_config_resolver=vector_store,include_vectors=True,)@@ -900,19 +922,21 @@ async def test_import_ovpack_restores_required_dense_vector_snapshot(}monkeypatch.setattr("openviking.storage.ovpack.vectors.embedding_snapshot_metadata",- lambda dimensions: {**embedding_metadata, "dimensions": dimensions},+ lambda dimensions, embedding_cfg: {**embedding_metadata, "dimensions": dimensions},)monkeypatch.setattr("openviking.storage.ovpack.vectors.current_embedding_metadata",- lambda: embedding_metadata,+ lambda embedding_cfg: embedding_metadata,)+ vector_store = FakeVectorStore()await export_ovpack(FakeExportVikingFS(),"viking://resources/demo",str(temp_ovpack_path),ctx=request_ctx,- vector_store=FakeVectorStore(),+ vector_store=vector_store,+ vector_config_resolver=vector_store,include_vectors=True,)@@ -928,6 +952,7 @@ async def test_import_ovpack_restores_required_dense_vector_snapshot(request_ctx,vector_mode="require",vector_store=vector_store,+ vector_config_resolver=vector_store,)assert result == "viking://resources/imported/demo"@@ -1150,8 +1175,10 @@ async def _restricted_pack_source(indexed_fs):},ctx=admin,)- acl = AclManager(backend)- acl.set_enabled(admin.account_id, True)+ acl = AclManager(+ backend,+ SimpleNamespace(get_account=AsyncMock(return_value=SimpleNamespace(enabled=True))),+ )fs.acl_manager = backend.acl_manager = aclawait fs.set_acl(root,diff --git a/tests/misc/test_vikingfs_find_without_rerank.py b/tests/misc/test_vikingfs_find_without_rerank.pyindex 27fcd2706..fd873e297 100644--- a/tests/misc/test_vikingfs_find_without_rerank.py+++ b/tests/misc/test_vikingfs_find_without_rerank.py@@ -150,6 +150,7 @@ async def test_find_accepts_image_url_without_text_query(monkeypatch) -> None:"",target_uri="viking://resources",image_url="data:image/png;base64,abc",+ ctx=_ctx(),)assert result.total == 1@@ -188,6 +189,7 @@ async def test_find_uses_quick_mode_with_rerank_config(monkeypatch) -> None:result = await fs.find("guide",target_uri="viking://resources/docs",+ ctx=_ctx(),)assert result.total == 0diff --git a/tests/models/test_query_embedding_cache.py b/tests/models/test_query_embedding_cache.pyindex ff2c44ecb..67b0b3693 100644--- a/tests/models/test_query_embedding_cache.py+++ b/tests/models/test_query_embedding_cache.py@@ -10,7 +10,9 @@ import pytestfrom openviking.models.embedder.base import (EmbedderBase,EmbedResult,+ QueryEmbeddingCache,embed_compat,+ query_embed_cache_scope,query_embed_cache_var,)@@ -42,7 +44,7 @@ class CountingEmbedder(EmbedderBase):async def test_embed_compat_reuses_same_query_text_within_request():embedder = CountingEmbedder()- query_embed_cache_var.set({})+ query_embed_cache_var.set(QueryEmbeddingCache())first = await embed_compat(embedder, "hello", is_query=True)second = await embed_compat(embedder, "hello", is_query=True)@@ -53,7 +55,7 @@ async def test_embed_compat_reuses_same_query_text_within_request():async def test_embed_compat_caches_distinct_texts_separately():embedder = CountingEmbedder()- query_embed_cache_var.set({})+ query_embed_cache_var.set(QueryEmbeddingCache())await embed_compat(embedder, "alpha", is_query=True)await embed_compat(embedder, "beta", is_query=True)@@ -66,7 +68,7 @@ async def test_embed_compat_dedupes_concurrent_same_text():# copy the request context, so the cache dict must be shared by reference# and the first find's in-flight embed is awaited by every sibling.embedder = CountingEmbedder()- query_embed_cache_var.set({})+ query_embed_cache_var.set(QueryEmbeddingCache())async def one():return await embed_compat(embedder, "shared", is_query=True)@@ -80,7 +82,7 @@ async def test_embed_compat_dedupes_concurrent_same_text():async def test_embed_compat_never_caches_resource_embeds():embedder = CountingEmbedder()- query_embed_cache_var.set({})+ query_embed_cache_var.set(QueryEmbeddingCache())await embed_compat(embedder, "hello", is_query=False)await embed_compat(embedder, "hello", is_query=False)@@ -102,7 +104,7 @@ async def test_embed_compat_does_not_cache_outside_request_scope():async def test_embed_compat_retries_after_a_failed_embed():embedder = CountingEmbedder()embedder.fail_next = 1- query_embed_cache_var.set({})+ query_embed_cache_var.set(QueryEmbeddingCache())failed = Falsetry:@@ -117,55 +119,113 @@ async def test_embed_compat_retries_after_a_failed_embed():async def test_query_embed_cache_scope_resets_after_exit():- from openviking.models.embedder.base import query_embed_cache_scope-- with query_embed_cache_scope():+ async with query_embed_cache_scope():assert query_embed_cache_var.get() is not Noneassert query_embed_cache_var.get() is Noneasync def test_query_embed_cache_scope_resets_on_exception():- from openviking.models.embedder.base import query_embed_cache_scope-with pytest.raises(RuntimeError):- with query_embed_cache_scope():+ async with query_embed_cache_scope():raise RuntimeError("boom")assert query_embed_cache_var.get() is None-async def test_embedders_with_same_model_name_do_not_share_entries():- # Keying by embedder identity keeps two embedders that happen to share a- # model_name from serving each other's vectors.- first = CountingEmbedder(model_name="shared-name")- second = CountingEmbedder(model_name="shared-name")- query_embed_cache_var.set({})-- await embed_compat(first, "same-text", is_query=True)- await embed_compat(second, "same-text", is_query=True)-- assert first.calls == ["same-text"]- assert second.calls == ["same-text"]---async def test_waiter_cancellation_leaves_shared_embed_running():- # Cancelling a waiter must not cancel the shared in-flight embed (shield),- # and the cache entry must stay usable for later waiters.+async def test_account_query_cache_isolated_by_account_and_config(monkeypatch):+ from openviking.config.binding import manager_over_source+ from openviking.config.embedding import AccountEmbeddingProvider+ from openviking.config.source import MemoryConfigSource+ from openviking.config.vector import AccountVectorConfigResolver+ from openviking_cli.utils.config import set_openviking_config+ from openviking_cli.utils.config.embedding_config import EmbeddingConfig+ from openviking_cli.utils.config.open_viking_config import (+ OpenVikingConfig,+ OpenVikingConfigSingleton,+ )++ clients = []++ def create(config):+ client = CountingEmbedder(config.dense.model)+ clients.append(client)+ return client++ monkeypatch.setattr(EmbeddingConfig, "get_embedder", create)+ base = OpenVikingConfig.from_dict(+ {+ "embedding": {+ "dense": {+ "model": "shared-name",+ "dimension": 1,+ "provider": "openai",+ "api_key": "cluster-key",+ }+ }+ }+ )+ set_openviking_config(base)+ manager = manager_over_source(MemoryConfigSource(), base_config=base)+ provider = AccountEmbeddingProvider(AccountVectorConfigResolver(manager), manager)+ try:+ await manager.initialize()+ await manager.patch_account(+ "a",+ {+ "embedding": {+ "dense": {+ "model": "shared-name",+ "dimension": 1,+ "credentials": [{"provider": "openai", "api_key": "a-key"}],+ }+ }+ },+ creating=True,+ )+ first, second = provider.bind("a"), provider.bind("b")+ async with query_embed_cache_scope():+ results = await asyncio.gather(+ embed_compat(first, "same-text", is_query=True),+ embed_compat(provider.bind("a"), "same-text", is_query=True),+ )+ assert all(result.dense_vector == [1.0] for result in results)+ await embed_compat(second, "same-text", is_query=True)+ assert [client.calls for client in clients] == [["same-text"], ["same-text"]]++ await manager.patch_account(+ "a",+ {+ "embedding": {+ "dense": {"credentials": [{"provider": "openai", "api_key": "rotated-key"}]}+ }+ },+ )+ await embed_compat(first, "same-text", is_query=True)+ await embed_compat(second, "same-text", is_query=True)+ assert [client.calls for client in clients] == [+ ["same-text"],+ ["same-text"],+ ["same-text"],+ ]+ finally:+ await provider.close()+ OpenVikingConfigSingleton.reset_instance()+++async def test_one_waiter_cancellation_leaves_shared_embed_running():+ # One cancelled sibling must not affect another waiter on the same query.embedder = CountingEmbedder(delay=0.1)- query_embed_cache_var.set({})+ query_embed_cache_var.set(QueryEmbeddingCache())waiter = asyncio.create_task(embed_compat(embedder, "shared", is_query=True))- await asyncio.sleep(0.01) # let the waiter create and await the shared task+ await asyncio.sleep(0.01)+ survivor = asyncio.create_task(embed_compat(embedder, "shared", is_query=True))waiter.cancel()with pytest.raises(asyncio.CancelledError):await waiter- # The shared embed survived the waiter cancellation and completed.- await asyncio.sleep(0.15)+ result = await survivorassert embedder.calls == ["shared"]-- result = await embed_compat(embedder, "shared", is_query=True)assert result.dense_vector == [1.0]- assert embedder.calls == ["shared"] # served from cache, no second embedasync def test_cancelled_shared_embed_is_evicted_and_retried():@@ -173,13 +233,13 @@ async def test_cancelled_shared_embed_is_evicted_and_retried():# cancellation, the poisoned key must be evicted, and the next embed of the# same text must start a fresh task instead of awaiting the dead one.embedder = CountingEmbedder(delay=0.1)- query_embed_cache_var.set({})+ query_embed_cache_var.set(QueryEmbeddingCache())waiter = asyncio.create_task(embed_compat(embedder, "shared", is_query=True))await asyncio.sleep(0.01) # let the waiter create and await the shared taskcache = query_embed_cache_var.get()assert cache is not None- next(iter(cache.values())).cancel()+ next(iter(cache.values())).task.cancel()with pytest.raises(asyncio.CancelledError):await waiterassert cache == {}@@ -189,13 +249,11 @@ async def test_cancelled_shared_embed_is_evicted_and_retried():assert embedder.calls == ["shared", "shared"]-async def test_waiter_cancelled_then_shared_embed_failure_evicts_entry():- # The last waiter is cancelled while the shared embed still runs; when that- # orphaned embed then fails, the stale entry must be evicted so the next- # embed of the same text starts fresh instead of replaying the old failure.+async def test_last_waiter_cancellation_stops_shared_embed_and_evicts_entry():+ # The cache owns shared work, so cancelling its last waiter also cancels+ # that work instead of leaving an orphaned API call in the request scope.embedder = CountingEmbedder(delay=0.1)- embedder.fail_next = 1- query_embed_cache_var.set({})+ query_embed_cache_var.set(QueryEmbeddingCache())waiter = asyncio.create_task(embed_compat(embedder, "shared", is_query=True))await asyncio.sleep(0.01) # let the waiter create and await the shared task@@ -203,9 +261,7 @@ async def test_waiter_cancelled_then_shared_embed_failure_evicts_entry():with pytest.raises(asyncio.CancelledError):await waiter- # Let the orphaned shared embed run to failure; the done callback must- # have evicted the failed entry.- await asyncio.sleep(0.2)+ await asyncio.sleep(0)assert query_embed_cache_var.get() == {}result = await embed_compat(embedder, "shared", is_query=True)diff --git a/tests/parse/test_media_understanding_summary.py b/tests/parse/test_media_understanding_summary.pyindex 248d6e5ae..3105db2c0 100644--- a/tests/parse/test_media_understanding_summary.py+++ b/tests/parse/test_media_understanding_summary.py@@ -184,6 +184,7 @@ async def test_media_concurrency_bounds_staging_and_inference(monkeypatch):f"viking://resources/video/clip-{index}.mp4",f"clip-{index}.mp4",llm_sem=asyncio.Semaphore(64),+ vlm=config_vlm,))for index in range(4)@@ -220,6 +221,7 @@ async def test_image_summary_downsamples_large_model_input(monkeypatch):result = await media_utils.generate_image_summary("viking://resources/docs/large.jpg","large.jpg",+ vlm=vlm,)assert result == {"name": "large.jpg", "summary": "image summary"}@@ -248,6 +250,7 @@ async def test_unknown_size_media_stops_at_hard_staging_limit(result = await media_utils.generate_video_summary("viking://resources/video/unknown-size.mp4","unknown-size.mp4",+ vlm=client,)assert result == {@@ -272,6 +275,7 @@ async def test_media_summary_stat_skips_directory_vector_count(monkeypatch):await media_utils.generate_video_summary("viking://resources/video/clip.mp4","clip.mp4",+ vlm=client,)fs.stat.assert_awaited_once_with(@@ -298,6 +302,7 @@ async def test_success_normalizes_markdown_and_filename_heading(result = await media_utils.generate_video_summary("viking://resources/video/quarterly.mov","quarterly.mov",+ vlm=client,)assert result["summary"].startswith("# quarterly\n\nA useful overview paragraph.")@@ -323,6 +328,7 @@ async def test_provider_failure_returns_empty_summary(monkeypatch):result = await media_utils.generate_video_summary("viking://resources/video/clip.mp4","clip.mp4",+ vlm=client,)assert result == {"name": "clip.mp4", "summary": ""}diff --git a/tests/retrieve/test_context_assembler_pipeline.py b/tests/retrieve/test_context_assembler_pipeline.pyindex 8012788a9..5f7ac0262 100644--- a/tests/retrieve/test_context_assembler_pipeline.py+++ b/tests/retrieve/test_context_assembler_pipeline.py@@ -48,7 +48,27 @@ class _FakeFindResult:self.skills = skills or []-def _service(*, hits, bodies, session=None, abstracts=None):+class _FakeVLMResolver:+ async def get_query_planner(self, account_id):+ del account_id+ return object()++ async def has_dedicated_query_planner(self, account_id):+ del account_id+ return True+++_DEFAULT_VLM_RESOLVER = _FakeVLMResolver()+++def _service(+ *,+ hits,+ bodies,+ session=None,+ abstracts=None,+ vlm_resolver=_DEFAULT_VLM_RESOLVER,+):abstracts = abstracts or {}async def fake_find(**kwargs):@@ -75,6 +95,7 @@ def _service(*, hits, bodies, session=None, abstracts=None):fs=SimpleNamespace(read=fake_read, abstract=fake_abstract),sessions=SimpleNamespace(get=fake_get),viking_fs=None,+ vlm_resolver=vlm_resolver,)@@ -151,8 +172,8 @@ async def test_assembly_returns_readable_entries_within_budget():async def test_query_expansion_fans_out_planned_queries(monkeypatch):queries_seen = []- async def fake_expand(*, query, session, mode, timeout_s=None):- del session, mode, timeout_s+ async def fake_expand(*, query, session, mode, **kwargs):+ del session, mode, kwargsreturn [query, "expanded query"], "used"async def fake_find(**kwargs):@@ -171,6 +192,7 @@ async def test_query_expansion_fans_out_planned_queries(monkeypatch):fs=SimpleNamespace(read=None),sessions=SimpleNamespace(get=fake_get),viking_fs=None,+ vlm_resolver=_DEFAULT_VLM_RESOLVER,)result = await assemble_context(@@ -410,17 +432,18 @@ async def test_rewrite_kernel_distinguishes_no_relevant_from_invalid_output(monkconfig = SimpleNamespace(retrieval=SimpleNamespace(recall_rewrite_timeout_s=1),- get_query_planner=lambda: _Planner(),)monkeypatch.setattr(rewrite_module, "get_openviking_config", lambda: config)monkeypatch.setattr(rewrite_module, "render_prompt", lambda *args, **kwargs: "rewrite prompt")statuses = []+ planner = _Planner()for _ in range(3):digest, status, _ = await rewrite_module.rewrite_context(query="q",rendered='<memory uri="viking://a">body</memory>',valid_uris=["viking://a"],+ planner=planner,)assert digest == ""statuses.append(status)diff --git a/tests/retrieve/test_hierarchical_retriever_rerank.py b/tests/retrieve/test_hierarchical_retriever_rerank.pyindex 3dbeb8b98..059c014f3 100644--- a/tests/retrieve/test_hierarchical_retriever_rerank.py+++ b/tests/retrieve/test_hierarchical_retriever_rerank.py@@ -59,7 +59,11 @@ class DummyStorage:async def _acl_enabled(self, ctx: RequestContext) -> bool:return self.acl_manager is not None and await self.acl_manager.is_enabled(ctx.account_id)- async def collection_exists_bound(self) -> bool:+ async def get_account_backend(self, account_id):+ assert account_id+ return self++ async def collection_exists(self) -> bool:return Trueasync def search_in_tenant(diff --git a/tests/retrieve/test_intent_analyzer_query_planner.py b/tests/retrieve/test_intent_analyzer_query_planner.pyindex cd64a6148..b805bbbb2 100644--- a/tests/retrieve/test_intent_analyzer_query_planner.py+++ b/tests/retrieve/test_intent_analyzer_query_planner.py@@ -89,13 +89,10 @@ def test_query_planner_prompt_mapping_targets_are_bundled():@pytest.mark.asyncioasync def test_intent_analyzer_uses_query_planner_when_configured(monkeypatch):planner = RecordingModel(_query_plan_response("planned query"))- vlm = RecordingModel(_query_plan_response("vlm query"))- config = SimpleNamespace(get_query_planner=lambda: planner)- monkeypatch.setattr(intent_module, "get_openviking_config", lambda: config)monkeypatch.setattr(intent_module, "render_prompt", lambda prompt_id, variables: "prompt")- result = await IntentAnalyzer().analyze(+ result = await IntentAnalyzer(query_planner=planner).analyze(compression_summary="",messages=[],current_message="where is my preference?",@@ -103,7 +100,6 @@ async def test_intent_analyzer_uses_query_planner_when_configured(monkeypatch):assert result.queries[0].query == "planned query"assert len(planner.prompts) == 1- assert vlm.prompts == []@pytest.mark.asyncio@@ -121,12 +117,9 @@ async def test_intent_analyzer_normalizes_non_string_reasoning(monkeypatch):]}""")- config = SimpleNamespace(get_query_planner=lambda: planner)-- monkeypatch.setattr(intent_module, "get_openviking_config", lambda: config)monkeypatch.setattr(intent_module, "render_prompt", lambda prompt_id, variables: "prompt")- result = await IntentAnalyzer().analyze(+ result = await IntentAnalyzer(query_planner=planner).analyze(compression_summary="",messages=[],current_message="where is my preference?",@@ -147,12 +140,9 @@ async def test_intent_analyzer_handles_bare_array_response(monkeypatch):}]""")- config = SimpleNamespace(get_query_planner=lambda: planner)-- monkeypatch.setattr(intent_module, "get_openviking_config", lambda: config)monkeypatch.setattr(intent_module, "render_prompt", lambda prompt_id, variables: "prompt")- result = await IntentAnalyzer().analyze(+ result = await IntentAnalyzer(query_planner=planner).analyze(compression_summary="",messages=[],current_message="where is my preference?",@@ -169,17 +159,15 @@ async def test_intent_analyzer_uses_model_specific_prompt(monkeypatch):_query_plan_response("planned query"),model="ollama/guoxuter/ov_intent_analysis_sft:v4_q8",)- config = SimpleNamespace(get_query_planner=lambda: planner)rendered: list[str] = []def fake_render_prompt(prompt_id, variables):rendered.append(prompt_id)return "rendered prompt"- monkeypatch.setattr(intent_module, "get_openviking_config", lambda: config)monkeypatch.setattr(intent_module, "render_prompt", fake_render_prompt)- result = await IntentAnalyzer().analyze(+ result = await IntentAnalyzer(query_planner=planner).analyze(compression_summary="",messages=[],current_message="where is my preference?",@@ -193,17 +181,15 @@ async def test_intent_analyzer_uses_model_specific_prompt(monkeypatch):@pytest.mark.asyncioasync def test_intent_analyzer_keeps_default_prompt_for_unmapped_model(monkeypatch):planner = RecordingModel(_query_plan_response("planned query"), model="ollama/qwen3.5:4b")- config = SimpleNamespace(get_query_planner=lambda: planner)rendered: list[str] = []def fake_render_prompt(prompt_id, variables):rendered.append(prompt_id)return "rendered prompt"- monkeypatch.setattr(intent_module, "get_openviking_config", lambda: config)monkeypatch.setattr(intent_module, "render_prompt", fake_render_prompt)- result = await IntentAnalyzer().analyze(+ result = await IntentAnalyzer(query_planner=planner).analyze(compression_summary="",messages=[],current_message="where is my preference?",@@ -214,14 +200,12 @@ async def test_intent_analyzer_keeps_default_prompt_for_unmapped_model(monkeypat@pytest.mark.asyncio-async def test_intent_analyzer_falls_back_to_vlm_without_query_planner(monkeypatch):+async def test_intent_analyzer_accepts_resolved_vlm_as_query_planner(monkeypatch):vlm = RecordingModel(_query_plan_response("vlm query"))- config = SimpleNamespace(get_query_planner=lambda: vlm)- monkeypatch.setattr(intent_module, "get_openviking_config", lambda: config)monkeypatch.setattr(intent_module, "render_prompt", lambda prompt_id, variables: "prompt")- result = await IntentAnalyzer().analyze(+ result = await IntentAnalyzer(query_planner=vlm).analyze(compression_summary="",messages=[],current_message="where is my preference?",diff --git a/tests/retrieve/test_skill_mixed_pagination.py b/tests/retrieve/test_skill_mixed_pagination.pyindex 16c49abae..cb144a379 100644--- a/tests/retrieve/test_skill_mixed_pagination.py+++ b/tests/retrieve/test_skill_mixed_pagination.py@@ -26,7 +26,7 @@ async def test_general_search_preserves_multiple_hits_from_one_skill(route):matches = result.skillselse:# Thinking obtains files through the ACL-aware global leaf query.- store._acl_enabled = lambda ctx: True+ store._acl_enabled = AsyncMock(return_value=True)result = await HierarchicalRetriever(store, None).retrieve(TypedQuery("hello", None, ""),ctx(),diff --git a/tests/retrieve/test_skill_package_results.py b/tests/retrieve/test_skill_package_results.pyindex 67dba4dfb..c3be9cb2d 100644--- a/tests/retrieve/test_skill_package_results.py+++ b/tests/retrieve/test_skill_package_results.py@@ -60,10 +60,14 @@ class PagedStore:self.calls = []self.child_calls = []- def _acl_enabled(self, ctx):+ async def _acl_enabled(self, ctx):return False- async def collection_exists_bound(self):+ async def get_account_backend(self, account_id):+ assert account_id+ return self++ async def collection_exists(self):return Truedef _page(self, records, kwargs):diff --git a/tests/server/test_admin_api.py b/tests/server/test_admin_api.pyindex a59d036b6..5508615fc 100644--- a/tests/server/test_admin_api.py+++ b/tests/server/test_admin_api.py@@ -19,6 +19,8 @@ from fastapi import FastAPIfrom fastapi import Request as FastAPIRequestfrom fastapi.responses import JSONResponse+from openviking.config.binding import manager_over_source+from openviking.config.source import MemoryConfigSourcefrom openviking.pyagfs.exceptions import AGFSNotFoundErrorfrom openviking.server.api_keys import APIKeyManagerfrom openviking.server.app import create_app@@ -132,6 +134,7 @@ class _FakeService:def __init__(self):self.viking_fs = _FakeVikingFS()self.sessions = self+ self.runtime_config_manager = manager_over_source(MemoryConfigSource())async def get_agent_evolution_enabled(self, account_id):del account_id@@ -185,6 +188,7 @@ def _build_lightweight_admin_test_app() -> FastAPI:@pytest_asyncio.fixture(scope="function")async def lightweight_admin_app(monkeypatch):app = _build_lightweight_admin_test_app()+ await app.state.fake_service.runtime_config_manager.initialize()await app.state.api_key_manager.load()return app@@ -1377,14 +1381,7 @@ async def test_account_memory_templates_reach_live_prompts(for user, peer in (("alice", None), ("bob", None), ("bob", "customer")):prompt = await prompt_for(account_id, user, peer)assert "CUSTOM_ACCOUNT_SCOPE EN" in prompt- # Preserve the Python protocol's existing static field contract. This- # change does not add a language context to that separate path.- expected_field = (- body["fields"][0]["description"]- if output_format == "python"- else "ACCOUNT_FIELD EN en"- )- assert expected_field in prompt+ assert "ACCOUNT_FIELD EN en" in promptassert "CUSTOM_ACCOUNT_SCOPE" not in await prompt_for("other-account", "alice")assert registry.get("profile").description == base_descriptionassert (await lightweight_admin_client.delete(url, headers=headers)).status_code == 200@@ -1466,7 +1463,9 @@ async def test_account_memory_templates_commit_keeps_snapshot_through_file_writereturn Mock(run=run)- compressor = SessionCompressorV3(vikingdb=None)+ vlm = Mock()+ resolver = Mock(get_vlm=AsyncMock(return_value=vlm))+ compressor = SessionCompressorV3(vikingdb=None, vlm_resolver=resolver)monkeypatch.setattr(compressor, "_get_or_create_react", orchestrator)try:await compressor._extract_user_memories(@@ -1476,6 +1475,7 @@ async def test_account_memory_templates_commit_keeps_snapshot_through_file_write)finally:await updater.close()+ resolver.get_vlm.assert_awaited_once_with(account_id)assert initialized == ["soul.md"]content = MemoryFileUtils.read(fs.files[uri], uri=uri).contentassert "# OLD_TEMPLATE" in content and "Business fact" in content@@ -1641,12 +1641,38 @@ async def test_account_memory_templates_corrupt_storage_is_not_overwritten(assert fs.agfs._files == original-async def test_create_account(admin_client: httpx.AsyncClient, admin_service: OpenVikingService):- """ROOT can create an account with first admin."""+async def test_create_account(+ admin_client: httpx.AsyncClient, admin_service: OpenVikingService, monkeypatch+):+ """ROOT provisioning applies account settings before initializing storage."""+ settings = {+ "embedding": {"max_retries": 5},+ "vectordb": {+ "backend": "vikingdb",+ "name": "account_context",+ "index_name": "default",+ "dimension": 1024,+ "vikingdb": {"host": "https://account.invalid"},+ },+ }+ adapter = Mock(mode="vikingdb", USE_CONTENT_FIELD=True)+ adapter.get.return_value = []+ adapter.get_collection.return_value.get_meta_data.return_value = {+ "Fields": [{"FieldName": name} for name in (+ "id", "uri", "account_id", "context_type", "abstract", "level",+ "user", "agent", "vector", "sparse_vector", "created_at", "updated_at",+ )]+ }+ adapter.upsert.side_effect = lambda rows: [row["id"] for row in rows]+ factory = Mock(return_value=adapter)+ monkeypatch.setattr(+ "openviking.storage.viking_vector_index_backend.create_collection_adapter",+ factory,+ )acct = _uid()resp = await admin_client.post("/api/v1/admin/accounts",- json={"account_id": acct, "admin_user_id": "alice"},+ json={"account_id": acct, "admin_user_id": "alice", "settings": settings},headers=root_headers(),)assert resp.status_code == 200@@ -1658,6 +1684,16 @@ async def test_create_account(admin_client: httpx.AsyncClient, admin_service: Opctx = RequestContext(user=UserIdentifier(acct, "alice"), role=Role.ADMIN)assert await admin_service.viking_fs.abstract("viking://resources", ctx=ctx)assert await admin_service.viking_fs.abstract("viking://user", ctx=ctx)+ stored = await admin_client.get(+ f"/api/v1/admin/accounts/{acct}/configuration", headers=root_headers()+ )+ assert stored.json()["result"]["settings"] == settings+ effective = await admin_service.vector_config_resolver.resolve(acct)+ assert effective.dedicated_vectordb+ assert effective.vectordb.name == "account_context"+ assert effective.embedding.max_retries == 5+ assert factory.call_args.args[0].vikingdb.host == "https://account.invalid"+ adapter.create_collection.assert_not_called()async def test_create_account_rolls_back_when_runtime_config_write_fails(@@ -2161,8 +2197,8 @@ async def test_delete_account(row[filter.field] == filter.value for row in indexed_rows.values())vectors = admin_service.viking_fs.vector_store- vectors._root_backend = _SingleAccountBackend(- vectors._config, bound_account_id=None, shared_adapter=adapter+ vectors._resolved_backends[acct] = _SingleAccountBackend(+ vectors._config, bound_account_id=acct, shared_adapter=adapter)original_delete = vectors.delete_account_datastarted, release = asyncio.Event(), asyncio.Event()@@ -3208,7 +3244,8 @@ async def test_trusted_mode_create_account_lists_current_account_metadata(manager = trusted_admin_app.state.api_key_manageraccount = next(item for item in manager.get_accounts() if item["account_id"] == acct)- assert set(account) == {"account_id", "created_at", "user_count"}+ assert set(account) == {"account_id", "created_at", "user_count", "status"}+ assert account["status"] == "active"async def test_user_page_summary_and_search_preserve_legacy_response(diff --git a/tests/server/test_admin_rebuild_api.py b/tests/server/test_admin_rebuild_api.pyindex 4806c8d5e..428f0af01 100644--- a/tests/server/test_admin_rebuild_api.py+++ b/tests/server/test_admin_rebuild_api.py@@ -2,6 +2,7 @@import asynciofrom types import SimpleNamespace+from unittest.mock import AsyncMockimport httpximport pytest@@ -27,11 +28,13 @@ ROOT_ACCOUNT_HEADERS = {@pytest.fixture-def semantic_config(monkeypatch):- monkeypatch.setattr(- "openviking.service.reindex_executor.get_openviking_config",- lambda: SimpleNamespace(vlm=SimpleNamespace(max_concurrent=2)),- )+def semantic_config():+ class Resolver:+ async def get_vlm(self, account_id):+ del account_id+ return SimpleNamespace(max_concurrent=2)++ return Resolver()def _make_reindex_run(ctx, counters):@@ -507,7 +510,7 @@ async def test_reindex_file_target_uses_exact_lock(monkeypatch):def _uri_to_path(self, uri, ctx):return "/local/default/resources/demo.md"- async def stat(self, uri, ctx):+ async def stat(self, uri, ctx, skip_count=None):return {"isDir": False}executor = ReindexExecutor()@@ -574,7 +577,7 @@ async def test_reindex_prune_existing_file_uses_exact_lock(monkeypatch):async def exists(self, uri, ctx):return True- async def stat(self, uri, ctx):+ async def stat(self, uri, ctx, skip_count=None):return {"isDir": False}executor = ReindexExecutor()@@ -824,7 +827,7 @@ async def test_reindex_semantic_processor_uses_uri_owner_for_user_scoped_recordsFakeSemanticProcessor,)- service = ReindexExecutor()+ service = ReindexExecutor(vlm_resolver=semantic_config)ctx = RequestContext(user=UserIdentifier(account_id="acct", user_id="admin"),role=Role.ROOT,@@ -1408,15 +1411,16 @@ async def test_reindex_memory_supports_semantic_and_vectors(monkeypatch):@pytest.mark.asyncio-async def test_reindex_semantic_processor_uses_configured_vlm_concurrency(monkeypatch):- from types import SimpleNamespace-+async def test_reindex_semantic_processor_uses_configured_vlm_concurrency(+ monkeypatch, semantic_config+):import openviking.service.reindex_executor as reindex_modseen = {}class FakeSemanticProcessor:- def __init__(self, max_concurrent_llm=64):+ def __init__(self, max_concurrent_llm=64, **kwargs):+ del kwargsseen["max_concurrent_llm"] = max_concurrent_llmasync def on_dequeue(self, data, lock=None):@@ -1424,17 +1428,14 @@ async def test_reindex_semantic_processor_uses_configured_vlm_concurrency(monkeyreturn ProcessResult.success()monkeypatch.setattr(reindex_mod, "SemanticProcessor", FakeSemanticProcessor)- monkeypatch.setattr(- reindex_mod,- "get_openviking_config",- lambda: SimpleNamespace(vlm=SimpleNamespace(max_concurrent=2)),- )ctx = RequestContext(user=UserIdentifier(account_id="test", user_id="alice"),role=Role.ROOT,)- await reindex_mod.ReindexExecutor()._run_semantic_processor(+ await reindex_mod.ReindexExecutor(+ vlm_resolver=semantic_config+ )._run_semantic_processor(uri="viking://resources/demo",context_type="resource",ctx=ctx,@@ -1456,7 +1457,7 @@ async def test_reindex_memory_semantic_and_vectors_rebuilds_full_subtree(monkeypseen["vectors"].append(uri)class FakeVikingFS:- async def stat(self, uri, ctx=None):+ async def stat(self, uri, ctx=None, skip_count=None):return {"isDir": True}monkeypatch.setattr(ReindexExecutor, "_run_semantic_processor", fake_run_semantic_processor)@@ -1523,7 +1524,7 @@ async def test_reindex_memory_non_recursive_limits_semantics_and_vectors(monkeypseen["vectors"] = kwargsclass FakeVikingFS:- async def stat(self, uri, ctx=None):+ async def stat(self, uri, ctx=None, skip_count=None):return {"isDir": True}monkeypatch.setattr(ReindexExecutor, "_run_semantic_processor", fake_run_semantic_processor)@@ -2220,7 +2221,7 @@ async def test_reindex_semantic_processor_runs_with_skip_vectorization(FakeSemanticProcessor,)- service = ReindexExecutor()+ service = ReindexExecutor(vlm_resolver=semantic_config)ctx = RequestContext(user=UserIdentifier(account_id="test", user_id="alice"),role=Role.ROOT,@@ -2265,7 +2266,7 @@ async def test_reindex_semantic_processor_passes_non_recursive_message(user=UserIdentifier(account_id="test", user_id="alice"),role=Role.ROOT,)- await ReindexExecutor()._run_semantic_processor(+ await ReindexExecutor(vlm_resolver=semantic_config)._run_semantic_processor(uri="viking://resources/demo",context_type="resource",ctx=ctx,@@ -2305,7 +2306,7 @@ async def test_reindex_semantic_processor_sets_memory_aggregation_policy(role=Role.ROOT,)- await ReindexExecutor()._run_semantic_processor(+ await ReindexExecutor(vlm_resolver=semantic_config)._run_semantic_processor(uri="viking://user/alice/memories/preferences",context_type="memory",ctx=ctx,@@ -2477,14 +2478,10 @@ async def test_reindex_resource_vector_text_summary_first_skips_content_read(monmonkeypatch.setattr(ReindexExecutor, "_safe_read_text", fail_if_content_read)monkeypatch.setattr(ReindexExecutor, "_fetch_existing_record", fake_fetch_existing_record)- monkeypatch.setattr(- "openviking.service.reindex_executor.get_openviking_config",- lambda: type(- "Config", (), {"embedding": type("Embedding", (), {"text_source": "summary_first"})()}- )(),- )-- service = ReindexExecutor()+ resolver = SimpleNamespace(resolve=AsyncMock(return_value=SimpleNamespace(+ embedding=SimpleNamespace(text_source="summary_first"),+ )))+ service = ReindexExecutor(vector_config_resolver=resolver)ctx = RequestContext(user=UserIdentifier(account_id="test", user_id="alice"),role=Role.ROOT,@@ -2497,6 +2494,7 @@ async def test_reindex_resource_vector_text_summary_first_skips_content_read(mon)assert vector_text == "summary for embedding"+ resolver.resolve.assert_awaited_once_with("test")@pytest.mark.asyncio@@ -2581,7 +2579,7 @@ async def test_reindex_memory_fallback_reads_existing_record_as_uri_owner(monkeyasync def exists(self, uri, ctx=None):return True- async def stat(self, uri, ctx=None):+ async def stat(self, uri, ctx=None, skip_count=None):return {"isDir": False}async def fake_read_memory_body(self, uri, *, ctx):@@ -2629,7 +2627,7 @@ async def test_reindex_memory_skips_fallback_when_body_read_fails(monkeypatch):async def exists(self, uri, ctx=None):return True- async def stat(self, uri, ctx=None):+ async def stat(self, uri, ctx=None, skip_count=None):return {"isDir": False}async def read_file(self, uri, ctx=None):@@ -2762,7 +2760,7 @@ async def test_reindex_memory_l2_falls_back_to_body_when_abstract_missing(monkeyasync def exists(self, uri, ctx=None):return True- async def stat(self, uri, ctx=None):+ async def stat(self, uri, ctx=None, skip_count=None):return {"isDir": False}seen = {}@@ -2813,7 +2811,7 @@ async def test_reindex_memory_l2_strips_memory_fields_from_abstract(monkeypatch)async def exists(self, uri, ctx=None):return True- async def stat(self, uri, ctx=None):+ async def stat(self, uri, ctx=None, skip_count=None):return {"isDir": False}seen = {}@@ -2875,7 +2873,7 @@ async def test_reindex_memory_vectors_walks_deep_subtree(monkeypatch):async def exists(self, uri, ctx=None):return True- async def stat(self, uri, ctx=None):+ async def stat(self, uri, ctx=None, skip_count=None):return {"isDir": True}async def tree(@@ -2950,7 +2948,7 @@ async def test_reindex_memory_vectors_rebuilds_directory_levels_without_regeneraasync def exists(self, uri, ctx=None):return True- async def stat(self, uri, ctx=None):+ async def stat(self, uri, ctx=None, skip_count=None):return {"isDir": True}async def tree(@@ -3341,6 +3339,10 @@ async def test_openviking_service_reindex_uses_default_root_context(monkeypatch)seen = {}class FakeExecutor:+ def __init__(self, vlm_resolver=None, vector_config_resolver=None):+ seen["vlm_resolver"] = vlm_resolver+ seen["vector_config_resolver"] = vector_config_resolver+async def execute(self, *, uri, mode, wait, ctx, dry_run=False):seen["uri"] = uriseen["mode"] = mode@@ -3348,17 +3350,19 @@ async def test_openviking_service_reindex_uses_default_root_context(monkeypatch)seen["ctx"] = ctxreturn {"status": "completed", "uri": uri}- import sys+ import openviking.service.reindex_executor as reindex_executormonkeypatch.setattr(- sys.modules["openviking.service.reindex_executor"],- "get_reindex_executor",- lambda: FakeExecutor(),+ reindex_executor,+ "ReindexExecutor",+ FakeExecutor,)service = OpenVikingService.__new__(OpenVikingService)service._initialized = Trueservice._user = UserIdentifier(account_id="acct", user_id="alice")+ service._vlm_resolver = object()+ service._vector_config_resolver = object()result = await OpenVikingService.reindex(service,@@ -3371,6 +3375,8 @@ async def test_openviking_service_reindex_uses_default_root_context(monkeypatch)assert seen["ctx"].role == Role.ROOTassert seen["ctx"].user.account_id == "acct"assert seen["ctx"].user.user_id == "alice"+ assert seen["vlm_resolver"] is service._vlm_resolver+ assert seen["vector_config_resolver"] is service._vector_config_resolver@pytest.mark.asyncio@@ -3380,6 +3386,10 @@ async def test_openviking_service_reindex_keeps_canonical_user_id(monkeypatch):seen = {}class FakeExecutor:+ def __init__(self, vlm_resolver=None, vector_config_resolver=None):+ seen["vlm_resolver"] = vlm_resolver+ seen["vector_config_resolver"] = vector_config_resolver+async def execute(self, *, uri, mode, wait, ctx, dry_run=False):seen["uri"] = uriseen["ctx"] = ctx@@ -3389,13 +3399,15 @@ async def test_openviking_service_reindex_keeps_canonical_user_id(monkeypatch):monkeypatch.setattr(reindex_executor,- "get_reindex_executor",- lambda: FakeExecutor(),+ "ReindexExecutor",+ FakeExecutor,)service = OpenVikingService.__new__(OpenVikingService)service._initialized = Trueservice._user = UserIdentifier(account_id="acct", user_id="alice")+ service._vlm_resolver = object()+ service._vector_config_resolver = object()ctx = RequestContext(user=UserIdentifier(account_id="acct", user_id="alice"),role=Role.ADMIN,@@ -3413,3 +3425,5 @@ async def test_openviking_service_reindex_keeps_canonical_user_id(monkeypatch):assert result == {"status": "completed", "uri": "viking://user/resources/memories"}assert seen["uri"] == "viking://user/resources/memories"assert seen["ctx"] is ctx+ assert seen["vlm_resolver"] is service._vlm_resolver+ assert seen["vector_config_resolver"] is service._vector_config_resolverdiff --git a/tests/server/test_agent_evolution_global_setting.py b/tests/server/test_agent_evolution_global_setting.pyindex e3b26d63b..9abb81644 100644--- a/tests/server/test_agent_evolution_global_setting.py+++ b/tests/server/test_agent_evolution_global_setting.py@@ -384,6 +384,36 @@ async def test_account_configuration_exposes_three_state_layer(settings_http):"github": {"token": "account-token"}}+ from openviking.server.auth import get_request_context++ url = "/api/v1/admin/accounts/default/configuration"+ model_settings = {+ "vlm": {+ "model": "account-model",+ "credentials": [{"provider": "openai", "api_key": "account-key"}],+ }+ }+ root_updated = await client.patch(url, json={"settings": model_settings})+ assert root_updated.status_code == 200, root_updated.text+ assert root_updated.json()["result"]["settings"]["vlm"] == model_settings["vlm"]++ admin = RequestContext(user=UserIdentifier("default", "admin"), role=Role.ADMIN)+ app = client._transport.app+ app.dependency_overrides[get_request_context] = lambda: admin+ try:+ visible = await client.get(url)+ assert visible.status_code == 200, visible.text+ assert visible.json()["result"]["settings"] == {"github": {"token": "account-token"}}+ denied = await client.patch(+ url, json={"settings": {"vlm": None, "embedding": {"max_retries": 5}}}+ )+ assert denied.status_code == 403, denied.text+ finally:+ app.dependency_overrides.pop(get_request_context)+ assert (await client.get(url)).json()["result"]["settings"] == root_updated.json()["result"][+ "settings"+ ]+async def test_cluster_agent_evolution_override_is_account_fallback(settings_http):client, service = settings_httpdiff --git a/tests/server/test_api_observer.py b/tests/server/test_api_observer.pyindex dd6bc62b0..40cfd3991 100644--- a/tests/server/test_api_observer.py+++ b/tests/server/test_api_observer.py@@ -3,6 +3,8 @@"""Tests for observer endpoints (/api/v1/observer/*)."""+import asyncio+import httpx@@ -46,14 +48,16 @@ async def test_observer_vikingdb(client: httpx.AsyncClient):async def test_observer_models(client: httpx.AsyncClient):- """GET /api/v1/observer/models should return models status."""- resp = await client.get("/api/v1/observer/models")+ resp = await client.get("/api/v1/observer/models", params={"format": "json"})assert resp.status_code == 200body = resp.json()assert body["status"] == "ok"result = body["result"]- assert "name" in result- assert "is_healthy" in result+ assert result["name"] == "models"+ assert isinstance(result["status"], dict)+ assert {"account_id", "embedding_dimension", "vlm", "embedding", "rerank"} <= result[+ "status"+ ].keys()async def test_observer_system(client: httpx.AsyncClient):@@ -70,13 +74,13 @@ async def test_observer_system(client: httpx.AsyncClient):async def test_observer_system_structured(client: httpx.AsyncClient):- """GET /api/v1/observer/system?format=json should include structured component payloads."""- resp = await client.get("/api/v1/observer/system", params={"format": "json"})- assert resp.status_code == 200- body = resp.json()- assert body["status"] == "ok"- result = body["result"]- assert "components" in result- queue = result["components"]["queue"]- assert "status" in queue- assert isinstance(queue["status"], dict)+ async with asyncio.timeout(10):+ response, models = await asyncio.gather(+ client.get("/api/v1/observer/system", params={"format": "json"}),+ client.get("/api/v1/observer/models", params={"format": "json"}),+ )+ assert response.status_code == models.status_code == 200+ components = response.json()["result"]["components"]+ assert isinstance(components["queue"]["status"], dict)+ assert components["models"]["status"] == models.json()["result"]["status"]+ assert isinstance(components["models"]["status"]["vlm"], list)diff --git a/tests/server/test_api_snapshot.py b/tests/server/test_api_snapshot.pyindex 295492b57..8468d6c7b 100644--- a/tests/server/test_api_snapshot.py+++ b/tests/server/test_api_snapshot.py@@ -284,7 +284,12 @@ async def test_restore_acl_and_reindex_identity(client_with_resource, service, mreindex_contexts.append(ctx)return 0- monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: _SpyExecutor())+ def factory(*, vlm_resolver, vector_config_resolver):+ assert vlm_resolver is service.viking_fs._vlm_resolver+ assert vector_config_resolver is service.vector_config_resolver+ return _SpyExecutor()++ monkeypatch.setattr(reindex_mod, "ReindexExecutor", factory)result = await service.fs.restore(project_dir=root,source_commit=v1["commit_oid"],@@ -644,7 +649,12 @@ async def test_restore_apply_triggers_reindex_hook(client_with_resource_and_blobcalls.append(uri)return {"ok": True}- monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: _SpyExecutor())+ def factory(*, vlm_resolver, vector_config_resolver):+ assert vlm_resolver is service.viking_fs._vlm_resolver+ assert vector_config_resolver is service.vector_config_resolver+ return _SpyExecutor()++ monkeypatch.setattr(reindex_mod, "ReindexExecutor", factory)# Mutate, commit v2, then restore back to c1 — must produce a reindex call.await service.viking_fs.write_file(blob_uri, b"v2-bytes\n", ctx=ctx)@@ -693,7 +703,12 @@ async def test_restore_delete_removes_orphaned_vectors(client_with_resource_and_deleted_calls.append((uri, int(level)))return 0- monkeypatch.setattr(reindex_mod, "get_reindex_executor", lambda: _SpyExecutor())+ def factory(*, vlm_resolver, vector_config_resolver):+ assert vlm_resolver is service.viking_fs._vlm_resolver+ assert vector_config_resolver is service.vector_config_resolver+ return _SpyExecutor()++ monkeypatch.setattr(reindex_mod, "ReindexExecutor", factory)# Add a brand-new file that does not exist at c1, then commit v2.new_uri = "viking://resources/restore_delete_fixture.txt"diff --git a/tests/server/test_privacy_config_service.py b/tests/server/test_privacy_config_service.pyindex ada239021..66a1c646d 100644--- a/tests/server/test_privacy_config_service.py+++ b/tests/server/test_privacy_config_service.py@@ -6,9 +6,9 @@ import asyncioimport pytestfrom openviking.core.namespace import canonical_user_root+from openviking.privacy.service import UserPrivacyConfigServicefrom openviking.privacy.skill_extractor import extract_skill_privacy_valuesfrom openviking.privacy.skill_placeholder import placeholderize_skill_content_with_blocks-from openviking.privacy.service import UserPrivacyConfigServicefrom openviking.server.identity import RequestContext, Rolefrom openviking.storage.viking_fs import VikingFSfrom openviking_cli.exceptions import NotFoundError@@ -212,10 +212,15 @@ async def test_skill_read_restores_placeholder_for_agent_segment_name(service):@pytest.mark.asyncioasync def test_skill_privacy_extraction_returns_content_blocks():content = 'api_key: "secret-xyz"\nbase_url: "https://example.com"\n'++ async def fake_completion_async(_prompt):+ return '{"values": {"api_key": "secret-xyz", "base_url": "https://example.com"}}'+result = await extract_skill_privacy_values(skill_name="extract-block-skill",skill_description="skill with secret",content=content,+ vlm=type("VLM", (), {"get_completion_async": staticmethod(fake_completion_async)})(),)assert result.values["api_key"] == "secret-xyz"@@ -337,24 +342,12 @@ async def test_placeholderization_only_replaces_structured_values(monkeypatch):async def fake_completion_async(_prompt):return '{"values": {"api_key": "different-secret"}}'- monkeypatch.setattr(- "openviking.privacy.skill_extractor.get_openviking_config",- lambda: type(- "Cfg",- (),- {- "vlm": type(- "VLM", (), {"get_completion_async": staticmethod(fake_completion_async)}- )()- },- )(),- )-content = 'api_key: "secret-xyz"\n'result = await extract_skill_privacy_values(skill_name="unmatched-skill",skill_description="skill with secret",content=content,+ vlm=type("VLM", (), {"get_completion_async": staticmethod(fake_completion_async)})(),)assert result.values == {}diff --git a/tests/server/test_server_health.py b/tests/server/test_server_health.pyindex 003133cb5..f8c6cb846 100644--- a/tests/server/test_server_health.py+++ b/tests/server/test_server_health.py@@ -288,6 +288,7 @@ async def test_ready_returns_200_after_initialized(monkeypatch):class MockService:_initialized = True+ embedding_provider = object()service = MockService()monkeypatch.setattr("openviking.server.dependencies._service", service)diff --git a/tests/session/memory/test_memory_react_system_prompt.py b/tests/session/memory/test_memory_react_system_prompt.pyindex 40343bf63..0bbeee9a7 100644--- a/tests/session/memory/test_memory_react_system_prompt.py+++ b/tests/session/memory/test_memory_react_system_prompt.py@@ -4,11 +4,36 @@Test that provider instruction correctly instructs LLM."""+from types import SimpleNamespace++import pytest+from openviking.message import ImagePart, Message, TextPart, ToolPartfrom openviking.session.memory.session_extract_context_provider import SessionExtractContextProviderfrom openviking.session.memory.vision_message_normalizer import IMAGE_DESCRIPTION_PROMPT[email protected](autouse=True)+def _runtime_config(monkeypatch):+ config = SimpleNamespace(+ output_language_override="",+ language_fallback="en",+ memory=SimpleNamespace(+ eager_prefetch=False,+ prefetch_search_topn=5,+ link_enabled=False,+ ),+ )+ monkeypatch.setattr(+ "openviking.session.memory.session_extract_context_provider.get_openviking_config",+ lambda: config,+ )+ monkeypatch.setattr(+ "openviking.session.memory.utils.language.get_openviking_config",+ lambda: config,+ )++class TestProviderInstruction:"""Test the provider instruction contains correct instructions."""@@ -261,6 +286,9 @@ class TestSessionConversationToolFiltering:def __init__(self):self.messages = None+ def is_available(self):+ return True+async def get_vision_completion_async(self, **kwargs):self.messages = kwargs.get("messages")return "A high level image description."@@ -275,9 +303,11 @@ class TestSessionConversationToolFiltering:],)]- provider = SessionExtractContextProvider(messages=messages)fake_vlm = FakeVisionVLM()- provider._vision_vlm = fake_vlm+ provider = SessionExtractContextProvider(+ messages=messages,+ vlm_config=fake_vlm,+ )await provider.prepare_extraction_messages()prompt_message = provider._build_conversation_message()@@ -313,8 +343,10 @@ class TestSessionConversationToolFiltering:parts=[ImagePart(url="https://example.com/private-family-photo.png")],)]- provider = SessionExtractContextProvider(messages=messages)- provider._vision_vlm = None+ provider = SessionExtractContextProvider(+ messages=messages,+ vlm_config=SimpleNamespace(is_available=lambda: False),+ )await provider.prepare_extraction_messages()prompt_message = provider._build_conversation_message()@@ -333,8 +365,10 @@ class TestSessionConversationToolFiltering:],)]- provider = SessionExtractContextProvider(messages=messages)- provider._vision_vlm = None+ provider = SessionExtractContextProvider(+ messages=messages,+ vlm_config=SimpleNamespace(is_available=lambda: False),+ )await provider.prepare_extraction_messages()prompt_message = provider._build_conversation_message()@@ -354,8 +388,10 @@ class TestSessionConversationToolFiltering:],)]- provider = SessionExtractContextProvider(messages=messages)- provider._vision_vlm = None+ provider = SessionExtractContextProvider(+ messages=messages,+ vlm_config=SimpleNamespace(is_available=lambda: False),+ )await provider.prepare_extraction_messages()diff --git a/tests/session/memory/test_streaming_memory_updater.py b/tests/session/memory/test_streaming_memory_updater.pyindex 1b9236d1c..b24fab812 100644--- a/tests/session/memory/test_streaming_memory_updater.py+++ b/tests/session/memory/test_streaming_memory_updater.py@@ -4,6 +4,7 @@from __future__ import annotationsimport asyncio+from types import SimpleNamespacefrom unittest.mock import AsyncMockimport pytest@@ -44,6 +45,35 @@ from openviking_cli.exceptions import ConflictErrorfrom openviking_cli.session.user_id import UserIdentifier+class _TestVLMResolver:+ model = "test-model"+ max_tokens = None++ async def get_vlm(self, account_id):+ del account_id+ return self+++def _patch_language_config(monkeypatch):+ config = SimpleNamespace(+ output_language_override="",+ language_fallback="en",+ memory=SimpleNamespace(+ eager_prefetch=False,+ prefetch_search_topn=5,+ link_enabled=False,+ ),+ )+ monkeypatch.setattr(+ "openviking.session.memory.utils.language.get_openviking_config",+ lambda: config,+ )+ monkeypatch.setattr(+ "openviking.session.memory.session_extract_context_provider.get_openviking_config",+ lambda: config,+ )++class InMemoryVikingFS:def __init__(self, files: dict[str, str] | None = None):self.files = dict(files or {})@@ -1630,6 +1660,7 @@ async def test_render_operation_after_file_content_persists_source_trace_id():@pytest.mark.asyncioasync def test_cross_extraction_merge_preserves_existing_uri_without_explicit_delete(monkeypatch):+ _patch_language_config(monkeypatch)existing_uri = "viking://user/u/memories/notes/existing.md"winner_uri = "viking://user/u/memories/notes/winner.md"old_file = __import__(@@ -1662,6 +1693,7 @@ async def test_cross_extraction_merge_preserves_existing_uri_without_explicit_de)async def fake_run(self):+ assert isinstance(self.context_provider._vlm_config, _TestVLMResolver)return (ResolvedOperations(upsert_operations=[new_op],@@ -1692,6 +1724,7 @@ async def test_cross_extraction_merge_preserves_existing_uri_without_explicit_demessages=[],ctx=_ctx(),registry=_registry(),+ vlm_resolver=_TestVLMResolver(),)assert [op.uris for op in merged.upsert_operations] == [[winner_uri]]@@ -1700,12 +1733,14 @@ async def test_cross_extraction_merge_preserves_existing_uri_without_explicit_de@pytest.mark.asyncioasync def test_force_merge_sends_delete_only_group_through_patch_merge(monkeypatch):+ _patch_language_config(monkeypatch)delete_file = _note_delete_file("obsolete")replacement_uri = "viking://user/u/memories/notes/replacement.md"merge_called = Falseasync def fake_run(self):nonlocal merge_called+ assert isinstance(self.context_provider._vlm_config, _TestVLMResolver)merge_called = Truereturn (ResolvedOperations(@@ -1738,6 +1773,7 @@ async def test_force_merge_sends_delete_only_group_through_patch_merge(monkeypatctx=_ctx(),registry=_registry(),force_merge=True,+ vlm_resolver=_TestVLMResolver(),)assert merge_called is True@@ -1769,6 +1805,7 @@ async def test_force_merge_does_not_drop_add_only_delete():@pytest.mark.asyncioasync def test_patch_merge_uses_original_messages_for_output_language(monkeypatch):+ _patch_language_config(monkeypatch)existing_uri = "viking://user/u/memories/notes/code.md"old_file = MemoryFile(uri=existing_uri,@@ -1791,6 +1828,7 @@ async def test_patch_merge_uses_original_messages_for_output_language(monkeypatccaptured_languages = []async def fake_run(self):+ assert isinstance(self.context_provider._vlm_config, _TestVLMResolver)captured_languages.append(self.context_provider.get_output_language())return (ResolvedOperations(@@ -1822,6 +1860,7 @@ async def test_patch_merge_uses_original_messages_for_output_language(monkeypatcmessages=[Message(id="m1", role="user", parts=[TextPart("请保持中文记忆")])],ctx=_ctx(),registry=_registry(),+ vlm_resolver=_TestVLMResolver(),)assert captured_languages == ["zh-CN"]diff --git a/tests/session/test_commit_skill_inference.py b/tests/session/test_commit_skill_inference.pyindex 1e48b348a..6aec50f28 100644--- a/tests/session/test_commit_skill_inference.py+++ b/tests/session/test_commit_skill_inference.py@@ -380,7 +380,10 @@ tags:viking_fs._async_agfs.pathlock_acquire_tree = AsyncMock(return_value={"lease_ref": "test"})viking_fs._async_agfs.pathlock_release = AsyncMock()- async def _fake_extract_skill_privacy_values(*, skill_name, skill_description, content):+ async def _fake_extract_skill_privacy_values(+ *, skill_name, skill_description, content, vlm+ ):+ assert vlm is account_vlmassert skill_name == "code-review"assert skill_description == "Review code from evidence"assert "api_key=secret-xyz" in content@@ -401,9 +404,12 @@ tags:privacy_config_service.upsert = AsyncMock()vikingdb = MagicMock()vikingdb.enqueue_embedding_msg = AsyncMock(return_value=True)+ account_vlm = object()+ vlm_resolver = SimpleNamespace(get_vlm=AsyncMock(return_value=account_vlm))processor = SkillProcessor(vikingdb=vikingdb,privacy_config_service=privacy_config_service,+ vlm_resolver=vlm_resolver,)processor._write_skill_content = AsyncMock()processor._enqueue_skill_package = AsyncMock()diff --git a/tests/session/train/test_gradient_estimator_component.py b/tests/session/train/test_gradient_estimator_component.pyindex 92546f855..79bf59356 100644--- a/tests/session/train/test_gradient_estimator_component.py+++ b/tests/session/train/test_gradient_estimator_component.py@@ -3,9 +3,10 @@from __future__ import annotations+import asynciofrom types import SimpleNamespace+from unittest.mock import AsyncMock-import asyncioimport pytestfrom openviking.session.memory.dataclass import MemoryFile@@ -251,10 +252,14 @@ async def test_experience_gradient_estimator_runs_extract_loop(monkeypatch):monkeypatch.setattr(gradient_estimator_module, "MemoryIsolationHandler", FakeIsolationHandler)monkeypatch.setattr(gradient_estimator_module, "ExtractLoop", FakeExtractLoop)+ vlm = SimpleNamespace(model="account-model")+ resolver = SimpleNamespace(get_vlm=AsyncMock(return_value=vlm))estimator = ExperienceGradientEstimator(- viking_fs=SimpleNamespace(), vlm=SimpleNamespace()+ viking_fs=SimpleNamespace(),+ vlm_resolver=resolver,)context = _context()+ context.request_context.account_id = "account-a"gradients = await estimator.estimate(analysis, _experience_set(), context)@@ -263,8 +268,11 @@ async def test_experience_gradient_estimator_runs_extract_loop(monkeypatch):"messages": context.messages,"trajectory_summary": analysis.trajectories[0].content,"trajectory_uri": analysis.trajectories[0].uri,+ "vlm_config": vlm,}+ resolver.get_vlm.assert_awaited_once_with(context.request_context.account_id)assert captured["request_context"] is context.request_contextassert captured["allowed_memory_types"] == {"experiences"}assert captured["prepare_messages_called"] is True+ assert captured["extract_loop_kwargs"]["vlm"] is vlmassert captured["extract_loop_kwargs"]["context_provider"]._isolation_handler is not Nonediff --git a/tests/session/train/test_trajectory_analyzer_component.py b/tests/session/train/test_trajectory_analyzer_component.pyindex 5cbb84d45..4bfcddae4 100644--- a/tests/session/train/test_trajectory_analyzer_component.py+++ b/tests/session/train/test_trajectory_analyzer_component.py@@ -22,6 +22,32 @@ from openviking.session.train.components.trajectory_analyzer import ()+def _patch_runtime_defaults(monkeypatch):+ config = SimpleNamespace(+ output_language_override="",+ language_fallback="en",+ memory=SimpleNamespace(+ eager_prefetch=False,+ prefetch_search_topn=5,+ link_enabled=False,+ custom_templates_dir=None,+ experimental_memory_switch=False,+ ),+ )+ monkeypatch.setattr(+ "openviking.session.memory.utils.language.get_openviking_config",+ lambda: config,+ )+ monkeypatch.setattr(+ "openviking.session.memory.session_extract_context_provider.get_openviking_config",+ lambda: config,+ )+ monkeypatch.setattr(+ "openviking_cli.utils.config.get_openviking_config",+ lambda: config,+ )++class FakeExtractLoop:created = []@@ -143,12 +169,23 @@ def _rollout() -> Rollout:async def test_trajectory_rollout_analyzer_extracts_and_persists_trajectory(monkeypatch):from openviking.session.train.components import trajectory_analyzer as module+ _patch_runtime_defaults(monkeypatch)FakeExtractLoop.created.clear()fs = FakeVikingFS()+ account_vlm = SimpleNamespace(+ model="account-vlm",+ get_vlm_instance=lambda: SimpleNamespace(model="account-vlm"),+ )++ class FakeResolver:+ async def get_vlm(self, account_id):+ assert account_id == "default"+ return account_vlm+monkeypatch.setattr(module, "ExtractLoop", FakeExtractLoop)monkeypatch.setattr(module, "get_viking_fs", lambda: fs)- analyzer = TrajectoryRolloutAnalyzer(viking_fs=fs, vlm=SimpleNamespace(model="fake"))+ analyzer = TrajectoryRolloutAnalyzer(viking_fs=fs, vlm_resolver=FakeResolver())context = TrajectoryAnalyzerContext(request_context=SimpleNamespace(user=SimpleNamespace(account_id="default", user_id="u"),@@ -181,6 +218,7 @@ async def test_trajectory_rollout_analyzer_extracts_and_persists_trajectory(monkassert created_loop._transaction_handle is Noneprovider = created_loop.kwargs["context_provider"]assert provider._transaction_handle is None+ assert provider._vlm_config is account_vlmassert [schema.memory_type for schema in provider.get_memory_schemas(context.request_context)] == ["trajectories"]@@ -211,6 +249,7 @@ async def test_trajectory_rollout_analyzer_extracts_skill_without_persisting_tra):from openviking.session.train.components import trajectory_analyzer as module+ _patch_runtime_defaults(monkeypatch)FakeExtractLoop.created.clear()fs = FakeVikingFS()monkeypatch.setattr(module, "ExtractLoop", FakeSkillOnlyExtractLoop)@@ -244,6 +283,7 @@ async def test_trajectory_rollout_analyzer_extracts_skill_without_persisting_traasync def test_trajectory_rollout_analyzer_evaluates_before_extracting_trajectory(monkeypatch):from openviking.session.train.components import trajectory_analyzer as module+ _patch_runtime_defaults(monkeypatch)FakeExtractLoop.created.clear()fs = FakeVikingFS()evaluator = FakeRolloutEvaluator()diff --git a/tests/storage/test_bulk_upsert.py b/tests/storage/test_bulk_upsert.pyindex 4702767b3..a188ae12a 100644--- a/tests/storage/test_bulk_upsert.py+++ b/tests/storage/test_bulk_upsert.py@@ -5,6 +5,7 @@ import asyncioimport threadingimport uuidfrom types import SimpleNamespace+from unittest.mock import AsyncMockimport pytest@@ -25,6 +26,15 @@ def make_backend(adapter):)+class _BorrowableBackend(_SingleAccountBackend):+ def __init__(self):+ super().__init__(+ VectorDBBackendConfig(backend="local", name="context", dimension=4),+ bound_account_id="acc1",+ shared_adapter=SimpleNamespace(mode="local"),+ )++@pytest.mark.asyncioasync def test_single_account_backend_upsert_many_uses_one_adapter_call():calls = []@@ -186,6 +196,7 @@ async def test_single_account_backend_upsert_many_rejects_invalid_adapter_result@pytest.mark.asyncioasync def test_viking_vector_index_backend_upsert_many_delegates_once():backend = object.__new__(VikingVectorIndexBackend)+ backend.acl_manager = Nonectx = SimpleNamespace(account_id="acc1")records = [{"id": "rec-1"}, {"id": "rec-2"}]calls = []@@ -195,7 +206,7 @@ async def test_viking_vector_index_backend_upsert_many_delegates_once():calls.append(data_list)return [row["id"] for row in data_list]- backend._get_backend_for_context = lambda _ctx: _BoundBackend()+ backend._get_backend_for_context = AsyncMock(return_value=_BoundBackend())assert await backend.upsert_many(records, ctx=ctx) == ["rec-1", "rec-2"]assert calls == [records]@@ -207,7 +218,7 @@ async def test_viking_vector_index_backend_bulk_ingest_balances_scope_on_error()ctx = SimpleNamespace(account_id="acc1")calls = []- class _BoundBackend:+ class _BoundBackend(_BorrowableBackend):async def begin_bulk_ingest(self):calls.append("begin")@@ -215,7 +226,7 @@ async def test_viking_vector_index_backend_bulk_ingest_balances_scope_on_error()calls.append("end")bound_backend = _BoundBackend()- backend._get_backend_for_context = lambda _ctx: bound_backend+ backend._get_backend_for_context = AsyncMock(return_value=bound_backend)with pytest.raises(RuntimeError, match="injected"):async with backend.bulk_ingest(ctx=ctx):@@ -234,7 +245,7 @@ async def test_bulk_ingest_cancellation_during_threaded_begin_balances_scope():begin_finished = threading.Event()calls = []- class _BoundBackend:+ class _BoundBackend(_BorrowableBackend):async def begin_bulk_ingest(self):def blocking_begin():begin_started.set()@@ -247,7 +258,8 @@ async def test_bulk_ingest_cancellation_during_threaded_begin_balances_scope():async def end_bulk_ingest(self):calls.append("end")- backend._get_backend_for_context = lambda _ctx: _BoundBackend()+ bound_backend = _BoundBackend()+ backend._get_backend_for_context = AsyncMock(return_value=bound_backend)async def enter_scope():async with backend.bulk_ingest(ctx=ctx):@@ -264,6 +276,7 @@ async def test_bulk_ingest_cancellation_during_threaded_begin_balances_scope():with pytest.raises(asyncio.CancelledError):await taskassert calls == ["begin", "end"]+ assert not bound_backend._operationsfinally:allow_begin.set()if not task.done():@@ -280,7 +293,7 @@ async def test_bulk_ingest_cancellation_during_threaded_end_waits_for_cleanup():end_finished = threading.Event()calls = []- class _BoundBackend:+ class _BoundBackend(_BorrowableBackend):async def begin_bulk_ingest(self):calls.append("begin")@@ -293,7 +306,8 @@ async def test_bulk_ingest_cancellation_during_threaded_end_waits_for_cleanup():await asyncio.to_thread(blocking_end)- backend._get_backend_for_context = lambda _ctx: _BoundBackend()+ bound_backend = _BoundBackend()+ backend._get_backend_for_context = AsyncMock(return_value=bound_backend)async def use_scope():async with backend.bulk_ingest(ctx=ctx):@@ -311,6 +325,7 @@ async def test_bulk_ingest_cancellation_during_threaded_end_waits_for_cleanup():with pytest.raises(asyncio.CancelledError):await taskassert calls == ["begin", "body", "end"]+ assert not bound_backend._operationsfinally:allow_end.set()if not task.done():@@ -329,6 +344,11 @@ async def test_viking_vector_index_backend_upsert_many_persists_batch(tmp_path):path=str(tmp_path),))+ backend.set_vector_config_resolver(+ SimpleNamespace(resolve=AsyncMock(return_value=SimpleNamespace(+ dedicated_vectordb=False, vectordb=backend._config,+ )))+ )ctx = RequestContext(user=UserIdentifier("acc1", "user1"), role=Role.USER)schema = {"CollectionName": collection_name,diff --git a/tests/storage/test_collection_schemas.py b/tests/storage/test_collection_schemas.pyindex aed262f89..805262634 100644--- a/tests/storage/test_collection_schemas.py+++ b/tests/storage/test_collection_schemas.py@@ -5,7 +5,9 @@ import hashlibimport inspectimport jsonimport logging+import threadingfrom types import SimpleNamespace+from unittest.mock import AsyncMockimport pytestimport requests@@ -15,10 +17,12 @@ from openviking.server.identity import RequestContext, Role, UserIdentifierfrom openviking.service.resource_service import ResourceServicefrom openviking.storage.collection_schemas import (CollectionSchemas,- TextEmbeddingHandler,_build_embedding_metadata,init_context_collection,)+from openviking.storage.collection_schemas import (+ TextEmbeddingHandler as ProductionTextEmbeddingHandler,+)from openviking.storage.errors import (ConnectionError,EmbeddingRebuildRequiredError,@@ -55,6 +59,43 @@ from openviking_cli.utils.config.vectordb_config import ()+class TextEmbeddingHandler(ProductionTextEmbeddingHandler):+ """Inject account resources into the existing worker behavior tests."""++ def __init__(self, vikingdb):+ from openviking.config.embedding import AccountEmbeddingProvider+ from openviking.config.vector import AccountVectorConfigResolver, VectorRuntimeSettings+ from openviking_cli.utils.config import get_openviking_config+ from openviking_cli.utils.config.embedding_config import EmbeddingConfig++ config = get_openviking_config()+ embedding = EmbeddingConfig(+ dense={"provider": "openai", "model": "test", "api_key": "test", "dimension": 2},+ max_input_tokens=max(100, config.embedding.max_input_tokens),+ circuit_breaker=vars(config.embedding.circuit_breaker),+ )+ settings = VectorRuntimeSettings(+ embedding, VectorDBBackendConfig(dimension=2), "test", False+ )+ manager = SimpleNamespace(+ add_update_consumer=lambda **kwargs: None,+ resolve_account=AsyncMock(return_value=settings),+ )+ # Factory is injected on this test's effective model only.+ object.__setattr__(embedding, "get_embedder", config.embedding.get_embedder)+ provider = AccountEmbeddingProvider(AccountVectorConfigResolver(manager), manager)+ vikingdb.account_uses_content_field = AsyncMock(+ return_value=getattr(+ vikingdb, "uses_content_field",+ config.storage.vectordb.backend in {"volcengine", "vikingdb"},+ )+ )+ super().__init__(vikingdb, provider)++ async def breaker(self):+ return (await self._embedding_provider._resource_for("default")).breaker++class _DummyEmbedder:def __init__(self):self.calls = 0@@ -70,6 +111,9 @@ class _DummyEmbedder:async def embed_async(self, text: str, is_query: bool = False) -> EmbedResult:return self.embed(text, is_query=is_query)+ def close(self):+ pass+class _DummyConfig:def __init__(@@ -563,7 +607,7 @@ async def test_embedding_handler_skips_noop_action_without_vector_db_or_embedderdef __getattr__(self, name):raise AssertionError(f"noop must not call {name}")- handler = TextEmbeddingHandler(_NoopVikingDB())+ handler = ProductionTextEmbeddingHandler(_NoopVikingDB())msg = EmbeddingMsg(message=None,context_data={"account_id": "acct", "uri": "viking://resources/repo"},@@ -575,7 +619,8 @@ async def test_embedding_handler_skips_noop_action_without_vector_db_or_embedderassert result.outcome is ProcessOutcome.SUCCESS-def test_embedding_handler_builds_circuit_breaker_from_config(monkeypatch):+async def test_embedding_handler_builds_circuit_breaker_from_config(monkeypatch):class _DummyVikingDB:is_closing = False@@ -593,9 +638,10 @@ def test_embedding_handler_builds_circuit_breaker_from_config(monkeypatch):handler = TextEmbeddingHandler(_DummyVikingDB())- assert handler._circuit_breaker._failure_threshold == 7- assert handler._circuit_breaker._base_reset_timeout == 60.0- assert handler._circuit_breaker._max_reset_timeout == 600.0+ breaker = await handler.breaker()+ assert breaker._failure_threshold == 7+ assert breaker._base_reset_timeout == 60.0+ assert breaker._max_reset_timeout == 600.0@pytest.mark.asyncio@@ -772,7 +818,7 @@ async def test_embedding_handler_open_breaker_logs_summary_instead_of_per_item_whandler = TextEmbeddingHandler(_QueueingVikingDB())monkeypatch.setattr(- handler._circuit_breaker,+ await handler.breaker(),"check",lambda: (_ for _ in ()).throw(CircuitBreakerOpen("open")),)@@ -790,7 +836,9 @@ async def test_embedding_handler_open_breaker_logs_summary_instead_of_per_item_wcollection_schemas.logger.removeHandler(caplog.handler)warnings = [record.message for record in caplog.records if record.levelno == logging.WARNING]- assert warnings.count("Embedding circuit breaker is open; re-enqueueing messages") == 1+ assert warnings.count(+ "Embedding circuit breaker is open; re-enqueueing messages account=default"+ ) == 1for result in (first_result, second_result):assert result.outcome is ProcessOutcome.REQUEUEDassert result.value is None@@ -835,7 +883,7 @@ async def test_embedding_auth_error_fails_terminally_without_reenqueue(monkeypat"(uri=viking://resources/sample)")assert vikingdb.enqueued == [] # terminal: not re-enqueued- handler._circuit_breaker.check() # breaker not tripped (would raise if open)+ (await handler.breaker()).check() # breaker not tripped (would raise if open)@pytest.mark.asyncio@@ -916,6 +964,7 @@ async def test_embedding_handler_materialize_content_read_failure_is_not_hidden("embedding text",{"uri": "viking://resources/missing.txt",+ "account_id": "default","abstract": "abstract fallback","is_leaf": True,"context_type": "resource",@@ -941,7 +990,7 @@ async def test_embedding_handler_materialize_content_keeps_inline(monkeypatch):handler = TextEmbeddingHandler(_DummyVikingDB())msg = EmbeddingMsg("already inline",- {"abstract": "abstract fallback", "is_leaf": False},+ {"abstract": "abstract fallback", "is_leaf": False, "account_id": "default"},)ctx = RequestContext(user=UserIdentifier("default", "default"), role=Role.ROOT)@@ -1069,7 +1118,7 @@ async def test_embedding_handler_drops_input_too_large_without_requeue(monkeypat"(uri=viking://resources/sample)")assert vikingdb.enqueued == []- assert handler._circuit_breaker._failure_count == 0+ assert (await handler.breaker())._failure_count == 0@pytest.mark.asyncio@@ -1913,11 +1962,14 @@ async def test_single_account_backend_upsert_runs_adapter_in_threadpool(monkeypa@pytest.mark.asyncio-async def test_single_account_backend_update_runs_adapter_in_threadpool(monkeypatch):+async def test_single_account_backend_update_runs_adapter_in_threadpool():calls = []+ event_loop_thread = threading.get_ident()+ adapter_threads = []class _Collection:def get_meta_data(self):+ adapter_threads.append(threading.get_ident())return {"Fields": [{"FieldName": "id"},@@ -1935,16 +1987,10 @@ async def test_single_account_backend_update_runs_adapter_in_threadpool(monkeypareturn _Collection()def update_data(self, data):+ adapter_threads.append(threading.get_ident())+ calls.append(data)return [data[0]["id"]]- async def _fake_to_thread(func, /, *args, **kwargs):- calls.append((func.__name__, args, kwargs))- return func(*args, **kwargs)-- monkeypatch.setattr(- "openviking.storage.viking_vector_index_backend.asyncio.to_thread", _fake_to_thread- )-backend = _SingleAccountBackend(config=VectorDBBackendConfig(backend="local", name="context", dimension=2),bound_account_id="acc1",@@ -1966,8 +2012,9 @@ async def test_single_account_backend_update_runs_adapter_in_threadpool(monkeypaassert result.updated_count == 1assert result.error_code is Noneassert result.error_message is None- assert [call[0] for call in calls] == ["_prepare_update_payload", "update_data"]- assert calls[-1][1] == (+ assert len(adapter_threads) == 2+ assert all(thread_id != event_loop_thread for thread_id in adapter_threads)+ assert calls == [[{"id": "rec-1",@@ -1976,7 +2023,7 @@ async def test_single_account_backend_update_runs_adapter_in_threadpool(monkeypa"account_id": "acc1",}],- )+ ]@pytest.mark.asyncio@@ -2028,11 +2075,13 @@ async def test_single_account_backend_partial_update_does_not_fill_omitted_text_@pytest.mark.asyncio-async def test_local_backend_update_preserves_omitted_fields_end_to_end(tmp_path):+async def test_local_backend_update_preserves_omitted_fields_end_to_end(+ vector_backend_factory, tmp_path+):if not getattr(vectordb_engine, "PersistStore", None):pytest.skip("local persistent vectordb engine is not available in this environment")- backend = VikingVectorIndexBackend(+ backend = vector_backend_factory(config=VectorDBBackendConfig(backend="local",name="context",@@ -2085,11 +2134,13 @@ async def test_local_backend_update_preserves_omitted_fields_end_to_end(tmp_path@pytest.mark.asyncio-async def test_local_backend_update_can_clear_string_field_end_to_end(tmp_path):+async def test_local_backend_update_can_clear_string_field_end_to_end(+ vector_backend_factory, tmp_path+):if not getattr(vectordb_engine, "PersistStore", None):pytest.skip("local persistent vectordb engine is not available in this environment")- backend = VikingVectorIndexBackend(+ backend = vector_backend_factory(config=VectorDBBackendConfig(backend="local",name="context",@@ -2624,8 +2675,10 @@ async def test_single_account_backend_upsert_without_partial_update_keeps_legacy@pytest.mark.asyncio-async def test_viking_vector_index_backend_upsert_partial_update_delegates_to_account_backend():- backend = VikingVectorIndexBackend(+async def test_viking_vector_index_backend_upsert_partial_update_delegates_to_account_backend(+ vector_backend_factory,+):+ backend = vector_backend_factory(config=VectorDBBackendConfig(backend="local", name="context", dimension=2))ctx = SimpleNamespace(account_id="acc1")@@ -2636,7 +2689,7 @@ async def test_viking_vector_index_backend_upsert_partial_update_delegates_to_accalls.append((data, options))return data["id"]- backend._get_backend_for_context = lambda _ctx: _BoundBackend()+ backend._get_backend_for_context = AsyncMock(return_value=_BoundBackend())result = await backend.upsert({"id": "rec-1", "abstract": "patched"},@@ -3098,38 +3151,38 @@ async def test_update_search_tags_with_levels_rejects_invalid_mode_before_filter@pytest.mark.asyncio-async def test_single_account_backend_mutations_run_adapter_in_threadpool(monkeypatch):+async def test_single_account_backend_mutations_run_adapter_in_threadpool():calls = []+ event_loop_thread = threading.get_ident()++ def record(name, kwargs=None):+ assert threading.get_ident() != event_loop_thread+ calls.append((name, kwargs))class _Adapter:mode = "local"USE_CONTENT_FIELD = Falsedef drop_collection(self):+ record("drop_collection")return Truedef delete(self, **kwargs):- calls.append(("adapter_delete_kwargs", kwargs))+ record("delete", kwargs)return 2def count(self, **kwargs):- calls.append(("adapter_count_kwargs", kwargs))+ record("count", kwargs)return 3def clear(self):+ record("clear")return Truedef close(self):+ record("close")return None- async def _fake_to_thread(func, /, *args, **kwargs):- calls.append((func.__name__, args, kwargs))- return func(*args, **kwargs)-- monkeypatch.setattr(- "openviking.storage.viking_vector_index_backend.asyncio.to_thread", _fake_to_thread- )-backend = _SingleAccountBackend(config=VectorDBBackendConfig(backend="local", name="context", dimension=2),bound_account_id=None,@@ -3144,7 +3197,7 @@ async def test_single_account_backend_mutations_run_adapter_in_threadpool(monkeyassert await backend.clear() is Trueawait backend.close()- assert [call[0] for call in calls if not call[0].startswith("adapter_")] == [+ assert [call[0] for call in calls] == ["drop_collection","delete","delete",diff --git a/tests/storage/test_context_update_plan.py b/tests/storage/test_context_update_plan.pyindex 18cbe2f14..2d2869550 100644--- a/tests/storage/test_context_update_plan.py+++ b/tests/storage/test_context_update_plan.py@@ -3454,7 +3454,8 @@ async def test_semantic_processor_runs_only_plan_execution_roots(monkeypatch):"openviking.storage.queuefs.semantic_processor.SemanticLockScope.resolve",AsyncMock(return_value=SimpleNamespace(lock=None, close=AsyncMock())),)- processor = SemanticProcessor()+ resolver = SimpleNamespace(get_vlm=AsyncMock())+ processor = SemanticProcessor(vlm_resolver=resolver)processor._cleanup_local_artifact = AsyncMock()msg = SemanticMsg(uri=root,diff --git a/tests/storage/test_embedding_msg.py b/tests/storage/test_embedding_msg.pyindex a9f45b1c3..bb5a1865f 100644--- a/tests/storage/test_embedding_msg.py+++ b/tests/storage/test_embedding_msg.py@@ -24,7 +24,7 @@ def test_embedding_msg_roundtrip_preserves_id_for_request_wait_tracker():try:msg = EmbeddingMsg("hello",- {"uri": "viking://user/default/skills/demo"},+ {"uri": "viking://user/default/skills/demo", "account_id": "default"},telemetry_id=telemetry_id,)tracker.register_embedding_root(telemetry_id, msg.id)@@ -41,26 +41,29 @@ def test_embedding_msg_roundtrip_preserves_id_for_request_wait_tracker():def test_embedding_msg_roundtrip_preserves_queue_enqueue_time():msg = EmbeddingMsg("hello",- {"uri": "viking://resources/demo"},+ {"uri": "viking://resources/demo", "account_id": "default"},queue_enqueued_at=123.456,)assert EmbeddingMsg.from_dict(msg.to_dict()).queue_enqueued_at == 123.456-def test_legacy_embedding_msg_defaults_to_embed_and_upsert():- restored = EmbeddingMsg.from_dict(- {- "message": "hello",- "context_data": {"uri": "viking://resources/demo"},- }- )-- assert restored.action is IndexAction.UPSERT+def test_legacy_embedding_msg_without_account_id_is_rejected():+ with pytest.raises(ValueError, match="account_id"):+ EmbeddingMsg.from_dict(+ {+ "message": "hello",+ "context_data": {"uri": "viking://resources/demo"},+ }+ )def test_embedding_msg_accepts_noop_index_action_roundtrip():- msg = EmbeddingMsg(None, {"uri": "viking://resources/demo"}, action=IndexAction.NONE)+ msg = EmbeddingMsg(+ None,+ {"uri": "viking://resources/demo", "account_id": "default"},+ action=IndexAction.NONE,+ )restored = EmbeddingMsg.from_json(msg.to_json())@@ -160,7 +163,7 @@ def test_field_patch_roundtrip_and_resolution():(EmbeddingMsg.for_embed(message="body",- context_data={"uri": "viking://resources/demo/a.py"},+ context_data={"uri": "viking://resources/demo/a.py", "account_id": "default"},),EmbedPayload,),@@ -168,18 +171,23 @@ def test_field_patch_roundtrip_and_resolution():EmbeddingMsg.for_update_fields(record_id="record-1",field_patch=FieldPatch(values={"md5": "new-md5"}),- context_data={"uri": "viking://resources/demo/a.py"},+ context_data={"uri": "viking://resources/demo/a.py", "account_id": "default"},),UpdateFieldsPayload,),(EmbeddingMsg.for_delete(record_ids=["record-1"],- context_data={"uri": "viking://resources/demo/a.py"},+ context_data={"uri": "viking://resources/demo/a.py", "account_id": "default"},),DeletePayload,),- (EmbeddingMsg.noop(context_data={"uri": "viking://resources/demo"}), NoopPayload),+ (+ EmbeddingMsg.noop(+ context_data={"uri": "viking://resources/demo", "account_id": "default"}+ ),+ NoopPayload,+ ),],)def test_embedding_msg_roundtrip_uses_action_specific_payload(message, payload_type):@@ -196,7 +204,7 @@ def test_embed_payload_rejects_patch_for_upsert():with pytest.raises(ValueError, match="upsert.*field patch"):EmbeddingMsg.for_embed(message="body",- context_data={"uri": "viking://resources/demo/a.py"},+ context_data={"uri": "viking://resources/demo/a.py", "account_id": "default"},action=IndexAction.UPSERT,field_patch=FieldPatch(values={"search_tags": ["scope=new"]}),)@@ -259,7 +267,7 @@ def test_update_fields_factory_rejects_duplicate_patch_representations():with pytest.raises(ValueError, match="field_patch cannot be combined"):EmbeddingMsg.for_update_fields(record_id="record-1",- context_data={"uri": "viking://resources/demo/a.py"},+ context_data={"uri": "viking://resources/demo/a.py", "account_id": "default"},field_patch=FieldPatch({"md5": "new-md5"}),fields={"md5": "ignored-md5"},)@@ -270,7 +278,10 @@ def test_legacy_upsert_discards_historically_ignored_fields():{"action": "upsert","message": "body",- "context_data": {"uri": "viking://resources/demo/a.py"},+ "context_data": {+ "uri": "viking://resources/demo/a.py",+ "account_id": "default",+ },"record_ids": ["ignored-record"],"update_fields": {"md5": "ignored-md5"},"initial_fields": {"vector": [0.1, 0.2]},@@ -293,7 +304,10 @@ def test_legacy_update_fields_message_normalizes_to_field_patch_payload():restored = EmbeddingMsg.from_dict({"message": None,- "context_data": {"uri": "viking://resources/demo/a.py"},+ "context_data": {+ "uri": "viking://resources/demo/a.py",+ "account_id": "default",+ },"action": "update_fields","record_ids": ["record-1"],"update_fields": {"search_tags": ["scope=new"]},diff --git a/tests/storage/test_embedding_msg_converter_tenant.py b/tests/storage/test_embedding_msg_converter_tenant.pyindex 6880de097..087bbb1b1 100644--- a/tests/storage/test_embedding_msg_converter_tenant.py+++ b/tests/storage/test_embedding_msg_converter_tenant.py@@ -1,7 +1,7 @@# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.# SPDX-License-Identifier: AGPL-3.0-"""Tenant-field backfill tests for EmbeddingMsgConverter."""+"""Explicit account identity and URI owner tests for EmbeddingMsgConverter."""import pytest@@ -27,14 +27,13 @@ from openviking_cli.session.user_id import UserIdentifier),],)-def test_embedding_msg_converter_backfills_account_and_owner_fields(+def test_embedding_msg_converter_preserves_account_and_backfills_owner_fields(uri, expected_uri, expected_owner_user_id):user = UserIdentifier("acme", "alice")context = Context(uri=uri, abstract="hello", user=user)- # Simulate legacy producer that forgot tenant fields.- context.account_id = ""+ # URI ownership may be derived, but account identity must remain explicit.context.owner_user_id = Nonemsg = EmbeddingMsgConverter.from_context(context)diff --git a/tests/storage/test_memory_semantic_stall.py b/tests/storage/test_memory_semantic_stall.pyindex 158de7062..99979cf56 100644--- a/tests/storage/test_memory_semantic_stall.py+++ b/tests/storage/test_memory_semantic_stall.py@@ -21,6 +21,11 @@ from openviking.telemetry.request_wait_tracker import get_request_wait_trackerfrom openviking.utils.circuit_breaker import CircuitBreakerOpen+def _processor():+ resolver = SimpleNamespace(get_vlm=AsyncMock(return_value=SimpleNamespace()))+ return SemanticProcessor(vlm_resolver=resolver)++def _make_msg(uri="viking://user/usr1/memories", context_type="memory", **kwargs):"""Build a minimal SemanticMsg for testing."""defaults = {@@ -48,7 +53,7 @@ def _build_data(msg: SemanticMsg) -> dict:@pytest.mark.parametrize("context_type", ["resource", "memory", "skill"])async def test_retry_cancellation_keeps_skill_wait_isolated(monkeypatch, context_type):- processor = SemanticProcessor()+ processor = _processor()processor._circuit_breaker = SimpleNamespace(check=MagicMock(side_effect=CircuitBreakerOpen), retry_after=0)@@ -88,7 +93,7 @@ async def test_retry_cancellation_keeps_skill_wait_isolated(monkeypatch, context@pytest.mark.asyncioasync def test_root_semantic_message_is_acknowledged_without_processing():- processor = SemanticProcessor()+ processor = _processor()result = await processor.on_dequeue(_build_data(_make_msg(uri="viking://", context_type="resource"))@@ -102,7 +107,7 @@ async def test_root_semantic_message_is_acknowledged_without_processing():@pytest.mark.asyncioasync def test_memory_empty_dir_still_returns_success():"""An empty memory directory must return a successful processing result."""- processor = SemanticProcessor()+ processor = _processor()fake_fs = MagicMock()fake_fs.exists = AsyncMock(return_value=True)@@ -135,7 +140,7 @@ async def test_memory_ls_error_returns_failed():Uses a real classify_api_error (no mock): FileNotFoundError is classifiedas permanent by the real classifier, so the processor returns FAILED."""- processor = SemanticProcessor()+ processor = _processor()fake_fs = MagicMock()fake_fs.exists = AsyncMock(return_value=True)@@ -170,7 +175,7 @@ async def test_memory_ls_transient_error_requeues():_reenqueue_semantic_msg(), bump requeue_count, and return REQUEUED withouta terminal error."""- processor = SemanticProcessor()+ processor = _processor()fake_fs = MagicMock()fake_fs.exists = AsyncMock(return_value=True)@@ -207,7 +212,7 @@ async def test_memory_write_error_returns_failed():Exercises the write failure path with real classify_api_error: PermissionErroris classified as permanent, so the processor returns FAILED."""- processor = SemanticProcessor()+ processor = _processor()fake_fs = MagicMock()fake_fs.exists = AsyncMock(return_value=True)diff --git a/tests/storage/test_queue_manager.py b/tests/storage/test_queue_manager.pyindex b19fa6530..55d7e79ff 100644--- a/tests/storage/test_queue_manager.py+++ b/tests/storage/test_queue_manager.py@@ -136,12 +136,16 @@ async def test_skill_shutdown_releases_lock_after_embedding_worker_exits(lambda: SimpleNamespace(exists=AsyncMock(return_value=True)),)monkeypatch.setattr(- "openviking.storage.collection_schemas.TextEmbeddingHandler", lambda _: SimpleNamespace()+ "openviking.storage.collection_schemas.TextEmbeddingHandler",+ lambda *_: SimpleNamespace(),)manager = QueueManager(object(), max_concurrent_semantic=concurrency, max_concurrent_embedding=concurrency)manager._poll_interval = 0.001+ manager.set_vlm_resolver(+ SimpleNamespace(get_vlm=AsyncMock(return_value=SimpleNamespace()))+ )manager.setup_standard_queues(object(), start=False)semantic = manager._queues[manager.SEMANTIC]._dequeue_handlermanager._queues = {diff --git a/tests/storage/test_semantic_executor_skip_files.py b/tests/storage/test_semantic_executor_skip_files.pyindex 7e45944c5..02292ed16 100644--- a/tests/storage/test_semantic_executor_skip_files.py+++ b/tests/storage/test_semantic_executor_skip_files.py@@ -53,12 +53,14 @@ class _FakeProcessor:def __init__(self):self.summarized_files = []self.vectorized_files = []+ self.overview_contexts = []async def _generate_single_file_summary(self, file_path, llm_sem=None, ctx=None):self.summarized_files.append(file_path)return {"name": file_path.split("/")[-1], "summary": "summary"}async def _generate_overview(self, dir_uri, file_summaries, children_abstracts, **kwargs):+ self.overview_contexts.append(kwargs.get("ctx"))return "overview"def _normalize_overview_generation(self, overview):@@ -107,6 +109,10 @@ async def test_messages_jsonl_excluded_from_summary(monkeypatch):monkeypatch.setattr("openviking.storage.queuefs.semantic_executor.get_viking_fs", lambda: fake_fs)+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_executor.get_openviking_config",+ lambda: SimpleNamespace(semantic=SimpleNamespace(overview_sample_limit=32)),+ )processor = _FakeProcessor()ctx = RequestContext(user=UserIdentifier("acc1", "user1"), role=Role.USER)@@ -122,6 +128,7 @@ async def test_messages_jsonl_excluded_from_summary(monkeypatch):assert "messages.jsonl" not in summarized_namesassert "notes.txt" in summarized_namesassert "document.pdf" in summarized_names+ assert processor.overview_contexts == [ctx]@pytest.mark.asyncio@@ -141,6 +148,10 @@ async def test_messages_jsonl_excluded_in_subdirectory(monkeypatch):monkeypatch.setattr("openviking.storage.queuefs.semantic_executor.get_viking_fs", lambda: fake_fs)+ monkeypatch.setattr(+ "openviking.storage.queuefs.semantic_executor.get_openviking_config",+ lambda: SimpleNamespace(semantic=SimpleNamespace(overview_sample_limit=32)),+ )processor = _FakeProcessor()ctx = RequestContext(user=UserIdentifier("acc1", "user1"), role=Role.USER)diff --git a/tests/storage/test_semantic_msg_ingest_options.py b/tests/storage/test_semantic_msg_ingest_options.pyindex fdf2235e1..441b6b468 100644--- a/tests/storage/test_semantic_msg_ingest_options.py+++ b/tests/storage/test_semantic_msg_ingest_options.py@@ -1,6 +1,7 @@# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.# SPDX-License-Identifier: AGPL-3.0+from openviking.storage.acl import AclSpec, AclUpdatefrom openviking.storage.queuefs.semantic_msg import SemanticMsgfrom openviking.utils.ingest_options import IngestOptions@@ -48,6 +49,7 @@ def test_semantic_msg_reads_legacy_search_tag_fields():{"uri": "viking://resources/demo","context_type": "resource",+ "account_id": "default","search_tags": ["team=search"],"search_tag_mode": "append",}diff --git a/tests/storage/test_semantic_msg_timestamp.py b/tests/storage/test_semantic_msg_timestamp.pyindex 52ecb3735..314c87e41 100644--- a/tests/storage/test_semantic_msg_timestamp.py+++ b/tests/storage/test_semantic_msg_timestamp.py@@ -46,12 +46,23 @@ def test_to_dict_carries_creation_timestamp():def test_from_dict_preserves_stored_timestamp():msg = SemanticMsg.from_dict(- {"uri": "viking://res/a", "context_type": "resource", "timestamp": 1234567890}+ {+ "uri": "viking://res/a",+ "context_type": "resource",+ "account_id": "default",+ "timestamp": 1234567890,+ })assert msg.timestamp == 1234567890def test_from_dict_without_timestamp_still_gets_fresh_one():- msg = SemanticMsg.from_dict({"uri": "viking://res/a", "context_type": "resource"})+ msg = SemanticMsg.from_dict(+ {+ "uri": "viking://res/a",+ "context_type": "resource",+ "account_id": "default",+ }+ )assert "timestamp" in msg.__dict__assert abs(msg.timestamp - _now_epoch()) <= 5diff --git a/tests/storage/test_semantic_processor_code_routing.py b/tests/storage/test_semantic_processor_code_routing.pyindex 8ae77de0f..b6e2c6bf8 100644--- a/tests/storage/test_semantic_processor_code_routing.py+++ b/tests/storage/test_semantic_processor_code_routing.py@@ -6,12 +6,12 @@ from unittest.mock import AsyncMock, MagicMock, patchimport pytest+from openviking.parse.parsers.code.ast import SkeletonExtractionResultfrom openviking.parse.parsers.constants import (FILE_TYPE_CODE,FILE_TYPE_DOCUMENTATION,FILE_TYPE_OTHER,)-from openviking.parse.parsers.code.ast import SkeletonExtractionResultfrom openviking.parse.parsers.media.utils import get_media_typefrom openviking.storage.queuefs.semantic_processor import SemanticProcessor@@ -26,6 +26,15 @@ def _config(vlm_available: bool = True):return config+class _TestVLMResolver:+ def __init__(self, vlm):+ self._vlm = vlm++ async def get_vlm(self, account_id):+ del account_id+ return self._vlm++async def _generate(extraction=None, vlm_available=True):config = _config(vlm_available)fs = MagicMock()@@ -50,14 +59,18 @@ async def _generate(extraction=None, vlm_available=True):with patches[0], patches[1]:if extraction is None:- result = await SemanticProcessor()._generate_text_summary(+ result = await SemanticProcessor(+ vlm_resolver=_TestVLMResolver(config.vlm)+ )._generate_text_summary("viking://resources/sample.py","sample.py",asyncio.Semaphore(1),)else:with patches[2]:- result = await SemanticProcessor()._generate_text_summary(+ result = await SemanticProcessor(+ vlm_resolver=_TestVLMResolver(config.vlm)+ )._generate_text_summary("viking://resources/sample.py","sample.py",asyncio.Semaphore(1),diff --git a/tests/storage/test_semantic_processor_language.py b/tests/storage/test_semantic_processor_language.pyindex 2dd284cf4..790358ee3 100644--- a/tests/storage/test_semantic_processor_language.py+++ b/tests/storage/test_semantic_processor_language.py@@ -21,6 +21,15 @@ from openviking.session.memory.utils.language import ()+class _TestVLMResolver:+ def __init__(self, vlm):+ self._vlm = vlm++ async def get_vlm(self, account_id):+ del account_id+ return self._vlm++class TestLanguageDetection:"""语言检测功能测试。"""@@ -216,7 +225,9 @@ class TestOverviewGenerationFlow:"openviking.storage.queuefs.semantic_processor.get_openviking_config",return_value=config,):- await SemanticProcessor()._generate_overview(+ await SemanticProcessor(+ vlm_resolver=_TestVLMResolver(config.vlm)+ )._generate_overview("viking://resources/example/client",[{"name": "client.go", "summary": description + "\n" + skeleton}],[],@@ -442,7 +453,7 @@ class TestGenerateTextSummaryOutputLanguage:return_value=mock_config,),):- processor = SemanticProcessor()+ processor = SemanticProcessor(vlm_resolver=_TestVLMResolver(mock_vlm))processor._current_ctx = MagicMock()result = await processor._generate_text_summary(@@ -491,7 +502,7 @@ class TestGenerateTextSummaryOutputLanguage:return_value=mock_config,),):- processor = SemanticProcessor()+ processor = SemanticProcessor(vlm_resolver=_TestVLMResolver(mock_vlm))processor._current_ctx = MagicMock()result = await processor._generate_text_summary(diff --git a/tests/storage/test_semantic_processor_lock_ownership.py b/tests/storage/test_semantic_processor_lock_ownership.pyindex 34a3b0cea..ded8fd46f 100644--- a/tests/storage/test_semantic_processor_lock_ownership.py+++ b/tests/storage/test_semantic_processor_lock_ownership.py@@ -3,6 +3,9 @@from __future__ import annotations+from types import SimpleNamespace+from unittest.mock import AsyncMock+import pytestfrom openviking.storage.queuefs.process_result import ProcessOutcome@@ -10,6 +13,11 @@ from openviking.storage.queuefs.semantic_msg import SemanticMsgfrom openviking.storage.queuefs.semantic_processor import SemanticProcessor+def _processor():+ resolver = SimpleNamespace(get_vlm=AsyncMock(return_value=SimpleNamespace()))+ return SemanticProcessor(vlm_resolver=resolver)++class _FakePathLock:"""Mock for _async_agfs pathlock operations."""@@ -39,7 +47,7 @@ class _FakeVikingFS:@pytest.mark.asyncioasync def test_memory_semantic_directory_does_not_release_borrowed_lock(monkeypatch):- processor = SemanticProcessor()+ processor = _processor()pathlock = _FakePathLock()borrowed_lease = {"id": "borrowed-lock", "owned": False}@@ -64,7 +72,7 @@ async def test_memory_semantic_directory_does_not_release_borrowed_lock(monkeypa@pytest.mark.parametrize("context_type", ["resource", "memory", "skill"])async def test_missing_root_is_acked_before_lock_scope_is_resolved(monkeypatch, context_type):"""Resolving the lock for a deleted root would recreate it to hold lock metadata."""- processor = SemanticProcessor()+ processor = _processor()fs = _FakeVikingFS()async def adopt(handoff):diff --git a/tests/storage/test_semantic_processor_overview_batching.py b/tests/storage/test_semantic_processor_overview_batching.pyindex 4b1239ab6..6a253f062 100644--- a/tests/storage/test_semantic_processor_overview_batching.py+++ b/tests/storage/test_semantic_processor_overview_batching.py@@ -31,6 +31,15 @@ class MergePlaceholderVLM(RecordingVLM):return "[first](viking://input_sample_f1) and [second](viking://input_sample_f2)"+class _TestVLMResolver:+ def __init__(self, vlm):+ self._vlm = vlm++ async def get_vlm(self, account_id):+ del account_id+ return self._vlm++@pytest.mark.asyncioasync def test_children_only_oversized_overview_is_batched(monkeypatch):vlm = RecordingVLM()@@ -56,7 +65,9 @@ async def test_children_only_oversized_overview_is_batched(monkeypatch):)children = [{"name": f"child-{index}", "abstract": "x" * 20} for index in range(3)]- overview = await SemanticProcessor()._generate_overview(+ overview = await SemanticProcessor(+ vlm_resolver=_TestVLMResolver(vlm)+ )._generate_overview("viking://resources/root",file_summaries=[],children_abstracts=children,@@ -95,7 +106,7 @@ async def test_sampled_overview_prompt_describes_full_directory_coverage(monkeypmonkeypatch.setattr(semantic_processor_module, "render_prompt", fake_render_prompt)- await SemanticProcessor()._generate_overview(+ await SemanticProcessor(vlm_resolver=_TestVLMResolver(vlm))._generate_overview("viking://resources/docs_flat",file_summaries=[],children_abstracts=[{"name": "sample", "abstract": "summary"}],@@ -132,7 +143,9 @@ async def test_batched_merge_resolves_placeholders_from_merge_output(monkeypatchlambda _name, values: values["file_summaries"],)- overview = await SemanticProcessor()._generate_overview(+ overview = await SemanticProcessor(+ vlm_resolver=_TestVLMResolver(vlm)+ )._generate_overview("viking://resources/业务 docs",file_summaries=[{"name": "first file.md", "summary": "first summary"},diff --git a/tests/storage/test_semantic_processor_target_preexisting.py b/tests/storage/test_semantic_processor_target_preexisting.pyindex 32ff9c3eb..242c59bf6 100644--- a/tests/storage/test_semantic_processor_target_preexisting.py+++ b/tests/storage/test_semantic_processor_target_preexisting.py@@ -8,6 +8,11 @@ from openviking.storage.queuefs.semantic_processor import SemanticProcessorfrom openviking.storage.viking_fs import SyncDiff+def _processor(**kwargs):+ resolver = SimpleNamespace(get_vlm=AsyncMock(return_value=SimpleNamespace()))+ return SemanticProcessor(vlm_resolver=resolver, **kwargs)++class _FakeVikingFS:async def exists(self, uri, ctx=None):return True@@ -114,7 +119,7 @@ async def test_target_source_syncs_before_semantic_executor(monkeypatch):_FakeTreeExecutor.calls = []_FakeTreeExecutor.runs = []- processor = SemanticProcessor()+ processor = _processor()processor._enqueue_parent_refresh = AsyncMock()processor._sync_topdown_recursive = AsyncMock(return_value=SyncDiff(@@ -160,7 +165,7 @@ async def test_stale_content_write_keeps_file_work_without_directory_aggregation_FakeTreeExecutor.calls = []_FakeTreeExecutor.runs = []- processor = SemanticProcessor()+ processor = _processor()processor._enqueue_parent_refresh = AsyncMock()changed = "viking://resources/wiki/changed.md"msg = SemanticMsg(@@ -200,7 +205,7 @@ async def test_memory_reindex_uses_semantic_executor(monkeypatch, recursive):_FakeTreeExecutor.calls = []_FakeTreeExecutor.runs = []- processor = SemanticProcessor()+ processor = _processor()processor._process_memory_directory = AsyncMock()msg = SemanticMsg(uri="viking://user/alice/memories/preferences",@@ -229,7 +234,7 @@ async def test_memory_trigger_does_not_select_hierarchical_aggregation(monkeypatAsyncMock(return_value=SimpleNamespace(lock=None, close=AsyncMock())),)- processor = SemanticProcessor()+ processor = _processor()processor._process_memory_directory = AsyncMock()msg = SemanticMsg(uri="viking://user/alice/memories/preferences",@@ -244,7 +249,7 @@ async def test_memory_trigger_does_not_select_hierarchical_aggregation(monkeypat@pytest.mark.asyncioasync def test_content_copy_does_not_enqueue_ancestor_refresh(monkeypatch):- processor = SemanticProcessor()+ processor = _processor()plan_refresh = AsyncMock()monkeypatch.setattr("openviking.storage.queuefs.semantic_processor.plan_abstract_overview_refresh",@@ -283,7 +288,7 @@ async def test_sync_wrapper_delegates_to_sync_tree_and_cleans_temp(monkeypatch):AsyncMock(),)- diff = await SemanticProcessor()._sync_topdown_recursive(+ diff = await _processor()._sync_topdown_recursive("viking://temp/import","viking://resources/root",lock=lease,@@ -316,7 +321,7 @@ async def test_sync_wrapper_whole_tree_mv_for_new_target(monkeypatch):AsyncMock(),)- await SemanticProcessor()._sync_topdown_recursive(+ await _processor()._sync_topdown_recursive("viking://temp/import","viking://resources/root",lock=None,@@ -336,7 +341,7 @@ async def test_sync_missing_source_never_touches_target(monkeypatch):)with pytest.raises(FileNotFoundError, match="refusing to sync"):- await SemanticProcessor()._sync_topdown_recursive(+ await _processor()._sync_topdown_recursive("viking://temp/missing","viking://resources/root",lock=None,diff --git a/tests/storage/test_semantic_queue_memory_dedupe.py b/tests/storage/test_semantic_queue_memory_dedupe.pyindex 9109dc156..3f023bc8b 100644--- a/tests/storage/test_semantic_queue_memory_dedupe.py+++ b/tests/storage/test_semantic_queue_memory_dedupe.py@@ -18,6 +18,11 @@ from openviking.storage.queuefs.semantic_processor import SemanticProcessorfrom openviking.storage.queuefs.semantic_queue import SemanticQueue, is_semantic_msg_stale+def _processor(**kwargs):+ resolver = SimpleNamespace(get_vlm=AsyncMock(return_value=SimpleNamespace()))+ return SemanticProcessor(vlm_resolver=resolver, **kwargs)++@pytest.mark.asyncioasync def test_memory_semantic_enqueue_deduped_within_window():mock_agfs = MagicMock()@@ -155,7 +160,7 @@ def _patch_semantic_config(monkeypatch, *, overview_sample_limit=32):async def test_stale_memory_semantic_write_is_success(monkeypatch):pathlock = _FakePathLock()viking_fs = _FakeVikingFS(pathlock)- processor = SemanticProcessor()+ processor = _processor()coalesce_key = f"memory|acc|u|p|viking://user/default/memories/preferences/{uuid4().hex}"with patch.object(NamedQueue, "enqueue", new_callable=AsyncMock):@@ -210,7 +215,7 @@ async def test_stale_memory_semantic_write_is_success(monkeypatch):@pytest.mark.asyncioasync def test_memory_directory_summarizes_all_uncached_files(monkeypatch):- processor = SemanticProcessor(max_concurrent_llm=4)+ processor = _processor(max_concurrent_llm=4)summaries = []async def generate_file_summary(file_path, llm_sem=None, ctx=None):@@ -218,8 +223,10 @@ async def test_memory_directory_summarizes_all_uncached_files(monkeypatch):name = file_path.rsplit("/", 1)[-1]return {"name": name, "summary": f"summary:{name}"}- async def generate_overview(dir_uri, file_summaries, children_abstracts, llm_sem=None):- del dir_uri, children_abstracts, llm_sem+ async def generate_overview(+ dir_uri, file_summaries, children_abstracts, llm_sem=None, **kwargs+ ):+ del dir_uri, children_abstracts, llm_sem, kwargssummaries.extend(file_summaries)return "overview"@@ -256,7 +263,7 @@ async def test_memory_directory_summarizes_all_uncached_files(monkeypatch):@pytest.mark.asyncioasync def test_memory_directory_vectorizes_changed_files_with_generated_summary(monkeypatch):- processor = SemanticProcessor(max_concurrent_llm=4)+ processor = _processor(max_concurrent_llm=4)dir_uri = "viking://user/default/memories/preferences"changed_uri = f"{dir_uri}/first.md"captured_file_vectorize = []@@ -267,8 +274,10 @@ async def test_memory_directory_vectorizes_changed_files_with_generated_summary(name = file_path.rsplit("/", 1)[-1]return {"name": name, "summary": f"summary:{name}", "content": "raw content"}- async def generate_overview(dir_uri, file_summaries, children_abstracts, llm_sem=None):- del dir_uri, children_abstracts, llm_sem+ async def generate_overview(+ dir_uri, file_summaries, children_abstracts, llm_sem=None, **kwargs+ ):+ del dir_uri, children_abstracts, llm_sem, kwargsassert len(captured_file_vectorize) == 1assert all("content" not in summary for summary in file_summaries)return "overview"@@ -327,7 +336,7 @@ async def test_memory_directory_vectorizes_changed_files_with_generated_summary(async def test_memory_directory_skips_vectorization_when_visible_semantics_are_unchanged(monkeypatch,):- processor = SemanticProcessor(max_concurrent_llm=4)+ processor = _processor(max_concurrent_llm=4)vectorize_directory = AsyncMock()vectorize_file = AsyncMock()diff --git a/tests/storage/test_skill_package_cancellation.py b/tests/storage/test_skill_package_cancellation.pyindex e19b7f74a..7b2c3171a 100644--- a/tests/storage/test_skill_package_cancellation.py+++ b/tests/storage/test_skill_package_cancellation.py@@ -174,14 +174,24 @@ async def test_active_skill_embedding_cancel_settles_only_after_write_exit("openviking_cli.utils.config.get_openviking_config", lambda: _DummyConfig(Embedder()))handler = TextEmbeddingHandler(- SimpleNamespace(is_closing=False, uses_content_field=False, upsert=upsert)+ SimpleNamespace(+ is_closing=False,+ uses_content_field=False,+ account_uses_content_field=AsyncMock(return_value=False),+ upsert=upsert,+ ),+ SimpleNamespace(bind=lambda _account_id: Embedder()),)telemetry_id = str(uuid4())tracker = get_request_wait_tracker()tracker.register_request(telemetry_id)msg = EmbeddingMsg("content",- {"uri": "viking://agent/skills/demo/file.md", "context_type": "skill"},+ {+ "uri": "viking://agent/skills/demo/file.md",+ "context_type": "skill",+ "account_id": "acc",+ },telemetry_id=telemetry_id,)tracker.register_embedding_root(telemetry_id, msg.id)@@ -269,7 +279,10 @@ async def test_semantic_cancel_drains_embeddings_before_releasing_package(monkey"openviking.storage.queuefs.semantic_processor.get_viking_fs",lambda: SimpleNamespace(exists=AsyncMock(return_value=True)),)- worker = asyncio.create_task(SemanticProcessor().on_dequeue({"data": msg.to_json()}))+ resolver = SimpleNamespace(get_vlm=AsyncMock())+ worker = asyncio.create_task(+ SemanticProcessor(vlm_resolver=resolver).on_dequeue({"data": msg.to_json()})+ )await asyncio.wait_for(started.wait(), 1)worker.cancel()await asyncio.sleep(0)diff --git a/tests/storage/test_skill_package_semantics.py b/tests/storage/test_skill_package_semantics.pyindex 4c1060179..7acf0d729 100644--- a/tests/storage/test_skill_package_semantics.py+++ b/tests/storage/test_skill_package_semantics.py@@ -60,7 +60,10 @@ async def test_skill_worker_keeps_package_locked_until_embeddings_finish(monkeyp"openviking.storage.queuefs.semantic_processor.get_viking_fs",lambda: SimpleNamespace(exists=AsyncMock(return_value=True)),)- worker = asyncio.create_task(SemanticProcessor().on_dequeue({"data": msg.to_json()}))+ resolver = SimpleNamespace(get_vlm=AsyncMock(return_value=SimpleNamespace()))+ worker = asyncio.create_task(+ SemanticProcessor(vlm_resolver=resolver).on_dequeue({"data": msg.to_json()})+ )await asyncio.wait_for(emitted.wait(), 1)assert locked and not worker.done() and not tracker.is_complete(msg.telemetry_id)# The HTTP timeout cleanup must not release the package while embedding runs.diff --git a/tests/storage/test_transfer_merge_binding.py b/tests/storage/test_transfer_merge_binding.pyindex a95df6274..c011a5400 100644--- a/tests/storage/test_transfer_merge_binding.py+++ b/tests/storage/test_transfer_merge_binding.py@@ -17,7 +17,6 @@ from openviking.storage.collection_schemas import CollectionSchemasfrom openviking.storage.vector_ids import vector_record_idfrom openviking.storage.vectordb import engine as vectordb_enginefrom openviking.storage.viking_fs import VikingFS-from openviking.storage.viking_vector_index_backend import VikingVectorIndexBackendfrom openviking.utils.agfs_utils import RagfsBindingConfig, mount_agfs_backendfrom openviking_cli.exceptions import InvalidArgumentError, PermissionDeniedErrorfrom openviking_cli.session.user_id import UserIdentifier@@ -47,10 +46,10 @@ def root_ctx():@pytest_asyncio.fixture-async def indexed_fs(binding_fs, tmp_path):+async def indexed_fs(vector_backend_factory, binding_fs, tmp_path):if not getattr(vectordb_engine, "PersistStore", None):pytest.skip("local persistent vectordb engine is unavailable")- backend = VikingVectorIndexBackend(+ backend = vector_backend_factory(config=VectorDBBackendConfig(backend="local", name="context", dimension=4, path=str(tmp_path / "vectors"))@@ -95,7 +94,7 @@ async def test_transfer_uses_queries_without_count_or_sort(await fs.write_file_bytes(target_file, b"old", ctx=ctx)await seed_vector(backend, source_file, "new")await seed_vector(backend, target_file, "old")- adapter = backend._get_backend_for_context(ctx)._adapter+ adapter = (await backend._get_backend_for_context(ctx))._adapteroriginal_count, original_query = adapter.count, adapter.querycount_calls, queries = [], []@@ -144,7 +143,7 @@ async def test_transfer_skips_source_record_disappearing_before_fetch(async def get_after_delete(ctx, ids):missing = [uri for uri in ids if uri == b or (disappear_all and uri == a)]if missing:- await backend._get_backend_for_context(ctx).strict_delete(missing)+ await (await backend._get_backend_for_context(ctx)).strict_delete(missing)return await original_get(ctx, ids)monkeypatch.setattr(backend, "_strict_transfer_get", get_after_delete)@@ -171,7 +170,7 @@ async def test_transfer_propagates_legacy_read_errors(indexed_fs, monkeypatch, oawait fs.write_file_bytes(target, b"old", ctx=ctx)await seed_vector(backend, source, "new")await seed_vector(backend, target, "old")- adapter = backend._get_backend_for_context(ctx)._adapter+ adapter = (await backend._get_backend_for_context(ctx))._adapteroriginal_query, original_get = adapter.query, adapter.getdef query(**kwargs):@@ -219,7 +218,7 @@ async def test_transfer_ignores_concurrent_sibling_index_changes(await fs.write_file_bytes(sibling, b"unrelated", ctx=ctx)await seed_vector(backend, sibling, "unrelated")- account_backend = backend._get_backend_for_context(ctx)+ account_backend = await backend._get_backend_for_context(ctx)original_query = account_backend.strict_querytrigger_uri = source_file if phase == "source" else target_filechanged = False@@ -312,7 +311,7 @@ async def test_directory_transfer_reads_all_exact_entries_with_native_storage(ctx=ctx,)read_ids: set[str] = set()- account_backend = backend._get_backend_for_context(ctx)+ account_backend = await backend._get_backend_for_context(ctx)original_query = account_backend.strict_queryasync def tracked_query(*args, **kwargs):diff --git a/tests/storage/test_vector_transfer.py b/tests/storage/test_vector_transfer.pyindex 83657828f..ffc92fd2c 100644--- a/tests/storage/test_vector_transfer.py+++ b/tests/storage/test_vector_transfer.py@@ -76,7 +76,7 @@ class _MemoryTransferBackend(VikingVectorIndexBackend):def mode(self) -> str:return self.backend_mode- def _get_backend_for_context(self, ctx):+ async def _get_backend_for_context(self, ctx):del ctxreturn SimpleNamespace(strict_query=self._query)@@ -277,13 +277,13 @@ def _records_under(@pytest.mark.asyncio-async def test_copy_uri_mapping_scans_real_local_path_records(tmp_path):+async def test_copy_uri_mapping_scans_real_local_path_records(vector_backend_factory, tmp_path):if not getattr(vectordb_engine, "PersistStore", None):pytest.skip("local persistent vectordb engine is not available in this environment")source = "viking://resources/src.md"target = "viking://resources/dst.md"- backend = VikingVectorIndexBackend(+ backend = vector_backend_factory(config=VectorDBBackendConfig(backend="local",name="context",@@ -384,8 +384,11 @@ async def test_get_l2_abstracts_by_uris_uses_strict_batched_lookup():@pytest.mark.asyncioasync def test_scroll_propagates_real_adapter_query_failure():- backend = _SingleAccountBackend.__new__(_SingleAccountBackend)- backend._bound_account_id = "acct"+ backend = _SingleAccountBackend(+ VectorDBBackendConfig(),+ bound_account_id="acct",+ shared_adapter=SimpleNamespace(mode="local"),+ )backend._async_adapter = SimpleNamespace(call=AsyncMock(side_effect=RuntimeError("injected query failure")))@@ -402,8 +405,11 @@ async def test_strict_delete_removes_existing_subset_when_attempted_ids_include_1,])- backend = _SingleAccountBackend.__new__(_SingleAccountBackend)- backend._bound_account_id = "acct"+ backend = _SingleAccountBackend(+ VectorDBBackendConfig(),+ bound_account_id="acct",+ shared_adapter=SimpleNamespace(mode="local"),+ )backend._async_adapter = SimpleNamespace(call=adapter_call)deleted = await backend.strict_delete(["written", "never-written"])@@ -563,16 +569,15 @@ async def test_legacy_transfer_reads_use_private_adapter_query_and_fetch(monkeyp)adapter._collection = Collection(collection)account_backend = _SingleAccountBackend(VectorDBBackendConfig(), "acct", shared_adapter=adapter)- monkeypatch.setattr(backend, "_get_backend_for_context", lambda ctx: account_backend)+ monkeypatch.setattr(+ backend, "_get_backend_for_context", AsyncMock(return_value=account_backend)+ )monkeypatch.setattr(backend,"_strict_transfer_get",VikingVectorIndexBackend._strict_transfer_get.__get__(backend),)- monkeypatch.setattr(- "openviking.storage.vectordb_adapters.base.get_openviking_config",- lambda: SimpleNamespace(embedding=SimpleNamespace(dimension=2)),- )+ adapter._dimension = 2paths = []def data_post(path, data):@@ -855,12 +860,12 @@ async def test_incremental_hydration_honors_explicit_summary_projection():@pytest.mark.asyncio-async def test_l2_diff_scan_reads_real_local_backend(tmp_path):+async def test_l2_diff_scan_reads_real_local_backend(vector_backend_factory, tmp_path):if not getattr(vectordb_engine, "PersistStore", None):pytest.skip("local persistent vectordb engine is not available in this environment")root = "viking://resources/docs"- backend = VikingVectorIndexBackend(+ backend = vector_backend_factory(config=VectorDBBackendConfig(backend="local", name="context", dimension=4, path=str(tmp_path))@@ -909,12 +914,14 @@ async def test_l2_diff_scan_reads_real_local_backend(tmp_path):@pytest.mark.asyncio-async def test_incremental_inventory_and_hydration_read_real_local_backend(tmp_path):+async def test_incremental_inventory_and_hydration_read_real_local_backend(+ vector_backend_factory, tmp_path+):if not getattr(vectordb_engine, "PersistStore", None):pytest.skip("local persistent vectordb engine is not available in this environment")root = "viking://resources/docs"- backend = VikingVectorIndexBackend(+ backend = vector_backend_factory(config=VectorDBBackendConfig(backend="local", name="context", dimension=4, path=str(tmp_path))diff --git a/tests/storage/test_viking_fs_glob.py b/tests/storage/test_viking_fs_glob.pyindex 5adac94ff..c651a5739 100644--- a/tests/storage/test_viking_fs_glob.py+++ b/tests/storage/test_viking_fs_glob.py@@ -19,6 +19,11 @@ class _DummyAgfs:class _RemoteGlobVectorStore:_backend_type = "vikingdb"+ _mode = "vikingdb"++ async def get_account_backend(self, account_id):+ assert account_id+ return selfdef __init__(self, records, count=1000, data_count=None):self.records = recordsdiff --git a/tests/storage/test_viking_vector_scope_filter.py b/tests/storage/test_viking_vector_scope_filter.pyindex ea3618875..6d08ee2da 100644--- a/tests/storage/test_viking_vector_scope_filter.py+++ b/tests/storage/test_viking_vector_scope_filter.py@@ -1,6 +1,7 @@# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.# SPDX-License-Identifier: Apache-2.0+import threadingfrom types import SimpleNamespacefrom unittest.mock import AsyncMock@@ -76,6 +77,16 @@ class _RecordingAsyncAdapter:return []+def _single_account_backend(async_adapter, account_id: str | None):+ backend = object.__new__(_SingleAccountBackend)+ backend._bound_account_id = account_id+ backend._operation_condition = threading.Condition()+ backend._operations = {}+ backend._retired = False+ backend._async_adapter = async_adapter+ return backend++@pytest.mark.asyncioasync def test_search_by_random_passes_runtime_acl_state_to_tenant_filter():ctx = _ctx()@@ -83,7 +94,7 @@ async def test_search_by_random_passes_runtime_acl_state_to_tenant_filter():acl_reader = _AclConfigReader(False)backend = object.__new__(VikingVectorIndexBackend)backend.acl_manager = AclManager(backend, acl_reader)- backend._get_backend_for_context = lambda _ctx: adapter+ backend._get_backend_for_context = AsyncMock(return_value=adapter)assert await backend.search_by_random(ctx=ctx) == []adapter.search_by_random.assert_awaited_once()@@ -168,7 +179,9 @@ def test_mixed_visible_and_outside_targets_keep_original_tenant_filter():@pytest.mark.asyncio@pytest.mark.parametrize("legacy_mode", [{}, {"acl_mode": None}, {"acl_mode": "none"}])-async def test_tenant_search_enforces_visible_roots_and_shared_acl(tmp_path, legacy_mode):+async def test_tenant_search_enforces_visible_roots_and_shared_acl(+ vector_backend_factory, tmp_path, legacy_mode+):ctx = _ctx()own_uri = "viking://user/alice/resources/notes"cross_user_uri = "viking://user/bob/resources/notes"@@ -249,7 +262,7 @@ async def test_tenant_search_enforces_visible_roots_and_shared_acl(tmp_path, leg},]- backend = VikingVectorIndexBackend(+ backend = vector_backend_factory(config=VectorDBBackendConfig(backend="local", name="context", dimension=4, path=str(tmp_path / "vectors"))@@ -425,9 +438,7 @@ def test_actor_peer_target_retains_account_and_exact_target_scope():@pytest.mark.asyncioasync def test_search_by_random_propagates_adapter_errors():- backend = object.__new__(_SingleAccountBackend)- backend._bound_account_id = None- backend._async_adapter = _FailingAsyncAdapter()+ backend = _single_account_backend(_FailingAsyncAdapter(), None)with pytest.raises(RuntimeError, match="search_by_random failed"):await backend.search_by_random(filter=Eq("uri", "viking://resources/a.md"))@@ -435,9 +446,7 @@ async def test_search_by_random_propagates_adapter_errors():@pytest.mark.asyncioasync def test_search_by_random_reuses_account_filter_for_raw_dsl():- backend = object.__new__(_SingleAccountBackend)- backend._bound_account_id = "acct"- backend._async_adapter = _RecordingAsyncAdapter()+ backend = _single_account_backend(_RecordingAsyncAdapter(), "acct")raw_filter = {"op": "must", "field": "uri", "conds": ["viking://resources"]}await backend.search_by_random(filter=raw_filter)diff --git a/tests/test_telemetry_runtime.py b/tests/test_telemetry_runtime.pyindex eb798f11b..46b3c3ae2 100644--- a/tests/test_telemetry_runtime.py+++ b/tests/test_telemetry_runtime.py@@ -7,6 +7,7 @@ import asyncioimport jsonfrom concurrent.futures import ThreadPoolExecutorfrom types import SimpleNamespace+from unittest.mock import AsyncMock, Mockimport pytest@@ -21,6 +22,7 @@ from openviking.observability.context import (reset_root_observability_context,)from openviking.storage.collection_schemas import TextEmbeddingHandler+from openviking.storage.queuefs.process_result import ProcessOutcomefrom openviking.storage.queuefs.semantic_executor import SemanticTreeStatsfrom openviking.storage.queuefs.semantic_msg import SemanticMsgfrom openviking.storage.queuefs.semantic_processor import SemanticProcessor@@ -728,7 +730,8 @@ async def test_semantic_processor_binds_registered_operation_telemetry(monkeypattelemetry = MemoryOperationTelemetry(operation="resources.add_resource", enabled=True)register_telemetry(telemetry)- processor = SemanticProcessor()+ resolver = SimpleNamespace(get_vlm=AsyncMock())+ processor = SemanticProcessor(vlm_resolver=resolver)class FakeVikingFS:async def exists(self, uri, ctx=None):@@ -738,8 +741,11 @@ async def test_semantic_processor_binds_registered_operation_telemetry(monkeypatreturn []class _FakeTreeExecutor:+ stale = False+def __init__(self, **kwargs):- pass+ assert kwargs["processor"]._vlm_resolver is resolver+ assert kwargs["ctx"].account_id == "default"async def run(self, root_uri):assert get_current_telemetry() is telemetry@@ -758,17 +764,19 @@ async def test_semantic_processor_binds_registered_operation_telemetry(monkeypat)try:- await processor.on_dequeue(+ outcome = await processor.on_dequeue(SemanticMsg(uri="viking://resources/demo",context_type="resource",recursive=False,+ propagate_to_parent=False,telemetry_id=telemetry.telemetry_id,).to_dict())finally:unregister_telemetry(telemetry.telemetry_id)+ assert outcome.outcome is ProcessOutcome.SUCCESSresult = telemetry.finish()summary = result.summaryassert summary["tokens"]["total"] == 18@@ -778,7 +786,8 @@ async def test_semantic_processor_binds_registered_operation_telemetry(monkeypat@pytest.mark.asyncioasync def test_semantic_processor_binds_metric_account_context(monkeypatch):- processor = SemanticProcessor()+ resolver = SimpleNamespace(get_vlm=AsyncMock())+ processor = SemanticProcessor(vlm_resolver=resolver)ran = {"value": False}class FakeVikingFS:@@ -789,8 +798,11 @@ async def test_semantic_processor_binds_metric_account_context(monkeypatch):return []class _FakeTreeExecutor:+ stale = False+def __init__(self, **kwargs):- pass+ assert kwargs["processor"]._vlm_resolver is resolver+ assert kwargs["ctx"].account_id == "acct-semantic"async def run(self, root_uri):ran["value"] = True@@ -810,14 +822,16 @@ async def test_semantic_processor_binds_metric_account_context(monkeypatch):lambda **kwargs: _FakeTreeExecutor(**kwargs),)- await processor.on_dequeue(+ outcome = await processor.on_dequeue(SemanticMsg(uri="viking://resources/demo",context_type="resource",recursive=False,+ propagate_to_parent=False,account_id="acct-semantic",).to_dict())+ assert outcome.outcome is ProcessOutcome.SUCCESSassert ran["value"] is True@@ -839,32 +853,21 @@ async def test_embedding_handler_binds_registered_operation_telemetry(monkeypatcasync def embed_async(self, text: str, is_query: bool = False) -> EmbedResult:return self.embed(text, is_query=is_query)- class _DummyConfig:- def __init__(self):- self.storage = SimpleNamespace(vectordb=SimpleNamespace(name="context"))- self.embedding = SimpleNamespace(- dimension=2,- get_embedder=lambda: _TelemetryAwareEmbedder(),- circuit_breaker=SimpleNamespace(- failure_threshold=5,- reset_timeout=300.0,- max_reset_timeout=300.0,- ),- )-class _DummyVikingDB:is_closing = Falseuses_content_field = False+ async def account_uses_content_field(self, account_id):+ assert account_id == "default"+ return False+async def upsert(self, _data, *, ctx=None, options=None):return "rec-1"- monkeypatch.setattr(- "openviking_cli.utils.config.get_openviking_config",- lambda: _DummyConfig(),+ provider = SimpleNamespace(bind=Mock(return_value=_TelemetryAwareEmbedder()))+ handler = TextEmbeddingHandler(+ _DummyVikingDB(), embedding_provider=provider,)-- handler = TextEmbeddingHandler(_DummyVikingDB())payload = {"data": json.dumps({@@ -882,10 +885,12 @@ async def test_embedding_handler_binds_registered_operation_telemetry(monkeypatc}try:- await handler.on_dequeue(payload)+ outcome = await handler.on_dequeue(payload)finally:unregister_telemetry(telemetry.telemetry_id)+ assert outcome.outcome is ProcessOutcome.SUCCESS+ provider.bind.assert_called_once_with("default")result = telemetry.finish()summary = result.summaryassert summary["tokens"]["embedding"] == {"total": 9}diff --git a/tests/unit/service/test_core_embedder_lifecycle.py b/tests/unit/service/test_core_embedder_lifecycle.pyindex 8b43e304d..3f8fa8afa 100644--- a/tests/unit/service/test_core_embedder_lifecycle.py+++ b/tests/unit/service/test_core_embedder_lifecycle.py@@ -2,16 +2,23 @@# SPDX-License-Identifier: AGPL-3.0"""Service lifecycle coverage for model clients."""+import asynciofrom types import SimpleNamespace+from unittest.mock import AsyncMockimport pytest+from openviking.config.embedding import AccountEmbeddingProvider+from openviking.config.vector import VectorRuntimeSettingsfrom openviking.service.core import OpenVikingService+from openviking_cli.utils.config.embedding_config import EmbeddingConfig+from openviking_cli.utils.config.vectordb_config import VectorDBBackendConfig@pytest.mark.asyncio-async def test_service_closes_embedder_after_workers_and_storage_stop(monkeypatch) -> None:+async def test_service_waits_for_account_embedder_before_closing_storage(monkeypatch) -> None:events = []+ started, storage_closing = asyncio.Event(), asyncio.Event()class _ResourceService:async def close_background_tasks(self) -> None:@@ -24,35 +31,76 @@ async def test_service_closes_embedder_after_workers_and_storage_stop(monkeypatcclass _VikingDBManager:def mark_closing(self) -> None:events.append("storage-mark")+ storage_closing.set()async def close(self) -> None:events.append("storage-close")class _Embedder:+ def prepare_embedding_input(self, content):+ return content++ async def embed_async(self, content, *, is_query):+ started.set()+ try:+ await asyncio.Event().wait()+ finally:+ events.append("request-end")+def close(self) -> None:events.append("embedder")+ monkeypatch.setattr(EmbeddingConfig, "get_embedder", lambda _: _Embedder())+ settings = VectorRuntimeSettings(+ embedding=EmbeddingConfig(+ dense={"provider": "openai", "model": "test", "api_key": "key", "dimension": 1}+ ),+ vectordb=VectorDBBackendConfig(dimension=1),+ embedding_profile="test",+ dedicated_vectordb=False,+ )+ provider = AccountEmbeddingProvider(+ SimpleNamespace(resolve=AsyncMock(return_value=settings)),+ SimpleNamespace(add_update_consumer=lambda **_: None),+ )service = OpenVikingService.__new__(OpenVikingService)service._config = SimpleNamespace(vlm=SimpleNamespace(close=lambda: events.append("vlm")))service._runtime_config_manager = None+ service._vlm_resolver = SimpleNamespace(close=lambda: events.append("resolver"))service._resource_service = _ResourceService()service._watch_scheduler = Noneservice._session_auto_commit_scheduler = Noneservice._queue_manager = _QueueManager()service._vikingdb_manager = _VikingDBManager()service._agfs_client = None- service._embedder = _Embedder()+ service._embedding_provider = provider+ service._embedder = Noneservice._initialized = Truemonkeypatch.setattr(service, "_release_data_dir_lock", lambda: None)- await service.close()+ pending = asyncio.create_task(provider.embed("account-a", "query", is_query=True))+ await started.wait()+ closing = asyncio.create_task(service.close())+ try:+ await storage_closing.wait()+ assert not closing.done()+ assert "embedder" not in events+ pending.cancel()+ with pytest.raises(asyncio.CancelledError):+ await pending+ await closing+ finally:+ pending.cancel()+ await asyncio.gather(pending, closing, return_exceptions=True)assert events == ["background","queue",+ "resolver","vlm","storage-mark",- "storage-close",+ "request-end","embedder",+ "storage-close",]- assert service._embedder is None+ assert service._embedding_provider is Nonediff --git a/tests/unit/session/memory/test_extract_loop_match_text.py b/tests/unit/session/memory/test_extract_loop_match_text.pyindex b5bc13dc2..53fbad82e 100644--- a/tests/unit/session/memory/test_extract_loop_match_text.py+++ b/tests/unit/session/memory/test_extract_loop_match_text.py@@ -1367,20 +1367,13 @@ class TestExtractionMaxOutputTokens:def _loop(self, *, vlm_max_tokens, per_loop=None):loop = ExtractLoop(- vlm=Mock(model="test-model"),+ vlm=Mock(model="test-model", max_tokens=vlm_max_tokens),viking_fs=Mock(),context_provider=Mock(),isolation_handler=Mock(),max_output_tokens=per_loop,)- with patch(- "openviking.session.memory.extract_loop.get_openviking_config"- ) as mock_config:- mock_config.return_value = SimpleNamespace(- memory=SimpleNamespace(link_enabled=False, extraction_output_format="python"),- vlm=SimpleNamespace(max_tokens=vlm_max_tokens),- )- loop._resolve_effective_max_output_tokens()+ loop._resolve_effective_max_output_tokens()return loopdef test_default_floor_used_when_unconfigured(self):diff --git a/tests/unit/session/test_extraction_batch.py b/tests/unit/session/test_extraction_batch.pyindex 2a3dabc36..327dfc964 100644--- a/tests/unit/session/test_extraction_batch.py+++ b/tests/unit/session/test_extraction_batch.py@@ -84,7 +84,15 @@ def test_phase2_batches_keep_a_turn_together_when_it_fits():@pytest.mark.asyncioasync def test_working_memory_batches_carry_the_previous_summary_forward():- session = Session(viking_fs=None)+ vlm = type("VLM", (), {"is_available": lambda self: True})()+ session = Session(+ viking_fs=None,+ vlm_resolver=type(+ "Resolver",+ (),+ {"get_vlm": AsyncMock(return_value=vlm)},+ )(),+ )messages = [_message("u1"), _message("u2"), _message("u3")]calls = []@@ -117,10 +125,17 @@ async def test_working_memory_batches_carry_the_previous_summary_forward():@pytest.mark.asyncioasync def test_working_memory_no_vlm_fallback_uses_all_messages(monkeypatch):- session = Session(viking_fs=None)messages = [_message("u1"), _message("u2"), _message("u3")]config = type("Config", (), {"vlm": None})()monkeypatch.setattr("openviking.session.session.get_openviking_config", lambda: config)+ session = Session(+ viking_fs=None,+ vlm_resolver=type(+ "Resolver",+ (),+ {"get_vlm": AsyncMock(return_value=None)},+ )(),+ )limits = ExtractionBatchLimits(max_messages=1)result = await session._generate_archive_summary_with_batching(@@ -134,11 +149,18 @@ async def test_working_memory_no_vlm_fallback_uses_all_messages(monkeypatch):@pytest.mark.asyncioasync def test_working_memory_prompt_fallback_uses_all_messages(monkeypatch):- session = Session(viking_fs=None)messages = [_message("u1"), _message("u2"), _message("u3")]vlm = type("VLM", (), {"is_available": lambda self: True})()config = type("Config", (), {"vlm": vlm})()monkeypatch.setattr("openviking.session.session.get_openviking_config", lambda: config)+ session = Session(+ viking_fs=None,+ vlm_resolver=type(+ "Resolver",+ (),+ {"get_vlm": AsyncMock(return_value=vlm)},+ )(),+ )def unavailable_prompt():raise ImportError("prompt module unavailable")diff --git a/tests/unit/test_vectorize_file_strategy.py b/tests/unit/test_vectorize_file_strategy.pyindex 5d4f598b9..e64b7263c 100644--- a/tests/unit/test_vectorize_file_strategy.py+++ b/tests/unit/test_vectorize_file_strategy.py@@ -53,6 +53,11 @@ class DummyFS:self.read_calls = []self.read_file_calls = 0self.read_file_bytes_calls = 0+ self.vector_store = self+ self._vector_config_resolver = self++ async def resolve(self, account_id):+ return types.SimpleNamespace(embedding=embedding_utils.get_openviking_config().embedding)async def read(self, _path, offset=0, size=-1, ctx=None):self.read_calls.append((offset, size))diff --git a/tests/unit/test_vlm_failover.py b/tests/unit/test_vlm_failover.pyindex 7d0bdfae2..16c21c766 100644--- a/tests/unit/test_vlm_failover.py+++ b/tests/unit/test_vlm_failover.py@@ -7,7 +7,11 @@ from unittest.mock import AsyncMock, Mockimport pytest-from openviking.models.vlm.base import FailoverVLM, PrimaryBackupSwitcher+from openviking.models.vlm.base import (+ FailoverVLM,+ PrimaryBackupSwitcher,+)+from openviking.models.vlm.token_usage import TokenUsageTrackerfrom openviking_cli.utils.config.vlm_config import VLMConfig@@ -633,24 +637,84 @@ class TestFailoverVLM:class TestVLMConfigWithBackup:"""Tests for VLMConfig with backup configuration integration."""- def test_config_without_backup_creates_single_instance(self, monkeypatch):- """Test that config without backup creates a single VLM instance."""- mock_factory = Mock()- mock_vlm = Mock()- mock_factory.create.return_value = mock_vlm-- monkeypatch.setattr("openviking.models.vlm.VLMFactory", mock_factory)+ async def test_account_config_updates_preserve_inflight_calls_and_usage(self, monkeypatch):+ import asyncio- config = VLMConfig(- model="test-model",- api_key="test-key",- provider="volcengine",+ from openviking.config.binding import manager_over_source+ from openviking.config.source import MemoryConfigSource+ from openviking.config.vlm import AccountVLMProvider+ from openviking_cli.utils.config import set_openviking_config+ from openviking_cli.utils.config.open_viking_config import (+ OpenVikingConfig,+ OpenVikingConfigSingleton,)- instance = config.get_vlm_instance()-- assert instance is mock_vlm- mock_factory.create.assert_called_once()+ started, release = asyncio.Event(), asyncio.Event()+ clients = []++ class Client:+ def __init__(self, config):+ self.model = config["model"]+ self._token_tracker = TokenUsageTracker()+ self.closed = 0+ clients.append(self)++ async def get_completion_async(self, prompt, max_tokens, **kwargs):+ if prompt == "hold":+ started.set()+ await release.wait()+ self._token_tracker.update(self.model, "openai", 100, 20)+ return f"{self.model}:{max_tokens}"++ def close(self):+ self.closed += 1++ monkeypatch.setattr("openviking.models.vlm.VLMFactory.create", Client)+ base = OpenVikingConfig.from_dict(+ {"vlm": {"model": "cluster", "provider": "openai", "api_key": "cluster-key"}}+ )+ set_openviking_config(base)+ manager = manager_over_source(MemoryConfigSource(), base_config=base)+ provider = AccountVLMProvider(manager)+ pending = None+ try:+ await manager.initialize()+ await manager.patch_account(+ "a",+ {+ "vlm": {+ "model": "a-v1",+ "credentials": [{"provider": "openai", "api_key": "a-key"}],+ }+ },+ )+ account = await provider.get_vlm("a")+ other = await provider.get_vlm("b")+ assert await account.get_completion_async("first", max_tokens=64) == "a-v1:64"+ assert provider.get_token_usage("a")["total_usage"]["total_tokens"] == 120+ assert provider.get_token_usage("b")["total_usage"]["total_tokens"] == 0++ pending = asyncio.create_task(account.get_completion_async("hold", max_tokens=64))+ await started.wait()+ await manager.patch_account("a", {"vlm": {"model": "a-v2"}})+ assert clients[0].closed == 0+ assert await other.get_completion_async("other", max_tokens=32) == "cluster:32"+ pending.cancel()+ with pytest.raises(asyncio.CancelledError):+ await pending+ assert clients[0].closed == 1+ assert await account.get_completion_async("updated", max_tokens=16) == "a-v2:16"+ assert provider.get_token_usage("a")["total_usage"]["total_tokens"] == 240+ assert provider.get_token_usage("b")["total_usage"]["total_tokens"] == 120+ finally:+ release.set()+ if pending is not None:+ pending.cancel()+ await asyncio.gather(pending, return_exceptions=True)+ await provider.close()+ OpenVikingConfigSingleton.reset_instance()+ assert len(clients) == 3+ assert all(client.closed == 1 for client in clients)def test_config_with_backup_creates_multicredential_instance(self, monkeypatch):"""Test that config with backup creates a MultiCredentialVLM instance."""diff --git a/tests/utils/test_resource_processor_processing_mode.py b/tests/utils/test_resource_processor_processing_mode.pyindex 90b557e9c..0cc515353 100644--- a/tests/utils/test_resource_processor_processing_mode.py+++ b/tests/utils/test_resource_processor_processing_mode.py@@ -168,7 +168,7 @@ async def test_flat_file_refreshes_parent_semantics_and_vectorizes_via_summary()processor = ResourceProcessor(_FakeVikingDB())summarizer = SimpleNamespace(refresh_file_parent=AsyncMock(return_value={"status": "success"}))- processor._get_summarizer = Mock(return_value=summarizer)+ processor._summarizer = summarizerresult = await processor.finish_prepared_resource({@@ -207,7 +207,7 @@ async def test_local_flat_file_refresh_passes_final_md5(monkeypatch, ctx):monkeypatch.setattr("openviking.utils.resource_processor.get_viking_fs", lambda: viking_fs)processor = ResourceProcessor(_FakeVikingDB())summarizer = SimpleNamespace(refresh_file_parent=AsyncMock(return_value={"status": "success"}))- processor._get_summarizer = Mock(return_value=summarizer)+ processor._summarizer = summarizerawait processor.finish_prepared_resource({@@ -293,7 +293,7 @@ async def test_local_incremental_noop_skips_semantic_queue_and_releases_resourceprocessor = ResourceProcessor(_FakeVikingDB())processor._build_parse_output_store = Mock(return_value=store)summarizer = SimpleNamespace(summarize=AsyncMock(return_value={"status": "success"}))- processor._get_summarizer = Mock(return_value=summarizer)+ processor._summarizer = summarizerresult = await processor.finish_prepared_resource({@@ -399,7 +399,7 @@ async def test_directory_semantic_plan_is_enqueued_without_artifact_or_legacy_disummarizer = SimpleNamespace(summarize=AsyncMock(return_value={"status": "success", "enqueued_count": 1}))- processor._get_summarizer = Mock(return_value=summarizer)+ processor._summarizer = summarizerawait processor.finish_prepared_resource({@@ -458,8 +458,8 @@ async def test_plan_artifact_is_cleaned_only_after_semantic_enqueue(monkeypatch,assert tmp_path.joinpath("artifacts", ref.root.split("/")[-1]).exists()return {"status": "success", "enqueued_count": 1}- processor._get_summarizer = Mock(- return_value=SimpleNamespace(summarize=AsyncMock(side_effect=summarize))+ processor._summarizer = SimpleNamespace(+ summarize=AsyncMock(side_effect=summarize))await processor.finish_prepared_resource(@@ -511,10 +511,8 @@ async def test_plan_enqueue_failure_cleans_artifact_and_releases_lock(monkeypatcmonkeypatch.setattr("openviking.utils.resource_processor.get_viking_fs", lambda: viking_fs)processor = ResourceProcessor(_FakeVikingDB())processor._build_parse_output_store = Mock(return_value=store)- processor._get_summarizer = Mock(- return_value=SimpleNamespace(- summarize=AsyncMock(side_effect=RuntimeError("queue unavailable"))- )+ processor._summarizer = SimpleNamespace(+ summarize=AsyncMock(side_effect=RuntimeError("queue unavailable")))with pytest.raises(RuntimeError, match="queue unavailable"):@@ -568,10 +566,8 @@ async def test_plan_enqueue_error_result_cleans_artifact_and_fails(monkeypatch,monkeypatch.setattr("openviking.utils.resource_processor.get_viking_fs", lambda: viking_fs)processor = ResourceProcessor(_FakeVikingDB())processor._build_parse_output_store = Mock(return_value=store)- processor._get_summarizer = Mock(- return_value=SimpleNamespace(- summarize=AsyncMock(return_value={"status": "error", "message": "queue rejected plan"})- )+ processor._summarizer = SimpleNamespace(+ summarize=AsyncMock(return_value={"status": "error", "message": "queue rejected plan"}))with pytest.raises(RuntimeError, match="queue rejected plan"):@@ -605,10 +601,8 @@ async def test_local_flat_refresh_failure_cleans_artifact(monkeypatch, ctx, tmp_await store.write_bytes(ref, "document/report.md", b"body")processor = ResourceProcessor(_FakeVikingDB())processor._build_parse_output_store = Mock(return_value=store)- processor._get_summarizer = Mock(- return_value=SimpleNamespace(- refresh_file_parent=AsyncMock(side_effect=RuntimeError("queue unavailable"))- )+ processor._summarizer = SimpleNamespace(+ refresh_file_parent=AsyncMock(side_effect=RuntimeError("queue unavailable")))with pytest.raises(RuntimeError, match="queue unavailable"):