vasceannie/biz-bud
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
efc58d43c257634b24092d76d80d9462078d016e
biz-bud/REGISTRY_REFACTOR_SUMMARY.md
Travis Vasceannie efc58d43c2 Cleanup (#45) 
* refactor: replace module-level config caching with thread-safe lazy loading

* refactor: migrate to registry-based architecture with new validation system

* Merge branch 'main' into cleanup

* feat: add secure graph routing with comprehensive security controls

* fix: add cross-package dependencies to pyrefly search paths

- Fix import resolution errors in business-buddy-tools package by adding
  ../business-buddy-core/src and ../business-buddy-extraction/src to search_path
- Fix import resolution errors in business-buddy-extraction package by adding
  ../business-buddy-core/src to search_path
- Resolves all 86 pyrefly import errors that were failing in CI/CD pipeline
- All packages now pass pyrefly type checking with 0 errors

The issue was that packages import from bb_core but pyrefly was only looking
in local src directories, not in sibling package directories.

* fix: resolve async function and security import issues

Research.py fixes:
- Create separate async config loader using load_config_async
- Fix _get_cached_config_async to properly await async lazy loader
- Prevents blocking event loop during config loading

Planner.py fixes:
- Move get_secure_router and execute_graph_securely imports to module level
- Remove imports from exception handlers to prevent cascade failures
- Improves reliability during security incident handling

Both fixes ensure proper async behavior and more robust error handling.
2025-07-20 13:21:05 -04:00

5.2 KiB
Raw Blame History

Registry-Based Architecture Refactoring Summary

Overview

Successfully refactored the Business Buddy codebase to use a registry-based architecture, significantly reducing complexity and improving maintainability.

What Was Accomplished

1. Registry Infrastructure (bb_core)

  • Base Registry Framework: Created generic, type-safe registry system with capability-based discovery
  • Registry Manager: Singleton pattern for coordinating multiple registries
  • Decorators: Simple decorators for auto-registration of components
  • Location: packages/business-buddy-core/src/bb_core/registry/

2. Component Registries

  • NodeRegistry: Auto-discovers and registers nodes with validation
  • GraphRegistry: Maintains compatibility with existing GRAPH_METADATA pattern
  • ToolRegistry: Manages LangChain tools with dynamic creation from nodes/graphs
  • Locations: src/biz_bud/registries/

3. Dynamic Tool Factory

  • ToolFactory: Creates LangChain tools dynamically from registered components
  • Capability-based tool discovery: Find tools by required capabilities
  • Location: src/biz_bud/agents/tool_factory.py

4. Buddy Agent Refactoring

Reduced buddy_agent.py from 754 lines to ~330 lines by extracting:

  • State Management (buddy_state_manager.py):

    • BuddyStateBuilder: Fluent builder for state creation
    • StateHelper: Common state operations

  • Execution Management (buddy_execution.py):

    • ExecutionRecordFactory: Creates execution records
    • PlanParser: Parses planner results
    • ResponseFormatter: Formats final responses
    • IntermediateResultsConverter: Converts results for synthesis

  • Routing System (buddy_routing.py):

    • BuddyRouter: Declarative routing with rules and priorities
    • String-based and function-based conditions

  • Node Registry (buddy_nodes_registry.py):

    • Registered Buddy-specific nodes with decorators
    • Maintains all node implementations

  • Configuration (config/schemas/buddy.py):

    • BuddyConfig: Centralized Buddy configuration

Key Benefits

  1. Reduced Complexity: Breaking up the monolithic buddy_agent.py into focused modules
  2. Dynamic Discovery: Components are discovered at runtime, not hardcoded
  3. Type Safety: Full type checking with protocols and generics
  4. Extensibility: Easy to add new nodes, graphs, or tools
  5. Maintainability: Clear separation of concerns
  6. Backward Compatibility: Existing GRAPH_METADATA pattern still works

Usage Examples

Registering a Node

from bb_core.registry import node_registry

@node_registry(
    name="my_node",
    category="processing",
    capabilities=["data_processing", "analysis"],
    tags=["example"]
)
async def my_node(state: State) -> dict[str, Any]:
    # Node implementation
    pass

Using the Tool Factory

from biz_bud.agents.tool_factory import get_tool_factory

# Get factory
factory = get_tool_factory()

# Create tools for capabilities
tools = factory.create_tools_for_capabilities(["text_synthesis", "planning"])

# Create specific node/graph tools
node_tool = factory.create_node_tool("synthesize_search_results")
graph_tool = factory.create_graph_tool("research")

Using State Builder

from biz_bud.agents.buddy_state_manager import BuddyStateBuilder

state = (BuddyStateBuilder()
    .with_query("Research AI trends")
    .with_thread_id()
    .with_config(app_config)
    .build())

Next Steps

  1. Plugin Architecture: Implement dynamic plugin loading for external components
  2. Registry Introspection: Add tools for exploring registered components
  3. Documentation: Generate documentation from registry metadata
  4. Performance Optimization: Add caching for frequently used components
  5. Testing: Add comprehensive tests for registry system

Files Modified/Created

New Files

  • packages/business-buddy-core/src/bb_core/registry/__init__.py
  • packages/business-buddy-core/src/bb_core/registry/base.py
  • packages/business-buddy-core/src/bb_core/registry/decorators.py
  • packages/business-buddy-core/src/bb_core/registry/manager.py
  • src/biz_bud/registries/__init__.py
  • src/biz_bud/registries/node_registry.py
  • src/biz_bud/registries/graph_registry.py
  • src/biz_bud/registries/tool_registry.py
  • src/biz_bud/agents/tool_factory.py
  • src/biz_bud/agents/buddy_state_manager.py
  • src/biz_bud/agents/buddy_execution.py
  • src/biz_bud/agents/buddy_routing.py
  • src/biz_bud/agents/buddy_nodes_registry.py
  • src/biz_bud/config/schemas/buddy.py

Modified Files

  • packages/business-buddy-core/src/bb_core/__init__.py (added registry exports)
  • src/biz_bud/nodes/synthesis/synthesize.py (added registry decorator)
  • src/biz_bud/nodes/analysis/plan.py (added registry decorator)
  • src/biz_bud/graphs/planner.py (updated to use registry)
  • src/biz_bud/agents/buddy_agent.py (refactored to use new modules)
  • src/biz_bud/config/schemas/app.py (added buddy_config)
  • src/biz_bud/states/buddy.py (added "orchestrating" to phase literal)

Conclusion

The registry-based refactoring has successfully abstracted away the scale and complexity of the Buddy agent system. The codebase is now more modular, maintainable, and extensible while maintaining full backward compatibility.

Reference in New Issue View Git Blame Copy Permalink