create-leafmesh 2.2.6__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/deploy.py

@@ -0,0 +1,213 @@
+"""leafmesh-deploy — deploy a scaffolded mesh to a cloud provider.
+
+Usage (from inside a scaffolded project):
+
+    leafmesh-deploy --plan        # describe what will be created, no API calls
+    leafmesh-deploy --apply       # do it: build + push image, create services
+    leafmesh-deploy --destroy     # reverse everything via the state file
+
+Provider selection:
+
+    --provider aws   (default)    # App Runner + Secrets Manager + ECR
+    --provider azure              # Container Apps + Key Vault + ACR
+    --provider gcp                # (planned)
+
+Authentication: zero prompts. We use whatever cloud creds are already on
+the box (`aws configure`, `gcloud auth`, `az login`, env vars). If creds
+are missing, we exit with a clean message — never interactive prompt.
+
+State: persisted at .leafmesh-deploy/<provider>.json per project. Add
+that path to .gitignore (the scaffolder already does).
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from create_leafmesh import __version__
+
+
+def _bail(msg: str, code: int = 2) -> int:
+    print(f"\n  Error: {msg}\n", file=sys.stderr)
+    return code
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(
+        prog="leafmesh-deploy",
+        description="Deploy a scaffolded LeafMesh mesh to a cloud provider.",
+        epilog="""
+examples:
+  leafmesh-deploy --plan                            show what would be created (AWS default)
+  leafmesh-deploy --apply                           build + deploy to AWS
+  leafmesh-deploy --destroy                         tear everything down
+
+  leafmesh-deploy --provider aws --region eu-west-1 --plan
+  leafmesh-deploy --provider azure --subscription-id <sub> \\
+                  --resource-group leafmesh-prod --location eastus --apply
+
+  leafmesh-deploy --print-policy                    print AWS IAM policy
+  leafmesh-deploy --print-policy --provider azure   print Azure RBAC
+        """,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("--version", action="version",
+                    version=f"leafmesh-deploy (from create-leafmesh {__version__})")
+
+    p.add_argument("--provider", default="aws",
+                    choices=("aws", "azure", "gcp"),
+                    help="Cloud provider (default: aws).")
+    # AWS-specific (also GCP region — resolved per provider below;
+    # no argparse default so the state file can win on re-runs)
+    p.add_argument("--region", default=None,
+                    help="Cloud region. Defaults: AWS us-east-1, "
+                         "GCP us-central1 (NOTE: GCP regions have no "
+                         "hyphen before the digit — us-east1, not us-east-1).")
+    # Azure-specific
+    p.add_argument("--subscription-id",
+                    help="Azure subscription ID. Required for --provider azure "
+                         "on first apply; subsequent runs read it from state.")
+    p.add_argument("--resource-group",
+                    help="Azure resource group. Required for --provider azure "
+                         "on first apply; subsequent runs read from state.")
+    p.add_argument("--location", default=None,
+                    help="Azure location (default: eastus, or the value "
+                         "recorded in state on re-runs). Ignored for AWS/GCP.")
+    # GCP-specific
+    p.add_argument("--project",
+                    help="GCP project ID. Required for --provider gcp on first "
+                         "apply; subsequent runs read it from state.")
+
+    group = p.add_mutually_exclusive_group(required=True)
+    group.add_argument("--plan",    action="store_true",
+                        help="Describe what will be created/updated — no API calls.")
+    group.add_argument("--apply",   action="store_true",
+                        help="Make it real — build image, push, deploy.")
+    group.add_argument("--destroy", action="store_true",
+                        help="Tear down everything in the state file.")
+    group.add_argument("--print-policy", action="store_true",
+                        help="Print the IAM policy / RBAC role definition "
+                             "leafmesh-deploy needs to operate. Pipe to a "
+                             "file + give to your cloud admin.")
+
+    args = p.parse_args(argv)
+
+    # --print-policy is a special case: no project context required,
+    # no cloud API calls. Emit JSON to stdout + exit 0.
+    if args.print_policy:
+        import json as _json
+        if args.provider == "aws":
+            from create_leafmesh.deploy_providers.aws import DEPLOY_OPERATOR_POLICY
+            print(_json.dumps(DEPLOY_OPERATOR_POLICY, indent=2))
+            return 0
+        if args.provider == "azure":
+            from create_leafmesh.deploy_providers.azure import DEPLOY_OPERATOR_RBAC
+            print(_json.dumps(DEPLOY_OPERATOR_RBAC, indent=2))
+            return 0
+        if args.provider == "gcp":
+            from create_leafmesh.deploy_providers.gcp import DEPLOY_OPERATOR_POLICY as _GCP_POL
+            print(_json.dumps(_GCP_POL, indent=2))
+            return 0
+        return _bail(f"--print-policy not implemented for provider {args.provider}")
+
+    # Pre-flight: we expect to be inside a scaffolded project
+    if not Path("configs/config.yaml").exists() and not args.destroy:
+        return _bail(
+            "configs/config.yaml not found — run leafmesh-deploy from inside a "
+            "scaffolded LeafMesh project directory."
+        )
+
+    if args.provider == "aws":
+        from create_leafmesh.deploy_providers.aws import AWSDeployer
+        try:
+            aws_d = AWSDeployer(region=args.region or "us-east-1")
+        except SystemExit:
+            raise
+        except Exception as e:
+            return _bail(f"failed to init AWS deployer: {type(e).__name__}: {e}")
+
+        if args.plan:    return aws_d.plan()
+        if args.apply:   return aws_d.apply()
+        if args.destroy: return aws_d.destroy()
+
+    if args.provider == "azure":
+        # On first apply we need subscription + RG explicitly. On destroy
+        # we can read them from the state file, so they're optional then.
+        from create_leafmesh.deploy_providers._shared import load_state, StateFileCorruptError
+        try:
+            state = load_state("azure")
+        except StateFileCorruptError:
+            state = {}
+
+        sub = args.subscription_id or state.get("subscription_id")
+        rg  = args.resource_group  or state.get("resource_group")
+        # --location now has NO argparse default, so the state file's
+        # recorded location wins on re-runs (split-region bug fix).
+        loc = args.location or state.get("location") or "eastus"
+
+        if not sub or not rg:
+            missing = []
+            if not sub: missing.append("--subscription-id")
+            if not rg:  missing.append("--resource-group")
+            return _bail(
+                f"Azure provider needs {', '.join(missing)} on first apply. "
+                f"After that, they're read from .leafmesh-deploy/azure.json."
+            )
+
+        from create_leafmesh.deploy_providers.azure import AzureDeployer
+        try:
+            az_d = AzureDeployer(subscription_id=sub, resource_group=rg,
+                                  location=loc)
+        except SystemExit:
+            raise
+        except Exception as e:
+            return _bail(f"failed to init Azure deployer: {type(e).__name__}: {e}")
+
+        if args.plan:    return az_d.plan()
+        if args.apply:   return az_d.apply()
+        if args.destroy: return az_d.destroy()
+
+    if args.provider == "gcp":
+        from create_leafmesh.deploy_providers._shared import load_state, StateFileCorruptError
+        try:
+            state = load_state("gcp")
+        except StateFileCorruptError:
+            state = {}
+
+        pid    = args.project or state.get("project_id")
+        # GCP regions are us-central1 / us-east1 (no hyphen before the
+        # digit). --region has no argparse default now, so the recorded
+        # state region wins on re-runs and the GCP default is actually
+        # reachable — previously "us-east-1" (an AWS region) leaked in
+        # and every GCP resource path 404'd.
+        region = args.region or state.get("region") or "us-central1"
+
+        if not pid:
+            return _bail(
+                "GCP provider needs --project on first apply. After that, "
+                "it's read from .leafmesh-deploy/gcp.json."
+            )
+
+        from create_leafmesh.deploy_providers.gcp import GCPDeployer
+        try:
+            gcp_d = GCPDeployer(project_id=pid, region=region)
+        except SystemExit:
+            raise
+        except Exception as e:
+            return _bail(f"failed to init GCP deployer: {type(e).__name__}: {e}")
+
+        if args.plan:    return gcp_d.plan()
+        if args.apply:   return gcp_d.apply()
+        if args.destroy: return gcp_d.destroy()
+
+    return _bail(f"unsupported provider: {args.provider}")
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except KeyboardInterrupt:
+        print("\n\n  Cancelled.\n")
+        sys.exit(130)   # standard SIGINT exit code — scripts must
+                        # never read an interrupted apply as success

create_leafmesh-2.4.0/create_leafmesh/deploy_providers/__init__.py

@@ -0,0 +1,6 @@
+"""Cloud-provider deployers for leafmesh-deploy.
+
+v1 ships AWS only (App Runner + Secrets Manager + ECR). GCP + Azure
+land later with the same shape: each provider exposes a class with
+plan(), apply(), destroy() methods + a state-file path.
+"""

create_leafmesh-2.4.0/create_leafmesh/deploy_providers/_shared.py

@@ -0,0 +1,156 @@
+"""Provider-agnostic helpers shared by every cloud deployer.
+
+Keep this module *pure*: no boto3, no azure-sdk, no gcloud imports.
+Anything that touches a cloud SDK belongs in the per-provider module
+(`aws.py`, `azure.py`, `gcp.py`). This module is import-cheap so the
+CLI can call into it even when the user hasn't installed the provider
+SDKs.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Environment-variable contract — every provider expects the same
+# config keys in .env.deploy / .env. New keys go here, not in the
+# per-provider module.
+# ─────────────────────────────────────────────────────────────────────
+REQUIRED_ENV_KEYS: tuple[str, ...] = (
+    "LEAFMESH_LICENSE_KEY",
+    "LEAFMESH_ENV_TOKEN",
+    "OPENAI_API_KEY",
+    "REDIS_URL",
+)
+
+OPTIONAL_ENV_KEYS: tuple[str, ...] = (
+    "ANTHROPIC_API_KEY",
+)
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Cosmetics — used by all providers' plan/apply/destroy output
+# ─────────────────────────────────────────────────────────────────────
+GREEN  = "\033[32m"
+CYAN   = "\033[36m"
+DIM    = "\033[2m"
+BOLD   = "\033[1m"
+RED    = "\033[31m"
+YELLOW = "\033[33m"
+RESET  = "\033[0m"
+
+
+def c(code: str, text: str) -> str:
+    """Wrap text in an ANSI colour."""
+    return f"{code}{text}{RESET}"
+
+
+def step(n: int, total: int, label: str) -> None:
+    """Print a numbered step header (no newline)."""
+    print(f"  {c(DIM, f'[{n}/{total}]')}  {label} ...", end="", flush=True)
+
+
+def ok(detail: str = "") -> None:
+    """Mark the in-progress step as successful."""
+    print(f"  {c(GREEN, 'OK')}  {c(DIM, detail)}".rstrip())
+
+
+def fail(msg: str) -> None:
+    """Print a FAIL marker + multi-line message."""
+    print(f"  {c(RED, 'FAIL')}  {msg}")
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Project introspection — derive the project name + read .env.deploy
+# ─────────────────────────────────────────────────────────────────────
+def project_name() -> str:
+    """Customer's project name = mesh.name from configs/config.yaml,
+    falling back to cwd. Lowercased + underscores → hyphens so the
+    name is valid in every cloud's resource-naming rules."""
+    cfg_path = Path("configs/config.yaml")
+    if cfg_path.exists():
+        try:
+            import yaml
+            cfg = yaml.safe_load(cfg_path.read_text())
+            name = str(cfg.get("name", "")).strip()
+            if name and name != "{{project_name}}":
+                return name.lower().replace("_", "-")
+        except Exception:
+            pass
+    return Path.cwd().name.lower().replace("_", "-")
+
+
+def read_env_deploy() -> dict[str, str]:
+    """Read .env.deploy (preferred) or .env into a flat dict.
+    Quotes stripped, comments + blank lines ignored."""
+    env_path = Path(".env.deploy")
+    if not env_path.exists():
+        env_path = Path(".env")
+    if not env_path.exists():
+        return {}
+    out: dict[str, str] = {}
+    for line in env_path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        k, _, v = line.partition("=")
+        out[k.strip()] = v.strip().strip("'").strip('"')
+    return out
+
+
+# ─────────────────────────────────────────────────────────────────────
+# State file management — per-provider state at .leafmesh-deploy/{provider}.json
+# ─────────────────────────────────────────────────────────────────────
+STATE_DIR = Path(".leafmesh-deploy")
+
+
+class StateFileCorruptError(Exception):
+    """Raised when a state file exists but won't parse. Callers must
+    distinguish this from "no state file" (which is legitimately {})."""
+
+
+def state_path(provider: str) -> Path:
+    """Per-provider state file path."""
+    return STATE_DIR / f"{provider}.json"
+
+
+def load_state(provider: str) -> dict[str, Any]:
+    """Return parsed state or {} if absent. Raise StateFileCorruptError
+    if the file is present but can't be parsed — destroy + apply must
+    refuse to proceed rather than silently treat corruption as 'fresh'."""
+    path = state_path(provider)
+    if not path.exists():
+        return {}
+    raw = path.read_text(encoding="utf-8")
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise StateFileCorruptError(
+            f"State file at {path} is corrupted ({e}). "
+            f"Inspect or restore from backup before re-running. "
+            f"Resources may still exist in the cloud — DO NOT assume "
+            f"a fresh start."
+        ) from e
+
+
+def save_state(provider: str, state: dict[str, Any]) -> None:
+    """Atomic write — temp file + os.replace. A crash mid-write must
+    never leave a truncated JSON file, because the corrupt-state guard
+    would then lock the user out of both apply and destroy."""
+    import os
+    STATE_DIR.mkdir(parents=True, exist_ok=True)
+    target = state_path(provider)
+    tmp = target.with_suffix(".json.tmp")
+    tmp.write_text(
+        json.dumps(state, indent=2, default=str) + "\n", encoding="utf-8",
+    )
+    os.replace(tmp, target)
+
+
+def delete_state(provider: str) -> None:
+    """Remove the state file (idempotent)."""
+    state_path(provider).unlink(missing_ok=True)