create-leafmesh 2.5.0__tar.gz → 2.5.2__tar.gz

{create_leafmesh-2.5.0 → create_leafmesh-2.5.2}/PKG-INFO

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

{create_leafmesh-2.5.0 → create_leafmesh-2.5.2}/create_leafmesh/__init__.py

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

{create_leafmesh-2.5.0 → create_leafmesh-2.5.2}/create_leafmesh/templates/_registry.yaml

@@ -25,9 +25,34 @@ version: 2
 templates:
 
   # ──────────────────────────────────────────────────────────────
-  # FINANCE & BACK-OFFICE
+  # START HERE
   # ──────────────────────────────────────────────────────────────
 
+  - slug: starter
+    status: ready
+    category: "Start here"
+    short_name: "Starter"
+    full_name: "Starter — build a mesh from scratch"
+    one_line: "Blank canvas: 1 LLM intake → human review gate → WORM audit, with copy-paste patterns to grow."
+    industries: ["any"]
+    roi_cells: []
+    agent_count: 3
+    cron_count: 0
+    trust_lead: "human-review gate on sensitive requests; hash-chained audit terminus; default-deny on reviewer timeout"
+    complexity: "low"
+    decision_tree_path: "start_from_scratch"
+    description: >
+      The template to pick when none of the business templates fit —
+      a minimal, working 3-agent mesh whose configs/config.yaml is
+      written as a guided tutorial. Read it top to bottom: an LLM
+      intake agent classifies a request and routes (via readable
+      can_call wires) either to a human reviewer or straight to the
+      hash-chained audit log. Ships three commented, copy-paste
+      patterns to grow into — a second LLM agent, a connector agent
+      for your system of record (MCP/Zapier/n8n), and a scheduled
+      cron. YAML-first: the only Python is the shared WORM audit sink.
+      Includes validate_config.py for pre-flight checks.
+
   - slug: finance-ops
     status: ready
     category: "Finance & back-office"

{create_leafmesh-2.5.0 → create_leafmesh-2.5.2}/create_leafmesh/templates/claude_skills/leafmesh/SKILL.md

@@ -1013,9 +1013,49 @@ rather than being manufactured as `false`/`""`. Two consequences:
   edges. `entry_points` targets are stricter — a typo'd target raises
   `ConfigError` at load.
 
-## Decorators -- The 5 Pipelines
-
-### @pre_compose -- Prepare inputs BEFORE the LLM
+## Decorators — Making an Agent Self-Reliant
+
+**We are not wiring a workflow of nodes. We are building an OPERATION —
+a team of self-reliant agents.** A node waits to be handed clean inputs
+and emits a fixed output. An AGENT, like a capable hire, does its own
+job end to end: it gathers what it needs before it decides, makes sense
+of what a system hands back, finishes its own work before passing it
+on, and addresses each colleague in the language that colleague needs.
+The decorators below are how an agent becomes self-reliant instead of a
+step in a pipe.
+
+An agent may call peers (`can_call`) — that *is* the operation. But it
+owns its own preparation and post-processing; it never leans on the next
+agent to clean up after it. **Self-reliant first, collaborative second.**
+
+(Most pure-LLM agents need NONE of these — the SDK derives behaviour
+from `yields`. Reach for a decorator only when the agent must do real
+work *around* the model.)
+
+| The agent needs to… | Reach for | When it runs |
+|---|---|---|
+| gather facts/inputs it needs BEFORE reasoning (fetch a CRM tier, clean the input, load policy) | `@pre_compose` | before the LLM |
+| make sense of a system-of-record's RAW response (a connector returned JSON → turn it into yields) | `@sdk.intelligence` | *is* the agent's logic |
+| finish its OWN work after deciding (validate, score, format, bound a retry) | `@chain` | after the LLM, in order |
+| keep each step's result, not just the final (a derivation with an audit trail of stages) | `@chain_with_results` | after the LLM |
+| do extra work ONLY in some cases (escalate + approve only when flagged) | `@conditional_chain` | after the LLM, if-condition |
+| hand a DIFFERENT shape to each peer it calls (billing wants the invoice, support the summary) | `@compose` | shaping the handoff |
+
+One judgment to keep straight: an agent that **always** needs a fact
+should `@pre_compose` it — don't make the model *decide* to fetch a
+thing it always needs. Pre-fetched facts the model reasons over; a
+**tool call** is the opposite (optional, model-chosen, for things it
+*may* reach for). Confusing the two is the most common modelling error.
+
+### @pre_compose — gather what you need before you decide
+*Essence: run fetch / clean / enrich BEFORE the model sees the prompt,
+so the agent reasons over already-resolved facts instead of choosing to
+go get them. The professional pulls the file before the meeting.*
+*Reach for it when* the agent must cite a live external fact (CRM tier,
+account balance, today's rate) or a normalised input in its reasoning,
+every time it runs.
+*Instead of* a tool call (optional, model-decided) or a fetch buried in
+the agent body (runs after the model already guessed).
 ```python
 from leafmesh import pre_compose
 
@@ -1029,7 +1069,39 @@ async def my_agent(llm_response, input_data, context):
     return {"result": llm_response}
 ```
 
-### @chain -- Sequential post-processing AFTER the LLM
+### @sdk.intelligence — make sense of what a system hands back
+*Essence: a connector (`integration:` / `framework:`) returns its
+system's RAW response; the intelligence function IS the agent's logic
+that turns that raw payload into the agent's declared `yields`. Without
+it the connector response passes through as-is — fine ONLY when the
+system's shape already matches your contract (it rarely does).*
+*Reach for it when* a programmatic/external agent calls a real system of
+record (CRM/ERP/WMS via MCP/Zapier/n8n) and you must map its response
+into the fields your wires and downstream agents expect.
+*Instead of* trusting the connector's shape to match your yields, or
+making a downstream agent reshape it (that's the next agent cleaning up
+after this one — not self-reliant).
+```python
+# Programmatic/external agent: the connector runs, then THIS shapes its
+# raw result into the agent's yields. Registered via the SDK (see the
+# audit sink in agency/_shared/ for the registration form).
+async def crm_lookup_agent(connector_response, input_data, context):
+    # connector_response = the CRM's raw JSON
+    return {
+        "customer_id": connector_response.get("id", ""),
+        "tier": connector_response.get("account", {}).get("tier", "standard"),
+    }
+```
+
+### @chain — finish your own work before handing off
+*Essence: run validate / score / format / bound-a-retry AFTER the model,
+in order, as part of THIS agent's job — so what it hands a colleague is
+already finished, not half-done.*
+*Reach for it when* the agent must clamp or validate its output, compute
+a deterministic field from the model's judgment, or bound a retry
+back-edge before it routes.
+*Instead of* leaving cleanup to the downstream agent, or scattering
+post-processing inline with no order guarantee.
 ```python
 from leafmesh import chain
 
@@ -1039,7 +1111,13 @@ async def my_agent(llm_response, input_data, context):
 # Runs: agent() -> validate() -> format_output()
 ```
 
-### @chain_with_results -- Chain that collects intermediate results
+### @chain_with_results — keep the trail, not just the answer
+*Essence: like `@chain`, but preserves EACH stage's result, not only the
+final one — for when the operation needs an audit trail of how the agent
+got there.*
+*Reach for it when* a multi-stage derivation must be inspectable after
+the fact (compliance, debugging a scored decision).
+*Instead of* `@chain`, when the intermediate results are throwaway.
 ```python
 from leafmesh import chain_with_results
 
@@ -1049,7 +1127,14 @@ async def my_agent(llm_response, input_data, context):
 # Returns: {"main_result": ..., "chain_results": [step1_result, step2_result, step3_result]}
 ```
 
-### @conditional_chain -- Chain only if condition is met
+### @conditional_chain — do the extra work only when it's warranted
+*Essence: run a follow-on pipeline ONLY if a condition on the result
+holds — the agent enriches/escalates itself when needed and skips the
+cost when not.*
+*Reach for it when* extra steps (a second review, an approval pass)
+apply to some results, not all.
+*Instead of* always running the steps (waste), or pushing the branch
+onto a `can_call` wire when it's really part of THIS agent's own job.
 ```python
 from leafmesh import conditional_chain
 
@@ -1061,7 +1146,14 @@ async def my_agent(llm_response, input_data, context):
     return {"needs_review": True, "data": llm_response}
 ```
 
-### @compose -- Shape output per downstream agent
+### @compose — speak to each colleague in their language
+*Essence: shape a DIFFERENT payload for each downstream agent this one
+calls — billing gets the invoice, support gets the summary — instead of
+broadcasting one fat dict and making each peer dig for its part.*
+*Reach for it when* one agent fans out to several peers that each need a
+different slice or shape of its result.
+*Instead of* emitting one combined dict and relying on every downstream
+agent to extract its part (which couples them all to your shape).
 ```python
 from leafmesh import compose
 

create_leafmesh-2.5.2/create_leafmesh/templates/starter/README.md

@@ -0,0 +1,112 @@
+# {{project_name}} — Starter Mesh
+
+A **blank canvas** for building a LeafMesh agent mesh from scratch. It
+ships a tiny, working 3-agent mesh and — more importantly — a
+`configs/config.yaml` written as a guided tutorial. Read that file top
+to bottom; this README is the 5-minute quick start.
+
+> New here? This is the template to pick when none of the business
+> templates (finance-ops, customer-support, …) match what you're
+> building. Start from this and grow it into your own department.
+
+## What's in the box
+
+```
+configs/config.yaml     ← the mesh + the tutorial (READ THIS)
+main.py                 ← boots the mesh, registers the audit sink
+agency/_shared/         ← the WORM audit sink (the only Python shipped)
+validate_config.py      ← pre-flight checker — run before main.py
+env                     ← copy to .env and fill in
+Dockerfile / compose    ← container assets
+tests/                  ← a config-shape test you can extend
+```
+
+The mesh itself is three agents:
+
+| Agent | Kind | Role |
+|---|---|---|
+| `intake_agent` | LLM | Reads a request, classifies it, decides if a human is needed |
+| `reviewer_human` | Human | Approves/rejects sensitive requests (HITL gate) |
+| `audit_logger_agent` | External | Hash-chained, append-only audit log (terminus) |
+
+Routine requests: `intake → audit`. Sensitive ones: `intake → reviewer → audit`.
+
+## Run it
+
+```bash
+pip install -r requirements.txt
+
+# state store
+docker run -d -p 6379:6379 redis:7-alpine
+
+# config
+cp env .env        # then edit: LEAFMESH_LICENSE_KEY, OPENAI_API_KEY
+
+# pre-flight — catches YAML / wiring / contract mistakes before boot
+python validate_config.py
+
+# go — API + docs at http://127.0.0.1:18820/docs
+python main.py
+```
+
+Fire a request (new terminal):
+
+```bash
+# routine → answered + logged, no human
+curl -X POST http://127.0.0.1:18820/api/mesh/call \
+  -H "Content-Type: application/json" \
+  -d '{"entry_point":"new_request",
+       "input_data":{"source":"manual","message":"What are your hours?"}}'
+
+# sensitive → parked at the reviewer (approve it from the Studio inbox)
+curl -X POST http://127.0.0.1:18820/api/mesh/call \
+  -H "Content-Type: application/json" \
+  -d '{"entry_point":"new_request",
+       "input_data":{"source":"manual","message":"Please refund order 1234"}}'
+```
+
+Watch the audit trail build:
+
+```bash
+tail -f logs/audit.jsonl
+```
+
+## How to grow it
+
+Everything you add is a few lines of YAML. The config file has three
+ready-to-uncomment patterns:
+
+- **PATTERN A — a second LLM agent.** Add a teammate (e.g. a reply
+  writer) and a `can_call` wire to hand off to it.
+- **PATTERN B — a connector agent.** Point an agent at *your* system of
+  record (CRM/ERP/ticketing) via `integration: mcp` (or zapier / n8n /
+  composio). No Python — the mesh never keeps a private copy of your data.
+- **PATTERN C — a scheduled agent.** Give an agent a `wake_up:` cron and
+  a matching entry point for time-driven work.
+
+The golden rules (from the LeafMesh skill):
+
+1. **One role, multiple responsibilities** — an agent is a person you'd
+   hire. Don't split one job across two agents.
+2. **Wires are the policy** — put routing rules in `can_call` conditions
+   where anyone can read them, not in code.
+3. **YAML-first** — reach for a Python module only for actuators with
+   side effects, domain math that must not be hallucinated, or controls
+   like the audit sink. If you find yourself writing glue, the SDK
+   probably already does it.
+
+After any change: `python validate_config.py` → `python main.py`.
+
+## Deploy
+
+When you're ready for the cloud, the bundled `leafmesh-deploy` pushes
+this project to AWS / Azure / GCP:
+
+```bash
+leafmesh-deploy --plan          # see what would be created
+leafmesh-deploy --apply         # build + deploy
+```
+
+---
+
+*Built with `create-leafmesh`. The config is the department.*

create_leafmesh-2.5.2/create_leafmesh/templates/starter/_prompts.json

@@ -0,0 +1 @@
+{"env_vars": []}

create_leafmesh-2.5.2/create_leafmesh/templates/starter/agency/__init__.py

@@ -0,0 +1,2 @@
+"""starter — agency. Most starter agents are pure-YAML; add Python
+modules here only for actuators, domain math, or controls."""

create_leafmesh-2.5.2/create_leafmesh/templates/starter/agency/_shared/__init__.py

@@ -0,0 +1 @@
+"""starter — shared utilities (WORM audit sink)."""

create_leafmesh-2.5.2/create_leafmesh/templates/starter/configs/config.yaml

@@ -0,0 +1,352 @@
+# {{project_name}} — Starter mesh (build from scratch)
+#
+# ─────────────────────────────────────────────────────────────────────
+# READ THIS FILE TOP TO BOTTOM. It is a working 3-agent mesh AND a
+# tutorial. Every block is commented so you can copy a pattern, rename
+# it, and grow your own department. Run it as-is first:
+#
+#     pip install -r requirements.txt
+#     docker run -d -p 6379:6379 redis:7-alpine     # state store
+#     cp env .env  &&  edit .env  (LEAFMESH_LICENSE_KEY, OPENAI_API_KEY)
+#     python validate_config.py                     # pre-flight check
+#     python main.py                                # API at :18820/docs
+#
+# Then trigger the example flow:
+#
+#     curl -X POST http://127.0.0.1:18820/api/mesh/call \
+#       -H "Content-Type: application/json" \
+#       -d '{"entry_point": "new_request",
+#            "input_data": {"source": "manual",
+#                           "message": "Please refund order 1234"}}'
+#
+# ─────────────────────────────────────────────────────────────────────
+# THE MENTAL MODEL (the one thing to internalise)
+#
+#   A mesh is a TEAM of agents that talk peer-to-peer, not a pipeline.
+#   • An agent is a person you'd HIRE — its name is a job title, its
+#     prompt is the job description, its yields are what it hands back.
+#   • Agents call each other via `can_call:` with a `condition:` on the
+#     wire — that condition IS the business rule, written where anyone
+#     can read it (no logic hidden in Python).
+#   • The Manager hovers above and only steps in on exceptions.
+#   • YAML-FIRST: most agents need NO Python. The SDK turns `yields:`
+#     into structured output automatically. Add a Python module only
+#     for things YAML can't do — see agency/README notes below.
+#
+# This starter has 3 agents: one LLM intake, one human review gate, one
+# WORM audit sink. Plus commented-out patterns (a second LLM agent, a
+# connector to your system of record, a scheduled cron) for you to
+# uncomment as you grow.
+# ─────────────────────────────────────────────────────────────────────
+
+name: "{{project_name}}"
+version: "1.0.0"
+architecture: "managed_mesh"
+environment: "development"
+debug: true
+log_level: "INFO"
+
+# ── State store. Sessions, conversation history, dedup windows live in
+#    Redis. localhost works for dev; point at your managed Redis in prod.
+redis:
+  host: "${REDIS_HOST:localhost}"
+  port: ${REDIS_PORT:6379}
+  db: 0
+  password: "${REDIS_PASSWORD:}"
+  auto_storage: true
+  decode_responses: true
+  default_ttl: 86400
+  session_ttl: 86400
+
+# ── Agent auto-discovery. Any agency/<name>_agent.py whose function
+#    name matches an agent in this file is auto-wired. Pure-YAML agents
+#    (no module) just work — the SDK derives their behaviour from the
+#    prompt + yields below.
+auto_discover:
+  directory: "./agency"
+  pattern: "*_agent.py"
+  recursive: false
+
+# ── The Manager — supervisor, NOT a router. It watches the event
+#    stream via the Summarizer and intervenes only on escalations,
+#    narration hints, and contract violations. The agents route
+#    themselves through can_call wires.
+manager:
+  enabled: true
+  model: "gpt-4o-mini"
+  domain: "generic"
+  can_intervene: true
+  prompt: |
+    This is a starter mesh. A request comes in, intake_agent reads it
+    and decides whether it needs a human; routine items it answers
+    itself, sensitive ones go to reviewer_human. Everything ends in
+    the audit log.
+
+    Escalate when:
+      - intake_agent fails to classify after its retries
+      - reviewer_human does not respond within the timeout
+  routing:
+    mode: "learning"          # "static" for regulated/safety paths
+    confidence_threshold: 0.7
+    fallback: "all"
+
+mesh:
+  call_timeout: 120
+
+# ─────────────────────────────────────────────────────────────────────
+# DATA STRUCTURES — the canonical shape of things flowing through the
+# mesh. Optional, but declaring them documents your domain and lets the
+# SDK validate inputs. `required:` lists the fields an entry payload
+# MUST carry.
+# ─────────────────────────────────────────────────────────────────────
+data_structures:
+  Request:
+    type: "object"
+    properties:
+      request_id:  { type: "string" }
+      source:      { type: "string" }   # manual | email | webform | api
+      message:     { type: "string" }
+      received_at_utc: { type: "string" }
+    required: ["source"]
+
+# ─────────────────────────────────────────────────────────────────────
+# ENTRY POINTS — every real-world trigger that can START a workflow.
+# Name them after the TRIGGER (what happened in the world), point them
+# at the agent that owns the first decision. A mesh has many doors.
+# ─────────────────────────────────────────────────────────────────────
+entry_points:
+  - name: "new_request"
+    target: "intake_agent"
+    description: "A new request arrives (form, email, manual entry)"
+
+  # Direct-call door — hit one agent directly, bypassing the chain.
+  # Handy for debugging / replay / programmatic ingest.
+  - name: "direct_call_intake"
+    target: "intake_agent"
+    description: "Run intake on one payload directly (debug / replay)"
+
+  # ── PATTERN: a scheduled entry point (cron). Uncomment the agent's
+  #    `wake_up:` below to enable. A door that time opens, not a person.
+  # - name: "nightly_sweep"
+  #   target: "your_cron_agent"
+  #   description: "Nightly housekeeping sweep"
+
+# ─────────────────────────────────────────────────────────────────────
+# AGENTS — the team.
+# ─────────────────────────────────────────────────────────────────────
+agents:
+
+  # ── 1) LLM AGENT ────────────────────────────────────────────────
+  # The most common kind. No Python needed: the SDK sends the prompt to
+  # the model, forces a JSON response matching `yields:`, and fills any
+  # missing key with a type default so the wires below always evaluate.
+  #
+  # The wires under `can_call:` ARE the routing policy. Read them like
+  # business rules: "if it needs a human, send it to the reviewer;
+  # otherwise log it and finish."
+  intake_agent:
+    name: "intake_agent"
+    agent_type: "llm"
+    description: "Reads an incoming request, classifies it, decides if a human must review"
+    model: "gpt-4o-mini"
+    temperature: 0.1
+    communication_type: "chain"
+    prompt: |
+      You are the intake desk. Read the incoming request and classify it.
+
+      Decide:
+        - category: one of [question, complaint, refund, other]
+        - priority: one of [low, normal, high]
+        - needs_human: true ONLY when the request involves money,
+          a complaint, or anything you are not confident answering.
+        - draft_reply: a short, polite reply IF needs_human is false;
+          otherwise leave it empty (a human will write it).
+        - summary: one sentence a human reviewer could act on.
+
+      Echo `request_id` from the input unchanged so downstream steps
+      stay addressable.
+
+      OUTPUT CONTRACT — respond with ONLY valid JSON containing exactly
+      these keys:
+      {"category": "", "priority": "", "needs_human": false, "draft_reply": "", "summary": "", "request_id": ""}
+
+    # enforce_yields makes `yields:` a hard contract: on a bad-shape
+    # response the Manager retries the agent with the validation error.
+    enforce_yields: true
+    enforce_yields_retry: 2
+
+    # `yields:` doubles as the structured-output schema AND the set of
+    # fields the wires below (and downstream agents) may reference.
+    yields:
+      category: "string"
+      priority: "string"
+      needs_human: "boolean"
+      draft_reply: "string"
+      summary: "string"
+      request_id: "string"
+
+    inputs:
+      message: "string"
+      source: "string"
+
+    # ── The routing policy, as wires. Conditions reference THIS agent's
+    #    own yields. Exactly one fires per run here, but a mesh can
+    #    fan out to several at once.
+    can_call:
+      # Needs a human → hand to the reviewer gate.
+      - agent: "reviewer_human"
+        condition: "calling_agent_response.needs_human == true"
+
+      # Routine → straight to the audit log (intake already drafted it).
+      - agent: "audit_logger_agent"
+        condition: "calling_agent_response.needs_human == false"
+
+    auto_store_response: true
+    auto_store_yields: true
+
+  # ── 2) HUMAN AGENT (HITL gate) ──────────────────────────────────
+  # A real person in the loop. `human_interface: default` routes the
+  # task to the hosted Studio inbox; swap in Slack/Teams/webhook later.
+  # The person replies with one of the words the wires expect (below).
+  #
+  # IMPORTANT: when a human responds, the SDK delivers their reply as
+  # `human_message` (and other human_* meta fields) — NOT as your
+  # declared yields. So wire conditions on a human agent must read
+  # `calling_agent_response.human_message`, never `.decision`.
+  reviewer_human:
+    name: "reviewer_human"
+    agent_type: "human"
+    is_human_powered: true
+    description: "Reviews sensitive requests before any reply is sent"
+    human_interface: "default"
+    communication_type: "dual"
+    human_timeout_seconds: 3600          # 1 hour, then the fallback fires
+
+    # operator_ids: ["you@yourcompany.com"]   # optional. UNSET = shared
+    #   inbox (everyone sees it). Only set REAL emails — a placeholder
+    #   assigns the task to a nonexistent person and it shows up in no
+    #   inbox at all.
+
+    # Default-deny on silence: if no one answers in time, the workflow
+    # does NOT auto-approve — it records the timeout and stops.
+    fallback_on_timeout: true
+    fallback_response:
+      decision: "halt_for_review"
+      message: "halt_for_review"          # must match a wire token below
+      note: "Reviewer did not respond — held for manual review"
+
+    yields:
+      decision: "string"
+      notes: "string"
+    inputs:
+      summary: "string"
+      request_id: "string"
+
+    human_prompt_template: |
+      Review this request before any reply goes out.
+      Reply "approve" to send, "reject" to decline.
+      Summary: {{summary}}
+
+    can_call:
+      # The person's reply arrives as human_message. Route on it.
+      - agent: "audit_logger_agent"
+        condition: "calling_agent_response.human_message == 'approve' or calling_agent_response.human_message == 'reject' or calling_agent_response.human_message == 'halt_for_review'"
+
+  # ── 3) AUDIT SINK (external, WORM) ──────────────────────────────
+  # The terminus of every flow. Hash-chained, append-only — tamper
+  # evident. This is the ONE bit of Python the starter ships
+  # (agency/_shared/audit_logger.py), registered in main.py. Leave it;
+  # it's your compliance backbone.
+  audit_logger_agent:
+    name: "audit_logger_agent"
+    agent_type: "external"
+    description: "Hash-chained WORM audit — the immutable terminus of every flow"
+    framework: "custom"
+    communication_type: "execute"
+    connector_config:
+      sink_type: "local_file"
+      local_file_path: "./logs/audit.jsonl"
+    yields:
+      audit_event_id: "string"
+      written_at_utc: "string"
+      hash_chain_prev: "string"
+      hash_chain_current: "string"
+    inputs:
+      session_id: "string"
+      payload: "object"
+    can_call: []          # terminal — the buck stops here
+
+  # ─────────────────────────────────────────────────────────────────
+  # PATTERNS TO GROW INTO — copy, uncomment, rename. (Commented out so
+  # the starter runs clean; `validate_config.py` will check them once
+  # you enable them.)
+  # ─────────────────────────────────────────────────────────────────
+
+  # ── PATTERN A: a second LLM agent the intake can hand off to.
+  #    e.g. a drafter that writes the customer-facing reply. Add a wire
+  #    on intake_agent: → responder_agent when needs_human == false,
+  #    and have responder_agent → audit_logger_agent.
+  #
+  # responder_agent:
+  #   name: "responder_agent"
+  #   agent_type: "llm"
+  #   description: "Writes the final customer reply for routine requests"
+  #   model: "gpt-4o-mini"
+  #   temperature: 0.3
+  #   communication_type: "chain"
+  #   prompt: |
+  #     Write a warm, concise reply to the customer based on the
+  #     intake summary and draft.
+  #     OUTPUT CONTRACT — respond with ONLY valid JSON containing
+  #     exactly these keys:
+  #     {"reply_text": "", "request_id": ""}
+  #   enforce_yields: true
+  #   yields:
+  #     reply_text: "string"
+  #     request_id: "string"
+  #   can_call:
+  #     - agent: "audit_logger_agent"
+
+  # ── PATTERN B: a CONNECTOR agent — your system of record. The mesh
+  #    should NOT keep a private copy of your CRM/ERP/ticketing data.
+  #    A programmatic agent with `integration:` + `connector_config:`
+  #    calls YOUR system. No Python module needed.
+  #
+  # crm_lookup_agent:
+  #   name: "crm_lookup_agent"
+  #   agent_type: "programmatic"
+  #   description: "Looks up the customer in YOUR CRM (system of record)"
+  #   integration: "mcp"                  # or: zapier | composio | n8n
+  #   connector_config:
+  #     transport: "http"
+  #     url: "${CRM_MCP_URL:}"            # set in .env when you wire it
+  #     tool_name: "get_customer"
+  #   yields:
+  #     customer_id: "string"
+  #     tier: "string"
+  #   inputs:
+  #     email: "string"
+
+  # ── PATTERN C: a SCHEDULED agent (cron). `wake_up:` is a 5-field cron
+  #    expression. Nobody calls it — time does. Pair it with a matching
+  #    entry_point above. Keep crons commented until the agent's
+  #    dependencies (e.g. a connector) are actually wired, or the
+  #    schedule just fills the logs with errors.
+  #
+  # nightly_digest_agent:
+  #   name: "nightly_digest_agent"
+  #   agent_type: "llm"
+  #   description: "Summarises the day's requests for the team"
+  #   model: "gpt-4o-mini"
+  #   communication_type: "chain"
+  #   wake_up: "0 18 * * *"               # every day at 18:00
+  #   prompt: |
+  #     Summarise today's requests into a short team digest.
+  #     OUTPUT CONTRACT — respond with ONLY valid JSON containing
+  #     exactly these keys:
+  #     {"digest": "", "total_requests": 0}
+  #   yields:
+  #     digest: "string"
+  #     total_requests: "number"
+  #   can_call:
+  #     - agent: "audit_logger_agent"