ARBuilder

Instructions

Implementation Reference

• src/mcp/tools/ask_orbit.py:287-440 (handler)

  The `execute` method is the core handler for the `ask_orbit` tool, matching user questions against a knowledge base and optional RAG retrieval to provide answers about Orbit chain deployment and management.

  def execute(self, **kwargs) -> dict[str, Any]:
      """Answer an Orbit chain question."""
      question = kwargs.get("question", "").strip()
      _question_type = kwargs.get("question_type", "general")  # reserved for future use
  
      if not question:
          return {"error": "Question is required and cannot be empty"}
  
      q_lower = question.lower()
  
      # Match against knowledge base topics
      answer_parts = []
      relevant_topics = []
  
      # Chain config questions
      if any(kw in q_lower for kw in [
          "chain config", "prepare config", "configure chain",
          "chain id", "chain owner", "chainconfig",
      ]):
          relevant_topics.append("chain_config")
  
      # Deployment questions
      if any(kw in q_lower for kw in [
          "deploy", "create rollup", "launch", "setup chain",
          "deployment", "createrollup",
      ]):
          relevant_topics.append("deployment")
  
      # Validator questions
      if any(kw in q_lower for kw in [
          "validator", "batch poster", "sequencer", "assertion",
      ]):
          relevant_topics.append("validators")
  
      # Gas token questions
      if any(kw in q_lower for kw in [
          "gas token", "native token", "custom token", "erc20 gas",
          "custom gas",
      ]):
          relevant_topics.append("gas_tokens")
  
      # AnyTrust questions
      if any(kw in q_lower for kw in [
          "anytrust", "dac", "keyset", "data availability",
          "committee", "any trust",
      ]):
          relevant_topics.append("anytrust")
  
      # Node setup questions
      if any(kw in q_lower for kw in [
          "node", "nitro", "node config", "run node", "start node",
          "devnode", "docker",
      ]):
          relevant_topics.append("node_setup")
  
      # Node troubleshooting questions
      if any(kw in q_lower for kw in [
          "error", "fail", "not working", "troubleshoot",
          "can't start", "won't start", "permission denied", "crash",
      ]) or ("node" in q_lower and any(kw in q_lower for kw in [
          "issue", "problem", "fix",
      ])):
          relevant_topics.append("node_troubleshooting")
  
      # Governance questions
      if any(kw in q_lower for kw in [
          "governance", "upgrade", "executor", "admin", "role",
          "permission",
      ]):
          relevant_topics.append("governance")
  
      # Code standards questions (include when question involves code examples)
      if any(kw in q_lower for kw in [
          "code", "script", "example", "how to",
          "register", "keyset", "deploy",
      ]):
          relevant_topics.append("code_standards")
  
      # Token bridge questions
      if any(kw in q_lower for kw in [
          "token bridge", "bridge", "gateway", "create bridge",
          "createtokenbridge",
      ]):
          relevant_topics.append("token_bridge")
  
      # Build answer from matched topics
      if relevant_topics:
          for topic in dict.fromkeys(relevant_topics):  # preserve order, deduplicate
              if topic in ORBIT_KNOWLEDGE:
                  info = ORBIT_KNOWLEDGE[topic]
                  answer_parts.append(
                      f"## {topic.replace('_', ' ').title()}"
                  )
                  for key, value in info.items():
                      if isinstance(value, list):
                          answer_parts.append(
                              f"**{key.replace('_', ' ').title()}:**"
                          )
                          for item in value:
                              answer_parts.append(f"  - {item}")
                      elif isinstance(value, dict):
                          answer_parts.append(
                              f"**{key.replace('_', ' ').title()}:**"
                          )
                          for sub_key, sub_value in value.items():
                              answer_parts.append(
                                  f"  - **{sub_key}:** {sub_value}"
                              )
                      else:
                          answer_parts.append(
                              f"**{key.replace('_', ' ').title()}:** {value}"
                          )
                  answer_parts.append("")
  
      # Try RAG context if available
      rag_context = ""
      if self.context_tool:
          try:
              ctx_result = self.context_tool.execute(
                  query=question,
                  n_results=3,
                  rerank=True,
                  category_boosts={
                      "orbit_sdk": 1.5,
                      "arbitrum_docs": 1.3,
                      "arbitrum_sdk": 1.0,
                      "stylus": 0.5,
                  },
              )
              if ctx_result.get("contexts"):
                  rag_context = "\n\n".join(
                      c.get("content", "")
                      for c in ctx_result["contexts"][:2]
                  )
          except Exception:
              pass  # RAG is optional
  
      # Build final answer
      if answer_parts:
          answer = "\n".join(answer_parts)
      else:
          answer = self._get_generic_answer(question)
  
      result = {
          "answer": answer,
          "topics": list(dict.fromkeys(relevant_topics)) if relevant_topics else ["general"],
          "references": self._get_references(relevant_topics),
      }
  
      if rag_context:
          result["additional_context"] = rag_context[:1000]
  
      return result