get_dimension_hierarchy

Instructions

Implementation Reference

• fccs_agent/tools/dimensions.py:57-89 (handler)

  The main tool handler function that executes get_dimension_hierarchy logic, including caching, client delegation, and response formatting.

  async def get_dimension_hierarchy(
      dimension_name: str,
      member_name: Optional[str] = None,
      depth: int = 5,
      include_metadata: bool = False
  ) -> dict[str, Any]:
      """Build a parent-child hierarchy for a dimension / Construir hierarquia pai-filho de uma dimensao.
  
      Args:
          dimension_name: Dimension to explore.
          member_name: Start from a specific member (optional).
          depth: Depth limit for the hierarchy (default: 5).
          include_metadata: Include raw metadata for each node.
  
      Returns:
          dict: Hierarchy tree structure.
      """
      cache = get_cache_service()
      cache_key = f"hierarchy:{dimension_name}:{member_name}:{depth}:{include_metadata}"
      
      if cache:
          cached_data = cache.get(cache_key)
          if cached_data:
              return {"status": "success", "data": cached_data, "source": "cache"}
  
      hierarchy = await _client.get_dimension_hierarchy(
          _app_name, dimension_name, member_name, depth, include_metadata
      )
      
      if cache and hierarchy:
          cache.set(cache_key, hierarchy, ttl_seconds=3600)  # Cache for 1 hour
          
      return {"status": "success", "data": hierarchy, "source": "fccs"}

• fccs_agent/tools/dimensions.py:115-140 (schema)

  Input schema and metadata definition for the get_dimension_hierarchy tool within TOOL_DEFINITIONS.

  {
      "name": "get_dimension_hierarchy",
      "description": "Build a parent-child hierarchy for a dimension / Construir hierarquia pai-filho",
      "inputSchema": {
          "type": "object",
          "properties": {
              "dimension_name": {
                  "type": "string",
                  "description": "Dimension to explore",
              },
              "member_name": {
                  "type": "string",
                  "description": "Start from a specific member (optional)",
              },
              "depth": {
                  "type": "number",
                  "description": "Depth limit for the hierarchy (default: 5)",
              },
              "include_metadata": {
                  "type": "boolean",
                  "description": "Include raw metadata for each node",
              },
          },
          "required": ["dimension_name"],
      },
  },

• fccs_agent/agent.py:150-150 (registration)

  Registration of the get_dimension_hierarchy tool handler in the central TOOL_HANDLERS dictionary.

  "get_dimension_hierarchy": dimensions.get_dimension_hierarchy,

• fccs_agent/client/fccs_client.py:276-378 (helper)

  Core helper method in FccsClient that implements the hierarchy building logic from dimension members, used by the tool handler.

  async def get_dimension_hierarchy(
      self,
      app_name: str,
      dimension_name: str,
      member_name: Optional[str] = None,
      depth: int = 5,
      include_metadata: bool = False
  ) -> dict[str, Any]:
      """Get dimension hierarchy / Obter hierarquia da dimensao."""
      members_response = await self.get_members(app_name, dimension_name)
  
      # Extract member items
      member_items = (
          members_response.get("items")
          or members_response.get("members")
          or (members_response if isinstance(members_response, list) else [])
      )
  
      if not member_items:
          return {
              "dimension": dimension_name,
              "requestedMember": member_name,
              "depth": depth,
              "hierarchy": [],
              "note": "No members returned for this dimension."
          }
  
      # Build hierarchy tree
      node_map: dict[str, dict] = {}
  
      for member in member_items:
          name = member.get("memberName") or member.get("name") or member.get("alias")
          if not name or name in node_map:
              continue
  
          parent_name = (
              member.get("parentName")
              or member.get("parent")
              or member.get("parent_member_name")
          )
  
          node_map[name] = {
              "node": {
                  "name": name,
                  "description": member.get("description") or member.get("alias"),
                  **({"metadata": member} if include_metadata else {}),
                  "children": [],
              },
              "parentName": parent_name,
          }
  
      # Link children to parents
      root_nodes = []
      for name, entry in node_map.items():
          parent = entry["parentName"]
          if parent and parent in node_map:
              node_map[parent]["node"]["children"].append(entry["node"])
          else:
              root_nodes.append(entry["node"])
  
      # Prune to requested depth
      def prune_node(node: dict, remaining_depth: int) -> dict:
          pruned = {"name": node["name"]}
          if node.get("description"):
              pruned["description"] = node["description"]
          if include_metadata and node.get("metadata"):
              pruned["metadata"] = node["metadata"]
  
          if remaining_depth > 0 and node.get("children"):
              pruned["children"] = [
                  prune_node(child, remaining_depth - 1)
                  for child in node["children"]
              ]
          else:
              pruned["children"] = []
              if node.get("children"):
                  pruned["truncatedChildren"] = len(node["children"])
  
          return pruned
  
      # Find target nodes
      if member_name:
          target = node_map.get(member_name)
          if not target:
              # Case-insensitive search
              for key, entry in node_map.items():
                  if key.lower() == member_name.lower():
                      target = entry
                      break
          if not target:
              raise ValueError(f"Member '{member_name}' not found in dimension '{dimension_name}'")
          targets = [target["node"]]
      else:
          targets = root_nodes
  
      return {
          "dimension": dimension_name,
          "requestedMember": member_name,
          "depth": depth,
          "totalMembers": len(member_items),
          "hierarchy": [prune_node(node, depth) for node in targets],
      }