create-leafmesh 2.1.0__py3-none-any.whl

create_leafmesh/templates/configs/config.yaml

@@ -0,0 +1,1028 @@
+name: "{{project_name}}"
+version: "1.0.0"
+architecture: "managed_mesh"
+environment: "development"                # "development" or "production"
+debug: true
+log_level: "INFO"
+
+redis:
+  host: "${REDIS_HOST:localhost}"
+  port: ${REDIS_PORT:6379}
+  db: 0
+  password: "${REDIS_PASSWORD:}"
+  auto_storage: true
+  decode_responses: true               # Decode Redis byte responses to strings
+  default_ttl: 3600                    # Default key TTL in seconds
+  session_ttl: 7200                    # Session TTL in seconds
+  # cluster_mode: true                   # Enable Redis cluster mode
+  # cluster_nodes:                        # Cluster node addresses
+  #   - "redis-node1:6379"
+  #   - "redis-node2:6379"
+  #   - "redis-node3:6379"
+
+  # TLS / encryption-in-transit
+  # Enable when your Redis server requires TLS (rediss://).
+  # ssl: true
+  # ssl_cert_reqs: required              # required | optional | none
+  # ssl_ca_certs: /etc/ssl/certs/redis-ca.crt
+  # ssl_certfile: /etc/ssl/certs/redis-client.crt   # mTLS, optional
+  # ssl_keyfile: /etc/ssl/private/redis-client.key  # mTLS, optional
+  # ssl_check_hostname: true
+
+# ═══════════════════════════════════════════════════
+# API — HTTP server (CORS, etc.)
+# ═══════════════════════════════════════════════════
+# The SDK ships with a built-in CORS allowlist:
+#   - https://platform.leafcraft.ai (hosted Studio)
+#   - http://localhost:3000 / 3001 / 5173 / 5174 / 8080 (common dev ports)
+# Add additional origins below if you serve your own UI from a different host.
+# api:
+#   cors_origins:
+#     - https://my-internal-tool.example.com
+#     - https://my-staging-studio.acme.com
+
+# Auto-discover agent files in agency/ directory
+# SDK matches Python function names to YAML agent names
+auto_discover:
+  directory: "./agency"
+  pattern: "*_agent.py"
+  # recursive: true                      # Search subdirectories (default: true)
+
+# ═══════════════════════════════════════════════════
+# MANAGER — Built-in mesh coordinator + conversation analyzer
+#
+# Two built-in agents, ONE config section:
+#   Summarizer — LLM-powered, analyzes every agent event automatically
+#   Manager    — Pure logic, enforces rules, retries, halts, escalates
+#
+# The "model" and "domain" fields drive the Summarizer's LLM calls.
+# The Manager never calls an LLM — it acts on the Summarizer's analysis.
+# ═══════════════════════════════════════════════════
+manager:
+  enabled: true
+  model: "gpt-4o-mini"              # Used by Summarizer for LLM analysis
+  domain: "generic"                  # Summarizer domain: "generic" | "ecommerce" | "data_analysis"
+  # ── Learning-based routing (BRD-008) ──
+  # Routes mesh_call requests to agents based on past success patterns.
+  # "learning" mode accumulates routing decisions in Redis and improves over time.
+  # No external dependencies — works with Redis only.
+  routing:
+    mode: "learning"                   # "static" (YAML rules only) or "learning" (adaptive)
+    memory_size: 100                   # Max routing decisions to remember
+    confidence_threshold: 0.7          # Min confidence to accept a learned route
+    fallback: "all"                    # Fallback when confidence too low: "all" evaluates every can_call
+    decay_days: 30                     # Days before old routing memory decays
+
+  # ── Escalation targets (BRD-011) ──
+  # When the manager detects repeated failures or timeouts, it escalates.
+  # Human agent escalation works out of the box. Webhook/channel need credentials.
+  escalation:
+    targets:
+      # Human agent escalation — routes to the client human agent
+      - type: "human_agent"
+        agent: "client"
+        # entry_point: "human_contact"   # Optional: specific entry point
+
+      # Webhook escalation (uncomment + configure URL)
+      # - type: "webhook"
+      #   url: "${ESCALATION_WEBHOOK_URL:}"
+      #   method: "POST"
+      #   headers:
+      #     Authorization: "Bearer ${ESCALATION_WEBHOOK_TOKEN:}"
+      #     Content-Type: "application/json"
+      #   payload_template:
+      #     incident: "{{incident_id}}"
+      #     severity: "{{severity}}"
+      #     message: "{{message}}"
+
+      # Channel escalation (uncomment + configure provider)
+      # - type: "channel"
+      #   provider: "slack"                # slack | telegram | discord | whatsapp | teams
+      #   channel_id: "${ESCALATION_SLACK_CHANNEL:}"
+      #   message_template: "🚨 Escalation: {{message}} (session: {{session_id}})"
+
+    auto_escalate:
+      max_retries: 3                   # Max retry attempts before escalating
+      max_errors_per_session: 5        # Error count threshold per session
+      timeout_threshold: 2             # Consecutive timeouts before escalating
+
+  # can_intervene: true                  # Allow manager interventions (default: true)
+  #                                        # Set false for read-only monitoring mode
+
+  # ── Everything below has sensible defaults — uncomment only to override ──
+  # coordination_rules:
+  #   score_threshold: 0.7
+  #   max_retries: 3
+  #   agent_rules:
+  #     processor_agent:
+  #       min_items: 1
+  #       max_items: 100
+  # health_check_interval: 60       # Seconds between health checks (default: 60)
+  # agent_timeout_threshold: 180    # Seconds before agent considered timed out (default: 180)
+  # chain_completion_timeout: 60    # Seconds to wait for can_call chain (default: 60)
+
+# Mesh settings — call timeout + cloud LLM provider configs
+mesh:
+  call_timeout: 60
+
+  # ── Cloud LLM Providers (uncomment to use) ──
+  # bedrock:
+  #   region: "us-east-1"                   # AWS region
+  #   # profile: "default"                  # AWS profile from ~/.aws/credentials
+  #   # endpoint_url: ""                    # Custom Bedrock endpoint (optional)
+  #   # Auth: AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY env vars, or IAM role
+  #
+  # vertex:
+  #   project: "my-gcp-project"             # GCP project ID (required)
+  #   location: "us-central1"               # GCP region
+  #   # Auth: GOOGLE_APPLICATION_CREDENTIALS or gcloud auth
+  #
+  # foundry:
+  #   endpoint: "https://my-resource.openai.azure.com"   # Azure AI Foundry endpoint (required)
+  #   # api_version: "2024-10-21"           # Omit for v1 mode (recommended), set for legacy Azure mode
+  #   # Auth: AZURE_FOUNDRY_API_KEY or AZURE_FOUNDRY_TOKEN env vars
+  #
+  # ── Local model server (vLLM, SGLang, Ollama, llama.cpp, etc.) ──
+  # Most servers expose OpenAI-compatible /v1/chat/completions — use server_type: openai
+  # local:
+  #   endpoint: "http://localhost:8000/v1/chat/completions"  # vLLM/SGLang default
+  #   server_type: "openai"              # "openai" | "ollama" | "textgen" | "huggingface" (auto-detected if omitted)
+  #   timeout: 120                       # Seconds (local models can be slow on CPU)
+  #   # headers:
+  #   #   Authorization: "Bearer ${VLLM_API_KEY:}"
+
+# ═══════════════════════════════════════════════════
+# ENTRY POINTS — Named portals into the mesh
+# Use: await leafmesh.mesh_call("entry_point_name", data)
+# This is the ONLY way to trigger agent workflows externally
+# ═══════════════════════════════════════════════════
+entry_points:
+  - name: "greet_user"
+    target: "greeter_agent"
+    description: "Main entry — greets user and starts the agent chain"
+    # condition: "always"              # Optional trigger condition
+
+  - name: "human_contact"
+    target: "client"
+    description: "Human-initiated — client contacts the mesh via channel/webhook"
+
+  - name: "process_data"
+    target: "processor_agent"
+    description: "Direct data processing bypass"
+
+  - name: "research"
+    target: "researcher_agent"
+    description: "Direct research — bypasses greeting flow"
+
+  - name: "advise"
+    target: "advisor_agent"
+    description: "Direct advice request — ad-hoc recommendations"
+
+  - name: "scheduled_report"
+    target: "scheduler_agent"
+    description: "On-demand status report (also runs on cron schedule)"
+
+# ═══════════════════════════════════════════════════
+# AGENTS — 4 types: human, llm, programmatic, external
+#
+# Registration:
+#   - agency/*_agent.py → auto_discover matches function names to YAML names
+#   - Standalone decorators: @chain, @compose, @pre_compose (no leafmesh instance needed)
+#
+# Data flow — HITL (Human-in-the-Loop):
+#
+#   Scenario 1 (system-initiated):
+#     mesh_call("greet_user", data) → greeter_agent → client (HITL)
+#       → [human reviews in ADK-Frontend inbox] → processor_agent
+#       → researcher_agent + fallback_researcher_agent
+#       → advisor_agent (OR fan-in)
+#
+#   Scenario 2 (human-initiated):
+#     webhook to "human_contact" → client → greeter_agent → client (HITL)
+#       → [human reviews in ADK-Frontend inbox] → processor_agent
+#       → researcher_agent + fallback_researcher_agent
+#       → advisor_agent (OR fan-in)
+#
+# Direct entries:
+#   mesh_call("research", data) → researcher_agent (standalone)
+#   mesh_call("advise", data)   → advisor_agent (standalone)
+#
+# Scheduled + on-demand:
+#   cron "0 9 * * *" → scheduler_agent → advisor_agent (daily report analysis)
+#   mesh_call("scheduled_report", data) → scheduler_agent → advisor_agent
+# ═══════════════════════════════════════════════════
+agents:
+
+  # ─────────────────────────────────────────────
+  # HUMAN AGENT — Receives input via ADK-Frontend inbox
+  # No Python file needed. The mesh handles everything.
+  #
+  # human_interface options:
+  #   "default"  — ADK-Frontend HITL inbox (recommended)
+  #                Writes request to Redis, emits stream event.
+  #                Human replies via the ADK-Frontend UI.
+  #                Supports parallel requests per session.
+  #   "webhook"  — External webhook (self-hosted)
+  #                POSTs to outbound_url, human responds via inbound webhook.
+  #                Also supports native channel adapters (Slack, Telegram, etc.)
+  #   "api"      — Python callback handler (testing/custom integrations)
+  #
+  # HITL (Human-in-the-Loop) dual-mode flow:
+  #   1. System-initiated: greeter → client (HITL) → processor
+  #      - Greeter sends result to client for human review
+  #      - Human sees request in ADK-Frontend inbox
+  #      - Human responds → routes to processor
+  #
+  #   2. Human-initiated: client → greeter → client (HITL) → processor
+  #      - Human contacts mesh via webhook to "human_contact" entry point
+  #      - Client routes to greeter (from_agent not set → first can_call match)
+  #      - Greeter responds back to client (dual callback)
+  #      - Human reviews in inbox → responds → routes to processor
+  #
+  # The can_call conditions use "from_agent" to distinguish who called:
+  #   - No from_agent → first contact, route to greeter
+  #   - from_agent == "greeter_agent" → greeter finished, route to processor
+  # ─────────────────────────────────────────────
+  client:
+    name: "client"
+    agent_type: "human"
+    is_human_powered: true
+    human_interface: "default"        # ADK-Frontend inbox (recommended)
+    communication_type: "dual"        # dual mode: request + wait for human response
+    human_timeout_seconds: 300
+    # operator_ids:                   # Operators who can see this agent's inbox requests
+    #   - "alice@company.com"         # Leave empty (or omit) for broadcast — all operators see it
+    #   - "bob@company.com"
+
+    # Human-specific templates (customize how context/prompts are presented)
+    # human_context_template: "Session {{session_id}}: {{context}}"
+    # human_prompt_template: "Please review the following and respond: {{message}}"
+
+    # Require explicit human confirmation before proceeding
+    # require_human_confirmation: false
+
+    # Conditions that trigger human escalation (e.g. keywords in the request)
+    # human_escalation_triggers:
+    #   - "urgent"
+    #   - "high_value"
+
+    # Fallback when human doesn't respond in time
+    # fallback_on_timeout: true
+    # fallback_response:
+    #   decision: "timeout_default"
+    #   message: "Request timed out"
+
+    # ── Webhook config (only needed when human_interface: "webhook") ──
+    # For self-hosted deployments without ADK-Frontend.
+    # Outbound notifies external system, inbound receives human response.
+    # NOTE: inbound_endpoint is auto-derived from entry_points — no need to set it.
+    # webhook_config:
+    #   outbound_url: "http://127.0.0.1:9999/human-notify"
+    #   outbound_headers:
+    #     Content-Type: "application/json"
+    #     # Authorization: "Bearer ${WEBHOOK_TOKEN:}"
+    #   outbound_timeout: 30
+    #   # inbound_auth_token: "${WEBHOOK_AUTH_TOKEN:}"
+    #   max_retries: 1
+    #   retry_delay: 2
+    #   # response_mapping:
+    #   #   user_reply: "response"
+
+    # ── Native channel adapters (only needed when human_interface: "webhook") ──
+    # Connect this human agent directly to messaging platforms.
+    # The SDK registers inbound webhook routes automatically on startup.
+    # Uncomment + add credentials for the channels you want.
+    #
+    # Inbound routes registered per channel:
+    #   Slack:     POST /channels/slack/client/events
+    #   Telegram:  POST /channels/telegram/client/webhook
+    #   Discord:   POST /channels/discord/client/interactions
+    #   WhatsApp:  GET  /channels/whatsapp/client/webhook  (verification)
+    #              POST /channels/whatsapp/client/webhook  (messages)
+    #   Teams:     POST /channels/teams/client/messages
+    # channels:
+    #   slack:
+    #     bot_token: "${SLACK_BOT_TOKEN:}"          # xoxb-… Bot OAuth token
+    #     signing_secret: "${SLACK_SIGNING_SECRET:}" # HMAC-SHA256 signing secret
+    #     listen_channels: ["${SLACK_CHANNEL_ID:}"]  # Channel IDs (empty = all)
+    #     post_channel: "${SLACK_CHANNEL_ID:}"
+    #
+    #   telegram:
+    #     bot_token: "${TELEGRAM_BOT_TOKEN:}"         # Token from @BotFather
+    #     signing_secret: "${TELEGRAM_SECRET_TOKEN:}" # Optional webhook secret
+    #     listen_channels: []                          # Chat IDs (empty = all)
+    #     post_channel: ""
+    #
+    #   discord:
+    #     bot_token: "${DISCORD_BOT_TOKEN:}"          # Bot token (no "Bot " prefix)
+    #     signing_secret: "${DISCORD_PUBLIC_KEY:}"    # App public key (Ed25519)
+    #     listen_channels: []                          # Channel IDs (empty = all)
+    #     post_channel: ""
+    #
+    #   whatsapp:
+    #     bot_token: "${WHATSAPP_ACCESS_TOKEN:}"      # Meta Graph API access token
+    #     signing_secret: "${META_APP_SECRET:}"        # Meta app secret (HMAC-SHA256)
+    #     post_channel: "${WHATSAPP_PHONE_NUMBER_ID:}" # Phone number ID (not phone number)
+    #     verify_token: "leafmesh_whatsapp_verify"     # Match this in Meta developer dashboard
+    #
+    #   teams:
+    #     bot_token: "${TEAMS_APP_ID:}"               # Bot Framework App ID
+    #     signing_secret: "${TEAMS_APP_PASSWORD:}"    # Bot Framework App password
+    #     post_channel: ""                             # Set at runtime from inbound activity
+
+    yields:
+      request_data: "object"
+
+    inputs:
+      user_message: "string"
+      request_type: "string"
+
+    # auto_store_response: true        # Auto-store responses in Redis (default: true)
+    # auto_store_yields: true          # Auto-store yields in Redis (default: true)
+
+    # HITL routing — from_agent distinguishes who called the human agent
+    # When greeter calls client: from_agent == "greeter_agent" → route to processor
+    # When human initiates (no from_agent): route to greeter first
+    can_call:
+      - agent: "greeter_agent"
+        condition: "not calling_agent_response.from_agent"
+      - agent: "processor_agent"
+        condition: "calling_agent_response.from_agent == 'greeter_agent'"
+
+  # ─────────────────────────────────────────────
+  # LLM AGENT — @pre_compose prepares data, context_parts shape tone
+  # auto_discover matches greeter_agent() in agency/greeter_agent.py
+  #
+  # Flow: processors run → context_parts injected → LLM called →
+  #       agent function post-processes → can_call chains to next
+  # ─────────────────────────────────────────────
+  greeter_agent:
+    name: "greeter_agent"
+    agent_type: "llm"
+    description: "Greets the user and gathers their requirements"
+    # ── Supported models (auto-routed to correct provider by model name) ──
+    # OpenAI:     gpt-4o-mini, gpt-4o, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-5.1, gpt-5.2
+    # OpenAI o:   o1, o1-mini, o3, o3-mini, o4-mini  (reasoning models — use thinking: true)
+    # Anthropic:  claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5-20251001
+    # Google:     gemini-2.0-flash, gemini-2.5-pro, gemini-3-pro-preview
+    # DeepSeek:   deepseek-chat, deepseek-reasoner  (R1 — native chain-of-thought)
+    # Bedrock:    bedrock/<model-id>  (requires mesh.bedrock config)
+    # Vertex:     vertex/<model-id>   (requires mesh.vertex config)
+    # Foundry:    foundry/<deployment> (requires mesh.foundry config)
+    # Local:      any name (e.g. llama3, mistral-7b) — requires mesh.local config
+    model: "gpt-4o-mini"
+    temperature: 0.7
+    max_tokens: 1000
+    # max_completion_tokens: 2000         # For newer models (o1, gpt-5.x) — use instead of max_tokens
+    communication_type: "dual"        # Options: "dual", "chain", "execute"
+    reasoning: true                    # SDK chain-of-thought tool injection (works with any model)
+    # thinking: true                     # Native model thinking (Anthropic/OpenAI o-series/Gemini 2.5+)
+    # thinking_budget: 8192              # Max thinking tokens (1024-32768)
+    # enable_prompt_caching: true        # Provider-native prompt caching (Anthropic: ~90% savings)
+    # optimization_strategy: "performance"  # "performance" | "cost" | "speed"
+
+    prompt: |
+      You are a friendly assistant. Given the user's message,
+      greet them warmly and summarize what they need help with.
+      Return a clear, structured JSON summary with keys:
+      "greeting", "user_need", "suggested_actions"
+
+    # Structured output — force LLM to respond with valid JSON matching this schema
+    # response_format:
+    #   type: "object"
+    #   properties:
+    #     greeting: { type: "string" }
+    #     user_need: { type: "string" }
+    #     suggested_actions: { type: "array", items: { type: "string" } }
+    #   required: ["greeting", "user_need"]
+
+    # Context parts — injected as separate system messages before LLM call
+    # Each part shapes HOW the LLM responds (tone, analysis, safety)
+    context_parts:
+      care: |
+        Always respond with empathy and warmth. Acknowledge the user's
+        situation before jumping to solutions. Use encouraging language
+        and offer reassurance when the user seems frustrated.
+      sentiment_analysis: |
+        Analyze the user's emotional tone before responding.
+        If negative sentiment detected, prioritize acknowledgment over action.
+        If positive, match their energy and build on momentum.
+        Include a 'detected_sentiment' field in your JSON response.
+      guardrails: |
+        Never share internal system details or agent architecture.
+        Do not make promises about timelines or guarantees.
+        If the request is outside your domain, clearly redirect.
+        Refuse harmful, illegal, or unethical requests.
+
+    yields:
+      greeting: "string"
+      user_input: "string"
+      detected_sentiment: "string"
+      status: "string"
+
+    inputs:
+      message: "string"
+
+    # LLM can call these tools during generation
+    tools: ["word_count", "timestamp"]
+    # tool_categories: ["data"]           # Grant access to an entire tool category
+    tool_choice: "auto"
+    max_tool_calls_per_message: 5
+    # tool_call_timeout: 30               # Tool execution timeout in seconds (0.1-300, default: 30)
+    # allow_parallel_tool_calls: true     # Allow tools to run in parallel (default: true)
+
+    # memory: true                        # Simple bool — enable with defaults
+    # memory:                             # Dict form — full control
+    #   strategy: "recency"               # "recency" | "relevance" | "hybrid"
+    #   limit: 10
+    #   cross_session: false
+    # memory_limit: 10                    # Legacy: max feed posts (prefer memory.limit)
+
+    # auto_store_response: true
+    # auto_store_yields: true
+
+    # Mesh chain — routes to human agent for review before processing
+    # In HITL flow: greeter → client (human reviews) → processor
+    can_call:
+      - agent: "client"
+
+    # Narration — plain-English routing hints for the Manager.
+    # Evaluated by the Summarizer when conditions alone don't cover everything.
+    # The Manager can route to ANY registered agent, not just those in can_call.
+    narration: >
+      If the user's request is urgent or mentions an escalation keyword,
+      route directly to advisor_agent — skip the processing step.
+      If the user asks for a scheduled report, route to scheduler_agent.
+
+  # ─────────────────────────────────────────────
+  # PROGRAMMATIC AGENT — @conditional_chain for branching logic
+  # auto_discover matches processor_agent() in agency/processor_agent.py
+  #
+  # Flow: receives greeter output → processes → conditional_chain
+  #       branches → can_call with conditions fans out to both agents
+  # ─────────────────────────────────────────────
+  processor_agent:
+    name: "processor_agent"
+    agent_type: "programmatic"
+    description: "Processes the greeter's output into actionable items"
+    communication_type: "chain"
+    parallel: true                     # Enable parallel processing
+    max_concurrent: 3                  # Max concurrent invocations
+    # auto_store_response: true        # Auto-store responses in Redis (default: true)
+    # auto_store_yields: true          # Auto-store yields in Redis (default: true)
+
+    yields:
+      processed_items: "list"
+      item_count: "number"
+      status: "string"
+      alert: "string"
+
+    inputs:
+      greeter_result: "object"
+
+    # Fan-out: researcher, fallback_researcher, and advisor are all called
+    can_call:
+      - agent: "researcher_agent"
+        condition: "calling_agent_response.item_count > 0"
+      - agent: "fallback_researcher_agent"
+        condition: "calling_agent_response.item_count > 0"
+      - agent: "advisor_agent"
+        condition: "calling_agent_response.item_count > 0"
+
+    # Narration — non-definitive routing the Manager evaluates via the Summarizer.
+    # These hints catch cases conditions can't express as boolean checks.
+    narration: >
+      If the processed items contain anything safety-related or flagged as high-risk,
+      route to advisor_agent immediately without waiting for research.
+      If the alert field mentions a data quality issue, route to fallback_researcher_agent only.
+
+  # ─────────────────────────────────────────────
+  # LLM AGENT — @chain_with_results for accumulating pipeline
+  # auto_discover matches researcher_agent() in agency/researcher_agent.py
+  #
+  # Features: memory, tool_categories, reasoning, parallel tool calls
+  # optimization_strategy controls model selection:
+  #   "performance" — pick the most capable model
+  #   "cost"        — pick the cheapest model that meets quality
+  #   "speed"       — pick the lowest-latency model
+  # ─────────────────────────────────────────────
+  researcher_agent:
+    name: "researcher_agent"
+    agent_type: "llm"
+    description: "Researches topics using tools and memory context"
+    model: "gpt-4o-mini"
+    temperature: 0.5
+    max_tokens: 1500
+    communication_type: "chain"
+    optimization_strategy: "performance"
+    reasoning: true                    # SDK chain-of-thought tool injection
+    thinking: true                     # Native model thinking for deep analysis
+    thinking_budget: 8192              # Max thinking tokens
+    enable_prompt_caching: true        # Cache system prompt + tools (~90% savings on Anthropic)
+
+    # ── Smart memory (BRD-009) ──
+    # Dict form enables advanced memory strategies. No external deps — Redis only.
+    # "hybrid" blends recency + relevance scoring for context selection.
+    memory:
+      strategy: "hybrid"               # "recency" | "relevance" | "hybrid"
+      limit: 10                        # Max feed posts to load per invocation
+      cross_session: true              # Persist memory across sessions
+      cross_session_limit: 50          # Max cross-session posts to retain
+      relevance_weight: 0.6            # Weight for relevance scoring (0.0-1.0)
+      recency_weight: 0.4             # Weight for recency scoring (0.0-1.0)
+      decay_hours: 24                  # Hours before old entries decay
+
+    prompt: |
+      You are a research analyst. Analyze the provided data thoroughly.
+      Use available tools to gather additional information.
+      Return structured findings with confidence scores.
+
+    yields:
+      findings: "list"
+      query: "string"
+      analysis: "object"
+      report: "object"
+      status: "string"
+
+    inputs:
+      research_topic: "string"
+      processed_data: "object"
+
+    # Tools: specific tools + entire category
+    tools: ["math_eval", "timestamp", "sensitive_data_lookup"]
+    tool_categories: ["data"]
+    tool_choice: "auto"
+    allow_parallel_tool_calls: true
+    max_tool_calls_per_message: 10
+    # tool_call_timeout: 30
+    # auto_store_response: true
+    # auto_store_yields: true
+
+    can_call:
+      - agent: "advisor_agent"
+
+  # ─────────────────────────────────────────────
+  # PROGRAMMATIC AGENT — Fast fallback researcher (no LLM)
+  # auto_discover matches fallback_researcher_agent() in agency/fallback_researcher_agent.py
+  #
+  # Race pattern: runs instantly while researcher_agent waits for LLM.
+  # advisor_agent's OR fan-in resolves as soon as this completes.
+  # ─────────────────────────────────────────────
+  fallback_researcher_agent:
+    name: "fallback_researcher_agent"
+    agent_type: "programmatic"
+    description: "Fast template-based research fallback — instant, no LLM"
+    communication_type: "chain"
+
+    yields:
+      findings: "list"
+      query: "string"
+      analysis: "object"
+      report: "object"
+      status: "string"
+
+    inputs:
+      processed_data: "object"
+
+    can_call:
+      - agent: "advisor_agent"
+
+  # ─────────────────────────────────────────────
+  # LLM AGENT — @chain + @compose (fan-in advisor)
+  # auto_discover matches advisor_agent() in agency/advisor_agent.py
+  #
+  # Flow: waits for processor AND researcher → LLM analyzes →
+  #       @compose shapes output → @chain validates + scores
+  # ─────────────────────────────────────────────
+  advisor_agent:
+    name: "advisor_agent"
+    agent_type: "llm"
+    description: "Analyzes upstream results and produces actionable recommendations"
+    model: "gpt-4o-mini"
+    temperature: 0.3
+    max_tokens: 1000
+    communication_type: "chain"
+    optimization_strategy: "performance"
+
+    # ── Fan-in with OR expression ──
+    # Waits for processor AND whichever research agent finishes first.
+    # The fallback_researcher_agent is instant (programmatic), so this
+    # typically resolves before researcher_agent's LLM call completes.
+    #
+    # Supported wait_for patterns:
+    #   "A AND B"                  — waits for both A and B
+    #   "A OR B"                   — waits for either A or B (first wins)
+    #   "A AND B?"                 — A required, B optional
+    #   "A AND (B OR C)"           — A required + first of B or C (used here)
+    #   "A AND (B OR C) AND D?"    — A required + first of B/C + D optional
+    # When called from processor_agent chain: waits for processor + research
+    # When called from scheduler_agent: no wait_for needed (single upstream)
+    # The SDK evaluates wait_for only when multiple upstreams are pending.
+    wait_for: "processor_agent AND (researcher_agent OR fallback_researcher_agent)"
+    wait_for_timeout: 120
+
+    prompt: |
+      You are a strategic advisor. Analyze the processed data and research
+      findings provided. Produce actionable recommendations with priority
+      scoring. Identify risks and suggest concrete next steps.
+
+    yields:
+      recommendations: "list"
+      risk_assessment: "string"
+      priority_score: "number"
+      next_steps: "list"
+      status: "string"
+
+    # Strict yields contract — Manager auto-retries (with feedback) when the
+    # advisor's output doesn't match the schema above. Each retry sees the
+    # previous (wrong) output + validation errors as _rerun_context so the
+    # LLM can self-correct. After enforce_yields_retry attempts, the
+    # Manager escalates instead of looping forever.
+    # enforce_yields: true
+    # enforce_yields_retry: 2
+
+    inputs:
+      processed_data: "object"
+      research_findings: "object"
+
+    # auto_store_response: true
+    # auto_store_yields: true
+
+  # ─────────────────────────────────────────────
+  # SCHEDULED AGENT — Cron wake_up + on-demand entry point
+  # auto_discover matches scheduler_agent() in agency/scheduler_agent.py
+  # Runs daily at 9 AM UTC AND via mesh_call("scheduled_report", data)
+  # Chains output to advisor_agent for LLM-powered analysis
+  # ─────────────────────────────────────────────
+  scheduler_agent:
+    name: "scheduler_agent"
+    agent_type: "programmatic"
+    description: "Generates periodic status reports and chains to advisor for analysis"
+    communication_type: "chain"        # Chain output to downstream agents
+    wake_up: "0 9 * * *"              # Every day at 9 AM UTC
+
+    yields:
+      report: "string"
+      generated_at: "string"
+      checks: "object"
+      metrics: "object"
+      status: "string"
+
+    inputs:
+      trigger: "string"
+
+    # memory: false                    # Enable if scheduler needs historical context
+    # auto_store_response: true
+    # auto_store_yields: true
+
+    # Chain scheduled reports to advisor for analysis
+    can_call:
+      - agent: "advisor_agent"
+        condition: "calling_agent_response.status == 'report_generated'"
+
+  # ═══════════════════════════════════════════════════
+  # EXTERNAL AGENTS (uncomment when framework is installed)
+  # One agent = one specific action/workflow/graph.
+  # Create multiple agents with different connector_config for multiple workflows.
+  # See agency/external_agents.py for Python implementations
+  # ═══════════════════════════════════════════════════
+
+  # ─── CrewAI ───
+  # crewai_research:
+  #   name: "crewai_research"
+  #   agent_type: "external"
+  #   framework: "crewai"
+  #   description: "Delegates research to a CrewAI crew"
+  #   connector_config:
+  #     endpoint: "${CREWAI_ENDPOINT:http://localhost:9000}"  # Required
+  #     api_key: "${CREWAI_API_KEY:}"                         # Bearer Token
+  #     # user_api_key: "${CREWAI_USER_API_KEY:}"             # User Bearer Token (preferred over api_key)
+  #     # poll_interval: 2.0           # Seconds between status polls (default: 2.0)
+  #     # max_poll_seconds: 300.0      # Max total polling time (default: 300)
+  #     # http_timeout: 30.0           # HTTP request timeout (default: 30)
+  #   yields:
+  #     research_result: "string"
+  #     sources: "list"
+  #   can_call:
+  #     - agent: "advisor_agent"
+
+  # ─── LangGraph ───
+  # langgraph_workflow:
+  #   name: "langgraph_workflow"
+  #   agent_type: "external"
+  #   framework: "langgraph"
+  #   description: "Runs a LangGraph stateful workflow"
+  #   connector_config:
+  #     endpoint: "${LANGGRAPH_ENDPOINT:http://localhost:8123}"  # Required
+  #     api_key: "${LANGCHAIN_API_KEY:}"
+  #     graph_id: "my_graph"           # Workflow selector — which graph to run (default: "agent")
+  #     # poll_interval: 1.0
+  #     # max_poll_seconds: 300.0
+  #     # http_timeout: 30.0
+  #   yields:
+  #     workflow_result: "object"
+
+  # ─── AutoGen ───
+  # autogen_team:
+  #   name: "autogen_team"
+  #   agent_type: "external"
+  #   framework: "autogen"
+  #   description: "Multi-agent conversation via external AutoGen Studio"
+  #   connector_config:
+  #     endpoint: "http://localhost:8081"   # AutoGen Studio or custom API URL
+  #     # api_key: "${AUTOGEN_API_KEY:}"   # Bearer token (optional)
+  #     # workflow_id: ""                  # Workflow/agent ID to execute
+  #     # timeout: 120                     # HTTP request timeout (seconds)
+  #     # poll_interval: 2                 # Seconds between status polls
+  #     # max_poll_seconds: 300            # Max total polling time
+  #   yields:
+  #     team_result: "string"
+
+  # ─── A2A (Agent-to-Agent Protocol) ───
+  # a2a_partner:
+  #   name: "a2a_partner"
+  #   agent_type: "external"
+  #   framework: "a2a"
+  #   description: "Communicates with an A2A-compatible agent"
+  #   connector_config:
+  #     url: "${A2A_AGENT_URL:http://partner-agent:8080}"  # Required (use 'url', not 'endpoint')
+  #     auth_token: "${A2A_AUTH_TOKEN:}"
+  #     # auth_scheme: "Bearer"        # Authorization header scheme (default: "Bearer")
+  #     # poll_interval: 2.0
+  #     # max_poll_seconds: 300.0
+  #     # http_timeout: 30.0
+  #   yields:
+  #     partner_response: "object"
+
+  # ─── MCP (Model Context Protocol) ─── http transport
+  # mcp_http_tool:
+  #   name: "mcp_http_tool"
+  #   agent_type: "external"
+  #   framework: "mcp"
+  #   description: "Access tools from an MCP server via HTTP"
+  #   connector_config:
+  #     tool_name: "my_tool"              # Required: name of the tool to call
+  #     transport: "http"                  # "http" or "stdio"
+  #     url: "${MCP_ENDPOINT:http://localhost:5000}"  # MCP server URL (use 'url', not 'endpoint')
+  #     auth_token: "${MCP_API_KEY:}"
+  #     # timeout: 60.0
+  #   yields:
+  #     tool_results: "object"
+
+  # ─── MCP (Model Context Protocol) ─── stdio transport
+  # mcp_stdio_tool:
+  #   name: "mcp_stdio_tool"
+  #   agent_type: "external"
+  #   framework: "mcp"
+  #   description: "Access tools from a local MCP server via stdio"
+  #   connector_config:
+  #     tool_name: "my_tool"              # Required: name of the tool to call
+  #     transport: "stdio"
+  #     command: "npx"                    # Executable to launch
+  #     args: ["-y", "@mcp/server-npm"]   # Command arguments
+  #     # env:                            # Environment variables for subprocess
+  #     #   MY_VAR: "value"
+  #     # timeout: 60.0
+  #   yields:
+  #     tool_results: "object"
+
+  # ─── Zapier ───
+  # zapier_sheets:
+  #   name: "zapier_sheets"
+  #   agent_type: "external"
+  #   framework: "zapier"
+  #   description: "Trigger Zapier actions — MCP path (prefer_mcp=true) or REST fallback"
+  #   connector_config:
+  #     connection: "google_sheets"        # App name (connection + action = tool name)
+  #     action: "create_row"              # Action to perform — workflow selector
+  #     mcp_key: "${ZAPIER_MCP_KEY:}"    # MCP path (preferred)
+  #     api_key: "${ZAPIER_API_KEY:}"    # REST fallback
+  #     # prefer_mcp: true               # Try MCP first, fall back to REST (default: true)
+  #     # instructions: ""               # Natural language instructions (REST path only)
+  #     # timeout: 60.0
+  #   yields:
+  #     action_result: "object"
+
+  # ─── Composio ───
+  # composio_github:
+  #   name: "composio_github"
+  #   agent_type: "external"
+  #   framework: "composio"
+  #   description: "Access Composio-managed integrations"
+  #   connector_config:
+  #     action: "GITHUB_STAR_A_REPOSITORY"  # Required: single Composio action — workflow selector
+  #     entity_id: "default"               # User/entity to act on behalf of
+  #     api_key: "${COMPOSIO_API_KEY:}"
+  #     # timeout: 60.0
+  #   yields:
+  #     integration_result: "object"
+
+  # ─── n8n ───
+  # n8n_workflow:
+  #   name: "n8n_workflow"
+  #   agent_type: "external"
+  #   framework: "n8n"
+  #   description: "Trigger n8n workflows via webhook"
+  #   connector_config:
+  #     webhook_url: "${N8N_WEBHOOK_URL:}"  # Required — each workflow has its own URL
+  #     auth_token: "${N8N_AUTH_TOKEN:}"
+  #     # timeout: 60.0                    # HTTP timeout (sync mode only)
+  #     # mode: "sync"                     # "sync" (default) or "callback"
+  #     # callback_timeout: 120.0          # Seconds to wait for callback (callback mode only)
+  #   yields:
+  #     workflow_result: "object"
+  #
+  # n8n + callback mode:
+  #   Use mode: "callback" when n8n workflow uses "Respond Immediately".
+  #   LeafMesh injects _leafmesh_callback_url + _leafmesh_session_id into payload.
+  #   n8n workflow should end with HTTP Request node POSTing result back to that URL.
+  #
+  # n8n_async_workflow:
+  #   name: "n8n_async_workflow"
+  #   agent_type: "external"
+  #   framework: "n8n"
+  #   description: "Long-running n8n workflow with async callback"
+  #   connector_config:
+  #     webhook_url: "${N8N_WEBHOOK_URL:}"
+  #     mode: "callback"
+  #     callback_timeout: 300.0            # 5 min — workflow takes time to process
+  #   yields:
+  #     workflow_result: "object"
+
+  # ═══════════════════════════════════════════════════
+  # PROGRAMMATIC + INTEGRATION AGENTS
+  # Same connectors as external agents but paired with Python intelligence.
+  # SDK reads connector_config in the same way — pass connection details here.
+  # One agent = one specific action/workflow.
+  # ═══════════════════════════════════════════════════
+
+  # ─── Zapier (programmatic) ───
+  # zapier_sheets:
+  #   name: "zapier_sheets"
+  #   agent_type: "programmatic"
+  #   description: "Adds a row to Google Sheets via Zapier"
+  #   communication_type: "chain"
+  #   integration: "zapier"              # Options: zapier | composio | n8n | mcp
+  #   connector_config:
+  #     connection: "google_sheets"      # Zapier app name  ┐ combined into
+  #     action: "create_row"            # Zapier action     ┘ google_sheets_create_row
+  #     mcp_key: "${ZAPIER_MCP_KEY:}"   # MCP path (preferred)
+  #     api_key: "${ZAPIER_API_KEY:}"   # REST fallback
+  #     # prefer_mcp: true
+  #     # instructions: ""
+  #     # timeout: 60.0
+  #   yields:
+  #     result: "object"
+
+  # ─── Composio (programmatic) ───
+  # composio_github:
+  #   name: "composio_github"
+  #   agent_type: "programmatic"
+  #   description: "Stars a GitHub repo via Composio"
+  #   communication_type: "chain"
+  #   integration: "composio"
+  #   connector_config:
+  #     action: "GITHUB_STAR_A_REPOSITORY"  # Required: Composio action enum (UPPERCASE)
+  #     entity_id: "default"               # User/entity context
+  #     api_key: "${COMPOSIO_API_KEY:}"
+  #     # timeout: 60.0
+  #   yields:
+  #     result: "object"
+
+  # ─── n8n (programmatic) ───
+  # n8n_notify:
+  #   name: "n8n_notify"
+  #   agent_type: "programmatic"
+  #   description: "Triggers an n8n workflow via webhook"
+  #   communication_type: "chain"
+  #   integration: "n8n"
+  #   connector_config:
+  #     webhook_url: "${N8N_WEBHOOK_URL:}"  # Required — each workflow has its own URL
+  #     auth_token: "${N8N_AUTH_TOKEN:}"
+  #     # timeout: 60.0
+  #     # mode: "callback"                 # Use callback for async/long-running workflows
+  #     # callback_timeout: 120.0
+  #   yields:
+  #     result: "object"
+
+  # ─── MCP (programmatic) ─── http transport
+  # mcp_search:
+  #   name: "mcp_search"
+  #   agent_type: "programmatic"
+  #   description: "Calls a specific tool on an MCP server"
+  #   communication_type: "chain"
+  #   integration: "mcp"
+  #   connector_config:
+  #     tool_name: "web_search"                   # Required: tool to invoke
+  #     transport: "http"                         # "http" or "stdio"
+  #     url: "${MCP_ENDPOINT:http://localhost:5000}"  # MCP server URL
+  #     auth_token: "${MCP_API_KEY:}"
+  #     # timeout: 60.0
+  #   yields:
+  #     result: "object"
+
+  # ─── MCP (programmatic) ─── stdio transport
+  # mcp_local:
+  #   name: "mcp_local"
+  #   agent_type: "programmatic"
+  #   description: "Calls a tool on a local MCP server via stdio"
+  #   communication_type: "chain"
+  #   integration: "mcp"
+  #   connector_config:
+  #     tool_name: "my_tool"           # Required: tool to invoke
+  #     transport: "stdio"
+  #     command: "npx"
+  #     args: ["-y", "@mcp/server-npm"]
+  #     # env:
+  #     #   MY_VAR: "value"
+  #     # timeout: 60.0
+  #   yields:
+  #     result: "object"
+
+# ═══════════════════════════════════════════════════
+# DATA STRUCTURES — Custom data type definitions (optional)
+# Define shared schemas that agents can reference for validation
+# ═══════════════════════════════════════════════════
+# data_structures:
+#   customer_profile:
+#     type: "object"
+#     properties:
+#       name: { type: "string" }
+#       email: { type: "string" }
+#       tier: { type: "string" }
+#     required: ["name", "email"]
+#     validation_rules:
+#       email: "email_format"
+#   order_item:
+#     type: "object"
+#     properties:
+#       product_id: { type: "string" }
+#       quantity: { type: "number" }
+#       price: { type: "number" }
+#     required: ["product_id", "quantity"]
+
+# Self-healing is always enabled (core safety feature, no config needed)
+
+# ═══════════════════════════════════════════════════
+# EVOLUTION — Genetic algorithm optimization
+# Set enabled: true and provide test_scenarios to auto-run on start()
+# Or call leafmesh.evolve_mesh_architecture(scenarios) at runtime
+# ═══════════════════════════════════════════════════
+# evolution:
+#   enabled: true
+#   strategy: "genetic"
+#   population_size: 10
+#   generations: 50
+#   mutation_rate: 0.1
+#   crossover_rate: 0.7
+#   elite_size: 2
+#   mutation_types:
+#     - "prompt_variation"
+#     - "temperature_adjustment"
+#     - "tool_selection"
+#   fitness_function: "task_completion_rate"
+#   selection_method: "tournament"
+#   test_scenarios: []
+
+# ═══════════════════════════════════════════════════
+# OBSERVABILITY
+#
+# Observability auto-enables when LEAFMESH_LICENSE_KEY is set in .env.
+# No YAML config needed — traces, metrics, and logs flow automatically.
+# Set LEAFMESH_ENV_TOKEN in .env to group telemetry by environment.
+# ═══════════════════════════════════════════════════
+
+# ═══════════════════════════════════════════════════
+# API ENDPOINTS (built-in, no config needed)
+#
+# Trigger workflows:
+#   POST /api/mesh/request          — trigger agent workflow via entry point
+#   POST /api/mesh/stream           — SSE stream of LLM response via entry point
+#   GET  /api/mesh/entry_points     — list available entry points
+#
+# Webhooks (HITL + external integrations):
+#   POST /webhook/{entry_point}     — new task OR resume human HITL response
+#   GET  /api/webhook/secret        — HMAC signing secret for webhook auth
+#
+# Sessions:
+#   POST /api/sessions/{session_id}/agents/{agent_name}/rerun
+#                                   — re-run an agent in an existing session
+#                                     with optional feedback / new input
+#                                     (used by ADK Studio "Rerun" button;
+#                                     mirrors sdk.rerun_agent in Python)
+#
+# Native channel adapters (registered when channels: is configured on a human agent):
+#   POST /channels/slack/{agent}/events          — Slack Events API
+#   POST /channels/telegram/{agent}/webhook      — Telegram Bot updates
+#   POST /channels/discord/{agent}/interactions  — Discord interactions
+#   GET  /channels/whatsapp/{agent}/webhook      — WhatsApp webhook verification
+#   POST /channels/whatsapp/{agent}/webhook      — WhatsApp messages
+#   POST /channels/teams/{agent}/messages        — Microsoft Teams activities
+#
+# Config validation:
+#   POST /api/yaml/validate         — validate a full config body (for editors)
+#
+# System:
+#   GET  /health                    — health check
+#   GET  /docs                      — interactive API docs (ReDoc)
+# ═══════════════════════════════════════════════════