Add Feedback and Example Learning Components to Flock

[AndreRatzenberger]

Add Feedback and Example Learning Components to Flock

Summary

This PR introduces two new utility components to the Flock framework that enable agents to learn from previous interactions:

1. FeedbackUtilityComponent: Enables agents to learn from user feedback stored in the webapp
2. ExampleUtilityComponent: Enables n-shot learning by injecting relevant examples into agent inputs

Both components follow Flock's unified component architecture and integrate seamlessly with the existing agent creation system.

Changes

New Components

FeedbackUtilityComponent (src/flock/components/utility/feedback_utility_component.py)

• Retrieves user feedback from SQLite or Azure Table Storage
• Filters feedback by timeframe, keywords, and recency
• Formats and injects relevant feedback into agent inputs before evaluation
• Configurable through FeedbackUtilityConfig with options for:
  • Storage backend selection (SQLite/Azure)
  • Feedback filtering criteria
  • Injection settings

ExampleUtilityComponent (src/flock/components/utility/example_utility_component.py)

• Provides n-shot learning capabilities through example injection
• Includes static seed_examples() method for easy example population
• Stores examples in the same storage backends as feedback
• Configurable through ExampleUtilityConfig with options for:
  • Maximum number of examples to include
  • Example filtering by keywords
  • Custom injection keys

Storage Extensions

Extended SharedLinkStoreInterface (src/flock/webapp/app/services/sharing_store.py)

• Added abstract methods for example storage:
  • save_example()
  • get_example()
  • get_all_examples_for_agent()
• Implemented example storage in both SQLiteSharedLinkStore and AzureTableSharedLinkStore
• Created separate examples table in SQLite and flockexamples table in Azure

Agent Integration

Updated DefaultAgent (src/flock/core/agent/default_agent.py)

• Added enable_feedback and feedback_config parameters
• Added enable_examples and example_config parameters
• Components are automatically added when enabled
• Maintains backward compatibility

Updated FlockFactory (src/flock/core/flock_factory.py)

• Added comprehensive feedback configuration options
• Added comprehensive example configuration options
• Maintains backward compatibility with existing factory usage

Documentation and Examples

Example Implementation (examples/09-n-shot-learning.py)

• Demonstrates how to use ExampleUtilityComponent for n-shot learning
• Shows example creation, seeding, and agent configuration
• Illustrates how examples influence agent responses

Usage

Feedback Learning

# Create agent with feedback learning
agent = DefaultAgent(
    name="customer_service",
    input="query: str",
    output="response: str",
    enable_feedback=True,
    feedback_config=FeedbackUtilityConfig(
        max_feedback_items=5,
        feedback_timeframe_days=30
    )
)

# Feedback will be automatically injected into inputs
result = flock.run(agent=agent, input={"query": "test"})

N-Shot Learning

# Create and seed examples
examples = [
    ExampleRecord(
        agent_name="customer_service",
        example_id="example_1",
        content="Q: How do I reset my password?\nA: ..."
    )
]
ExampleUtilityComponent.seed_examples(examples)

# Create agent with example learning
agent = DefaultAgent(
    name="customer_service",
    enable_examples=True,
    example_config=ExampleUtilityConfig(
        max_examples=3,
        example_input_key="examples_context"
    )
)

Testing

The components have been designed with testability in mind:

• Mock-friendly storage interfaces
• Clear separation of concerns
• Comprehensive configuration options
• Error handling with graceful degradation

Breaking Changes

None. All changes are backward compatible:

• New parameters have default values
• Existing agent creation continues to work
• Storage extensions are additive

Benefits

1. Continuous Learning: Agents can improve from user feedback over time
2. N-Shot Learning: Easy to provide examples that guide agent behavior
3. Unified Storage: Uses existing infrastructure for persistence
4. Flexible Configuration: Fine-tune what feedback/examples are included
5. Production Ready: Supports both local SQLite and cloud Azure storage

Future Enhancements

Potential areas for future improvement:

• Semantic similarity matching for feedback/examples
• Feedback aggregation and summarization
• Analytics dashboard for feedback effectiveness
• Cross-agent learning capabilities

Checklist

• Components implement proper lifecycle hooks
• Storage backends handle errors gracefully
• Configuration is comprehensive and documented
• Examples demonstrate usage patterns
• Backward compatibility maintained
• Code follows Flock's architectural patterns

Review Notes

When reviewing, please pay special attention to:

1. Storage implementation in both SQLite and Azure backends
2. Error handling in the component lifecycle
3. Configuration parameter validation
4. Example seeding mechanism

These components provide a solid foundation for learning systems in Flock and enable agents to improve their performance over time through user feedback and examples.