feat(organization): add semantic organization behaviors

Author: xiaoland

.changes/100.added.md

@@ -0,0 +1,2 @@
+Add extensible semantic Organization behaviors, bounded graph-use queries, and Human-reviewed
+acceptance fixtures; also recognize schema-v3 SVC development database provider configuration.

app/business/graph_navigation_retrieval/__init__.py

@@ -1,3 +1,3 @@
-from .main import GraphNavigationRetrievalManager
+from .main import GraphNavigationQueryContract, GraphNavigationRetrievalManager
 
-__all__ = ["GraphNavigationRetrievalManager"]
+__all__ = ["GraphNavigationQueryContract", "GraphNavigationRetrievalManager"]

app/business/graph_navigation_retrieval/main.py

@@ -1,14 +1,21 @@
 """Bounded, presentation-neutral navigation over persisted graph authority."""
 
+from collections import deque
+from collections.abc import Collection
+from dataclasses import dataclass
+import inspect
 import typing
 
+import pydantic
 import sqlmodel
 
 from app.business.info_base.block import BlockManager
 from app.business.info_base.relation import RelationManager
 from app.engine import SessionLocal
 from app.schemas.graph_navigation_retrieval import (
   BlockNeighborhood,
+  ConnectedComponentsResult,
+  ConnectedSeedComponent,
   GraphDirection,
   GraphModel,
   PathFound,
@@ -28,11 +35,78 @@
 DEFAULT_MAX_EXPLORED_BLOCKS = 1000
 MAX_MAX_EXPLORED_BLOCKS = 10000
 FRONTIER_QUERY_SIZE = 200
+DEFAULT_MAX_EXPLORED_RELATIONS = 10000
+
+
+@dataclass(frozen=True)
+class GraphNavigationQueryContract:
+  name: str
+  description: str
+  input_model: type[pydantic.BaseModel]
+
+  @property
+  def input_schema(self) -> dict[str, typing.Any]:
+    return self.input_model.model_json_schema()
 
 
 class GraphNavigationRetrievalManager:
   """Own graph-navigation semantics while hiding query and closure mechanics."""
 
+  @classmethod
+  def get_query_contracts(cls) -> tuple[GraphNavigationQueryContract, ...]:
+    """Describe public typed graph queries without exposing runtime sessions."""
+    contracts: list[GraphNavigationQueryContract] = []
+    names = (
+      name
+      for name in dir(cls)
+      if name.startswith(("get_", "find_"))
+      and name not in {"get_query_contract", "get_query_contracts"}
+    )
+    for name in names:
+      function = getattr(cls, name)
+      signature = inspect.signature(function, eval_str=True)
+      fields: dict[str, tuple[typing.Any, typing.Any]] = {}
+      for parameter in signature.parameters.values():
+        if parameter.name == "db_session":
+          continue
+        if parameter.annotation is inspect.Parameter.empty:
+          raise TypeError(f"Graph query {name} parameter {parameter.name} must be typed")
+        default = ... if parameter.default is inspect.Parameter.empty else parameter.default
+        annotation = parameter.annotation
+        if typing.get_origin(annotation) is Collection:
+          item_type = typing.get_args(annotation)[0]
+          annotation = tuple[item_type, ...]
+        fields[parameter.name] = (annotation, default)
+      input_model = typing.cast(typing.Any, pydantic.create_model)(
+        f"GraphNavigation_{name}_Arguments",
+        __config__=pydantic.ConfigDict(extra="forbid"),
+        **fields,
+      )
+      input_model.model_json_schema()
+      contracts.append(
+        GraphNavigationQueryContract(
+          name=name,
+          description=inspect.getdoc(function) or name.replace("_", " "),
+          input_model=input_model,
+        )
+      )
+    return tuple(contracts)
+
+  @classmethod
+  def get_query_contract(cls, name: str) -> GraphNavigationQueryContract | None:
+    return next(
+      (contract for contract in cls.get_query_contracts() if contract.name == name),
+      None,
+    )
+
+  @classmethod
+  def invoke_query(cls, name: str, arguments: dict[str, typing.Any]) -> typing.Any:
+    contract = cls.get_query_contract(name)
+    if contract is None:
+      raise ValueError("Graph navigation query is not available")
+    validated = contract.input_model.model_validate(arguments)
+    return getattr(cls, name)(**validated.model_dump())
+
   @classmethod
   def get_random_block(
     cls,
@@ -143,6 +217,122 @@ def get_relation_neighborhood(
       graph=GraphModel(blocks=blocks, relations=(relation,)),
     )
 
+  @classmethod
+  def get_connected_components(
+    cls,
+    seed_block_ids: typing.Collection[BlockID],
+    *,
+    contents: typing.Collection[str],
+    max_explored_blocks: int = DEFAULT_MAX_EXPLORED_BLOCKS,
+    max_explored_relations: int = DEFAULT_MAX_EXPLORED_RELATIONS,
+    db_session: sqlmodel.Session | None = None,
+  ) -> ConnectedComponentsResult:
+    """Partition existing seeds by bounded undirected exact-content reachability."""
+    seeds = tuple(dict.fromkeys(seed_block_ids))
+    relation_contents = tuple(dict.fromkeys(contents))
+    if not relation_contents:
+      raise ValueError("contents must not be empty")
+    if max_explored_blocks < 1 or max_explored_relations < 1:
+      raise ValueError("exploration bounds must be positive")
+    if len(seeds) > max_explored_blocks:
+      raise ValueError("seed blocks exceed max_explored_blocks")
+    if db_session is None:
+      with SessionLocal() as owned_session:
+        return cls.get_connected_components(
+          seeds,
+          contents=relation_contents,
+          max_explored_blocks=max_explored_blocks,
+          max_explored_relations=max_explored_relations,
+          db_session=owned_session,
+        )
+
+    existing_blocks = BlockManager.get_many(seeds, db_session)
+    existing_seed_ids = {block.id for block in existing_blocks if block.id is not None}
+    missing = tuple(seed for seed in seeds if seed not in existing_seed_ids)
+    assigned_seeds: set[BlockID] = set()
+    explored_blocks = set(existing_seed_ids)
+    seen_relations: set[RelationID] = set()
+    explored_relation_count = 0
+    proof_relations: dict[RelationID, RelationModel] = {}
+    components: list[ConnectedSeedComponent] = []
+    truncated = False
+
+    for seed in seeds:
+      if seed not in existing_seed_ids or seed in assigned_seeds:
+        continue
+      if truncated:
+        components.append(
+          ConnectedSeedComponent(seed_blocks=(seed,), member_blocks=(seed,))
+        )
+        assigned_seeds.add(seed)
+        continue
+
+      members = {seed}
+      frontier = deque((seed,))
+      while frontier and not truncated:
+        current = frontier.popleft()
+        for endpoint in ("from", "to"):
+          cursor: RelationID | None = None
+          while not truncated:
+            remaining = max_explored_relations - explored_relation_count
+            if remaining == 0:
+              truncated = True
+              break
+            requested = min(FRONTIER_QUERY_SIZE, remaining + 1)
+            page = RelationManager.get_endpoint_page(
+              (current,),
+              endpoint=typing.cast(typing.Literal["from", "to"], endpoint),
+              contents=relation_contents,
+              cursor=cursor,
+              limit=requested,
+              db_session=db_session,
+            )
+            if len(page) > remaining:
+              page = page[:remaining]
+              truncated = True
+            explored_relation_count += len(page)
+            for relation in page:
+              if relation.id is None or relation.id in seen_relations:
+                continue
+              relation_id = relation.id
+              seen_relations.add(relation_id)
+              neighbor = relation.to_ if relation.from_ == current else relation.from_
+              if neighbor in members:
+                continue
+              if (
+                neighbor not in explored_blocks
+                and len(explored_blocks) >= max_explored_blocks
+              ):
+                truncated = True
+                break
+              members.add(neighbor)
+              explored_blocks.add(neighbor)
+              frontier.append(neighbor)
+              proof_relations[relation_id] = relation
+            if truncated or len(page) < requested:
+              break
+            cursor = typing.cast(RelationID, page[-1].id)
+
+      component_seeds = tuple(seed_id for seed_id in seeds if seed_id in members)
+      assigned_seeds.update(component_seeds)
+      components.append(
+        ConnectedSeedComponent(
+          seed_blocks=component_seeds,
+          member_blocks=tuple(sorted(members)),
+        )
+      )
+
+    proof_blocks = BlockManager.get_many(explored_blocks, db_session)
+    return ConnectedComponentsResult(
+      components=tuple(components),
+      proof_graph=GraphModel(
+        blocks=proof_blocks,
+        relations=tuple(proof_relations.values()),
+      ),
+      missing_seed_blocks=missing,
+      truncated=truncated,
+    )
+
   @classmethod
   def find_path(  # noqa: PLR0913
     cls,

app/business/info_base/resolver/__init__.py

@@ -10,7 +10,12 @@
   UnknownResolverError,
   UnsupportedResolverCapability,
 )
-from .main import Resolver, ResolverDraftCapability, ResolverManager
+from .main import (
+  Resolver,
+  ResolverDraftCapability,
+  ResolverManager,
+  ResolverMethodContract,
+)
 
 __all__ = [
   "ResolverManager",
@@ -26,6 +31,7 @@
   "ResolverContentError",
   "UnsupportedResolverCapability",
   "ResolverDraftCapability",
+  "ResolverMethodContract",
   "AudioResolver",
   "EPUBResolver",
   "FileResolver",

app/business/info_base/resolver/main.py

@@ -1,5 +1,7 @@
 import abc
+from collections.abc import Collection
 from dataclasses import dataclass
+import inspect
 import typing
 from typing import Optional as Opt
 
@@ -30,6 +32,19 @@ class ResolverDraftCapability:
   resolver_cls: type["Resolver"]
 
 
+@dataclass(frozen=True)
+class ResolverMethodContract:
+  """One Agent-projectable public read method on a registered Resolver."""
+
+  name: str
+  description: str
+  input_model: type[pydantic.BaseModel]
+
+  @property
+  def input_schema(self) -> dict[str, typing.Any]:
+    return self.input_model.model_json_schema()
+
+
 class ResolverManager:
   RESOLVER_CLS: dict[ResolverType, type["Resolver"]] = {}
   """Global resolver registry.
@@ -86,6 +101,82 @@ def get_draft_capability(
         return capability
     raise UnknownDraftResolverError(resolver)
 
+  @classmethod
+  def get_method_contracts(
+    cls,
+    resolver: ResolverType,
+  ) -> tuple[ResolverMethodContract, ...]:
+    """Discover typed public read methods on one registered Resolver."""
+    resolver_cls = cls.RESOLVER_CLS.get(resolver)
+    if resolver_cls is None:
+      return ()
+    contracts: list[ResolverMethodContract] = []
+    for name, function in inspect.getmembers(resolver_cls, predicate=inspect.isfunction):
+      if name.startswith("_") or not name.startswith(("get_", "read_")):
+        continue
+      try:
+        signature = inspect.signature(function, eval_str=True)
+        fields: dict[str, tuple[typing.Any, typing.Any]] = {}
+        for parameter in signature.parameters.values():
+          if parameter.name == "self":
+            continue
+          if parameter.kind in (parameter.VAR_POSITIONAL, parameter.VAR_KEYWORD):
+            raise TypeError("Variadic Resolver methods are not projectable")
+          if parameter.annotation is inspect.Parameter.empty:
+            raise TypeError("Resolver method parameters must be typed")
+          default = (
+            ... if parameter.default is inspect.Parameter.empty else parameter.default
+          )
+          annotation = parameter.annotation
+          if typing.get_origin(annotation) is Collection:
+            item_type = typing.get_args(annotation)[0]
+            annotation = tuple[item_type, ...]
+          fields[parameter.name] = (annotation, default)
+        input_model = typing.cast(typing.Any, pydantic.create_model)(
+          f"{resolver_cls.__name__}_{name}_Arguments",
+          __config__=pydantic.ConfigDict(extra="forbid"),
+          **fields,
+        )
+        input_model.model_json_schema()
+      except (NameError, TypeError, pydantic.PydanticSchemaGenerationError):
+        continue
+      contracts.append(
+        ResolverMethodContract(
+          name=name,
+          description=inspect.getdoc(function) or name.replace("_", " "),
+          input_model=input_model,
+        )
+      )
+    return tuple(contracts)
+
+  @classmethod
+  def get_method_contract(
+    cls,
+    resolver: ResolverType,
+    name: str,
+  ) -> ResolverMethodContract | None:
+    return next(
+      (
+        contract for contract in cls.get_method_contracts(resolver) if contract.name == name
+      ),
+      None,
+    )
+
+  @classmethod
+  async def invoke_method(
+    cls,
+    block: BlockModel,
+    name: str,
+    arguments: dict[str, typing.Any],
+  ) -> typing.Any:
+    """Validate and invoke one projected read method on an exact Block Resolver."""
+    contract = cls.get_method_contract(block.resolver, name)
+    if contract is None:
+      raise ValueError("Resolver method is not available")
+    validated = contract.input_model.model_validate(arguments)
+    value = getattr(cls.get(block), name)(**validated.model_dump())
+    return await value if inspect.isawaitable(value) else value
+
   @classmethod
   def match_media_type(cls, media_type: str | None) -> ResolverType | None:
     """Map one specific media type to an installed exact core resolver ID.