docs: improve clarity and correctness of documentation (#28)

Author: rbeauchamp

.claude/commands/continue-session.md

@@ -1 +1 @@
-Please think deeper and proceed per continue-session-prompt.md
+Please read and think deeply about continue-session-prompt.md and then proceed per the instructions there.

README.md

@@ -7,12 +7,12 @@
 ![License](https://img.shields.io/badge/License-MIT-yellow)
 [![llms.txt](https://img.shields.io/badge/llms.txt-green)](https://raw.githubusercontent.com/artificial-sapience/clearflow/main/llms.txt)
 
-Correctness-first orchestration for emergent AI. Type-safe, deeply immutable, 100% code coverage.
+Correctness-first orchestration for probabilistic AI. Type-safe, deeply immutable, 100% code coverage.
 
 ## Why ClearFlow?
 
 - **Message-driven architecture** – Commands trigger actions, Events record facts
-- **100% test coverage** – Every path proven to work
+- **100% test coverage** – Every path verified to work
 - **Type-safe flows** – Full static typing with pyright strict mode
 - **Deep immutability** – All state transformations create new immutable data
 - **Minimal dependencies** – Only Pydantic for validation and immutability
@@ -45,9 +45,9 @@ pip install clearflow
 
 | Example | What It Shows |
 |---------|---------------|
-| [Chat](examples/chat/) | Message routing between user and LLM |
-| [Portfolio Analysis](examples/portfolio_analysis/) | DSPy-driven portfolio analysis |
-| [RAG](examples/rag/) | Document processing pipeline |
+| [Chat](examples/chat/) | OpenAI integration with conversation history |
+| [Portfolio Analysis](examples/portfolio_analysis/) | Multi-agent coordination using DSPy |
+| [RAG](examples/rag/) | Document chunking and FAISS vector search |
 
 ## AI Assistant Integration
 

clearflow/_internal/callback_handler.py

@@ -1,8 +1,4 @@
-"""Internal callback handler implementation.
-
-This module contains the private implementation for managing observers
-with automatic error isolation.
-"""
+"""Internal callback handler implementation."""
 
 import sys
 from collections.abc import Sequence
@@ -12,11 +8,7 @@
 
 
 class CallbackHandler:
-    """Internal handler that manages observers with automatic error isolation.
-
-    Executes all registered observers for each event, ensuring that
-    errors in one observer don't affect others or the flow execution.
-    """
+    """Internal handler that manages observers with automatic error isolation."""
 
     def __init__(self, observers: Sequence[Observer]) -> None:
         """Initialize with observers.

clearflow/_internal/flow_impl.py

@@ -1,10 +1,4 @@
-"""Message flow implementation for type-safe routing.
-
-Provides an explicit routing API for building message-driven workflows where
-messages are routed based on their types. Uses strategic type erasure at
-routing boundaries to handle union types while maintaining type safety at
-flow input/output boundaries.
-"""
+"""Message flow implementation for type-safe routing."""
 
 import types
 from dataclasses import dataclass
@@ -159,51 +153,21 @@ def _validate_terminal_type_not_routed(
 
 @final
 class _Flow[TStartIn: Message, TEnd: Message](Node[TStartIn, TEnd]):
-    """Executable AI workflow that routes messages through nodes based on their types.
-
-    Orchestrates message flow through a graph of AI operations, routing based on
-    message types. Each node performs a specific AI task (LLM calls, vector search,
-    validation) and produces typed outputs that determine the next step.
-
-    Why _Flow is internal:
-    - Complex type erasure patterns needed for union type routing
-    - Internal optimization strategies for message dispatch
-    - Separation of builder API from execution mechanics
-    - Maintains simpler public API surface
-
-    The flow provides:
-    - Type-safe message routing at runtime
-    - Automatic causality chain preservation
-    - Observer hooks for monitoring AI decisions
-    - Single termination enforcement for clear workflow completion
-
-    """
+    """Executable workflow that routes messages through nodes based on their types."""
 
-    starting_node: NodeInterface[Message, Message] = Field(
-        description="First node to process incoming messages, typically parsing or validation"
-    )
+    starting_node: NodeInterface[Message, Message] = Field(description="First node to process incoming messages")
     routes: tuple[RouteEntry, ...] = Field(
         description="Routing table mapping (source_node, message_type) pairs to destination nodes"
     )
-    terminal_type: type[Message] = Field(
-        description="Message type that immediately completes the flow when produced by any node"
-    )
-    callbacks: CallbackHandler | None = Field(
-        default=None, description="Optional handler for observer callbacks to monitor flow execution events"
-    )
+    terminal_type: type[Message] = Field(description="Message type that completes the flow when produced")
+    callbacks: CallbackHandler | None = Field(default=None, description="Optional handler for observer callbacks")
 
     async def _safe_callback(self, method: str, *args: str | Message | Exception | None) -> None:
         """Execute callback safely without affecting flow.
 
-        REQ-016: Zero overhead when no callbacks
-        REQ-017: Async execution (non-blocking)
-
-        CallbackHandler internally handles all errors (REQ-005, REQ-006) so we don't
-        need additional error handling here.
-
         Args:
             method: Name of callback method to invoke
-            *args: Arguments to pass to the callback method (flow_name, node_name, message, error)
+            *args: Arguments to pass to the callback method
 
         """
         if not self.callbacks:  # REQ-016: Zero overhead when no callbacks
@@ -311,20 +275,11 @@ async def process(self, message: TStartIn) -> TEnd:
 @final
 @dataclass(frozen=True)
 class _FlowBuilder[TStartIn: Message, TStartOut: Message](FlowBuilder[TStartIn, TStartOut]):
-    """Module private builder for composing message routes with explicit source nodes.
-
-    Uses the pattern from the original flow API where each route explicitly
-    specifies: from_node -> outcome -> to_node. This enables sequential thinking
-    about workflow construction.
+    """Internal builder for composing message routes with explicit source nodes.
 
     Type parameters:
         TStartIn: The input message type the flow accepts
-        TStartOut: The output type of the start node (remains constant throughout builder chain)
-
-    The builder maintains stable type parameters throughout the chain, unlike tracking
-    current message types, because type erasure makes intermediate types meaningless.
-
-    Call end_flow() to specify where the flow terminates and get the completed flow.
+        TStartOut: The output type of the start node
     """
 
     name: str
@@ -399,9 +354,6 @@ def _validate_and_create_route[TFromIn: Message, TFromOut: Message, TToIn: Messa
     def observe(self, *observers: Observer) -> "_FlowBuilder[TStartIn, TStartOut]":
         """Attach observers to the flow.
 
-        REQ-009: MessageFlow accepts optional observers
-        REQ-016: Zero overhead when no observers
-
         Args:
             *observers: Observer instances to monitor flow execution
 
@@ -428,17 +380,6 @@ def route[TFromIn: Message, TFromOut: Message, TToIn: Message, TToOut: Message](
     ) -> "_FlowBuilder[TStartIn, TStartOut]":
         """Route specific message type from source node to destination.
 
-        Explicitly specifies that when `from_node` produces a message of type `outcome`,
-        route it to `to_node`. This matches the original flow API pattern for clarity.
-
-        Type Erasure Rationale:
-            Python's type system cannot express "route only this specific type from
-            a union to the next node." For example, if a node outputs
-            UserMessage | SystemMessage, we cannot type-check at compile time that
-            only UserMessage goes to a specific handler. We use type erasure
-            (outcome: type[Message]) to allow this flexibility while maintaining
-            runtime validation.
-
         Args:
             from_node: Source node that may emit the outcome message type
             outcome: Specific message type that triggers this route
@@ -472,15 +413,11 @@ def end_flow[TEnd: Message](
     ) -> Node[TStartIn, TEnd]:
         """Declare the message type that completes this flow.
 
-        When any node in the flow produces an instance of the terminal type,
-        the flow immediately terminates and returns that message. The terminal
-        type cannot be routed between nodes - it always ends the flow.
-
         Args:
             terminal_type: The message type that completes the flow
 
         Returns:
-            A Node that represents the complete flow with single terminal type
+            A Node that represents the complete flow
 
         """
         # Validate that terminal type is not already routed
@@ -501,11 +438,8 @@ def create_flow[TStartIn: Message, TStartOut: Message](
 ) -> FlowBuilder[TStartIn, TStartOut]:
     """Create a flow with type-safe routing.
 
-    This is the entry point for building message-driven workflows. The flow
-    starts at the given node and routes messages based on their types.
-
     Args:
-        name: The name of the flow for identification and debugging
+        name: The name of the flow
         starting_node: The starting node that processes TStartIn
 
     Returns:

clearflow/flow.py

@@ -12,10 +12,6 @@
 class FlowBuilder[TStartIn: Message, TStartOut: Message](ABC):
     """Builder for composing message-driven flows.
 
-    Provides a fluent API for composing message routes through nodes.
-    Users interact with this interface to define how messages flow
-    through their system based on message types.
-
     Type parameters:
         TStartIn: The input message type the flow accepts
         TStartOut: The output type of the start node
@@ -61,18 +57,14 @@ def end_flow[TEnd: Message](
     ) -> Node[TStartIn, TEnd]:
         """Declare the message type that completes this flow.
 
-        When any node in the flow produces an instance of the terminal type,
-        the flow immediately terminates and returns that message. The terminal
-        type cannot be routed between nodes - it always ends the flow.
-
-        This enforces single responsibility: each flow has exactly one
-        completion condition defined by its terminal type.
+        When any node produces an instance of the terminal type, the flow
+        immediately terminates and returns that message.
 
         Args:
             terminal_type: The message type that completes the flow
 
         Returns:
-            A Node that represents the complete flow with single terminal type
+            A Node that represents the complete flow
 
         """
         ...

clearflow/message.py

@@ -26,22 +26,17 @@ def _utc_now() -> AwareDatetime:
 
 
 class Message(StrictBaseModel, ABC):
-    """Base message class for message-driven AI orchestration.
-
-    Messages enable type-safe, immutable data flow between nodes with full causality tracking.
-    Each message carries metadata for tracing, debugging, and understanding AI decision chains.
-
-    Why use Message:
-    - Type-safe routing: Route on message types, not strings
-    - Causality tracking: Trace AI decisions through triggered_by chains
-    - Immutable state: Prevent unintended mutations in complex flows
-    - Session isolation: run_id ensures messages stay within their flow
-
-    Perfect for:
-    - LLM orchestration with traceable decision chains
-    - Multi-agent workflows requiring audit trails
-    - RAG pipelines with clear data lineage
-    - Any AI system requiring reproducible execution paths
+    """Abstract base class for Commands and Events in message-driven flows.
+
+    A Message is an immutable data structure that flows between nodes, carrying
+    both domain data and metadata for causality tracking and flow isolation.
+
+    Attributes:
+        id: Unique identifier for this message instance
+        triggered_by_id: ID of the message that caused this one (None for root commands)
+        timestamp: UTC time when this message was created
+        run_id: Session identifier linking all messages in a single flow execution
+
     """
 
     id: uuid.UUID = Field(
@@ -62,24 +57,19 @@ class Message(StrictBaseModel, ABC):
 
 
 class Event(Message):
-    """Immutable fact representing something that has occurred in the AI workflow.
-
-    Events capture completed actions, state transitions, and outcomes from AI operations.
-    Every event MUST be triggered by another message, ensuring complete causality chains.
+    """An immutable record of something that has occurred.
 
-    Why use Event:
-    - Past-tense facts: Events describe what HAS happened, not what should happen
-    - Required causality: triggered_by_id is mandatory, ensuring traceable AI decisions
-    - Immutable history: Once created, events form an unchangeable audit trail
-    - Type-based routing: Different event types trigger different downstream actions
+    Events represent facts about state changes or completed actions in the system.
+    They are named in past tense (e.g., OrderPlaced, DocumentProcessed) and
+    must always have a triggered_by_id linking to the message that caused them.
 
-    Example event types for AI systems:
-    - LLMResponseGenerated: Captures model output with metadata
-    - DocumentIndexed: Records successful vector storage operation
-    - ValidationFailed: Documents why an AI output was rejected
-    - ThresholdExceeded: Signals when metrics cross boundaries
+    Events cannot be rejected or modified - they represent what has already happened.
+    If an error occurs, emit a new event describing the failure rather than
+    trying to undo the original event.
 
-    This is an abstract base - create domain-specific events for your AI workflow.
+    Constraints:
+        - Must have triggered_by_id (cannot be None)
+        - Cannot be instantiated directly (create concrete subclasses)
     """
 
     @model_validator(mode="after")
@@ -111,24 +101,20 @@ def _validate_event(self) -> "Event":
 
 
 class Command(Message):
-    """Imperative request for an action to be performed in the AI workflow.
+    """An imperative request to perform an action that may change state.
 
-    Commands express intent and trigger operations like LLM calls, data retrieval, or analysis.
-    Initial commands (triggered_by_id=None) start new flow executions.
+    Commands express intent to transform or process data. They are named
+    using imperative verbs (e.g., ProcessOrder, ValidateDocument) and are
+    processed by a single node that decides how to fulfill the request.
 
-    Why use Command:
-    - Clear intent: Commands use imperative language (ProcessDocument, GenerateResponse)
-    - Flow initiation: Commands with triggered_by_id=None start new workflows
-    - Decoupled execution: Nodes decide HOW to fulfill commands independently
-    - Request/response pattern: Commands trigger events upon completion
+    Commands may result in:
+        - One or more events describing what happened
+        - Error events if the operation fails
 
-    Example command types for AI systems:
-    - AnalyzeDocument: Request document understanding via LLM
-    - RetrieveContext: Fetch relevant vectors from embedding store
-    - GenerateSummary: Produce condensed output from source material
-    - ValidateOutput: Check AI response against quality criteria
+    Root commands (triggered_by_id=None) initiate new flow executions.
 
-    This is an abstract base - create domain-specific commands for your AI operations.
+    Constraints:
+        - Cannot be instantiated directly (create concrete subclasses)
     """
 
     @model_validator(mode="after")