create-leafmesh 2.1.0__py3-none-any.whl

create_leafmesh/templates/docker-compose.yml

@@ -0,0 +1,28 @@
+services:
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+
+  app:
+    build: .
+    ports:
+      - "18820:18820"
+    env_file:
+      - .env
+    environment:
+      REDIS_HOST: redis
+      REDIS_PORT: 6379
+    depends_on:
+      redis:
+        condition: service_healthy
+
+volumes:
+  redis_data:

create_leafmesh/templates/dockerignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+env/
+.env
+.git/
+.gitignore
+.vscode/
+.idea/
+logs/
+*.log
+.DS_Store
+Thumbs.db

create_leafmesh/templates/env

@@ -0,0 +1,109 @@
+# {{project_name}} environment variables
+
+# Required
+LEAFMESH_LICENSE_KEY=your-license-key-here    # Get yours at https://leafcraft.ai
+OPENAI_API_KEY=your-key-here
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+
+# Alternative LLM Providers (uncomment to use)
+# ANTHROPIC_API_KEY=your-anthropic-key
+# GOOGLE_API_KEY=your-google-key
+# DEEPSEEK_API_KEY=your-deepseek-key
+
+# Microsoft Foundry / Azure AI (uncomment to use)
+# AZURE_FOUNDRY_API_KEY=your-foundry-api-key
+# AZURE_FOUNDRY_TOKEN=your-entra-id-token          # Alternative: Entra ID bearer token
+
+# External Integrations (uncomment when needed)
+# COMPOSIO_API_KEY=your-composio-key
+# ZAPIER_NLA_API_KEY=your-zapier-key
+# N8N_BASE_URL=http://localhost:5678
+# N8N_API_KEY=your-n8n-key
+# CREWAI_API_KEY=your-crewai-key
+# LANGGRAPH_API_URL=http://localhost:8123
+# LANGGRAPH_API_KEY=your-langgraph-key
+
+# Webhooks (for human agent interface)
+# WEBHOOK_OUTBOUND_URL=https://your-webhook-endpoint.com
+# WEBHOOK_TOKEN=your-webhook-token
+# WEBHOOK_AUTH_TOKEN=your-inbound-auth-token
+
+# API Server
+# Default port is 18820. Change if running multiple projects locally.
+# LEAFMESH_API_PORT=18820
+
+# Observability
+# Observability auto-enables with a valid LEAFMESH_LICENSE_KEY.
+# LEAFMESH_ENV_TOKEN is your unique environment key (from https://leafcraft.ai).
+LEAFMESH_ENV_TOKEN=your-env-token-here
+
+# ────────────────────────────────────────────────────────────────────────
+# Optional security / hardening knobs
+# All have safe defaults — uncomment only when you need to tune them.
+# ────────────────────────────────────────────────────────────────────────
+
+# X-API-Key auth middleware. Default in the SDK is ON — every request to
+# the API server must carry a valid X-API-Key header (validated against
+# the LeafCraft auth backend). For LOCAL DEVELOPMENT WITHOUT INTERNET or
+# without a real LeafCraft account yet, set to 0 to disable the middleware
+# entirely (no header required, no backend call, requests pass through).
+# Never set =0 in production.
+# LEAFMESH_AUTH_STRICT=1
+
+# Cookie SameSite policy for SSE auth (HITL / evolution / trace streams).
+# Default Lax = cookie sent only on same-site requests. Set to None when
+# your frontend lives on a different host than the SDK (ADK Studio at
+# app.example.com → SDK at api.example.com, or local dev with frontend
+# on localhost:5173 → SDK on 127.0.0.1:18820). The SDK auto-flips
+# Secure=true with None; loopback HTTP works because browsers treat
+# 127.0.0.1 / localhost as secure contexts.
+# LEAFMESH_SSE_COOKIE_SAMESITE=None
+
+# OTel — span attribute redaction. Default ON (user input/output replaced
+# with `<redacted bytes:N>` before export). Set to 0 to ship raw content
+# (only for self-hosted OTel collectors with strict access control).
+# LEAFMESH_OTEL_REDACT_PII=1
+
+# OTel content redaction toggle for the prompt-builder guardrail. Off-switch
+# for the BEGIN/END_USER_MESSAGE / BEGIN/END_TOOL_RESULT delimiters.
+# LEAFMESH_DISABLE_PROMPT_GUARDRAIL=0
+
+# Webhook hardening (HMAC + replay protection).
+# Set to 1 to keep accepting body-only HMAC during a migration window.
+# LEAFMESH_WEBHOOK_ALLOW_LEGACY_HMAC=0
+# LEAFMESH_WEBHOOK_REPLAY_SKEW_S=300
+# LEAFMESH_WEBHOOK_RATE_LIMIT_MAX=60
+# LEAFMESH_WEBHOOK_RATE_LIMIT_WINDOW_S=60
+# LEAFMESH_WEBHOOK_MAX_PAYLOAD_BYTES=1048576    # 1 MiB
+
+# Knowledge ingest / query caps.
+# LEAFMESH_KNOWLEDGE_MAX_DOCS_PER_INGEST=1000
+# LEAFMESH_KNOWLEDGE_MAX_DOC_BYTES=2097152      # 2 MiB
+# LEAFMESH_KNOWLEDGE_MAX_INGEST_TOTAL_BYTES=52428800  # 50 MiB
+# LEAFMESH_KNOWLEDGE_QUERY_RATE_LIMIT_MAX=120
+# LEAFMESH_KNOWLEDGE_QUERY_RATE_LIMIT_WINDOW_S=60
+
+# LLM hard timeout — prevents a stuck provider from pinning an agent slot.
+# LEAFMESH_LLM_HARD_TIMEOUT_S=300
+
+# Cron min-interval (seconds). Default 60s — schedules below this are rejected.
+# LEAFMESH_CRON_MIN_INTERVAL_SECONDS=60
+
+# MCP subprocess allowlist (comma-separated absolute paths or basenames).
+# Empty = warn-only at startup. Set to "*" for "any command" with explicit
+# operator opt-in. Anything else acts as a strict allowlist.
+# LEAFMESH_MCP_COMMAND_ALLOWLIST=
+
+# Teams adapter — fail-closed by default. Set to 1 only for local development
+# behind a tunnel (production must wire a Bot Framework JWT validator).
+# LEAFMESH_TEAMS_ALLOW_UNVERIFIED=0
+
+# Conversation history hard byte cap (per session).
+# LEAFMESH_MAX_SESSION_HISTORY_BYTES=5242880    # 5 MiB
+
+# Security headers.
+# LEAFMESH_HSTS_ENABLED=1
+# LEAFMESH_REFERRER_POLICY=no-referrer
+# LEAFMESH_CSP="default-src 'none'; frame-ancestors 'none'; base-uri 'none'"

create_leafmesh/templates/gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environment
+.venv/
+venv/
+env/
+
+# Environment variables
+.env
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Logs
+logs/
+*.log
+
+# Docker
+docker-compose.override.yml
+
+# OS
+.DS_Store
+Thumbs.db

create_leafmesh/templates/hitl_stub_receiver.py

@@ -0,0 +1,149 @@
+"""
+HITL Stub Receiver — captures outbound webhook notifications from LeafMesh.
+
+When the SDK's human agent (client) receives a task mid-flow, it sends an
+outbound webhook to this stub. This simulates the external system that would
+notify a real human (Slack, email, dashboard, etc).
+
+The stub prints the webhook payload and a ready-to-use curl command so you
+can respond as the human and continue the agent chain.
+
+Usage:
+    # Terminal 1: start the stub receiver
+    python hitl_stub_receiver.py
+
+    # Terminal 2: start the mesh
+    python main.py
+
+    # Terminal 3: trigger the mesh (Scenario 1 — system-initiated)
+    curl -X POST http://127.0.0.1:18820/api/mesh/request \\
+      -H "Content-Type: application/json" \\
+      -d '{"entry_point": "greet_user", "data": {"message": "I need help with my order"}}'
+
+    # ... the stub will print the outbound webhook + curl command to respond
+
+See README.md for full HITL walkthrough (Scenario 1 and Scenario 2).
+"""
+import json
+import sys
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from datetime import datetime
+
+
+class StubHandler(BaseHTTPRequestHandler):
+    def do_POST(self):
+        length = int(self.headers.get("Content-Length", 0))
+        body = self.rfile.read(length)
+
+        print(f"\n{'='*60}")
+        print(f"[{datetime.now().strftime('%H:%M:%S')}] OUTBOUND WEBHOOK RECEIVED")
+        print(f"Path: {self.path}")
+        print(f"{'='*60}")
+
+        try:
+            payload = json.loads(body)
+            print(json.dumps(payload, indent=2, default=str))
+
+            # Extract useful info for the human response
+            session_id = payload.get("session_id", "unknown")
+            agent = payload.get("agent_name", payload.get("from_agent", "unknown"))
+            print(f"\n>>> To respond as the human, POST to the LeafMesh server.")
+            print(f">>> The SDK binds HMAC to a fresh timestamp + nonce —")
+            print(f">>> see the helper at the bottom of this file for a working example.")
+            print(f"")
+            print(f"    SECRET=$(curl -s http://127.0.0.1:18820/api/webhook/secret | jq -r .webhook_secret)")
+            print(f"    TS=$(date +%s)")
+            print(f"    NONCE=$(python3 -c 'import secrets; print(secrets.token_urlsafe(16))')")
+            print(f"    BODY='{{\"session_id\": \"{session_id}\", \"decision\": \"approved\", \"message\": \"Looks good, proceed\"}}'")
+            print(f"    SIG=$(printf '%s' \"$TS.$NONCE.$BODY\" | openssl dgst -sha256 -hmac \"$SECRET\" -hex | awk '{{print $NF}}')")
+            print(f"    curl -X POST http://127.0.0.1:18820/webhook/greet_user \\\\")
+            print(f'      -H "Content-Type: application/json" \\\\')
+            print(f'      -H "X-LeafMesh-Signature: sha256=$SIG" \\\\')
+            print(f'      -H "X-LeafMesh-Timestamp: $TS" \\\\')
+            print(f'      -H "X-LeafMesh-Nonce: $NONCE" \\\\')
+            print(f"      -d \"$BODY\"")
+        except Exception:
+            print(body.decode(errors="replace"))
+
+        print(f"{'='*60}\n")
+        sys.stdout.flush()
+
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(json.dumps({"status": "received"}).encode())
+
+    def log_message(self, format, *args):
+        pass  # Suppress default logging
+
+
+def sign_and_post_response(
+    session_id: str,
+    decision: str = "approved",
+    message: str = "Looks good, proceed",
+    leafmesh_url: str = "http://127.0.0.1:18820",
+    entry_point: str = "greet_user",
+) -> int:
+    """Reference implementation for signing a HITL response on the SDK's
+    HMAC-with-timestamp-and-nonce scheme.
+
+    Pulls the webhook secret from /api/webhook/secret, builds the canonical
+    signed material (`f"{ts}.{nonce}.".encode() + body`), and POSTs to
+    /webhook/{entry_point} with all three headers.
+
+    Returns the HTTP status code.
+    """
+    import hmac as _hmac
+    import hashlib as _hashlib
+    import secrets as _secrets
+    import time as _time
+    import urllib.request as _ur
+
+    # Fetch the signing secret from the SDK.
+    try:
+        with _ur.urlopen(f"{leafmesh_url}/api/webhook/secret", timeout=5) as resp:
+            secret_data = json.loads(resp.read())
+    except Exception as e:
+        print(f"Could not fetch webhook secret from {leafmesh_url}: {e}")
+        return 0
+    secret = (secret_data or {}).get("webhook_secret")
+    if not secret:
+        print("Server is not configured for webhook auth — set LEAFMESH_LICENSE_KEY or LEAFMESH_WEBHOOK_SECRET.")
+        return 0
+
+    body = json.dumps(
+        {"session_id": session_id, "decision": decision, "message": message}
+    ).encode("utf-8")
+    timestamp = str(int(_time.time()))
+    nonce = _secrets.token_urlsafe(16)
+    signed_material = f"{timestamp}.{nonce}.".encode("utf-8") + body
+    sig = _hmac.new(secret.encode("utf-8"), signed_material, _hashlib.sha256).hexdigest()
+
+    req = _ur.Request(
+        f"{leafmesh_url}/webhook/{entry_point}",
+        data=body,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "X-LeafMesh-Signature": f"sha256={sig}",
+            "X-LeafMesh-Timestamp": timestamp,
+            "X-LeafMesh-Nonce": nonce,
+        },
+    )
+    try:
+        with _ur.urlopen(req, timeout=10) as resp:
+            return resp.status
+    except Exception as e:
+        print(f"POST failed: {e}")
+        return 0
+
+
+if __name__ == "__main__":
+    server = HTTPServer(("127.0.0.1", 9999), StubHandler)
+    print(f"HITL Stub Receiver listening on http://127.0.0.1:9999")
+    print(f"Waiting for outbound webhook notifications from LeafMesh...\n")
+    sys.stdout.flush()
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\nStopped.")

create_leafmesh/templates/main.py

@@ -0,0 +1,105 @@
+"""{{project_name}} — LeafMesh Multi-Agent Project
+
+Agent registration:
+  - agency/*_agent.py  → auto_discover matches function names to YAML agent names
+  - agency/tools.py    → import here so @global_tool decorators register
+
+Standalone decorators (no leafmesh instance needed):
+  from leafmesh import pre_compose, chain, compose, conditional_chain, chain_with_results
+"""
+import asyncio
+import signal
+from dotenv import load_dotenv
+from leafmesh import LeafMesh, LeafMeshLogger
+
+# Import tools so @global_tool decorators register before leafmesh.start()
+import agency.tools  # noqa: F401
+
+load_dotenv()
+logger = LeafMeshLogger(__name__)
+
+# auto_discover in config.yaml wires agency/*_agent.py files automatically
+leafmesh = LeafMesh.from_yaml("configs/config.yaml")
+
+
+async def main():
+    await leafmesh.start()
+
+    # leafmesh.start() launches a built-in API server at http://127.0.0.1:18820
+    # See config.yaml for the full endpoint reference, or visit /docs for interactive API docs.
+    # Key endpoints:
+    #   POST /api/mesh/request            — trigger agent workflows via entry points
+    #   POST /api/mesh/stream             — SSE stream of LLM response
+    #   POST /webhook/{entry_point}       — unified webhook (new task or human response)
+    #   GET  /docs                        — interactive API docs (ReDoc)
+
+    # Log registered agents
+    agents = leafmesh.registry.list_agents() if hasattr(leafmesh, 'registry') and leafmesh.registry else []
+    if agents:
+        agent_summary = ", ".join(f"{a.name} ({a.agent_type})" for a in agents)
+        logger.info(f"Registered agents: {agent_summary}")
+    logger.info("{{project_name}} is running — press Ctrl+C to stop")
+    logger.info("API docs: http://127.0.0.1:18820/docs")
+    logger.info("Docker:   docker compose up --build")
+
+    # ─── mesh_call: the external entry point into the agent mesh ───
+    # This is how you trigger agent workflows from code, APIs, or webhooks.
+    # The mesh automatically chains agents via can_call rules in config.yaml.
+    #
+    # result = await leafmesh.mesh_call(
+    #     "greet_user",
+    #     {"message": "Hello, I need help organizing my tasks"},
+    #     session_id="optional-session-id"
+    # )
+    # logger.info(f"Result: {result}")
+    #
+    # # Direct research (bypasses greeting flow):
+    # result = await leafmesh.mesh_call("research", {"research_topic": "market trends"})
+    #
+    # # Direct advice:
+    # result = await leafmesh.mesh_call("advise", {"processed_data": {...}})
+    #
+    # # On-demand scheduled report (also runs daily at 9 AM UTC via cron):
+    # result = await leafmesh.mesh_call("scheduled_report", {"trigger": "manual"})
+
+    # ─── Usage analytics & LLM cache stats ───
+    # These are available after agents have run:
+    #
+    # analytics = await leafmesh.get_usage_analytics()
+    # logger.info(f"Usage: {analytics}")
+    #   → Returns: agent call counts, error rates, avg latency per agent
+    #
+    # cache_stats = await leafmesh.get_llm_cache_stats()
+    # logger.info(f"LLM cache: {cache_stats}")
+    #   → Returns: hit_count, miss_count, hit_rate, cached_keys
+    #
+    # ─── Upstream yields ───
+    # Agents define yields in YAML (typed key-value pairs).
+    # The SDK auto-stores them to Redis and auto-injects them into
+    # downstream agents as input_data["upstream_yields"][agent_name].
+    # Fan-in agents receive yields from ALL contributing upstream agents.
+
+    # Keep the process alive until interrupted
+    stop_event = asyncio.Event()
+    loop = asyncio.get_running_loop()
+    import sys
+    if sys.platform != "win32":
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            loop.add_signal_handler(sig, stop_event.set)
+        await stop_event.wait()
+    else:
+        # Windows: add_signal_handler not supported, use KeyboardInterrupt
+        try:
+            await stop_event.wait()
+        except KeyboardInterrupt:
+            pass
+
+    logger.info("Shutting down...")
+    await leafmesh.stop()
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        pass

create_leafmesh/templates/requirements.txt

@@ -0,0 +1,10 @@
+# {{project_name}} — Dependencies
+
+# LeafMesh SDK (includes all providers + connectors)
+leafmesh
+
+# Scheduler (enables wake_up cron in YAML)
+apscheduler>=3.10.0
+
+# Project dependencies
+python-dotenv>=1.0.0

create_leafmesh-2.1.0.dist-info/METADATA

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: create-leafmesh
+Version: 2.1.0
+Summary: Project scaffolding tool for LeafMesh
+License-Expression: MIT
+Requires-Python: >=3.10

create_leafmesh-2.1.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+create_leafmesh/__init__.py,sha256=m_g1ZFIPUBpVL_oB6LSkan5DfRl-y_1fP67ZdWrX1h0,88
+create_leafmesh/cli.py,sha256=Y3aIIX3WUw0vTIEvz905CyDYFADrZVgPSNvumDAS0qE,8880
+create_leafmesh/create.py,sha256=XCoArGNU0sXcGU2ScFG_bFceYGOEsDGXySIs8a8mk2c,3207
+create_leafmesh/templates/Dockerfile,sha256=Dmog9_BfFEVKCG3rGWJ9j-CPld64KKi392e0-ETNUXs,455
+create_leafmesh/templates/README.md,sha256=1jjcgnSboYNlSf2yYkyjSoIs-UMngI9cc-Tu6bdvLUs,10871
+create_leafmesh/templates/docker-compose.yml,sha256=yjUeMBlC2AAgmkX51BXesW1I9bE650SpPs5ThGGrXKM,460
+create_leafmesh/templates/dockerignore,sha256=7M9sHH1JmUPSlJ06zaC2D_GAYxkY9X95VjSzyh8DUXA,136
+create_leafmesh/templates/env,sha256=63stn8M9cYhbClGbpfksEWVB2MqMXcgdZNhnwfiQyO0,4827
+create_leafmesh/templates/gitignore,sha256=cPk8HY32uzIbuM2byii939_ElGwunDeGvAuuLj7QUdo,264
+create_leafmesh/templates/hitl_stub_receiver.py,sha256=DAQVwtaIhgG22SrJF6Pf6dBvUOV-yJP1tQ45yd7IrQA,5796
+create_leafmesh/templates/main.py,sha256=d0YFoCO03zzhg0j0e3Bk3NQIzVv4XKFWN9pAzMUnt4E,4145
+create_leafmesh/templates/requirements.txt,sha256=2uXz3SRqbqAkCij9RstSEPSTMQVs6ZhvL6vbbHcnPxA,208
+create_leafmesh/templates/agency/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+create_leafmesh/templates/agency/advisor_agent.py,sha256=gfXLXe4_h9HCrj6FAuF0kGzegfwgzrqE2cSO5rwrH64,6467
+create_leafmesh/templates/agency/external_agents.py,sha256=GF6DVuamZo1PboQnVB_r3GA5d6N39UGE7eZrQqufE9c,9827
+create_leafmesh/templates/agency/fallback_researcher_agent.py,sha256=mqKfOKDycqPhkf8QFb5m7SiFF3iIlm1wSi1C5IgT65A,3050
+create_leafmesh/templates/agency/greeter_agent.py,sha256=9iaiakf6doT-kg1CwPAeGJM8i-3gbDJ6o_tYg1dst5E,3039
+create_leafmesh/templates/agency/processor_agent.py,sha256=j3bCesnUvZKIS7DPBJ_SeqiL4L7TQm5j7u9WZMddRtA,3618
+create_leafmesh/templates/agency/researcher_agent.py,sha256=JJjCo4SEqcahiv2xsvOuMU71wiygV2eycPCszUlWwE0,4184
+create_leafmesh/templates/agency/scheduler_agent.py,sha256=-ZEKwZ_ChaLn7IFvpWHmb2koWdIOOBG6l3FsC2nBwMU,2508
+create_leafmesh/templates/agency/tools.py,sha256=M7kgHDZfd_S3AKW5FIOW0JDBUqRZnzVnk9bszvzHNSY,4548
+create_leafmesh/templates/claude_skills/leafmesh/SKILL.md,sha256=Dn2KBsl4n9wX2JV_jm-o8LOGCsN0nzlg3-C6fvZOWO8,91196
+create_leafmesh/templates/claude_skills/leafmesh/agent-config-fields.md,sha256=CaRQepcfsemFUeW9diSOnRGEPYPDaoJlt7uv5-fGFU0,60479
+create_leafmesh/templates/claude_skills/leafmesh/examples.md,sha256=oRviamSANLOZF7hdIz3UxFpbItCOK7Kjt-DzZK0Cl1E,14857
+create_leafmesh/templates/claude_skills/leafmesh/reference.md,sha256=JY6vrB1ETPnhUApWc9qK1ZbjsHrYKVznRIetnjKameo,15940
+create_leafmesh/templates/configs/config.yaml,sha256=KHFePtyQH02eFDIhUvrx5t4BgCc9GfqV-4PPXywU5LA,47232
+create_leafmesh-2.1.0.dist-info/METADATA,sha256=IyuDHwZi6F7BtK05tIO3btqxHT5qJaPm6nt5bf2meWs,154
+create_leafmesh-2.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+create_leafmesh-2.1.0.dist-info/entry_points.txt,sha256=HLh-Hxx7Nf-Wq6l6NaSJbaiowCHjzm6raIA2ZW0zGuc,61
+create_leafmesh-2.1.0.dist-info/top_level.txt,sha256=WNrfYclQe8LCuUacHcXbauq6cYBlC1i5CIiyQHs1nnY,16
+create_leafmesh-2.1.0.dist-info/RECORD,,

create_leafmesh-2.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

create_leafmesh-2.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+create-leafmesh = create_leafmesh.cli:main

create_leafmesh-2.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+create_leafmesh