1. Behavior and Context

In the jazzmine architecture, Flows exist as high-level blueprints.

• Deterministic Identity: Every flow uses uuid5 based on its name to generate a stable ID. This ensures that the ID remains consistent across process restarts, which is critical for maintaining stable point IDs in the Qdrant vector database.
• Automatic Registration: The system uses a WeakValueDictionary registry. Flows are automatically registered upon instantiation. Because the registry uses weak references, flows are automatically cleaned up by the garbage collector when no longer referenced in your application code, preventing memory leaks.
• Prompt-Centric Design: Every flow knows how to "explain itself" to an LLM via the build_prompt method, which generates highly structured XML instructions.

2. Purpose

• Task Abstraction: Encapsulating specific business logic and tool requirements into discrete, reusable objects.
• Stateful Orchestration: Modeling how sub-tasks relate to oneward another (order of operations, concurrency, branching).
• Search Optimization: Generating "Embedding Text" that acts as a semantic fingerprint for the ProceduralMemory retrieval system.
• Versioning: Providing checksum-based change detection to ensure the database always matches the current state of the source code.

3. High-Level API

Example: Defining a Standard Task (Leaf Flow)

from jazzmine.core.flows import Flow

# A standalone procedure for checking inventory
check_stock_flow = Flow(
    name="check_inventory",
    description="Check the current stock levels for a product.",
    condition="The user provides a product ID or name and asks about availability.",
    desired_effects=["Retrieve current stock count", "Report warehouse location"],
    examples=[
        "Is the iPhone 15 in stock?",
        "Check availability for SKU-99",
        "How many units do we have left?",
        "Do we have any green shirts?",
        "Where is the inventory for this item?"
    ],
    tools=["inventory_api"],
    priority=(1, 0)
)

from jazzmine.core.flows import FlowBuilder

# Combine existing flows into a pipeline
purchase_pipeline = FlowBuilder.sequential(
    "product_purchase",
    "Complete process from stock check to payment.",
    "User wants to buy an item they just found.",
    [
        "I'll take it", "Buy this now", "Place an order", 
        "Checkout please", "I want to purchase this"
    ],
    check_stock_flow,
    process_payment_flow,
    send_confirmation_flow
)

4. Detailed Functionality

Class: BaseFlow (Abstract)

The root of all procedural skills.

Class: Flow

A leaf node representing a single, discrete skill.

• Tools: Includes a list of tool names the agent is authorized to use while this flow is active.
• Priority: A tuple (major, minor) used to resolve conflicts during flow selection.
• Embedding Logic: Joins the description, condition, examples, and effects. This provides a rich semantic surface for the vector search.

Class: CompositeFlow (Base for Workflows)

A container for multiple sub-flows.

• Recursive Structure: Can contain standard Flows or other CompositeFlows.
• Embedding Strategy: Unlike leaf flows, composites do not aggregate their children's text. They only embed their own top-level description and examples. This prevents a high-level workflow from "hijacking" search results when a user only intends to trigger a specific sub-step.

Workflow Types

Class: FlowBuilder

A factory class providing static methods for cleaner composite flow generation.

• sequential(...)
• parallel(...)
• conditional(...)

5. Error Handling & Constraints

• Example Minimum: Every flow must have at least 5 examples. A ValueError is raised during initialization otherwise. This ensures the semantic search has enough signal to be reliable.
• Objective Requirement: Non-composite flows must have at least 1 desired effect.
• Syntax Validation: The class automatically runs ast.parse on the internal logic during setup to ensure the flow is technically sound before it ever reaches an LLM.

6. Remarks

• Identity Stability: Because of the uuid5 implementation, if you rename a flow in code, the framework treats it as a DELETE of the old name and a CREATE of the new one in the database.
• XML Escaping: All user-provided fields (names, descriptions) are automatically escaped to prevent the Agent's reasoning LLM from misinterpreting text as control tags.
• Registry Management: The BaseFlow.registry is a WeakValueDictionary, meaning it only keeps track of flows that are currently "alive" in your application. This is essential for long-running server processes.