Vote: Which Hook System API Do You Prefer?

[wu-changxing]

🗳️ Vote: Which Hook System API Do You Prefer?

We're adding hooks to ConnectOnion and need your input on the API design!

What are hooks?

Hooks let you observe and modify agent behavior at key lifecycle points:

• 💰 Track token usage and costs
• 💾 Cache tool results
• 📝 Add timestamps to prompts
• 🔍 Custom logging and monitoring
• 🔄 Implement retry logic

---

The Five Options

Vote by reacting to this discussion:

• 👍 for Option 1 (TypedDict Hooks)
• ❤️ for Option 2 (Event Wrappers)
• 🚀 for Option 3 (Decorator Pattern)
• 👀 for Option 4 (Event Emitter)
• 🎯 for Option 5 (Sub-class Pattern)

---

Option 1: TypedDict Hooks (hooks=dict(...))

from connectonion import Agent, HookEvents

agent = Agent(
    "assistant",
    tools=[search],

    # ✨ IDE autocomplete with type annotation
    hooks=dict(
        before_llm=[add_timestamp],
        after_llm=[log_tokens],
        after_tool=[cache_results],
    )
)

Why you might like it:

• All configuration in one place (declarative)
• Easy to see what hooks are active
• Reusable across agents
• Optional IDE autocomplete: hooks: HookEvents = dict(...)

React with 👍 if this is your favorite

---

Option 2: Event Wrappers (hooks=[...])

from connectonion import Agent, before_llm, after_llm, after_tool

agent = Agent(
    "assistant",
    tools=[search],
    hooks=[
        before_llm(add_timestamp),
        after_llm(log_tokens),
        after_tool(cache_results),
    ]
)

Why you might like it:

• IDE autocomplete - suggests before_llm, after_llm
• Can't misspell - it's a function import
• Perfect for plugins:

  from connectonion.thinking import chain_of_thought
  hooks=[chain_of_thought()]  # Just works!

React with ❤️ if this is your favorite

---

Option 3: Decorator Pattern (@hook('event_name'))

from connectonion import Agent, hook

@hook('before_llm')
def add_timestamp(data):
    from datetime import datetime
    data['messages'].append({
        'role': 'system',
        'content': f'Current time: {datetime.now()}'
    })
    return data

@hook('after_llm')
def log_tokens(data):
    print(f"Tokens: {data['usage']['total_tokens']}")

agent = Agent("assistant", tools=[search],
    hooks=[add_timestamp, log_tokens])

Why you might like it:

• Familiar pattern (like @xray, @replay)
• Reusable across modules
• Self-documenting

React with 🚀 if this is your favorite

---

Option 4: Event Emitter (agent.on(...))

from connectonion import Agent

agent = Agent("assistant", tools=[search])

# Simple lambda
agent.on('after_llm', lambda d: print(f"Tokens: {d['usage']}"))

# Decorator syntax
@agent.on('before_llm')
def add_timestamp(data):
    from datetime import datetime
    data['messages'].append({
        'role': 'system',
        'content': f'Current time: {datetime.now()}'
    })
    return data

Why you might like it:

• Familiar to JavaScript/Node.js developers
• Dynamic add/remove hooks at runtime
• Discoverable with autocomplete

React with 👀 if this is your favorite

---

Option 5: Sub-class Pattern (OOP style)

from connectonion import Agent, Hook

class CostTracker(Hook):
    """Reusable hook class for tracking costs"""
    def after_llm(self, data):
        cost = data['usage']['total_tokens'] * 0.00001
        print(f"Cost: ${cost:.4f}")

class SmartCache(Hook):
    """Reusable hook class with state"""
    def __init__(self, ttl=3600):
        self.cache = {}
        self.ttl = ttl

    def after_tool(self, data):
        key = f"{data['tool_name']}:{hash(str(data['tool_args']))}"
        self.cache[key] = data['result']
        return data

# Use hook classes
agent = Agent(
    "assistant",
    tools=[search],
    hooks=[CostTracker(), SmartCache(ttl=7200)]
)

Alternative: Agent Subclass

class MonitoredAgent(Agent):
    """Custom agent with built-in monitoring"""

    def after_llm(self, data):
        print(f"Tokens: {data['usage']['total_tokens']}")

    def after_tool(self, data):
        print(f"Tool {data['tool_name']}: {data['status']}")

agent = MonitoredAgent("assistant", tools=[search])

Why you might like it:

• Full OOP - encapsulate state and behavior
• Perfect for complex hooks with initialization
• IDE autocomplete on method names
• Easy to share as packages (pip install connectonion-cost-tracker)
• Type hints on methods for better IDE support

React with 🎯 if this is your favorite

---

Common Use Cases

Cost Tracking (Simple)

# Option 1: TypedDict
agent = Agent("assistant", tools=[search], hooks=dict(
    after_llm=[lambda d: print(f"Cost: ${d['usage']['total_tokens'] * 0.00001:.4f}")]
))

# Option 5: Sub-class
class CostTracker(Hook):
    def after_llm(self, data):
        print(f"Cost: ${data['usage']['total_tokens'] * 0.00001:.4f}")

agent = Agent("assistant", tools=[search], hooks=[CostTracker()])

Smart Caching (With State)

# Option 5 shines for stateful hooks!
class SmartCache(Hook):
    def __init__(self, ttl=3600):
        self.cache = {}
        self.ttl = ttl
        self.hits = 0
        self.misses = 0

    def after_tool(self, data):
        key = f"{data['tool_name']}:{hash(str(data['tool_args']))}"

        # Check cache first
        if key in self.cache:
            self.hits += 1
            return self.cache[key]

        self.misses += 1
        self.cache[key] = data['result']
        return data

    def get_stats(self):
        return {'hits': self.hits, 'misses': self.misses}

cache = SmartCache(ttl=3600)
agent = Agent("assistant", tools=[search], hooks=[cache])
# Later: print(cache.get_stats())

Custom Logging (With Configuration)

# Option 5: Configurable logging
class StructuredLogger(Hook):
    def __init__(self, log_level="INFO", include_timing=True):
        self.logger = logging.getLogger(__name__)
        self.logger.setLevel(log_level)
        self.include_timing = include_timing

    def before_tool(self, data):
        self.logger.info(f"Tool: {data['tool_name']}")

    def after_tool(self, data):
        msg = f"Tool {data['tool_name']}: {data['status']}"
        if self.include_timing:
            msg += f" ({data['timing']:.2f}ms)"
        self.logger.info(msg)

agent = Agent("assistant", tools=[search],
    hooks=[StructuredLogger(log_level="DEBUG", include_timing=True)])

---

Hook Data Reference

Each hook receives a data dictionary with relevant context:

before_llm(data)

{'messages': [...], 'tools': [...], 'iteration': 1}

after_llm(data)

{'response': LLMResponse, 'usage': {'total_tokens': 150}, 'timing': 234.5}

before_tool(data) / after_tool(data)

{'tool_name': 'search', 'tool_args': {...}, 'result': '...', 'status': 'success'}

---

🗳️ How to Vote

React to this discussion:

• 👍 for Option 1 (TypedDict Hooks)
• ❤️ for Option 2 (Event Wrappers)
• 🚀 for Option 3 (Decorator Pattern)
• 👀 for Option 4 (Event Emitter)
• 🎯 for Option 5 (Sub-class Pattern)

Or comment with:

• Your preferred option and why
• Your primary use case (logging, caching, cost tracking, etc.)
• Any concerns or suggestions
• Whether you'd use multiple options or just one
• For Option 5: Would you prefer Hook classes or Agent subclassing?

---

📚 More Information

Detailed examples: docs/hook-system-options.md

Design journey: docs/design-decisions/010-hook-system-design.md

Technical discussion: Issue #31

---

Your vote shapes the API! 🙏

We're especially interested in:

• Which option feels most natural to you?
• Would you prefer just one option or multiple options?
• What's your primary use case?
• For Option 5: Would you publish hooks as separate packages?

[gourab337]

Hook 1 and 2 feels the most natural to me. In the order of development, TypeDict can be prioritised first (for best practice and maximal adoption), followed by Even Wrappers. We can analyse our users following that to determine if we choose sub class pattern (in case the users are teams building for complex workflows/ enterprise systems), or startups/solo devs preferring intuitiveness and flexibility.

For sub class pattern, agent subclass or hook classes both look equally good. I would vote for hook classes as agent subclass structure might violate DRY?

[wu-changxing]

implemented! check newest version!

[crossterra-agent]

Waiting for developer to complete implementation on PR https://github.com/CrossTerra/monorepo/pull/2008.