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

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

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

{create_leafmesh-2.5.1 → 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.1"
+__version__ = "2.5.2"

{create_leafmesh-2.5.1 → 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.1 → create_leafmesh-2.5.2}/create_leafmesh.egg-info/PKG-INFO

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

{create_leafmesh-2.5.1 → create_leafmesh-2.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "create-leafmesh"
-version = "2.5.1"
+version = "2.5.2"
 description = "Project scaffolding + cloud-deploy tool for LeafMesh"
 readme = "README.md"
 requires-python = ">=3.10"