goose-py 0.11.25__tar.gz → 0.12.0__tar.gz

{goose_py-0.11.25 → goose_py-0.12.0}/.gitignore

@@ -3,3 +3,4 @@ __pycache__
 poetry.lock
 notebooks
 dist
+.aider*

goose_py-0.12.0/PKG-INFO

@@ -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.12.0/README.md

@@ -0,0 +1,237 @@
+# 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.12.0/examples/01_structured_responses.py

@@ -0,0 +1,105 @@
+"""
+Example demonstrating structured LLM responses.
+
+This example shows how to create a structured result type and use it
+with a flow to ensure the LLM output conforms to expected schema.
+"""
+
+import asyncio
+import os
+
+from aikernel import LLMMessagePart, LLMSystemMessage, LLMUserMessage, get_router
+from pydantic import Field
+
+from goose import Agent, FlowArguments, Result, flow, task
+
+
+# Define a structured result type
+class RecipeResult(Result):
+    """Recipe with structured attributes."""
+    title: str = Field(description="The title of the recipe")
+    ingredients: list[str] = Field(description="List of ingredients needed")
+    steps: list[str] = Field(description="Step-by-step cooking instructions")
+    prep_time_minutes: int = Field(description="Preparation time in minutes")
+    cooking_time_minutes: int = Field(description="Cooking time in minutes")
+
+
+class RecipeFlowArguments(FlowArguments):
+    """Arguments for the recipe flow."""
+    ingredient: str
+
+
+@task
+async def generate_recipe(*, agent: Agent, ingredient: str) -> RecipeResult:
+    """Generate a recipe that uses the specified ingredient."""
+    print(f"Generating recipe for {ingredient}...")
+    
+    # Create a router for Gemini 2.0 Flash
+    router = get_router(models=("gemini-2.0-flash",))
+    
+    # System message with instructions
+    system_message = LLMSystemMessage(
+        parts=[LLMMessagePart(content=f"You are a creative chef. Create a recipe using {ingredient} as a main ingredient.")]
+    )
+    
+    # User request message
+    user_message = LLMUserMessage(
+        parts=[LLMMessagePart(content=f"Please create a recipe that features {ingredient} as a main ingredient.")]
+    )
+    
+    # Make the actual LLM call
+    return await agent(
+        messages=[system_message, user_message],
+        model="gemini-2.0-flash",
+        task_name="generate_recipe",
+        response_model=RecipeResult,
+        router=router
+    )
+
+
+@flow
+async def recipe_flow(*, flow_arguments: RecipeFlowArguments, agent: Agent) -> None:
+    """Flow for generating a recipe with structured output."""
+    await generate_recipe(agent=agent, ingredient=flow_arguments.ingredient)
+
+
+async def main():
+    """Run the recipe flow and display the results."""
+    # Create a unique run ID
+    run_id = f"recipe-{os.getpid()}"
+    
+    print("=== Structured LLM Responses Example ===")
+    print("This example demonstrates how to create structured result types")
+    print("and ensure LLM outputs conform to expected schemas.\n")
+    
+    # Run the recipe flow
+    async with recipe_flow.start_run(run_id=run_id) as run:
+        await recipe_flow.generate(RecipeFlowArguments(ingredient="avocado"))
+        
+        # Get the recipe from the result
+        recipe = run.get_result(task=generate_recipe)
+        
+        # Display the recipe information
+        print("\n--- Generated Recipe ---")
+        print(f"Recipe: {recipe.title}")
+        print("\nIngredients:")
+        for item in recipe.ingredients:
+            print(f"- {item}")
+        
+        print("\nInstructions:")
+        for i, step in enumerate(recipe.steps, 1):
+            print(f"{i}. {step}")
+        
+        print(f"\nPrep time: {recipe.prep_time_minutes} minutes")
+        print(f"Cooking time: {recipe.cooking_time_minutes} minutes")
+        
+        # Access fields directly with type safety
+        total_time = recipe.prep_time_minutes + recipe.cooking_time_minutes
+        print(f"Total time: {total_time} minutes")
+        
+        print("\nNote: This demonstrates how structured outputs provide type safety and")
+        print("predictable fields that can be accessed in your application code.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())