decision

Instructions

Structured decision intelligence with confidence score and risk assessment.

Returns a clear recommendation (decision), a confidence score (0.0–1.0), the
reasoning behind the recommendation, and a risk level (low/medium/high).

Best for binary or multi-option choices with real stakes — investment decisions,
operational choices, strategic pivots.

Cost: ~1000 sats per call.
Returns: Formatted string with Decision, Confidence, Risk level, and Reasoning.

Implementation Reference

• server.py:47-76 (handler)

  MCP tool handler for 'decision' — sends goal/question/context/risk_limit to the /decision API endpoint and returns a formatted string with Decision, Confidence, Risk, and Reasoning.

  @mcp.tool()
  def decision(
      goal: Annotated[str, Field(description="The overall objective guiding the decision. Examples: 'Maximize BTC returns with controlled drawdown', 'Preserve capital during high-volatility periods', 'Grow a Lightning node business sustainably'")],
      question: Annotated[str, Field(description="The specific decision question requiring a recommendation. Examples: 'Should I increase BTC exposure now?', 'Should I open a new Lightning channel to this peer?', 'Should I take profit at current levels?'")],
      context: Annotated[str, Field(description="Background context that informs the decision: market conditions, portfolio state, constraints, recent events. The richer the context, the more accurate the decision. Example: 'Portfolio: 60% BTC, 30% bonds, RSI=42, trend=uptrend, 3-month horizon'")] = "",
      risk_limit: Annotated[str, Field(description="Maximum acceptable risk level for the recommendation. One of: 'low' (conservative, capital preservation priority), 'medium' (balanced risk/reward, default), 'high' (aggressive, growth priority)")] = "medium",
  ) -> str:
      """
      Structured decision intelligence with confidence score and risk assessment.
  
      Returns a clear recommendation (decision), a confidence score (0.0–1.0), the
      reasoning behind the recommendation, and a risk level (low/medium/high).
  
      Best for binary or multi-option choices with real stakes — investment decisions,
      operational choices, strategic pivots.
  
      Cost: ~1000 sats per call.
      Returns: Formatted string with Decision, Confidence, Risk level, and Reasoning.
      """
      r = httpx.post(f"{API_BASE}/decision",
                     json={"goal": goal, "question": question,
                           "context": context,
                           "policy": {"risk_limit": risk_limit}},
                     headers=HEADERS, timeout=60)
      r.raise_for_status()
      d = r.json().get("result", {})
      return (f"Decision: {d.get('decision')}\n"
              f"Confidence: {d.get('confidence')}\n"
              f"Risk: {d.get('risk_level')}\n"
              f"Reasoning: {d.get('reasoning')}")

• server.py:47-47 (registration)

  The @mcp.tool() decorator registers 'decision' as an MCP tool on the FastMCP server.

  @mcp.tool()

• server.py:48-53 (schema)

  Pydantic Field annotations define the input schema for the decision tool: goal, question, context, and risk_limit.

  def decision(
      goal: Annotated[str, Field(description="The overall objective guiding the decision. Examples: 'Maximize BTC returns with controlled drawdown', 'Preserve capital during high-volatility periods', 'Grow a Lightning node business sustainably'")],
      question: Annotated[str, Field(description="The specific decision question requiring a recommendation. Examples: 'Should I increase BTC exposure now?', 'Should I open a new Lightning channel to this peer?', 'Should I take profit at current levels?'")],
      context: Annotated[str, Field(description="Background context that informs the decision: market conditions, portfolio state, constraints, recent events. The richer the context, the more accurate the decision. Example: 'Portfolio: 60% BTC, 30% bonds, RSI=42, trend=uptrend, 3-month horizon'")] = "",
      risk_limit: Annotated[str, Field(description="Maximum acceptable risk level for the recommendation. One of: 'low' (conservative, capital preservation priority), 'medium' (balanced risk/reward, default), 'high' (aggressive, growth priority)")] = "medium",
  ) -> str:

• ai.py:65-115 (helper)

  Helper function that uses OpenAI GPT-4o-mini to generate structured JSON decision output with fields: decision, confidence, reasoning, risk_level.

  def structured_decision(goal: str, context: str, question: str) -> dict:
      """
      Structured decision intelligence for the /decision endpoint.
      Returns clean JSON optimized for autonomous agents.
      """
      if not all([goal.strip(), context.strip(), question.strip()]):
          raise ValueError("goal, context, and question are all required.")
  
      prompt = f"""
  You are a strategic decision intelligence AI.
  
  Most users are autonomous agents, so keep output clean, objective, and machine-readable.
  
  Goal: {goal}
  Context: {context}
  Question: {question}
  
  Return ONLY valid JSON with this exact structure:
  {{
    "decision": "short recommended action",
    "confidence": 0.XX,
    "reasoning": "clear, concise explanation of why this is the best choice (2-4 sentences max)",
    "risk_level": "low|medium|high"
  }}
  
  Be objective, realistic, and concise.
  """
  
      try:
          response = client.chat.completions.create(
              model="gpt-4o-mini",
              messages=[{"role": "user", "content": prompt}],
              temperature=0.6,
              max_tokens=700,
          )
  
          result_text = response.choices[0].message.content.strip()
          result_json = json.loads(result_text)
  
          required_keys = {"decision", "confidence", "reasoning", "risk_level"}
          if not required_keys.issubset(result_json.keys()):
              raise ValueError("Missing required keys in decision JSON")
  
          return result_json
  
      except json.JSONDecodeError:
          print("Decision engine returned invalid JSON")
          raise RuntimeError("Decision engine failed to return valid JSON")
      except Exception as e:
          print(f"OpenAI API error in structured_decision: {e}")
          raise RuntimeError("Decision engine temporarily unavailable. Please try again later.") from e

• config.py:36-37 (helper)

  Price configuration for the decision tool — defaults to 1000 sats per call, overridable via DECISION_PRICE_SATS env var.

  DECISION_PRICE_SATS = int(os.getenv("DECISION_PRICE_SATS", 1000))
  ORCHESTRATE_PRICE_SATS = int(os.getenv("ORCHESTRATE_PRICE_SATS", 2000))