create-leafmesh 2.1.0__py3-none-any.whl

create_leafmesh/templates/agency/researcher_agent.py

@@ -0,0 +1,99 @@
+"""LLM Agent — Auto-discovered with @chain_with_results (accumulating pipeline).
+
+auto_discover matches function name 'researcher_agent' to YAML agent config.
+
+Features showcased:
+  - @chain_with_results: each step's return is accumulated into a list
+  - Smart memory (BRD-009): strategy: "hybrid" with cross-session persistence
+    context["memory_posts"] has relevance+recency weighted past interactions
+  - tool_categories: ["data"] — all tools in the "data" category are available
+  - tools: ["math_eval", "timestamp"] — specific tools also included
+  - reasoning: true — enables chain-of-thought for deeper analysis
+  - allow_parallel_tool_calls: true — LLM can invoke multiple tools at once
+
+Execution flow:
+  1. LLM generates response (with memory context + tools available)
+  2. This function post-processes the LLM response
+  3. @chain_with_results runs: analyze_data -> format_findings
+     Each step's result is accumulated in context["chain_results"]
+"""
+from leafmesh import chain_with_results, LeafMeshLogger
+
+logger = LeafMeshLogger(__name__)
+
+
+def analyze_data(result, context):
+    """Chain step 1: Enrich the result with analysis and a confidence score.
+
+    With @chain_with_results, this return value is appended to
+    context["chain_results"] AND passed to the next step.
+    """
+    items = result.get("findings", [])
+    result["analysis"] = {
+        "total_findings": len(items),
+        "confidence_score": 0.85 if items else 0.1,
+        "data_quality": "high" if len(items) >= 3 else "limited",
+    }
+    return result
+
+
+def format_findings(result, context):
+    """Chain step 2: Structure into a formal report format.
+
+    context["chain_results"] already contains the output from analyze_data.
+    """
+    analysis = result.get("analysis", {})
+    result["report"] = {
+        "title": "Research Findings",
+        "confidence": analysis.get("confidence_score", 0),
+        "quality": analysis.get("data_quality", "unknown"),
+        "finding_count": analysis.get("total_findings", 0),
+        "formatted": True,
+    }
+    return result
+
+
+@chain_with_results(analyze_data, format_findings)
+async def researcher_agent(llm_response, input_data, context):
+    """Post-process the LLM's research response.
+
+    At this point:
+      - LLM already generated research using the YAML prompt + tools
+      - context["memory_posts"] has past conversation history (memory: true)
+      - After this function, @chain_with_results runs analyze_data -> format_findings
+      - Each step result is accumulated in context["chain_results"]
+    """
+    # ─── Smart memory access (BRD-009: strategy "hybrid" in YAML) ───
+    # Past interactions are injected as context["memory_posts"], scored by
+    # relevance (0.6 weight) + recency (0.4 weight). Cross-session enabled
+    # means memory persists across sessions for returning users.
+    # Each post has "role" (user/assistant) and "content" (text).
+    memory_posts = context.get("memory_posts", [])
+    prior_findings_count = sum(1 for p in memory_posts if p.get("role") == "assistant")
+
+    # ─── Upstream yields access ───
+    # When processor_agent stores yields, the SDK injects them here.
+    upstream_yields = input_data.get("upstream_yields", {})
+    processor_yields = upstream_yields.get("processor_agent", {})
+    # processor_yields has: processed_items, item_count, status, alert
+
+    findings = []
+    if llm_response:
+        findings.append({"source": "llm", "content": llm_response})
+
+    calling_data = input_data.get("calling_agent_response", {})
+    if calling_data.get("processed_items"):
+        for item in calling_data["processed_items"]:
+            findings.append({"source": "upstream", "content": item.get("item", "")})
+
+    query = input_data.get("message", input_data.get("research_topic", ""))
+    logger.info(f"Research complete — {len(findings)} findings for: {query[:60]}")
+
+    return {
+        "findings": findings,
+        "query": query,
+        "prior_research_sessions": prior_findings_count,
+        "upstream_item_count": processor_yields.get("item_count", 0),
+        "source_agent": "researcher_agent",
+        "status": "researched",
+    }

create_leafmesh/templates/agency/scheduler_agent.py

@@ -0,0 +1,67 @@
+"""Programmatic Agent — Cron-scheduled, chains to advisor for analysis.
+
+auto_discover matches function name 'scheduler_agent' to YAML agent config.
+
+Features showcased:
+  - wake_up: "0 9 * * *" — cron expression triggers this agent automatically
+  - communication_type: "chain" — output chains to advisor_agent via can_call
+  - Entry point: mesh_call("scheduled_report", ...) for on-demand reports
+  - No LLM, no external deps — pure Python on a schedule
+
+Use cases for scheduled agents:
+  - Daily/weekly report generation → chain to LLM agent for analysis
+  - Health checks and alerting → chain to human agent for review
+  - Periodic data aggregation → chain to downstream processors
+
+All agent functions use the 3-param signature: (llm_response, input_data, context)
+For programmatic agents, llm_response is always None.
+input_data will be empty on scheduled runs (no upstream caller).
+On-demand runs via mesh_call("scheduled_report", data) will have input_data.
+"""
+from datetime import datetime, timezone
+from leafmesh import LeafMeshLogger
+
+logger = LeafMeshLogger(__name__)
+
+
+async def scheduler_agent(llm_response, input_data, context):
+    """Generate a status report with mesh metrics.
+
+    This runs on the cron schedule defined in config.yaml AND can be
+    triggered on-demand via mesh_call("scheduled_report", data).
+
+    communication_type: "chain" means the result is forwarded to
+    advisor_agent via can_call for LLM-powered analysis.
+    """
+    now = datetime.now(timezone.utc)
+    trigger = input_data.get("trigger", "scheduled")
+
+    # ─── Gather mesh metrics ───
+    # In production, you'd pull real metrics from your data sources.
+    # The advisor_agent receives this as input_data and analyzes it.
+    checks = {
+        "system_status": "healthy",
+        "scheduled_run": trigger == "scheduled",
+        "on_demand": trigger != "scheduled",
+    }
+
+    metrics = {
+        "report_time": now.isoformat(),
+        "trigger_type": trigger,
+        "uptime_hours": 24,
+        "total_requests_today": 0,
+        "error_rate": 0.0,
+    }
+
+    logger.info(f"Report generated ({trigger}) — status={checks['system_status']}")
+
+    return {
+        "report": f"Status report ({trigger}) at {now.isoformat()}",
+        "generated_at": now.isoformat(),
+        "checks": checks,
+        "metrics": metrics,
+        "processed_items": [
+            {"item": f"Daily {trigger} report", "category": "normal"},
+        ],
+        "status": "report_generated",
+    }

create_leafmesh/templates/agency/tools.py

@@ -0,0 +1,123 @@
+"""Custom tools that LLM agents can call during generation.
+
+Two decorator types:
+  @global_tool — Auto-registers in GlobalToolRegistry on import
+  @tool        — Creates a local FunctionTool (register manually)
+
+Tools are referenced in YAML agent config:
+  tools: ["word_count", "timestamp"]       # specific tools by name
+  tool_categories: ["text", "utility"]     # all tools in a category
+  tool_choice: "auto"
+
+Import these in main.py so @global_tool registration runs:
+  from agency.tools import word_count, timestamp, format_as_markdown
+"""
+from leafmesh import global_tool, tool
+
+
+@global_tool(
+    name="word_count",
+    description="Count the number of words in a text string",
+    category="text",
+)
+def word_count(text: str) -> dict:
+    """Count words in the given text."""
+    words = text.split()
+    return {"word_count": len(words), "character_count": len(text)}
+
+
+@global_tool(
+    name="timestamp",
+    description="Get the current UTC timestamp",
+    category="utility",
+)
+def timestamp() -> dict:
+    """Return the current UTC time."""
+    from datetime import datetime, timezone
+    now = datetime.now(timezone.utc)
+    return {"utc": now.isoformat(), "unix": int(now.timestamp())}
+
+
+@global_tool(
+    name="math_eval",
+    description="Evaluate a simple math expression (addition, subtraction, multiplication, division)",
+    category="data",
+)
+def math_eval(expression: str) -> dict:
+    """Safely evaluate a math expression."""
+    allowed = set("0123456789+-*/.(). ")
+    if not all(c in allowed for c in expression):
+        return {"error": "Invalid characters in expression"}
+    try:
+        result = eval(expression, {"__builtins__": {}})  # noqa: S307
+        return {"expression": expression, "result": result}
+    except Exception as e:
+        return {"error": str(e)}
+
+
+@global_tool(
+    name="sensitive_data_lookup",
+    description="Look up sensitive data records (restricted access)",
+    category="data",
+    allowed_agents=["researcher_agent", "advisor_agent"],
+    requires_confirmation=True,
+    timeout_seconds=15,
+)
+def sensitive_data_lookup(record_id: str) -> dict:
+    """Look up a sensitive data record by ID.
+
+    - allowed_agents: only researcher_agent and advisor_agent can call this
+    - requires_confirmation: manager must approve before execution
+    - timeout_seconds: auto-cancel if it takes longer than 15s
+    """
+    return {
+        "record_id": record_id,
+        "data": f"Record {record_id} contents",
+        "classification": "internal",
+    }
+
+
+# ─── @tool example (local, not auto-registered) ──────────────
+# Use @tool for agent-specific tools that don't need global access.
+
+@tool(
+    name="format_as_markdown",
+    description="Format a list of items as a markdown checklist",
+    timeout_seconds=10,
+    requires_confirmation=False,
+)
+def format_as_markdown(items: list) -> str:
+    """Convert a list to markdown checklist."""
+    return "\n".join(f"- [ ] {item}" for item in items)
+
+
+# ═══════════════════════════════════════════════════════════════
+# BUILT-IN TOOLS REFERENCE
+# These are provided by LeafMesh — no code needed, just reference
+# them by name in your YAML config under `tools:` or by category
+# under `tool_categories:`.
+#
+# Category: "web"
+#   - web_search       — Search the web (requires API key config)
+#   - web_scrape       — Scrape a URL and return content
+#
+# Category: "data"
+#   - json_parse       — Parse and validate JSON strings
+#   - csv_parse        — Parse CSV data into structured format
+#
+# Category: "text"
+#   - text_summarize   — Summarize long text passages
+#   - text_translate   — Translate text between languages
+#
+# Category: "utility"
+#   - file_read        — Read file contents
+#   - file_write       — Write content to a file
+#   - http_request     — Make HTTP requests
+#
+# YAML usage:
+#   tools: ["calculator", "web_search"]       # pick specific tools
+#   tool_categories: ["data", "utility"]      # pick entire categories
+#   tool_choice: "auto"                       # auto | none | required
+#   allow_parallel_tool_calls: true           # LLM can call multiple tools at once
+#   max_tool_calls_per_message: 10            # safety limit per LLM turn
+# ═══════════════════════════════════════════════════════════════