create-leafmesh 2.3.2__tar.gz → 2.4.0__tar.gz

create_leafmesh-2.4.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: create-leafmesh
+Version: 2.4.0
+Summary: Project scaffolding + cloud-deploy tool for LeafMesh
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: questionary<3,>=2.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: boto3<2,>=1.34
+
+# create-leafmesh
+
+Project scaffolding tool for [LeafMesh](https://pypi.org/project/leafmesh/) — the YAML-native multi-agent orchestration platform.
+
+## Install
+
+```bash
+pip install create-leafmesh
+```
+
+## Create a Project
+
+```bash
+create-leafmesh create my-project
+cd my-project
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+python main.py
+```
+
+## CLI Options
+
+```bash
+# Create in a specific directory
+create-leafmesh create my-project -o /path/to/dir
+
+# Skip git initialization
+create-leafmesh create my-project --no-git
+
+# Interactive mode (prompts for project name)
+create-leafmesh create
+```
+
+## Generated Project Structure
+
+```
+my-project/
+  configs/
+    config.yaml              # Agent definitions, mesh wiring, HITL config
+  agency/
+    greeter_agent.py         # LLM agent with @pre_compose
+    processor_agent.py       # Programmatic agent with @conditional_chain
+    researcher_agent.py      # LLM agent with @chain_with_results + smart memory
+    fallback_researcher_agent.py  # Fast fallback (race pattern)
+    advisor_agent.py         # LLM fan-in with @chain + @compose
+    scheduler_agent.py       # Cron-scheduled agent
+    tools.py                 # Custom tools (@global_tool, @tool)
+    external_agents.py       # Integration reference (CrewAI, LangGraph, etc.)
+  main.py                    # Entry point
+  hitl_stub_receiver.py      # Webhook stub for testing HITL locally
+  requirements.txt
+  .env                       # API keys
+  Dockerfile
+  docker-compose.yml         # Redis + app
+```
+
+## What's Included
+
+- **8 agents** showcasing all 4 agent types (human, llm, programmatic, external)
+- **Human-in-the-Loop (HITL)** with dual webhook mode and `from_agent` routing
+- **Fan-in/fan-out** with OR expressions (`processor AND (researcher OR fallback)`)
+- **Smart memory** with hybrid recency/relevance scoring
+- **Scheduled agents** with cron expressions
+- **Custom tools** with access control and categories
+- **All 5 decorators**: `@pre_compose`, `@chain`, `@chain_with_results`, `@conditional_chain`, `@compose`
+- **HITL test stub** (`hitl_stub_receiver.py`) for local webhook testing
+- **Docker-ready** with Redis included
+- **Full README** with HITL walkthrough (2 scenarios, step-by-step)
+
+## Requirements
+
+- Python 3.10+
+- Redis server running (default: localhost:6379)
+- At least one LLM API key (e.g. `OPENAI_API_KEY` in `.env`)
+
+## Links
+
+- [LeafMesh SDK](https://pypi.org/project/leafmesh/)
+- [LeafCraft Studios](https://leafcraft.ai)
+
+## License
+
+MIT

create_leafmesh-2.4.0/create_leafmesh/__init__.py

@@ -0,0 +1,3 @@
+"""create-leafmesh — Project scaffolding + cloud-deploy tool for LeafMesh."""
+
+__version__ = "2.4.0"

create_leafmesh-2.4.0/create_leafmesh/templates/_inspire/agency/advisor_agent.py

@@ -0,0 +1,195 @@
+"""LLM Agent — Auto-discovered with @chain + @compose (OR fan-in advisor).
+
+auto_discover matches function name 'advisor_agent' to YAML agent config.
+
+Features showcased:
+  - @chain: sequential post-processing pipeline (validate_inputs -> score_priorities)
+  - @compose: inject helper functions into context (report shaping, alert shaping)
+  - wait_for: "processor_agent AND (researcher_agent OR fallback_researcher_agent)"
+  - OR fan-in: whichever research agent finishes first satisfies the expression
+  - optimization_strategy: "performance" — prioritizes quality over cost
+
+Execution flow:
+  1. Fan-in: SDK waits for processor_agent AND (researcher OR fallback_researcher)
+  2. fallback_researcher_agent is instant → OR resolves immediately
+  3. LLM analyzes combined upstream results
+  4. This function post-processes, picking the best research source
+  5. @compose injects shape_report and shape_alerts into context
+  6. @chain runs: validate_inputs -> score_priorities (sequential pipeline)
+
+Fan-in patterns (all supported by the SDK):
+  wait_for: "A AND B"                  — waits for both A and B
+  wait_for: "A OR B"                   — waits for either A or B (first wins)
+  wait_for: "A AND B?"                 — A required, B optional
+  wait_for: "A AND (B OR C)"           — A required + first of B or C (used here)
+  wait_for: "A AND (B OR C) AND D?"    — A required + first of B/C + D optional
+"""
+from typing import Any
+
+from leafmesh import chain, compose, LeafMeshLogger
+
+logger = LeafMeshLogger(__name__)
+
+
+def _up(input_data: dict[str, Any], context: dict[str, Any],
+        key: str, default: Any = None) -> Any:
+    """Shape-tolerant upstream read: flat input_data → upstream_yields
+    (flat or keyed by agent name) → context['upstream']."""
+    if key in input_data and input_data[key] not in (None, ""):
+        return input_data[key]
+    uy = input_data.get("upstream_yields")
+    if isinstance(uy, dict):
+        if key in uy and uy[key] not in (None, ""):
+            return uy[key]
+        for v in uy.values():
+            if isinstance(v, dict) and v.get(key) not in (None, ""):
+                return v[key]
+    for container_key in ("upstream_results",):
+        ur = input_data.get(container_key)
+        if isinstance(ur, dict):
+            for v in ur.values():
+                if isinstance(v, dict) and v.get(key) not in (None, ""):
+                    return v[key]
+    cu = context.get("upstream") if isinstance(context, dict) else None
+    if isinstance(cu, dict) and cu.get(key) not in (None, ""):
+        return cu[key]
+    return default
+
+
+def _up_agent(input_data: dict[str, Any], context: dict[str, Any],
+              agent: str) -> dict[str, Any]:
+    """Shape-tolerant per-agent yields read — checks every container the
+    SDK may deliver agent-keyed yields in."""
+    containers = (
+        input_data.get("upstream_yields"),
+        input_data.get("upstream_results"),
+        context.get("upstream") if isinstance(context, dict) else None,
+    )
+    for c in containers:
+        if isinstance(c, dict) and isinstance(c.get(agent), dict):
+            return c[agent]
+    return {}
+
+
+def validate_inputs(result, context):
+    """Chain step 1: Validate that upstream data is present and well-formed."""
+    if not result.get("recommendations"):
+        result["recommendations"] = ["No specific recommendations available"]
+    if not result.get("risk_assessment"):
+        result["risk_assessment"] = "Unable to assess — insufficient data"
+    result["validated"] = True
+    return result
+
+
+def score_priorities(result, context):
+    """Chain step 2: Score and rank recommendations by priority."""
+    recs = result.get("recommendations", [])
+    result["priority_score"] = min(1.0, len(recs) * 0.2) if recs else 0.0
+    result["next_steps"] = recs[:3] if recs else ["Gather more data"]
+    result["scored"] = True
+    return result
+
+
+def shape_report(data, context):
+    """Compose helper: Shape output for report consumption."""
+    return {
+        "title": "Advisory Report",
+        "recommendations": data.get("recommendations", []),
+        "risk_assessment": data.get("risk_assessment", ""),
+        "priority_score": data.get("priority_score", 0),
+        "project": "{{project_name}}",
+    }
+
+
+def shape_alerts(data, context):
+    """Compose helper: Shape output for alerting systems."""
+    score = data.get("priority_score", 0)
+    return {
+        "alert_level": "high" if score > 0.7 else "medium" if score > 0.4 else "low",
+        "summary": data.get("risk_assessment", ""),
+        "action_required": score > 0.5,
+    }
+
+
+@chain(validate_inputs, score_priorities)
+@compose(report=shape_report, alerts=shape_alerts)
+async def advisor_agent(llm_response, input_data, context):
+    """Analyze upstream results and produce actionable recommendations.
+
+    At this point:
+      - Fan-in complete: processor_agent AND (researcher OR fallback) finished
+      - input_data["upstream_yields"] has yields from all contributing agents
+      - context["report"] and context["alerts"] are injected by @compose
+      - After this function, @chain runs validate_inputs -> score_priorities
+    """
+    # ─── Fan-in upstream yields (shape-tolerant) ───
+    # For OR fan-in, the SDK includes yields from whichever agents completed.
+    # Check both research agents — prefer LLM researcher (higher confidence).
+    processor_yields = _up_agent(input_data, context, "processor_agent")
+    researcher_yields = _up_agent(input_data, context, "researcher_agent")
+    fallback_yields = _up_agent(input_data, context, "fallback_researcher_agent")
+
+    # ─── Pick the best research source ───
+    # LLM researcher has confidence 0.85, fallback has 0.6
+    skipped_agents = []
+    if researcher_yields and researcher_yields.get("status") == "researched":
+        research_data = researcher_yields
+        research_source = "researcher_agent"
+        research_confidence = 0.85
+    elif fallback_yields and fallback_yields.get("status") == "researched":
+        research_data = fallback_yields
+        research_source = "fallback_researcher_agent"
+        research_confidence = 0.6
+        skipped_agents.append("researcher_agent")
+    else:
+        research_data = {}
+        research_source = "none"
+        research_confidence = 0.0
+        skipped_agents.extend(["researcher_agent", "fallback_researcher_agent"])
+
+    # ─── Build recommendations from upstream data ───
+    # _up fallbacks recover the data when yields arrive flat (un-keyed).
+    processed_items = processor_yields.get("processed_items") \
+        or _up(input_data, context, "processed_items", []) or []
+    findings = research_data.get("findings") \
+        or _up(input_data, context, "findings", []) or []
+
+    recommendations = []
+    if processed_items:
+        urgent = [i for i in processed_items if i.get("category") == "urgent"]
+        if urgent:
+            recommendations.append(f"Address {len(urgent)} urgent item(s) immediately")
+        recommendations.append(f"Review {len(processed_items)} processed items")
+
+    if findings:
+        recommendations.append(f"Incorporate {len(findings)} research finding(s)")
+
+    risk = "low"
+    if any(i.get("category") == "urgent" for i in processed_items):
+        risk = "elevated — urgent items detected"
+
+    logger.info(f"Advisory complete — {len(recommendations)} recommendations, risk={risk}, source={research_source}")
+
+    return {
+        "recommendations": recommendations,
+        "risk_assessment": risk,
+        "research_source": research_source,
+        "research_confidence": research_confidence,
+        "skipped_agents": skipped_agents,
+        "source_data": {
+            "processed_count": len(processed_items),
+            "finding_count": len(findings),
+        },
+        "status": "advised",
+    }
+
+# ─── Alternative: @chain_with_results ───
+# If you want to accumulate results from each chain step:
+#
+# from leafmesh import chain_with_results
+#
+# @chain_with_results(validate_inputs, score_priorities)
+# async def advisor_agent(llm_response, input_data, context):
+#     # After execution, context["chain_results"] has a list of
+#     # each step's return value: [validate_result, score_result]
+#     ...

create_leafmesh-2.4.0/create_leafmesh/templates/_inspire/agency/fallback_researcher_agent.py

@@ -0,0 +1,110 @@
+"""Programmatic Agent — Fast template-based research fallback (no LLM).
+
+auto_discover matches function name 'fallback_researcher_agent' to YAML agent config.
+
+Features showcased:
+  - Programmatic agent: pure Python, no LLM call, instant response
+  - OR fan-in: advisor_agent uses wait_for: "processor_agent AND (researcher_agent OR fallback_researcher_agent)"
+  - Race pattern: this agent completes instantly while researcher_agent waits for LLM
+  - Mirrors researcher_agent's output schema so advisor_agent can consume either
+
+Execution flow:
+  1. processor_agent fans out to researcher_agent AND fallback_researcher_agent
+  2. This agent returns immediately with template-based findings
+  3. researcher_agent is still waiting for LLM response
+  4. advisor_agent's OR expression resolves — it proceeds with fallback data
+  5. researcher_agent result arrives later (already resolved, ignored by fan-in)
+"""
+from typing import Any
+
+from leafmesh import chain, LeafMeshLogger
+
+logger = LeafMeshLogger(__name__)
+
+
+def _up(input_data: dict[str, Any], context: dict[str, Any],
+        key: str, default: Any = None) -> Any:
+    """Shape-tolerant upstream read: flat input_data → upstream_yields
+    (flat or keyed by agent name) → context['upstream']."""
+    if key in input_data and input_data[key] not in (None, ""):
+        return input_data[key]
+    uy = input_data.get("upstream_yields")
+    if isinstance(uy, dict):
+        if key in uy and uy[key] not in (None, ""):
+            return uy[key]
+        for v in uy.values():
+            if isinstance(v, dict) and v.get(key) not in (None, ""):
+                return v[key]
+    for container_key in ("upstream_results",):
+        ur = input_data.get(container_key)
+        if isinstance(ur, dict):
+            for v in ur.values():
+                if isinstance(v, dict) and v.get(key) not in (None, ""):
+                    return v[key]
+    cu = context.get("upstream") if isinstance(context, dict) else None
+    if isinstance(cu, dict) and cu.get(key) not in (None, ""):
+        return cu[key]
+    return default
+
+
+def enrich_findings(result, context):
+    """Chain step: Add analysis metadata to template findings."""
+    findings = result.get("findings", [])
+    result["analysis"] = {
+        "total_findings": len(findings),
+        "confidence_score": 0.6,
+        "data_quality": "template",
+        "source_type": "fallback_template",
+    }
+    result["report"] = {
+        "title": "Fallback Research Findings",
+        "confidence": 0.6,
+        "quality": "template",
+        "finding_count": len(findings),
+        "formatted": True,
+    }
+    return result
+
+
+@chain(enrich_findings)
+async def fallback_researcher_agent(llm_response, input_data, context):
+    """Instant template-based research — no LLM needed.
+
+    Provides a fast fallback so the advisor_agent can proceed immediately
+    via OR fan-in without waiting for the slower LLM-based researcher_agent.
+    """
+    # Shape-tolerant upstream reads via _up — processor yields may arrive
+    # flat, keyed under upstream_yields/upstream_results, or in context.
+    upstream_item_count = _up(input_data, context, "item_count", 0)
+
+    calling_data = input_data.get("calling_agent_response", {})
+    processed_items = calling_data.get("processed_items") \
+        or _up(input_data, context, "processed_items", []) or []
+
+    # Build template-based findings from upstream data
+    findings = []
+    for item in processed_items:
+        findings.append({
+            "source": "template",
+            "content": item.get("item", ""),
+            "recommendation": f"Review and address: {item.get('item', 'unknown')}",
+        })
+
+    if not findings:
+        findings.append({
+            "source": "template",
+            "content": "No specific items to research",
+            "recommendation": "Gather more information from the user",
+        })
+
+    logger.info(f"Fallback research — {len(findings)} template findings")
+
+    return {
+        "findings": findings,
+        "query": str(_up(input_data, context, "message", "")
+                     or _up(input_data, context, "research_topic", "") or ""),
+        "upstream_item_count": upstream_item_count,
+        "source_agent": "fallback_researcher_agent",
+        "source_type": "fallback_template",
+        "status": "researched",
+    }

create_leafmesh-2.4.0/create_leafmesh/templates/_inspire/agency/greeter_agent.py

@@ -0,0 +1,129 @@
+"""LLM Agent — Auto-discovered with @pre_compose (all 3 processor types).
+
+auto_discover matches function name 'greeter_agent' to YAML agent config.
+
+Execution flow:
+  1. Processors run BEFORE the LLM call (data preparation)
+  2. context_parts (care, sentiment, guardrails) shape the LLM's tone
+  3. LLM generates response using YAML prompt + prepared data
+  4. This function post-processes the LLM response
+
+Processor results in context["prepared_data"]:
+  - context_processor → context["prepared_data"]["business_context"]
+  - input_processor   → context["prepared_data"]["clean_user_input"]
+  - others_processor  → context["prepared_data"]["others"]
+"""
+from typing import Any
+
+from leafmesh import pre_compose, LeafMeshLogger
+
+logger = LeafMeshLogger(__name__)
+
+
+def _up(input_data: dict[str, Any], context: dict[str, Any],
+        key: str, default: Any = None) -> Any:
+    """Shape-tolerant upstream read: flat input_data → upstream_yields
+    (flat or keyed by agent name) → context['upstream']."""
+    if key in input_data and input_data[key] not in (None, ""):
+        return input_data[key]
+    uy = input_data.get("upstream_yields")
+    if isinstance(uy, dict):
+        if key in uy and uy[key] not in (None, ""):
+            return uy[key]
+        for v in uy.values():
+            if isinstance(v, dict) and v.get(key) not in (None, ""):
+                return v[key]
+    for container_key in ("upstream_results",):
+        ur = input_data.get(container_key)
+        if isinstance(ur, dict):
+            for v in ur.values():
+                if isinstance(v, dict) and v.get(key) not in (None, ""):
+                    return v[key]
+    cu = context.get("upstream") if isinstance(context, dict) else None
+    if isinstance(cu, dict) and cu.get(key) not in (None, ""):
+        return cu[key]
+    return default
+
+
+def process_context(input_data, context):
+    """context_processor: Prepare business context for the LLM prompt.
+    Runs before LLM — enriches the prompt with relevant domain info."""
+    return {
+        "domain": "task_management",
+        "session_id": context.get("session_id", "unknown"),
+    }
+
+
+def clean_input(input_data, context):
+    """input_processor: Extract and clean the user's message.
+    Runs before LLM — normalizes input for consistent processing.
+    When the human client calls back, the SDK delivers only meta fields
+    (human_message etc.) — treat human_message as the user utterance."""
+    raw = input_data.get("message", "") or input_data.get("human_message", "")
+    return {"user_message": str(raw or "").strip()}
+
+
+def load_extras(input_data, context):
+    """others_processor: Load auxiliary data (feature flags, config, etc.).
+    Runs before LLM — provides supplementary data."""
+    return {"timestamp_requested": "message" in input_data}
+
+
+@pre_compose(
+    context_processor=process_context,
+    input_processor=clean_input,
+    others_processor=load_extras,
+)
+async def greeter_agent(llm_response, input_data, context):
+    """Post-process the LLM's response.
+
+    At this point:
+      - Processors already ran (before LLM call)
+      - context_parts (care, sentiment, guardrails) already shaped the LLM's tone
+      - llm_response has the LLM's output
+      - context["prepared_data"] has processor results
+    """
+    prepared = context.get("prepared_data", {})
+
+    # ─── Memory access (add memory: true to this agent's YAML to enable) ───
+    # memory_posts = context.get("memory_posts", [])
+    # Each post has "role" (user/assistant) and "content" (text).
+    # See researcher_agent.py for a working memory example.
+
+    # ─── Upstream yields access ───
+    # If this agent is called by another agent (e.g., client → greeter_agent),
+    # the SDK injects upstream yields as input_data["upstream_yields"].
+    # upstream_yields = input_data.get("upstream_yields", {})
+    # client_yields = upstream_yields.get("client", {})
+
+    # Shape-tolerant read — message may arrive flat, under upstream
+    # containers, or (conversational HITL) as human_message meta only.
+    user_input = str(
+        _up(input_data, context, "message", "")
+        or input_data.get("human_message", "")
+        or ""
+    )
+    logger.info(f"Greeting user — input: {user_input[:80]}")
+
+    # llm_response is a parsed dict (the LLM's structured JSON output).
+    # Extract the SPECIFIC fields we want — don't assign the whole dict
+    # to a single key, that produces "greeting: type mismatch (got dict)".
+    if isinstance(llm_response, dict):
+        greeting = llm_response.get("greeting") or "Hello!"
+        # If the LLM also produced a sentiment, prefer it over our default
+        sentiment = llm_response.get("detected_sentiment") or "neutral"
+    else:
+        # Fallback if LLM returned a plain string
+        greeting = str(llm_response) if llm_response else "Hello!"
+        sentiment = "neutral"
+
+    return {
+        "greeting": greeting,
+        "user_input": user_input,
+        "detected_sentiment": sentiment,
+        "domain": prepared.get("business_context", {}).get("domain", "general"),
+        "status": "greeted",
+        # Identity passthrough — the client (human) inbox declares these inputs
+        "user_message": str(_up(input_data, context, "user_message", "") or "") or user_input,
+        "request_type": str(_up(input_data, context, "request_type", "") or ""),
+    }