goose-py 0.11.25__py3-none-any.whl → 0.12.0__py3-none-any.whl

goose/__init__.py

@@ -1,3 +1,18 @@
+"""Goose: A framework for building LLM-based agents and workflows.
+
+Goose provides tools for creating structured agent applications with support for:
+- Task-based workflow orchestration
+- Caching and state management
+- Result validation and typing
+- Agent conversations and refinement
+
+Main components:
+- Agent: Base agent for interacting with LLMs
+- flow: Decorator for creating connected workflows
+- task: Decorator for creating individual tasks
+- Result: Base class for structured response types
+"""
+
 from goose._internal.agent import Agent
 from goose._internal.flow import FlowArguments, flow
 from goose._internal.result import Result, TextResult

goose/_internal/agent.py

@@ -1,3 +1,9 @@
+"""Agent module for interacting with language models.
+
+This module provides the Agent class for handling interactions with language models,
+along with protocols for custom logging.
+"""
+
 import logging
 from datetime import datetime
 from typing import Any, Literal, Protocol, overload
@@ -22,10 +28,27 @@ ExpectedMessage = LLMUserMessage | LLMAssistantMessage | LLMSystemMessage | LLMT
 
 
 class IAgentLogger(Protocol):
+    """Protocol for custom agent response logging.
+
+    Implement this protocol to create custom loggers for agent responses.
+    """
+
     async def __call__(self, *, response: AgentResponse[Any]) -> None: ...
 
 
 class Agent:
+    """Agent for interacting with language models.
+
+    The Agent class handles interactions with language models, including generating
+    structured and unstructured responses, asking questions, and refining results.
+    It also manages logging of model interactions.
+
+    Attributes:
+        flow_name: The name of the flow this agent is part of
+        run_id: The ID of the current run
+        logger: Optional custom logger for agent responses
+    """
+
     def __init__(
         self,
         *,
@@ -33,6 +56,13 @@ class Agent:
         run_id: str,
         logger: IAgentLogger | None = None,
     ) -> None:
+        """Initialize an Agent.
+
+        Args:
+            flow_name: The name of the flow this agent is part of
+            run_id: The ID of the current run
+            logger: Optional custom logger for agent responses
+        """
         self.flow_name = flow_name
         self.run_id = run_id
         self.logger = logger
@@ -46,15 +76,33 @@ class Agent:
         router: LLMRouter[M],
         response_model: type[R] = TextResult,
     ) -> R:
+        """Generate a structured response from the language model.
+
+        This method sends a sequence of messages to the language model and expects
+        a structured response conforming to the provided response_model.
+
+        Args:
+            messages: List of messages to send to the language model
+            model: The language model alias to use
+            task_name: Name of the task for logging and tracking
+            router: LLM router for routing the request
+            response_model: Pydantic model class for the expected response structure
+
+        Returns:
+            A validated instance of the response_model
+
+        Raises:
+            ValidationError: If the response cannot be parsed into the response_model
+        """
         start_time = datetime.now()
         typed_messages: list[ExpectedMessage] = [*messages]
 
         if response_model is TextResult:
-            response = await llm_unstructured(model=model, messages=typed_messages, router=router)
+            response = await llm_unstructured(messages=typed_messages, router=router)
             parsed_response = response_model.model_validate({"text": response.text})
         else:
             response = await llm_structured(
-                model=model, messages=typed_messages, response_model=response_model, router=router
+                messages=typed_messages, response_model=response_model, router=router
             )
             parsed_response = response.structured_response
 
@@ -96,9 +144,23 @@ class Agent:
         task_name: str,
         router: LLMRouter[M],
     ) -> str:
+        """Ask the language model for an unstructured text response.
+
+        This method sends a sequence of messages to the language model and
+        receives a free-form text response.
+
+        Args:
+            messages: List of messages to send to the language model
+            model: The language model alias to use
+            task_name: Name of the task for logging and tracking
+            router: LLM router for routing the request
+
+        Returns:
+            The text response from the language model
+        """
         start_time = datetime.now()
         typed_messages: list[ExpectedMessage] = [*messages]
-        response = await llm_unstructured(model=model, messages=typed_messages, router=router)
+        response = await llm_unstructured(messages=typed_messages, router=router)
         end_time = datetime.now()
 
         if isinstance(messages[0], LLMSystemMessage):
@@ -138,10 +200,30 @@ class Agent:
         task_name: str,
         response_model: type[R],
     ) -> R:
+        """Refine a previous structured response based on feedback.
+
+        This method uses a find-and-replace approach to refine a previous structured
+        response. It identifies parts of the previous response to change and applies
+        these changes to create an updated response.
+
+        Args:
+            messages: List of messages including the previous response and feedback
+            model: The language model alias to use
+            router: LLM router for routing the request
+            task_name: Name of the task for logging and tracking
+            response_model: The model class of the response to refine
+
+        Returns:
+            A refined instance of the response_model
+
+        Raises:
+            Honk: If no previous result is found in the message history
+            ValidationError: If the refined result cannot be validated against the response_model
+        """
         start_time = datetime.now()
         typed_messages: list[ExpectedMessage] = [*messages]
         find_replace_response = await llm_structured(
-            model=model, messages=typed_messages, response_model=FindReplaceResponse, router=router
+            messages=typed_messages, response_model=FindReplaceResponse, router=router
         )
         parsed_find_replace_response = find_replace_response.structured_response
         end_time = datetime.now()
@@ -252,6 +334,19 @@ class Agent:
     def __apply_find_replace[R: Result](
         self, *, result: R, find_replace_response: FindReplaceResponse, response_model: type[R]
     ) -> R:
+        """Apply find-replace operations to a result.
+
+        Takes a result object and a set of replacements, applies the replacements,
+        and validates the new result against the response model.
+
+        Args:
+            result: The original result to modify
+            find_replace_response: Object containing the replacements to apply
+            response_model: The model class to validate the result against
+
+        Returns:
+            A new instance of the response model with replacements applied
+        """
         dumped_result = result.model_dump_json()
         for replacement in find_replace_response.replacements:
             dumped_result = dumped_result.replace(replacement.find, replacement.replace)
@@ -261,6 +356,21 @@ class Agent:
     def __find_last_result[R: Result](
         self, *, messages: list[LLMUserMessage | LLMAssistantMessage | LLMSystemMessage], response_model: type[R]
     ) -> R:
+        """Find the last result in a conversation history.
+
+        Searches through messages in reverse order to find the most recent
+        assistant message that can be parsed as the given response model.
+
+        Args:
+            messages: List of messages to search through
+            response_model: The model class to validate found results against
+
+        Returns:
+            The last result that can be validated as the response model
+
+        Raises:
+            Honk: If no valid result is found in the message history
+        """
         for message in reversed(messages):
             if isinstance(message, LLMAssistantMessage):
                 try:

goose/_internal/flow.py

@@ -1,3 +1,10 @@
+"""Flow module for orchestrating sequences of tasks.
+
+This module provides the Flow class and flow decorator for building
+workflows that coordinate multiple tasks with state management,
+persistence, and run tracking.
+"""
+
 from collections.abc import AsyncIterator, Callable
 from contextlib import asynccontextmanager
 from types import CodeType
@@ -12,18 +19,46 @@ from .store import IFlowRunStore, InMemoryFlowRunStore
 
 
 class IGenerator[FlowArgumentsT: FlowArguments](Protocol):
+    """Protocol for flow generator functions.
+
+    This protocol defines the interface for functions that can be used
+    to create flows.
+
+    Type Parameters:
+        FlowArgumentsT: Type of flow arguments
+    """
+
     __name__: str
 
     async def __call__(self, *, flow_arguments: FlowArgumentsT, agent: Agent) -> None: ...
 
 
 class IAdapter[ResultT: Result](Protocol):
+    """Protocol for adapters that transform conversations to results.
+
+    This protocol defines the interface for functions that can adapt
+    conversations to structured results.
+
+    Type Parameters:
+        ResultT: Type of result
+    """
+
     __code__: CodeType
 
     async def __call__(self, *, conversation: Conversation, agent: Agent) -> ResultT: ...
 
 
 class Flow[FlowArgumentsT: FlowArguments]:
+    """Orchestrates a sequence of tasks with persistent state.
+
+    A Flow manages the execution of tasks, tracks state, and handles
+    persistence of results. It provides mechanisms for starting runs,
+    generating results, and regenerating flows.
+
+    Type Parameters:
+        FlowArgumentsT: Type of flow arguments
+    """
+
     def __init__(
         self,
         fn: IGenerator[FlowArgumentsT],
@@ -33,6 +68,14 @@ class Flow[FlowArgumentsT: FlowArguments]:
         store: IFlowRunStore | None = None,
         agent_logger: IAgentLogger | None = None,
     ) -> None:
+        """Initialize a Flow.
+
+        Args:
+            fn: The flow generator function
+            name: Optional custom name for the flow (defaults to function name)
+            store: Optional store for persisting flow runs
+            agent_logger: Optional logger for agent responses
+        """
         self._fn = fn
         self._name = name
         self._agent_logger = agent_logger
@@ -40,6 +83,14 @@ class Flow[FlowArgumentsT: FlowArguments]:
 
     @property
     def flow_arguments_model(self) -> type[FlowArgumentsT]:
+        """Get the flow arguments model type.
+
+        Returns:
+            The FlowArguments type used by this flow
+
+        Raises:
+            Honk: If the flow function has an invalid signature
+        """
         arguments_model = self._fn.__annotations__.get("flow_arguments")
         if arguments_model is None:
             raise Honk("Flow function has an invalid signature. Must accept `flow_arguments` and `agent` as arguments.")
@@ -48,10 +99,23 @@ class Flow[FlowArgumentsT: FlowArguments]:
 
     @property
     def name(self) -> str:
+        """Get the name of the flow.
+
+        Returns:
+            The name of the flow (custom name or function name)
+        """
         return self._name or self._fn.__name__
 
     @property
     def current_run(self) -> FlowRun[FlowArgumentsT]:
+        """Get the current flow run.
+
+        Returns:
+            The current flow run
+
+        Raises:
+            Honk: If there is no current flow run
+        """
         run = get_current_flow_run()
         if run is None:
             raise Honk("No current flow run")
@@ -59,6 +123,23 @@ class Flow[FlowArgumentsT: FlowArguments]:
 
     @asynccontextmanager
     async def start_run(self, *, run_id: str) -> AsyncIterator[FlowRun[FlowArgumentsT]]:
+        """Start a new run of this flow.
+
+        This context manager starts a new flow run or loads an existing one,
+        sets it as the current run, and handles persistence when the context exits.
+
+        Args:
+            run_id: Unique identifier for this run
+
+        Yields:
+            The flow run instance
+
+        Example:
+            ```python
+            async with my_flow.start_run(run_id="123") as run:
+                await my_flow.generate(MyFlowArguments(...))
+            ```
+        """
         existing_serialized_run = await self._store.get(run_id=run_id)
         if existing_serialized_run is not None:
             run = FlowRun.load(
@@ -78,6 +159,17 @@ class Flow[FlowArgumentsT: FlowArguments]:
         set_current_flow_run(old_run)
 
     async def generate(self, flow_arguments: FlowArgumentsT, /) -> None:
+        """Execute the flow with the given arguments.
+
+        This method runs the flow function with the provided arguments,
+        executing all tasks defined within the flow.
+
+        Args:
+            flow_arguments: Arguments for the flow
+
+        Raises:
+            Honk: If there is no current flow run
+        """
         flow_run = get_current_flow_run()
         if flow_run is None:
             raise Honk("No current flow run")
@@ -86,6 +178,14 @@ class Flow[FlowArgumentsT: FlowArguments]:
         await self._fn(flow_arguments=flow_arguments, agent=flow_run.agent)
 
     async def regenerate(self) -> None:
+        """Regenerate the flow using the same arguments.
+
+        This method re-executes the flow function with the same arguments
+        as the previous execution, which is useful for retrying a flow.
+
+        Raises:
+            Honk: If there is no current flow run
+        """
         flow_run = get_current_flow_run()
         if flow_run is None:
             raise Honk("No current flow run")
@@ -110,6 +210,32 @@ def flow[FlowArgumentsT: FlowArguments](
     store: IFlowRunStore | None = None,
     agent_logger: IAgentLogger | None = None,
 ) -> Flow[FlowArgumentsT] | Callable[[IGenerator[FlowArgumentsT]], Flow[FlowArgumentsT]]:
+    """Decorator for creating Flow instances.
+
+    This decorator transforms async functions into Flow objects that can
+    orchestrate task execution, manage state, and handle persistence.
+
+    Examples:
+        ```python
+        @flow
+        async def my_workflow(*, flow_arguments: MyFlowArguments, agent: Agent) -> None:
+            # Flow implementation...
+
+        # Or with parameters
+        @flow(name="custom_name", store=CustomStore())
+        async def my_workflow(*, flow_arguments: MyFlowArguments, agent: Agent) -> None:
+            # Flow implementation...
+        ```
+
+    Args:
+        fn: The function to decorate
+        name: Optional custom name for the flow
+        store: Optional store for persisting flow runs
+        agent_logger: Optional logger for agent responses
+
+    Returns:
+        A Flow instance, or a decorator function if used with parameters
+    """
     if fn is None:
 
         def decorator(fn: IGenerator[FlowArgumentsT]) -> Flow[FlowArgumentsT]:

goose/_internal/result.py

@@ -1,20 +1,56 @@
+"""Result models for agent responses.
+
+This module provides the base classes and models for structured results from LLM agents.
+"""
+
 from pydantic import BaseModel, ConfigDict, Field
 
 
 class Result(BaseModel):
+    """Base class for all result models.
+
+    All result models in Goose extend from this class to have consistent
+    behavior. Results are frozen (immutable) by default.
+    """
+
     model_config = ConfigDict(frozen=True)
 
 
 class TextResult(Result):
+    """Simple text result model.
+
+    A basic result type that contains unstructured text output from an agent.
+
+    Attributes:
+        text: The text content of the result
+    """
+
     text: str
 
 
 class Replacement(BaseModel):
+    """Represents a text replacement operation.
+
+    Used in find-and-replace operations to refine structured results.
+
+    Attributes:
+        find: The text to find in the original result
+        replace: The text to replace the found text with
+    """
+
     find: str = Field(description="Text to find, to be replaced with `replace`")
     replace: str = Field(description="Text to replace `find` with")
 
 
 class FindReplaceResponse(BaseModel):
+    """Model for find-and-replace operations on structured results.
+
+    Used to refine existing results by applying a series of replacements.
+
+    Attributes:
+        replacements: List of replacement operations to apply
+    """
+
     replacements: list[Replacement] = Field(
         description="List of replacements to make in the previous result to satisfy the user's request"
     )

goose/_internal/task.py

@@ -1,3 +1,10 @@
+"""Task module for defining and executing LLM tasks.
+
+This module provides the Task class and task decorator for creating and executing
+individual LLM tasks within a flow. Tasks handle execution, caching, conversation
+management, and result refinement.
+"""
+
 import hashlib
 from collections.abc import Awaitable, Callable
 from typing import Any, overload
@@ -12,6 +19,16 @@ from goose.errors import Honk
 
 
 class Task[**P, R: Result]:
+    """A task within a flow that produces a structured result.
+
+    Tasks are the building blocks of flows and represent individual LLM operations.
+    They handle execution, result caching, conversation management, and result refinement.
+
+    Type Parameters:
+        P: Parameter types for the task function
+        R: Result type for the task, must be a subclass of Result
+    """
+
     def __init__(
         self,
         generator: Callable[P, Awaitable[R]],
@@ -19,11 +36,25 @@ class Task[**P, R: Result]:
         *,
         retries: int = 0,
     ) -> None:
+        """Initialize a Task.
+
+        Args:
+            generator: The function that implements the task
+            retries: Number of automatic retries if the task fails
+        """
         self._generator = generator
         self._retries = retries
 
     @property
     def result_type(self) -> type[R]:
+        """Get the return type of the task.
+
+        Returns:
+            The result type class for this task
+
+        Raises:
+            Honk: If the task function has no return type annotation
+        """
         result_type = self._generator.__annotations__.get("return")
         if result_type is None:
             raise Honk(f"Task {self.name} has no return type annotation")
@@ -31,9 +62,27 @@ class Task[**P, R: Result]:
 
     @property
     def name(self) -> str:
+        """Get the name of the task.
+
+        Returns:
+            The name of the task, derived from the generator function name
+        """
         return self._generator.__name__
 
     async def generate(self, state: NodeState, *args: P.args, **kwargs: P.kwargs) -> R:
+        """Generate a result for this task.
+
+        Executes the task generator function to produce a result. Uses caching
+        based on input hashing to avoid redundant executions.
+
+        Args:
+            state: The current node state for this task execution
+            *args: Positional arguments for the task function
+            **kwargs: Keyword arguments for the task function
+
+        Returns:
+            The generated result, either freshly computed or from cache
+        """
         state_hash = self.__hash_task_call(*args, **kwargs)
         if state_hash != state.last_hash:
             result = await self._generator(*args, **kwargs)
@@ -51,6 +100,24 @@ class Task[**P, R: Result]:
         context: LLMSystemMessage | None = None,
         index: int = 0,
     ) -> str:
+        """Ask a follow-up question about a task's result.
+
+        This method allows for a conversational interaction with a task after
+        it has been executed, to ask questions or get explanations about the result.
+
+        Args:
+            user_message: The user's question or message
+            router: LLM router for routing the request
+            model: The model to use for generating the response
+            context: Optional system message to provide context
+            index: Index of the task instance when the same task appears multiple times
+
+        Returns:
+            The response text from the model
+
+        Raises:
+            Honk: If the task has not been initially generated
+        """
         flow_run = self.__get_current_flow_run()
         node_state = flow_run.get_state(task=self, index=index)
 
@@ -82,6 +149,24 @@ class Task[**P, R: Result]:
         context: LLMSystemMessage | None = None,
         index: int = 0,
     ) -> R:
+        """Refine a task's result based on feedback.
+
+        This method allows for iterative refinement of a task's result based on
+        user feedback or additional requirements.
+
+        Args:
+            user_message: The user's feedback or refinement request
+            router: LLM router for routing the request
+            model: The model to use for generating the response
+            context: Optional system message to provide context
+            index: Index of the task instance when the same task appears multiple times
+
+        Returns:
+            A refined result of the same type as the original result
+
+        Raises:
+            Honk: If the task has not been initially generated
+        """
         flow_run = self.__get_current_flow_run()
         node_state = flow_run.get_state(task=self, index=index)
 
@@ -106,18 +191,46 @@ class Task[**P, R: Result]:
         return result
 
     def edit(self, *, result: R, index: int = 0) -> None:
+        """Manually edit a task's result.
+
+        This method allows for direct editing of a task's result, bypassing
+        the usual generation process.
+
+        Args:
+            result: The new result to use
+            index: Index of the task instance to edit
+        """
         flow_run = self.__get_current_flow_run()
         node_state = flow_run.get_state(task=self, index=index)
         node_state.edit_last_result(result=result.model_dump_json())
         flow_run.upsert_node_state(node_state)
 
     def undo(self, *, index: int = 0) -> None:
+        """Undo the most recent change to a task's state.
+
+        This method reverts the task's state to its previous version.
+
+        Args:
+            index: Index of the task instance to undo
+        """
         flow_run = self.__get_current_flow_run()
         node_state = flow_run.get_state(task=self, index=index)
         node_state.undo()
         flow_run.upsert_node_state(node_state)
 
     async def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
+        """Execute the task within a flow.
+
+        This method is called when the task is invoked as a function within a flow.
+        It manages state setup, generation, and state persistence.
+
+        Args:
+            *args: Positional arguments for the task function
+            **kwargs: Keyword arguments for the task function
+
+        Returns:
+            The result of the task
+        """
         flow_run = self.__get_current_flow_run()
         node_state = flow_run.get_next_state(task=self)
         result = await self.generate(node_state, *args, **kwargs)
@@ -125,6 +238,22 @@ class Task[**P, R: Result]:
         return result
 
     def __hash_task_call(self, *args: P.args, **kwargs: P.kwargs) -> int:
+        """Create a hash of task arguments for caching.
+
+        Generates a unique hash based on the task's input arguments
+        to determine when inputs have changed and results need to be regenerated.
+
+        Args:
+            *args: Positional arguments to hash
+            **kwargs: Keyword arguments to hash
+
+        Returns:
+            An integer hash of the arguments
+
+        Raises:
+            Honk: If an argument cannot be hashed
+        """
+
         def update_hash(argument: Any, current_hash: Any = hashlib.sha256()) -> None:
             try:
                 if isinstance(argument, list | tuple | set):
@@ -152,6 +281,14 @@ class Task[**P, R: Result]:
         return int(result.hexdigest(), 16)
 
     def __get_current_flow_run(self) -> FlowRun[Any]:
+        """Get the current flow run.
+
+        Returns:
+            The current flow run
+
+        Raises:
+            Honk: If there is no current flow run
+        """
         run = get_current_flow_run()
         if run is None:
             raise Honk("No current flow run")
@@ -168,6 +305,30 @@ def task[**P, R: Result](
     *,
     retries: int = 0,
 ) -> Task[P, R] | Callable[[Callable[P, Awaitable[R]]], Task[P, R]]:
+    """Decorator for creating Task instances.
+
+    This decorator transforms async functions into Task objects that can be
+    used in flows. Tasks handle execution, caching, conversation, and result refinement.
+
+    Examples:
+        ```python
+        @task
+        async def generate_summary(text: str) -> TextResult:
+            # Task implementation...
+
+        # Or with parameters
+        @task(retries=2)
+        async def generate_summary(text: str) -> TextResult:
+            # Task implementation...
+        ```
+
+    Args:
+        generator: The function to decorate
+        retries: Number of automatic retries if the task fails
+
+    Returns:
+        A Task instance, or a decorator function if used with parameters
+    """
     if generator is None:
 
         def decorator(fn: Callable[P, Awaitable[R]]) -> Task[P, R]:

goose/errors.py

@@ -1,2 +1,16 @@
+"""Errors module for Goose.
+
+This module defines the custom exception classes used in the Goose framework.
+"""
+
+
 class Honk(Exception):
+    """Base exception class for Goose framework errors.
+
+    This exception is raised when an error occurs in the Goose framework,
+    such as invalid task configuration, missing requirements, or runtime errors.
+
+    The name "Honk" follows the goose theme of the framework.
+    """
+
     pass

goose_py-0.12.0.dist-info/METADATA

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: goose-py
+Version: 0.12.0
+Summary: A tool for AI workflows based on human-computer collaboration and structured output.
+Author-email: Nash Taylor <nash@chelle.ai>, Joshua Cook <joshua@chelle.ai>, Michael Sankur <michael@chelle.ai>
+Requires-Python: >=3.12
+Requires-Dist: aikernel==0.1.43
+Requires-Dist: jsonpath-ng>=1.7.0
+Requires-Dist: pydantic>=2.8.2
+Description-Content-Type: text/markdown
+
+# Goose
+
+Goose is a framework for building LLM-based agents and workflows with strong typing and state management. Here's what's fundamentally possible:
+
+1. Structured LLM interactions - Organize model calls with typed inputs/outputs
+2. Task orchestration - Create reusable tasks that can be composed into flows
+3. Stateful conversations - Maintain conversation history and model outputs
+4. Result caching - Avoid redundant computation based on input hashing
+5. Iterative refinement - Enhance results through progressive feedback loops
+6. Result validation - Ensure model outputs conform to expected schemas
+7. Run persistence - Save and reload workflow executions
+8. Custom logging - Track telemetry and performance metrics
+
+It enables building reliable, maintainable AI applications with proper error handling, state tracking, and flow control while ensuring type safety throughout.
+
+## Key Features
+
+### Structured LLM Interactions
+
+Organize model calls with typed inputs and outputs using Pydantic models. This ensures that responses from language models conform to expected structures.
+
+```mermaid
+graph LR
+    A[User Input] --> B[Agent]
+    B --> C[LLM Model]
+    C --> D[Structured Response]
+    D --> E[Validated Result]
+    E --> F[Application Logic]
+    
+    classDef user fill:#f9f,stroke:#333,stroke-width:2px
+    classDef llm fill:#bbf,stroke:#333,stroke-width:2px
+    classDef validation fill:#bfb,stroke:#333,stroke-width:2px
+    
+    class A user
+    class C llm
+    class D,E validation
+```
+
+### Task Orchestration
+
+Create reusable tasks that can be composed into flows. Tasks are decorated functions that handle specific operations, while flows coordinate multiple tasks.
+
+```mermaid
+graph TD
+    A[Flow] --> B[Task 1]
+    A --> C[Task 2]
+    A --> D[Task 3]
+    B --> E[Result 1]
+    C --> F[Result 2]
+    D --> G[Result 3]
+    E --> H[Flow Output]
+    F --> H
+    G --> H
+    
+    classDef flow fill:#f9f,stroke:#333,stroke-width:2px
+    classDef task fill:#bbf,stroke:#333,stroke-width:2px
+    classDef result fill:#bfb,stroke:#333,stroke-width:2px
+    
+    class A flow
+    class B,C,D task
+    class E,F,G,H result
+```
+
+### Stateful Conversations
+
+Maintain conversation history and model outputs across multiple interactions. The framework tracks the state of each task in a flow.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Flow
+    participant Task
+    participant Agent
+    participant LLM
+    
+    User->>Flow: Start Conversation
+    Flow->>Task: Execute
+    Task->>Agent: Generate Response
+    Agent->>LLM: Send Messages
+    LLM-->>Agent: Generate Response
+    Agent-->>Task: Store Result
+    Task-->>Flow: Update State
+    Flow-->>User: Return Result
+    
+    User->>Flow: Follow-up Question
+    Flow->>Task: Get State
+    Task->>Agent: Send Previous Context + New Question
+    Agent->>LLM: Send Updated Messages
+    LLM-->>Agent: Generate Response
+    Agent-->>Task: Update Conversation
+    Task-->>Flow: Update State
+    Flow-->>User: Return Result
+```
+
+### Result Caching
+
+Avoid redundant computation by caching results based on input hashing. The framework automatically detects when inputs change and only regenerates results when necessary.
+
+```mermaid
+flowchart TD
+    A[Task Call] --> B{Inputs Changed?}
+    B -- Yes --> C[Execute Task]
+    B -- No --> D[Return Cached Result]
+    C --> E[Cache Result]
+    E --> F[Return Result]
+    D --> F
+    
+    classDef decision fill:#f9f,stroke:#333,stroke-width:2px
+    classDef action fill:#bbf,stroke:#333,stroke-width:2px
+    classDef cache fill:#bfb,stroke:#333,stroke-width:2px
+    
+    class B decision
+    class A,C,F action
+    class D,E cache
+```
+
+### Iterative Refinement
+
+Enhance results through progressive feedback loops. The framework supports asking follow-up questions about results and refining them based on feedback.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Task
+    participant Agent
+    participant LLM
+    
+    User->>Task: Generate Initial Result
+    Task->>Agent: Send Request
+    Agent->>LLM: Generate Structured Output
+    LLM-->>Agent: Return Output
+    Agent-->>Task: Store Result
+    Task-->>User: Return Result
+    
+    User->>Task: Request Refinement
+    Task->>Agent: Send Feedback + Original Result
+    Agent->>LLM: Generate Find/Replace Operations
+    LLM-->>Agent: Return Changes
+    Agent-->>Task: Apply Changes to Result
+    Task-->>User: Return Refined Result
+```
+
+### Result Validation
+
+Ensure model outputs conform to expected schemas using Pydantic validation. All results must conform to predefined models.
+
+```mermaid
+flowchart LR
+    A[LLM Response] --> B[Parse JSON]
+    B --> C{Valid Schema?}
+    C -- Yes --> D[Return Validated Result]
+    C -- No --> E[Raise Error]
+    
+    classDef input fill:#bbf,stroke:#333,stroke-width:2px
+    classDef validation fill:#f9f,stroke:#333,stroke-width:2px
+    classDef output fill:#bfb,stroke:#333,stroke-width:2px
+    classDef error fill:#fbb,stroke:#333,stroke-width:2px
+    
+    class A input
+    class B,C validation
+    class D output
+    class E error
+```
+
+### Run Persistence
+
+Save and reload workflow executions. The framework provides interfaces for storing flow runs, allowing for resuming work or reviewing past executions.
+
+```mermaid
+graph TD
+    A[Start Flow] --> B[Create Flow Run]
+    B --> C[Execute Tasks]
+    C --> D[Save Run State]
+    D --> E[End Flow]
+    
+    F[Later Time] --> G[Load Saved Run]
+    G --> H[Resume Execution]
+    H --> D
+    
+    classDef flow fill:#f9f,stroke:#333,stroke-width:2px
+    classDef execution fill:#bbf,stroke:#333,stroke-width:2px
+    classDef storage fill:#bfb,stroke:#333,stroke-width:2px
+    
+    class A,E,F flow
+    class B,C,H execution
+    class D,G storage
+```
+
+### Custom Logging
+
+Track telemetry and performance metrics. The framework supports custom loggers to record model usage, token counts, and execution time.
+
+```mermaid
+flowchart TD
+    A[Agent Call] --> B[Execute LLM Request]
+    B --> C[Record Metrics]
+    C --> D{Custom Logger?}
+    D -- Yes --> E[Send to Custom Logger]
+    D -- No --> F[Log to Default Logger]
+    E --> G[Return Result]
+    F --> G
+    
+    classDef action fill:#bbf,stroke:#333,stroke-width:2px
+    classDef logging fill:#bfb,stroke:#333,stroke-width:2px
+    classDef decision fill:#f9f,stroke:#333,stroke-width:2px
+    
+    class A,B,G action
+    class C,E,F logging
+    class D decision
+```
+
+## Building with Goose
+
+Goose enables building reliable, maintainable AI applications with proper error handling, state tracking, and flow control while ensuring type safety throughout. This approach reduces common issues in LLM applications like:
+
+- Type inconsistencies in model responses
+- Loss of context between interactions
+- Redundant LLM calls for identical inputs
+- Difficulty in resuming interrupted workflows
+- Lack of structured error handling
+
+Start building more robust LLM applications with Goose's typed, stateful approach to agent development.
+
+## Installation and Package Management
+
+Goose uses `uv` for package management. Never use pip with this project.
+
+```bash
+# Install dependencies
+uv add <package-name>
+
+# Update dependencies file
+uv sync
+
+# Run commands
+uv run <command>
+```

{goose_py-0.11.25.dist-info → goose_py-0.12.0.dist-info}/RECORD

@@ -1,18 +1,18 @@
-goose/__init__.py,sha256=Muw7HCImZHk3kLCTWhV9Lg-Sfmhnwf_Tae-zCj7woyY,338
-goose/errors.py,sha256=-0OyZQJWYTRw5YgnCB2_uorVaUsL6Z0QYQO2FqzCiyg,32
+goose/__init__.py,sha256=58IFJL7Zd4WMqlbWhOtDVbU4sUegFjTIYuGsDQJAZU4,842
+goose/errors.py,sha256=FtCv1uGzsDijktcFePVvAQd0rC0MuSBLFIh8YwwJ_BU,429
 goose/flow.py,sha256=YsZLBa5I1W27_P6LYGWbtFX8ZYx9vJG3KtENYChHm5E,111
 goose/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 goose/runs.py,sha256=ub-r_gzbUbaIzWXX-jc-dncNxEh6zTfzIkmnDfCSbRI,160
 goose/task.py,sha256=95rspdxETJoY12IHBl3KjnVIdqQnf1jDKlnGWNWOTvQ,53
-goose/_internal/agent.py,sha256=9Hz15SOrhaJWgOXhfQYYW4nrolB2xbMG5G3RwHX_k90,9187
+goose/_internal/agent.py,sha256=K1dKXsfI1a7W8RUNoDcEOs4zX_1-LCHvOEcxzsTiicg,13405
 goose/_internal/conversation.py,sha256=vhJwe1pHk2lV60DaB9Tz9KbpzQo7_thRYInPjbIoUTE,1437
-goose/_internal/flow.py,sha256=8MJxlhHYSAzUHZefpF_sRJc37o532OF0X7l3KRopDmc,4115
-goose/_internal/result.py,sha256=vtJMfBxb9skfl8st2tn4hBmEq6qmXiJTme_B5QTgu2M,538
+goose/_internal/flow.py,sha256=nfmy-RyWnt1jh0TBMpy-YpX8ayltjUcPtLOZ4mDFfds,7947
+goose/_internal/result.py,sha256=MXH1jhZSzN_T1ZkslJk6b49otovBlWLhiyr3pAmT1OM,1522
 goose/_internal/state.py,sha256=kA116MpsetsQz6nYodsXOqE3uYz37OTgjC9Vcy_3Qvg,8065
 goose/_internal/store.py,sha256=tWmKfa1-yq1jU6lT3l6kSOmVt2m3H7I1xLMTrxnUDI8,889
-goose/_internal/task.py,sha256=A13TsBQJlo1yuAqbUpDY8k15JAd5WZxqgrz32F18H2U,6311
+goose/_internal/task.py,sha256=I2COwqtRFkO46jvberh_XMMnPCOlJu4Y5-JajMUjaG4,11672
 goose/_internal/types/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 goose/_internal/types/telemetry.py,sha256=xpfkhx7zCdZjjKU8rPuUJ2UHgqmZ084ZupzbTU36gSM,3791
-goose_py-0.11.25.dist-info/METADATA,sha256=varvcbhfLhYcbexYd9BFx_Usp2PMxsgboBWspwXOc1I,444
-goose_py-0.11.25.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-goose_py-0.11.25.dist-info/RECORD,,
+goose_py-0.12.0.dist-info/METADATA,sha256=qCPOuLUaoejhbU6C-EhVt0aqPPpE3xpi8VSWf9tyrbM,7621
+goose_py-0.12.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+goose_py-0.12.0.dist-info/RECORD,,

goose_py-0.11.25.dist-info/METADATA

@@ -1,14 +0,0 @@
-Metadata-Version: 2.4
-Name: goose-py
-Version: 0.11.25
-Summary: A tool for AI workflows based on human-computer collaboration and structured output.
-Author-email: Nash Taylor <nash@chelle.ai>, Joshua Cook <joshua@chelle.ai>, Michael Sankur <michael@chelle.ai>
-Requires-Python: >=3.12
-Requires-Dist: aikernel==0.1.42
-Requires-Dist: jsonpath-ng>=1.7.0
-Requires-Dist: pydantic>=2.8.2
-Description-Content-Type: text/markdown
-
-# Goose
-
-Docs to come.