autobots-devtools-shared-lib 0.4.0__tar.gz → 0.5.2__tar.gz

{autobots_devtools_shared_lib-0.4.0 → autobots_devtools_shared_lib-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autobots-devtools-shared-lib
-Version: 0.4.0
+Version: 0.5.2
 Summary: Shared library functions to be used for all autobots projects
 License: MIT
 Author: Pralhad
@@ -25,6 +25,7 @@ Requires-Dist: opentelemetry-sdk (>=1.30.0,<2.0.0)
 Requires-Dist: pydantic-settings (>=2.10.1)
 Requires-Dist: python-dotenv (>=1.1.1)
 Requires-Dist: pyyaml (>=6.0.3)
+Requires-Dist: referencing (>=0.37.0)
 Requires-Dist: uvicorn[standard] (>=0.32.0)
 Description-Content-Type: text/markdown
 

{autobots_devtools_shared_lib-0.4.0 → autobots_devtools_shared_lib-0.5.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "autobots-devtools-shared-lib"
-version = "0.4.0"
+version = "0.5.2"
 description = "Shared library functions to be used for all autobots projects"
 readme = "README.md"
 authors = [
@@ -10,6 +10,7 @@ license = {text = "MIT"}
 requires-python = ">=3.12,<4.0.0"
 dependencies = [
     "chainlit>=2.9.6",
+    "referencing>=0.37.0",
     "jsonschema>=4.26.0",
     "langchain>=1.0.0",
     "langchain-anthropic>=1.4.0",

{autobots_devtools_shared_lib-0.4.0 → autobots_devtools_shared_lib-0.5.2}/src/autobots_devtools_shared_lib/common/utils/format_utils.py

@@ -43,7 +43,7 @@ def output_format_converter(
     )
 
     meta = AgentMeta.instance()
-    schema = meta.schema_map.get(agent_name)  # pyright: ignore[reportAttributeAccessIssue]
+    schema = meta.output_schema_map.get(agent_name)  # pyright: ignore[reportAttributeAccessIssue]
 
     if schema is None:
         return f"Error: no output schema configured for agent '{agent_name}'"

{autobots_devtools_shared_lib-0.4.0 → autobots_devtools_shared_lib-0.5.2}/src/autobots_devtools_shared_lib/dynagent/agents/agent_config_utils.py

@@ -2,7 +2,7 @@
 # ABOUTME: Reads agents.yaml and provides typed accessors for prompts, tools, schemas.
 
 import json
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
@@ -10,6 +10,9 @@ import yaml
 
 from autobots_devtools_shared_lib.common.observability.logging_utils import get_logger
 from autobots_devtools_shared_lib.dynagent.config.dynagent_settings import get_dynagent_settings
+from autobots_devtools_shared_lib.dynagent.utils.schema_directive_resolver import (
+    resolve_parent_with_directives,
+)
 
 logger = get_logger(__name__)
 
@@ -17,11 +20,12 @@ __all__ = [
     "AgentConfig",
     "get_agent_list",
     "get_batch_enabled_agents",
+    "get_capabilities_map",
     "get_config_dir",
     "get_default_agent",
     "get_prompt_map",
-    "get_schema_map",
-    "get_schema_path_map",
+    "get_resolved_input_schema_map",
+    "get_resolved_output_schema_map",
     "get_tool_map",
     "load_agents_config",
     "load_prompt",
@@ -36,8 +40,13 @@ class AgentConfig:
     agent_id: str
     prompt: str
     tools: list[str]
+    # inputs: schema_name -> directive_filename (or None)
+    inputs: dict[str, str | None] = field(default_factory=dict)
+    # output: single-entry {schema_name -> directive_filename} map (or None)
+    output: dict[str, str | None] | None = None
+    # optional list of human-readable capabilities
+    capabilities: list[str] = field(default_factory=list)
     section: str | None = None
-    output_schema: str | None = None
     approach: str | None = None
     dynamic: bool = False
     batch_enabled: bool = False
@@ -47,12 +56,44 @@ class AgentConfig:
     @classmethod
     def from_dict(cls, agent_id: str, data: dict[str, Any]) -> "AgentConfig":
         """Create AgentConfig from a dictionary."""
+
+        raw_inputs = data.get("inputs") or []
+        inputs: dict[str, str | None] = {}
+        for item in raw_inputs:
+            if not isinstance(item, dict):
+                continue
+            schema_name = item.get("schema")
+            if not schema_name:
+                continue
+            directives_name = item.get("directives")
+            inputs[schema_name] = directives_name
+
+        raw_output = data.get("output")
+        output_cfg: dict[str, str | None] | None = None
+        if isinstance(raw_output, dict):
+            schema_name_val = raw_output.get("schema")
+            directives_name_val = raw_output.get("directives")
+            if isinstance(schema_name_val, str) or isinstance(directives_name_val, str):
+                schema_key = schema_name_val if isinstance(schema_name_val, str) else ""
+                output_cfg = {
+                    schema_key: directives_name_val
+                    if isinstance(directives_name_val, str)
+                    else None
+                }
+
+        raw_capabilities = data.get("capabilities")
+        capabilities: list[str] = []
+        if isinstance(raw_capabilities, list):
+            capabilities = [item for item in raw_capabilities if isinstance(item, str)]
+
         return cls(
             agent_id=agent_id,
             prompt=data.get("prompt", ""),
             tools=data.get("tools", []),
+            inputs=inputs,
+            output=output_cfg,
+            capabilities=capabilities,
             section=data.get("section"),
-            output_schema=data.get("output_schema"),
             approach=data.get("approach"),
             dynamic=data.get("dynamic", False),
             batch_enabled=data.get("batch_enabled", False),
@@ -114,21 +155,15 @@ def load_prompt(name: str) -> str:
         return f"Error reading prompt: {e}"
 
 
-def load_schema(name: str) -> dict:
-    """Read and parse a JSON schema file by name from the schemas/ directory.
-
-    Args:
-        name: Schema filename (e.g., "joke-output.json", "01-preface.json")
+def load_schema(name: str, base_dir: Path | None = None) -> dict:
+    """Read and parse a JSON schema file by name.
 
-    Returns:
-        Parsed JSON schema as dictionary
-
-    Raises:
-        FileNotFoundError: If schema file doesn't exist
-        ValueError: If JSON is invalid
+    When base_dir is provided, reads from base_dir/schemas; otherwise uses
+    the active config_dir/schemas.
     """
-    config_dir = get_config_dir()
-    schema_dir = Path(config_dir) / "schemas"
+    if base_dir is None:
+        base_dir = get_config_dir()
+    schema_dir = Path(base_dir) / "schemas"
     schema_file = schema_dir / name
 
     if not schema_file.exists():
@@ -149,6 +184,77 @@ def load_schema(name: str) -> dict:
         raise
 
 
+def _build_parent_paths(schema_name: str) -> list[Path]:
+    """Compute candidate parent schema paths in common and domain-specific folders."""
+    config_dir = get_config_dir()
+    if not schema_name.endswith(".json"):
+        schema_name = f"{schema_name}.json"
+
+    domain_schema = Path(config_dir) / "schemas" / schema_name
+    common_schema = Path(config_dir).parent / "common" / "schemas" / schema_name
+    return [common_schema, domain_schema]
+
+
+def _normalize_directive_filename(directive_name: str) -> str:
+    """Ensure directive filenames resolve to json files."""
+    return directive_name if directive_name.endswith(".json") else f"{directive_name}.json"
+
+
+def get_resolved_input_schema_map() -> dict[str, dict[str, dict]]:
+    """Return {agent_name: {schema_key: resolved_schema_dict}} for all input schemas."""
+    config_dir = get_config_dir()
+    agents = load_agents_config()
+
+    result: dict[str, dict[str, dict]] = {}
+
+    for agent_name, cfg in agents.items():
+        per_agent: dict[str, dict] = {}
+        for schema_name, directive_name in cfg.inputs.items():
+            if not directive_name:
+                continue
+            parent_paths = _build_parent_paths(schema_name)
+            directive_path = (
+                config_dir / "directives" / _normalize_directive_filename(directive_name)
+            )
+            resolved = resolve_parent_with_directives(parent_paths, directive_path)
+            schema_key = Path(schema_name).stem
+            per_agent[schema_key] = resolved
+        result[agent_name] = per_agent
+
+    return result
+
+
+def _resolve_output_schema_for_agent(cfg: AgentConfig, config_dir: Path) -> dict | None:
+    """Resolve a single agent's output schema from output schema+directive config."""
+    if cfg.output is None:
+        return None
+
+    # Expect at most one entry in the output map.
+    for schema_name, directive_name in cfg.output.items():
+        if not schema_name:
+            return None
+        parent_paths = _build_parent_paths(schema_name)
+        if directive_name:
+            directive_path = (
+                config_dir / "directives" / _normalize_directive_filename(directive_name)
+            )
+            return resolve_parent_with_directives(parent_paths, directive_path)
+
+        return resolve_parent_with_directives(parent_paths, None)
+
+    return None
+
+
+def get_resolved_output_schema_map() -> dict[str, dict | None]:
+    """Return {agent_name: resolved output schema or None} for all agents."""
+    config_dir = get_config_dir()
+    agents = load_agents_config()
+    return {
+        agent_name: _resolve_output_schema_for_agent(cfg, config_dir)
+        for agent_name, cfg in agents.items()
+    }
+
+
 def get_agent_list() -> list[str]:
     """Return list of agent names from config."""
     return list(load_agents_config().keys())
@@ -159,34 +265,9 @@ def get_prompt_map() -> dict[str, str]:
     return {name: load_prompt(cfg.prompt) for name, cfg in load_agents_config().items()}
 
 
-def get_schema_path_map() -> dict[str, str | None]:
-    """Return {agent_name: raw_schema_path_or_None}."""
-    return {name: cfg.output_schema for name, cfg in load_agents_config().items()}
-
-
-def get_schema_map() -> dict[str, dict | None]:
-    """Return {agent_name: parsed_schema_dict_or_None} loaded from schema files.
-
-    Reads all schema files referenced in agents.yaml at startup.
-    Agents without output_schema get None.
-
-    Returns:
-        Dictionary mapping agent names to parsed schema dicts
-
-    Raises:
-        FileNotFoundError: If a referenced schema file is missing
-        ValueError: If a schema file contains invalid JSON
-    """
-    result = {}
-    for agent_name, cfg in load_agents_config().items():
-        if cfg.output_schema is None:
-            result[agent_name] = None
-        else:
-            logger.info(f"Loading schema '{cfg.output_schema}' for agent '{agent_name}'")
-            result[agent_name] = load_schema(cfg.output_schema)
-
-    logger.info(f"Loaded {sum(1 for v in result.values() if v is not None)} schemas")
-    return result
+def get_capabilities_map() -> dict[str, list[str]]:
+    """Return {agent_name: capabilities[]} from agents config."""
+    return {name: cfg.capabilities for name, cfg in load_agents_config().items()}
 
 
 def get_tool_map() -> dict[str, list[Any]]:

{autobots_devtools_shared_lib-0.4.0 → autobots_devtools_shared_lib-0.5.2}/src/autobots_devtools_shared_lib/dynagent/agents/agent_meta.py

@@ -1,5 +1,5 @@
 # ABOUTME: Singleton holding all agent configuration loaded at startup.
-# ABOUTME: Provides prompt_map, tool_map, and schema_path_map.
+# ABOUTME: Provides prompt_map, tool_map, input/output schema maps, and capabilities.
 
 from __future__ import annotations
 
@@ -14,15 +14,17 @@ class AgentMeta:
     _instance: AgentMeta | None = None
     prompt_map: dict[str, str]
     tool_map: dict[str, list[Any]]
-    schema_path_map: dict[str, str | None]
-    schema_map: dict[str, dict | None]
+    input_schema_map: dict[str, dict[str, dict]]
+    output_schema_map: dict[str, dict | None]
+    capabilities_map: dict[str, list[str]]
     default_agent: str | None
 
     def __init__(self) -> None:
         self.prompt_map = _agent_config.get_prompt_map()
         self.tool_map = _agent_config.get_tool_map()
-        self.schema_path_map = _agent_config.get_schema_path_map()
-        self.schema_map = _agent_config.get_schema_map()  # pyright: ignore[reportAttributeAccessIssue]
+        self.input_schema_map = _agent_config.get_resolved_input_schema_map()
+        self.output_schema_map = _agent_config.get_resolved_output_schema_map()
+        self.capabilities_map = _agent_config.get_capabilities_map()
         self.default_agent = _agent_config.get_default_agent()
 
     @classmethod

{autobots_devtools_shared_lib-0.4.0 → autobots_devtools_shared_lib-0.5.2}/src/autobots_devtools_shared_lib/dynagent/agents/middleware.py

@@ -1,6 +1,7 @@
 # ABOUTME: Middleware that injects agent-specific prompts and tools on every LLM call.
 # ABOUTME: Reads current agent_name from state and overrides via AgentMeta.
 
+import json
 from collections import defaultdict
 from collections.abc import Awaitable, Callable
 
@@ -26,7 +27,20 @@ async def inject_agent_async(
 
     # Format prompt safely — missing placeholders become empty strings
     raw_prompt = meta.prompt_map.get(agent_name, "")
-    format_values = defaultdict(str, **request.state)
+
+    # Inject resolved input schemas (if any) as JSON strings using their schema keys.
+    input_schemas = meta.input_schema_map.get(agent_name, {})
+    input_directives_map = {
+        schema_key: json.dumps(schema, indent=2, sort_keys=True)
+        for schema_key, schema in input_schemas.items()
+    }
+
+    input_directives = {"input_schemas": input_directives_map}
+    output_directives = {"output_schema": meta.output_schema_map.get(agent_name, {}) or {}}
+
+    # request.state values take precedence on key collision, consistent with previous behavior.
+    combined_values = {**input_directives, **output_directives, **request.state}
+    format_values = defaultdict(str, **combined_values)
     system_prompt = raw_prompt.format_map(format_values)
 
     tools = meta.tool_map.get(agent_name, [])
@@ -52,7 +66,20 @@ def inject_agent_sync(
 
     # Format prompt safely — missing placeholders become empty strings
     raw_prompt = meta.prompt_map.get(agent_name, "")
-    format_values = defaultdict(str, **request.state)
+
+    # Inject resolved input schemas (if any) as JSON strings using their schema keys.
+    input_schemas = meta.input_schema_map.get(agent_name, {})
+    input_directives_map = {
+        schema_key: json.dumps(schema, indent=2, sort_keys=True)
+        for schema_key, schema in input_schemas.items()
+    }
+
+    input_directives = {"input_schemas": input_directives_map}
+    output_directives = {"output_schema": meta.output_schema_map.get(agent_name, {}) or {}}
+
+    # request.state values take precedence on key collision, consistent with previous behavior.
+    combined_values = {**input_directives, **output_directives, **request.state}
+    format_values = defaultdict(str, **combined_values)
     system_prompt = raw_prompt.format_map(format_values)
 
     tools = meta.tool_map.get(agent_name, [])

{autobots_devtools_shared_lib-0.4.0 → autobots_devtools_shared_lib-0.5.2}/src/autobots_devtools_shared_lib/dynagent/services/structured_converter.py

@@ -9,6 +9,7 @@ from langchain.messages import ToolMessage
 from langchain_core.messages import BaseMessage
 
 from autobots_devtools_shared_lib.common.observability.logging_utils import get_logger
+from autobots_devtools_shared_lib.dynagent.agents.agent_meta import AgentMeta
 
 logger = get_logger(__name__)
 
@@ -110,11 +111,17 @@ class StructuredOutputConverter:
         # Create conversion prompt
         conversion_prompt = self._create_conversion_prompt(filtered_messages)
 
+        # Prefer pre-resolved output schema from AgentMeta when available.
+        meta = AgentMeta.instance()
+        effective_schema = meta.output_schema_map.get(current_agent) or json_schema
+
         # Use structured output to convert
         try:
-            schema_title = json_schema.get("title", "structured output")
+            schema_title = effective_schema.get("title", "structured output")
             logger.info(f"Converting conversation to {schema_title} for agent {current_agent}")
-            structured_llm = self.model.with_structured_output(json_schema, method="json_schema")
+            structured_llm = self.model.with_structured_output(
+                effective_schema, method="json_schema"
+            )
             result = structured_llm.invoke(conversion_prompt)
 
         except Exception as e:

autobots_devtools_shared_lib-0.5.2/src/autobots_devtools_shared_lib/dynagent/utils/schema_directive_resolver.py

@@ -0,0 +1,328 @@
+"""Schema + directive resolver.
+
+Responsible for:
+- Loading parent schema JSON docs from one or more paths (common + domain).
+- Deep-merging parents with domain overriding common.
+- Applying directive JSON (directives: [...]) via JSON Pointer and x-fbp-pragmas.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from pathlib import Path
+from typing import Any
+
+from referencing import Registry, Resource
+from referencing.jsonschema import DRAFT202012
+
+from autobots_devtools_shared_lib.common.observability.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+def _resolve_json_pointer(document: Any, pointer: str) -> Any:
+    """Resolve a JSON Pointer (RFC 6901) against a document.
+
+    Raises ValueError if the pointer cannot be resolved.
+    """
+    if pointer == "":
+        return document
+    if pointer == "/":
+        # Directive convention: "/" means the root document, not the RFC 6901 empty-string key.
+        # Schemas in this codebase never have an empty-string key, so treat "/" as root.
+        return document
+
+    if not pointer.startswith("/"):
+        raise ValueError(f"Invalid JSON Pointer (must start with '/'): {pointer}")
+
+    current = document
+    # Split on '/' and ignore the first empty segment
+    for raw_token in pointer.split("/")[1:]:
+        token = raw_token.replace("~1", "/").replace("~0", "~")
+        if isinstance(current, list):
+            try:
+                index = int(token)
+            except ValueError as e:  # pragma: no cover - defensive
+                raise ValueError(
+                    f"Non-numeric index '{token}' for list in pointer {pointer}"
+                ) from e
+            try:
+                current = current[index]
+            except IndexError as e:
+                raise ValueError(f"Index '{index}' out of range for pointer {pointer}") from e
+        elif isinstance(current, dict):
+            if token not in current:
+                raise ValueError(f"Key '{token}' not found while resolving pointer {pointer}")
+            current = current[token]
+        else:  # pragma: no cover - defensive
+            raise TypeError(
+                f"Cannot traverse into non-container type at token '{token}' for pointer {pointer}"
+            )
+    return current
+
+
+def _merge_pragmas(
+    target_node: dict[str, Any], pragma_obj: dict[str, list[str]], description: str | None
+) -> None:
+    """Merge x-fbp-pragmas into the target node in-place."""
+    existing_pragmas = target_node.get("x-fbp-pragmas")
+    if not isinstance(existing_pragmas, dict):
+        existing_pragmas = {}
+        target_node["x-fbp-pragmas"] = existing_pragmas
+
+    for scope, items in pragma_obj.items():
+        if not isinstance(items, list):  # pragma: no cover - defensive
+            logger.warning("Expected list for pragma scope '%s', got %r", scope, items)
+            continue
+        existing_list = existing_pragmas.get(scope)
+        if not isinstance(existing_list, list):
+            existing_list = []
+            existing_pragmas[scope] = existing_list
+        existing_list.extend(items)
+
+    if description:
+        # Directive descriptions directly override/define the node description.
+        target_node["description"] = description
+
+
+def _retrieve_from_path(base_dir: Path):
+    """Create a retriever that loads JSON schema files relative to a base directory."""
+
+    def _retrieve(uri: str) -> Resource:
+        from urllib.parse import unquote, urlparse
+
+        parsed = urlparse(uri)
+        path = Path(unquote(parsed.path))
+        if not path.is_absolute():
+            path = base_dir / path
+        contents = json.loads(path.read_text())
+        return Resource(contents=contents, specification=DRAFT202012)
+
+    return _retrieve
+
+
+def _resolve_all_refs(schema: Any, resolver, _seen: frozenset[str] = frozenset()) -> Any:
+    """Recursively resolve all $ref in a schema, returning a plain dict.
+
+    Uses the referencing library's Resolver to look up each $ref URI,
+    then recurses into the resolved content with its updated resolver context
+    (critical for resolving relative $ref in nested files).
+
+    The ``_seen`` parameter tracks resolved URIs to prevent infinite recursion
+    from circular $ref chains.
+    """
+    if isinstance(schema, dict):
+        if "$ref" in schema:
+            ref = schema["$ref"]
+            if ref in _seen:
+                raise ValueError(f"Circular $ref detected: {ref}")
+            resolved = resolver.lookup(ref)
+            return _resolve_all_refs(resolved.contents, resolved.resolver, _seen | {ref})
+        return {k: _resolve_all_refs(v, resolver, _seen) for k, v in schema.items()}
+    if isinstance(schema, list):
+        return [_resolve_all_refs(item, resolver, _seen) for item in schema]
+    return schema
+
+
+def _merge_parent_schemas(parent_docs: list[dict]) -> dict:
+    """Deep-merge a list of parent schema documents (domain overrides common)."""
+
+    def _merge(a: dict, b: dict) -> dict:
+        result: dict = copy.deepcopy(a)
+        for key, value in b.items():
+            if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+                result[key] = _merge(result[key], value)
+            else:
+                result[key] = copy.deepcopy(value)
+        return result
+
+    merged: dict = {}
+    for doc in parent_docs:
+        merged = _merge(merged, doc)
+    return merged
+
+
+def _flatten_directive_entries(
+    entries: list[dict],
+    directive_dir: Path,
+    link_target: str = "",
+    _seen: frozenset[str] = frozenset(),
+    _sources: list[dict] | None = None,
+) -> list[tuple[str, dict, str | None]]:
+    """Flatten directive entries, resolving ``$ref`` links recursively.
+
+    Entries with ``$ref`` load the referenced directive file and rebase its entries
+    under the linking entry's ``target``. Recursion is guarded by ``_seen``.
+
+    Rebasing rule:
+        - Referenced ``/``            → ``link_target`` (or ``/`` at top level)
+        - Referenced ``/properties/x`` → ``link_target + /properties/x``
+
+    Args:
+        entries: The ``directives`` list from a directive document.
+        directive_dir: Directory for resolving relative ``$ref`` paths.
+        link_target: JSON Pointer prefix for all targets in ``entries``.
+            Empty string means no rebasing (top-level call).
+        _seen: Resolved directive file paths — guards against circular references.
+        _sources: Optional list; each loaded directive file appends its metadata here.
+
+    Returns:
+        Flat list of ``(pointer, pragma_obj, description)`` tuples.
+    """
+    result: list[tuple[str, dict, str | None]] = []
+
+    for entry in entries:
+        if not isinstance(entry, dict):
+            raise TypeError(f"Directive entries must be objects, got {type(entry)!r}")
+
+        has_ref = "$ref" in entry
+        has_pragmas = "x-fbp-pragmas" in entry
+
+        if not has_ref and not has_pragmas:
+            raise ValueError(
+                f"Directive entry must have 'x-fbp-pragmas' or '$ref' "
+                f"(target={entry.get('target')!r}): {entry}"
+            )
+
+        entry_target: str = entry.get("target", "/")
+
+        # Compute the absolute JSON Pointer for this entry.
+        if entry_target == "/":
+            abs_target = link_target if link_target else "/"
+        else:
+            abs_target = (link_target + entry_target) if link_target else entry_target
+
+        # Emit this entry's own x-fbp-pragmas at abs_target.
+        if has_pragmas:
+            result.append((abs_target, entry["x-fbp-pragmas"], entry.get("description")))
+
+        # Resolve $ref: load the referenced directive file and rebase its entries.
+        if has_ref:
+            ref: str = entry["$ref"]
+            ref_path = (directive_dir / ref).resolve()
+            ref_uri = str(ref_path)
+
+            if ref_uri in _seen:
+                raise ValueError(f"Circular $ref in directives detected: {ref!r}")
+
+            try:
+                ref_doc = json.loads(ref_path.read_text())
+            except (OSError, json.JSONDecodeError) as e:
+                raise ValueError(f"Failed to load directive $ref {ref!r}: {e}") from e
+
+            if _sources is not None:
+                _sources.append(
+                    {
+                        "id": ref_doc.get("id", ref_path.stem),
+                        "title": ref_doc.get("title", ref_path.stem),
+                    }
+                )
+
+            sub_entries = ref_doc.get("directives", [])
+            if not isinstance(sub_entries, list):
+                raise TypeError(f"'directives' in {ref!r} must be a list")
+
+            result.extend(
+                _flatten_directive_entries(
+                    sub_entries,
+                    ref_path.parent,
+                    abs_target,
+                    _seen | {ref_uri},
+                    _sources,
+                )
+            )
+
+    return result
+
+
+def resolve_parent_with_directives(parent_paths: list[Path], directive_path: None | Path) -> dict:
+    """Load parent schema(s), merge common+domain, then apply directives.
+
+    Args:
+        parent_paths: Ordered [common_parent, domain_parent] schema file paths.
+        directive_path: Path to directive JSON with a top-level 'directives' array.
+    """
+    parent_docs: list[dict] = []
+    for path in parent_paths:
+        if path.exists():
+            try:
+                with Path.open(path) as f:
+                    parent_docs.append(json.load(f))
+            except json.JSONDecodeError as e:
+                error_msg = f"Invalid JSON in schema {path}: {e}"
+                logger.exception(error_msg)
+                raise ValueError(error_msg) from e
+
+    if not parent_docs:
+        error_msg = f"No parent schema files found at {[str(p) for p in parent_paths]}"
+        logger.error(error_msg)
+        raise FileNotFoundError(error_msg)
+
+    merged_parent = _merge_parent_schemas(parent_docs)
+
+    if not directive_path or not directive_path.exists():
+        error_msg = f"Directive file not found: {directive_path}"
+        # logger.error(error_msg)
+        # raise FileNotFoundError(error_msg)
+        return merged_parent
+
+    try:
+        with Path.open(directive_path) as f:
+            directive_doc = json.load(f)
+    except json.JSONDecodeError as e:
+        error_msg = f"Invalid JSON in directive {directive_path}: {e}"
+        logger.exception(error_msg)
+        raise ValueError(error_msg) from e
+
+    entries = directive_doc.get("directives", [])
+    if not isinstance(entries, list):
+        raise TypeError(f"'directives' must be a list in directive file '{directive_path.name}'")
+
+    # Resolve $ref file references so JSON Pointer directives can navigate into them.
+    # Determine the base directory from the last existing parent path for relative $ref.
+    base_dir = parent_paths[0].resolve().parent
+    for path in reversed(parent_paths):
+        if path.exists():
+            base_dir = path.resolve().parent
+            break
+
+    registry: Registry = Registry(retrieve=_retrieve_from_path(base_dir))
+    base_uri = base_dir.as_uri() + "/"
+    resolver = registry.resolver(base_uri)
+    merged = _resolve_all_refs(merged_parent, resolver)
+
+    sources = merged.get("x-fbp-directive-sources")
+    if not isinstance(sources, list):
+        sources = []
+        merged["x-fbp-directive-sources"] = sources
+
+    directive_source = {
+        "id": directive_doc.get("id", directive_path.stem),
+        "title": directive_doc.get("title", directive_path.stem),
+    }
+    sources.append(directive_source)
+
+    transitive_sources: list[dict] = []
+    flat_entries = _flatten_directive_entries(
+        entries, directive_path.parent, _sources=transitive_sources
+    )
+    sources.extend(transitive_sources)
+
+    for pointer, pragma_obj, description in flat_entries:
+        if not isinstance(pragma_obj, dict):
+            raise TypeError(
+                f"'x-fbp-pragmas' must be an object in directive '{directive_path.name}' "
+                f"for target '{pointer}', got {type(pragma_obj)!r}"
+            )
+
+        try:
+            target_node = _resolve_json_pointer(merged, pointer)
+        except ValueError as e:
+            error_msg = f"Failed to resolve JSON Pointer '{pointer}' in directive '{directive_path.name}': {e}"
+            logger.exception(error_msg)
+            raise ValueError(error_msg) from e
+
+        _merge_pragmas(target_node, pragma_obj, description)
+
+    return merged