apecloud
diff --git a/‎aperag/domains/knowledge_base/schemas.py‎
Lines changed: 31 additions & 1 deletion b/‎aperag/domains/knowledge_base/schemas.py‎
Lines changed: 31 additions & 1 deletion
diff --git a/‎aperag/domains/knowledge_base/service/collection_service.py‎
Lines changed: 9 additions & 1 deletion b/‎aperag/domains/knowledge_base/service/collection_service.py‎
Lines changed: 9 additions & 1 deletion
diff --git a/‎aperag/schema/common.py‎
Lines changed: 128 additions & 0 deletions b/‎aperag/schema/common.py‎
Lines changed: 128 additions & 0 deletions
@@ -37,14 +37,16 @@
 from datetime import datetime
 from typing import Any, Literal, Optional
 
-from pydantic import AnyUrl, BaseModel, Field, conint
+from pydantic import AnyUrl, BaseModel, Field, computed_field, conint
 
 from aperag.schema.common import (
     Chunk,
     CollectionConfig,
     PageResult,
     PaginatedResponse,
+    VectorBackendInfo,
     VisionChunk,
+    project_vector_backend_info,
 )
 
 __all__ = [
@@ -104,6 +106,34 @@ class Collection(BaseModel):
     is_published: Optional[bool] = Field(False, description="Whether the collection is published to marketplace")
     published_at: Optional[datetime] = Field(None, description="Publication time, null when not published")
 
+    # task #61 P1-D3 (PR for #87): read-only projection of the deployment
+    # vector backend identity + capability matrix. Modelled as a Pydantic
+    # v2 ``@computed_field`` so it is **only** present on the OpenAPI
+    # output schema (``Collection-Output``) and is **not** part of any
+    # input shape that reuses :class:`Collection` (e.g.
+    # ``CollectionCreate``/``CollectionUpdate``, plus the request-side
+    # composites ``Agent-Input.collections`` /
+    # ``CreateTurnRequest.collections`` that inherit ``Collection-Input``).
+    # Per dongdong msg=fa88e97b BLOCKER: marking ``vector_backend`` as a
+    # plain ``Optional[VectorBackendInfo]`` field would have leaked the
+    # deployment-wide setting onto every input shape that references
+    # ``Collection`` and let callers think they could submit a
+    # per-collection override on agent / chat requests — exactly the
+    # error this projection lock is meant to prevent (per architect
+    # msg=0044261f read-only output projection lock + PM msg=caf7e4df).
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def vector_backend(self) -> Optional[VectorBackendInfo]:
+        # Lazy import keeps the module import graph compatible with the
+        # G1 boundary rules: ``aperag.config`` is allowed from a domain
+        # schema, but importing it at module-load time on every domain
+        # schema introduces a settings-side-effect at import which a few
+        # tests intentionally avoid. Doing the import inside the property
+        # also matches the existing ``utils.py`` lazy-resolver style.
+        from aperag.config import settings
+
+        return project_vector_backend_info(settings.vector_db_type)
+
 
 class Document(BaseModel):
     id: Optional[str] = None
 
@@ -175,7 +175,15 @@ async def validate_collection_models(self, user: str, config) -> None:
             )
 
     async def build_collection_response(self, instance: CollectionRow) -> Collection:
-        """Build Collection response object for API return."""
+        """Build Collection response object for API return.
+
+        ``Collection.vector_backend`` is a Pydantic v2 ``@computed_field``
+        (per task #61 P1-D3 / PR for #87 — read-only projection of the
+        deployment vector backend identity + capability matrix). It is
+        populated automatically on serialization, so it is intentionally
+        **not** passed as a constructor argument — passing it would also
+        not work because computed fields are not accepted as input.
+        """
         return Collection(
             id=instance.id,
             title=instance.title,
 
@@ -303,6 +303,131 @@ class Chunk(BaseModel):
     metadata: Optional[dict[str, Any]] = None
 
 
+# task #61 P1-D3 (PR for #87): expose the deployment-wide vector backend
+# identity + capability matrix on collection metadata reads.
+#
+# Unlike ``CollectionConfig.graph_backend_type`` which is a per-collection
+# choice (`postgres` / `neo4j` / `nebula`), the active vector backend is
+# deployment-wide via ``settings.vector_db_type`` (``aperag/config.py``).
+# Per architect msg=bc92ca70 we project that single deployment value onto
+# every collection read, so the FE can render a static "vector backend
+# identity + capability matrix" panel without per-collection migration or
+# per-collection runtime probe.
+#
+# Capability flags are **static declarations** — they mirror the spec
+# decisions surfaced by task #83 (P1-V1~V4, vector adapter behavior fixes).
+# The matrix is intentionally additive: new flags can be added without
+# breaking older clients that bind to a subset of fields.
+class VectorBackendCapabilities(BaseModel):
+    """Static capability matrix for the deployment's vector backend.
+
+    Per task-61 spec § 2.3 P1-D3 (`task-61-db-adapter-compat-spec-v1.md`)
+    the capability flags are documented declarations of behavior that the
+    FE may surface in a "what does this backend support" panel. Flag
+    values are derived from the spec decisions logged on task #83 (vector
+    adapter behavior); they are not measured at runtime. If task #83
+    re-frames the declared values the static matrix below should track.
+    """
+
+    supports_atomic_batch_upsert: bool = Field(
+        ...,
+        description=("Whether the backend guarantees atomic visibility of a batch upsert. Per task #83 P1-V2."),
+    )
+    supports_filter_or_with_empty_parts: bool = Field(
+        ...,
+        description=(
+            "Whether the backend accepts a top-level OR filter that contains empty/no-op parts. Per task #83 P1-V3."
+        ),
+    )
+    supports_legacy_mode: bool = Field(
+        ...,
+        description=(
+            "Whether the backend exposes a legacy compatibility mode that the "
+            "platform may still create/read. Per task #83 P1-V4."
+        ),
+    )
+
+
+class VectorBackendInfo(BaseModel):
+    """Deployment vector backend identity + capability projection.
+
+    Read-only on collection metadata. Projected from
+    ``settings.vector_db_type``; **not** persisted per collection. If a
+    future task introduces a per-collection vector backend override, this
+    schema can stay; the projection helper would then read from the
+    collection row first and fall back to ``settings.vector_db_type``.
+    """
+
+    type: Literal["pgvector", "qdrant"] = Field(
+        ...,
+        description=("Active deployment vector backend identity, projected from ``settings.vector_db_type``."),
+    )
+    capabilities: VectorBackendCapabilities = Field(
+        ...,
+        description="Static capability declaration for the deployment vector backend.",
+    )
+
+
+# Per task #83 P1-V* spec declaration. Capability values do **not**
+# change at runtime — the dict key is the ``settings.vector_db_type``
+# lookup. Cross-PR consistency: the 2 connector-level truth flags
+# (``supports_atomic_batch_upsert`` + ``supports_legacy_mode``) mirror
+# the ``aperag/vectorstore/base.py::BACKEND_CAPABILITIES`` ClassVar
+# attached to each connector by task #83 (PR #1948). The 3rd flag
+# (``supports_filter_or_with_empty_parts``) is schema-layer-only —
+# task #83 P1-V3 makes both adapters reject empty Or parts uniformly,
+# so the flag stays False for every backend; it remains in the schema
+# so the FE can render the declared behavior explicitly per spec
+# § 2.3 P1-D3 「显示『允许差异但显式』」(per architect msg=fe7e48cb
+# cross-PR ground-truth-source = connector ClassVar).
+_STATIC_VECTOR_BACKEND_CAPABILITIES: dict[str, VectorBackendCapabilities] = {
+    "pgvector": VectorBackendCapabilities(
+        # PGVector inherits PG transactional semantics for batch upsert
+        # — mirror of ``PGVectorConnector.BACKEND_CAPABILITIES`` per
+        # task #83 PR #1948.
+        supports_atomic_batch_upsert=True,
+        # Post task #83 P1-V3 (PR #1948): translator-level
+        # defense-in-depth rejects empty Or parts on top of the
+        # ``Or.__post_init__`` DSL-level reject, uniformly across
+        # adapters.
+        supports_filter_or_with_empty_parts=False,
+        # PGVector has no separate legacy schema mode — mirror of
+        # ``PGVectorConnector.BACKEND_CAPABILITIES`` per task #83.
+        supports_legacy_mode=False,
+    ),
+    "qdrant": VectorBackendCapabilities(
+        # Qdrant batch upsert is best-effort; per task #83 P1-V2.
+        # Mirror of ``QdrantConnector.BACKEND_CAPABILITIES``.
+        supports_atomic_batch_upsert=False,
+        # Per task #83 P1-V3 (PR #1948): Qdrant translator also
+        # rejects empty Or parts. Uniform with PGVector.
+        supports_filter_or_with_empty_parts=False,
+        # Qdrant exposes a legacy collection mode; per task #83 P1-V4.
+        # Mirror of ``QdrantConnector.BACKEND_CAPABILITIES``.
+        supports_legacy_mode=True,
+    ),
+}
+
+
+def project_vector_backend_info(vector_db_type: str) -> Optional[VectorBackendInfo]:
+    """Build a static :class:`VectorBackendInfo` for the active backend.
+
+    The argument is the raw ``settings.vector_db_type`` string. Unknown
+    backends return ``None`` rather than raising — the projection field is
+    declared ``Optional[VectorBackendInfo]`` so the FE can render a
+    "unknown backend" placeholder without a hard failure on misconfigured
+    deployments.
+    """
+
+    backend = (vector_db_type or "").strip().lower()
+    capabilities = _STATIC_VECTOR_BACKEND_CAPABILITIES.get(backend)
+    if capabilities is None:
+        return None
+    # mypy: ``backend`` is checked against the dict keys, which match the
+    # ``Literal['pgvector', 'qdrant']`` shape. Pydantic will re-validate.
+    return VectorBackendInfo(type=backend, capabilities=capabilities)  # type: ignore[arg-type]
+
+
 __all__ = [
     "ModelSpec",
     "KnowledgeGraphConfig",
@@ -312,4 +437,7 @@ class Chunk(BaseModel):
     "PaginatedResponse",
     "VisionChunk",
     "Chunk",
+    "VectorBackendCapabilities",
+    "VectorBackendInfo",
+    "project_vector_backend_info",
 ]