Merge branch 'dev/docs' into docs-build

Author: elmorenox

docs/public/building-from-scratch.md

@@ -16,6 +16,32 @@ CodonWorkload is the foundation for building observable AI agents. Whether you b
 
 For complete method signatures and parameters, see the [API Reference](api-reference.md).
 
+### Execution and Results
+
+**`execute(payload, *, deployment_id, entry_nodes=None, max_steps=1000)`**
+
+Executes the workload synchronously and returns an `ExecutionReport`. This is the primary method for running workloads in synchronous contexts.
+
+- **Async alternative**: Use `execute_async()` for async/await environments
+- **Parameters**: See [execute() API reference](api-reference.md#codon_sdk.agents.CodonWorkload.execute) for details
+
+**`report.node_results(node_name)`**
+
+Retrieves all outputs from a specific node during workload execution. Returns a list of results in execution order.
+
+- **Usage**: `final_output = report.node_results("output_node")[-1]` gets the most recent result
+- **Multiple executions**: If a node runs multiple times, you get all results as a list
+- **Parameters**: See [node_results() API reference](api-reference.md#codon_sdk.agents.ExecutionReport.node_results) for details
+
+**`report.ledger`**
+
+Complete audit trail of execution events for compliance monitoring and debugging.
+
+**Key Properties**
+
+- **`logic_id`**: Unique identifier for this specific workload configuration. Changes when nodes/edges are modified. See [logic_id API reference](api-reference.md#codon_sdk.agents.CodonWorkload.logic_id).
+- **`agent_class_id`**: Stable identifier for this workload type (format: 'name:version'). Consistent across deployments. See [agent_class_id API reference](api-reference.md#codon_sdk.agents.CodonWorkload.agent_class_id).
+
 ## Key Concepts
 
 **Nodes**: Individual Python functions that perform specific tasks (e.g., "summarize", "validate", "format"). Each node receives input, processes it, and can emit output to other nodes.
@@ -106,7 +132,7 @@ workload.add_node(prompt_builder, name="prompt_builder", role="format_prompt")
 workload.add_edge("prompt_builder", "call_model")
 workload.add_edge("call_model", "finalize")
 
-# Execute the workload
+# Execute the workload (also available: execute_async() for async contexts)
 report = workload.execute({"question": "What is the meaning of life, the universe, and everything?"}, deployment_id="local")
 
 # Check results
@@ -183,6 +209,7 @@ def build_multi_agent_workload() -> CodonWorkload:
 # Use the multi-agent workload
 multi_agent = build_multi_agent_workload()
 project = {"topic": "The impact of community gardens on urban wellbeing"}
+# Execute workload (also available: execute_async() for async contexts)
 multi_report = multi_agent.execute(project, deployment_id="demo", max_steps=20)
 final_document = multi_report.node_results("writer")[-1]
 ```
@@ -218,13 +245,15 @@ When you execute workloads after initializing telemetry, each node function call
 
 ### Runtime Operations
 The `runtime` parameter provides access to workflow operations:
+
 - `runtime.emit(node_name, payload)` - Send tokens to other nodes
 - `runtime.record_event(event_type, metadata={})` - Add custom audit entries
 - `runtime.state` - Shared dictionary for coordination between nodes
 - `runtime.stop()` - Halt execution early
 
 ### Audit Ledger
 Every workflow execution generates a comprehensive audit trail:
+
 - Token enqueue/dequeue events
 - Node completion events  
 - Custom events via `runtime.record_event()`

docs/public/instrumentation/index.md

@@ -28,4 +28,6 @@ pip install codon-sdk
 pip install codon-instrumentation-langgraph
 ```
 
-Each integration provides telemetry and observability for its respective framework while working alongside the core Codon SDK.
+Each integration provides telemetry and observability for its respective framework while working alongside the core Codon SDK.
+
+**Universal Interface:** All instrumentation packages convert framework-specific workflows into standard CodonWorkloads. This means you get the same `execute()`, `execute_async()`, `node_results()`, and other methods regardless of whether you built from scratch or wrapped an existing framework. See [Execution and Results](../building-from-scratch.md#execution-and-results) for the complete interface.

docs/public/instrumentation/langgraph.md

@@ -74,16 +74,18 @@ workload = LangGraphWorkloadAdapter.from_langgraph(
 )
 
 initial_state = {"topic": "Sustainable cities"}
+# Execute workload (also available: execute_async() for async contexts)
 report = workload.execute({"state": initial_state}, deployment_id="dev")
 print(report.node_results("writer")[-1])
 print(f"Ledger entries: {len(report.ledger)}")
 ```
 
 ### What Happened?
-1. Every LangGraph node was registered as a Codon node via `add_node`, producing a `NodeSpec`.
-2. Edges in the LangGraph became workload edges, so `runtime.emit` drives execution.
-3. `execute` seeded tokens with the provided state, ran the graph in token order, and captured telemetry & audit logs.
-4. You can inspect `report.ledger` for compliance, or `report.node_results(...)` for business outputs.
+1. **LangGraph → CodonWorkload**: Your LangGraph was converted into a standard CodonWorkload with the same execution interface as [building from scratch](../building-from-scratch.md#execution-and-results)
+2. **Node Registration**: Every LangGraph node was registered as a Codon node via `add_node`, producing a `NodeSpec`
+3. **Edge Conversion**: Edges in the LangGraph became workload edges, so `runtime.emit` drives execution
+4. **Token Execution**: `execute` seeded tokens with the provided state, ran the graph in token order, and captured telemetry & audit logs
+5. **Universal Interface**: You can use all the same methods - `execute()`, `report.node_results()`, `logic_id`, etc. - documented in [Execution and Results](../building-from-scratch.md#execution-and-results)
 
 ## Platform Integration
 
@@ -193,6 +195,7 @@ workload = LangGraphWorkloadAdapter.from_langgraph(
     name="ReflectiveAgent",
     version="0.1.0",
 )
+# Execute workload (also available: execute_async() for async contexts)
 result = workload.execute({"state": {"topic": "urban gardens"}}, deployment_id="demo")
 print(result.node_results("finalize")[-1])
 ```

sdk/src/codon_sdk/agents/codon_workload.py

@@ -218,6 +218,15 @@ class ExecutionReport:
     context: Dict[str, Any]
 
     def node_results(self, node: str) -> List[Any]:
+        """Get all results from a specific node during execution.
+
+        Args:
+            node: Name of the node to retrieve results from.
+
+        Returns:
+            List of results in execution order. Empty list if node never executed.
+            Use [-1] to get the most recent result if node executed multiple times.
+        """
         return [record.result for record in self.results.get(node, [])]
 
 
@@ -410,12 +419,23 @@ def __init__(
 
     @property
     def agent_class_id(self) -> str:
+        """Stable identifier for this workload type.
+        
+        Format is 'name:version' (e.g., 'my-agent:1.0.0'). Remains consistent 
+        across deployments as long as name and version don't change.
+        """
         if self._agent_class_id is None:
             raise WorkloadRegistrationError("Agent class ID has not been computed")
         return self._agent_class_id
 
     @property
     def logic_id(self) -> str:
+        """Unique identifier for this specific workload configuration.
+        
+        Generated from the complete workload structure (nodes, edges, topology).
+        Changes whenever nodes or edges are added/modified, useful for detecting
+        workload configuration changes.
+        """
         if self._logic_id is None:
             raise WorkloadRegistrationError("Logic ID has not been computed")
         return self._logic_id
@@ -521,6 +541,24 @@ async def execute_async(
         event_handler: Optional[Callable[[StreamEvent], Awaitable[None]]] = None,
         **kwargs: Any,
     ) -> ExecutionReport:
+        """Execute the workload asynchronously.
+
+        Args:
+            payload: Initial data passed to entry nodes as token payload.
+            deployment_id: Identifier for this deployment (required, used in telemetry context).
+            entry_nodes: List of node names to start execution from. If None, uses nodes with 
+                no predecessors, or all nodes if no entry nodes are found.
+            max_steps: Maximum execution steps before raising WorkloadRuntimeError (default: 1000).
+            event_handler: Optional callback for streaming execution events.
+            **kwargs: Additional arguments for execution context.
+
+        Returns:
+            ExecutionReport: Execution results with node outputs and audit logs.
+
+        Raises:
+            ValueError: If deployment_id is empty.
+            WorkloadRuntimeError: If no nodes registered, entry nodes invalid, or max_steps exceeded.
+        """
         if not deployment_id:
             raise ValueError("deployment_id is required when executing a workload")
         if not self._node_specs:
@@ -796,6 +834,23 @@ def execute(
         max_steps: int = 1000,
         **kwargs: Any,
     ) -> ExecutionReport:
+        """Execute the workload synchronously.
+
+        Args:
+            payload: Initial data passed to entry nodes as token payload.
+            deployment_id: Identifier for this deployment (required, used in telemetry context).
+            entry_nodes: List of node names to start execution from. If None, uses nodes with 
+                no predecessors, or all nodes if no entry nodes are found.
+            max_steps: Maximum execution steps before raising WorkloadRuntimeError (default: 1000).
+            **kwargs: Additional arguments passed to execute_async.
+
+        Returns:
+            ExecutionReport: Execution results with node outputs and audit logs.
+
+        Raises:
+            ValueError: If deployment_id is empty.
+            WorkloadRuntimeError: If no nodes registered, entry nodes invalid, or max_steps exceeded.
+        """
         return _run_coroutine_sync(
             lambda: self.execute_async(
                 payload,