Add billing API endpoints and enhance agent execution capabilities

[jfrench9]

Summary

This PR introduces comprehensive billing and organization management capabilities while enhancing the agent execution system with new strategy and response mode options. The changes span multiple releases (v0.2.11 and v0.2.12) and significantly expand the client's functionality.

Key Accomplishments

🏢 Billing & Organization Management

• Added complete billing API endpoints with checkout functionality
• Implemented organization management capabilities
• Enhanced credit transaction listing with improved filtering options
• Updated checkout models with refined resource configuration options

🤖 Agent Execution Enhancements

• Enhanced auto_select_agent and execute_specific_agent APIs with execution strategy support
• Added response mode configuration options for more flexible agent interactions
• Improved agent metadata and listing capabilities
• Significant expansion of agent execution logic (+168 lines combined)

🔧 Client Extensions

• New: Added comprehensive AgentClient extension (+526 lines) for simplified agent interactions
• Enhanced extensions module with better initialization and configuration
• Improved client extensibility architecture

Breaking Changes

• Agent execution APIs now support additional parameters for execution strategy and response modes
• Some checkout model fields may have updated validation requirements
• Credit transaction listing API may return additional fields

Testing Notes

• Verify all existing agent execution workflows continue to function correctly
• Test new billing and checkout endpoints with various payment scenarios
• Validate organization management operations across different user permission levels
• Ensure the new AgentClient extension works seamlessly with existing agent APIs
• Test backward compatibility with existing client integrations

Infrastructure Considerations

• The billing endpoints may require additional database migrations for production deployment
• Monitor API rate limits as the expanded functionality may increase client usage patterns
• Consider caching strategies for organization and billing data to optimize performance
• Ensure proper error handling and logging for the new checkout and billing workflows

---

🤖 Generated with Claude Code

Branch Info:

• Source: feature/billing-api
• Target: main
• Type: feature

Co-Authored-By: Claude noreply@anthropic.com

[jfrench9]

@claude can you review

[claude]

Claude finished @jfrench9's task —— View job

---

PR Code Review Complete ✅

PR #33: Add billing API endpoints and enhance agent execution capabilities

Review Summary:

I have completed a comprehensive review of all 11 changed files (722 additions, 23 deletions). This PR significantly enhances the client's capabilities with billing functionality and improved agent execution strategies.

---

✅ Strengths

1. Agent Execution Enhancements

• Excellent documentation: Both auto_select_agent.py and execute_specific_agent.py have comprehensive docstrings explaining execution strategies, modes, and credit costs
• Smart execution strategy: Automatic selection between sync (<5s), SSE (5-30s), and async (>30s) based on expected execution time
• Response mode override: Flexible mode parameter allows users to override automatic strategy selection
• Proper error handling: Comprehensive HTTP status code handling (400, 402, 404, 422, 429, 500)

2. New AgentClient Extension (+526 lines)

• Well-structured architecture: Clean separation of concerns with proper data classes
• Comprehensive functionality: Supports both auto-selection and specific agent execution
• SSE integration: Proper handling of streaming responses and progress monitoring
• Convenience methods: Easy-to-use methods like query(), analyze_financials(), research(), rag()
• Error handling: Detailed authentication and execution error handling

3. Billing Models

• Security conscious: Billing models properly handle sensitive checkout operations
• Flexible resource configuration: CreateCheckoutRequestResourceConfig uses dynamic properties for different resource types
• Comprehensive status tracking: CheckoutStatusResponse includes provisioning progress and error states

4. Credit Transaction Enhancements

• Enhanced filtering: New parameters for transaction_type, operation_type, date ranges
• Better pagination: Proper limit/offset parameters with sensible defaults
• Detailed documentation: Clear explanation of transaction types and filtering capabilities

---

⚠️ Areas of Concern

1. Missing SSE Client Dependency

Priority: High

# agent_client.py:14
from .sse_client import SSEClient, SSEConfig, EventType

The new AgentClient imports SSEClient but I can confirm sse_client.py exists in the extensions directory, so this should work correctly.

2. Complex Response Parsing Logic

Priority: Medium - agent_client.py:125-231, 280-384

The response parsing logic handles both dict and attrs objects with substantial code duplication:

# Duplicated logic for both execute_query and execute_agent methods
if isinstance(response_data, dict):
    data = response_data
else:
    data = response_data

Recommendation: Extract response parsing into a shared utility method to reduce duplication and improve maintainability.

3. Exception Handling Patterns

Priority: Medium - agent_client.py:217-231, 371-384

Generic exception handling with string matching:

if "401" in error_msg or "403" in error_msg or "unauthorized" in error_msg.lower():
    raise Exception(f"Authentication failed during agent execution: {error_msg}")

Recommendation: Use proper exception types instead of string-based error detection for more robust error handling.

4. Resource Configuration Validation

Priority: Medium - create_checkout_request_resource_config.py

The CreateCheckoutRequestResourceConfig model accepts any properties via additional_properties without validation:

# No field validation - accepts any configuration
additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)

Recommendation: Add validation for known resource types (graph vs repository) to prevent configuration errors.

---

🔒 Security Review

✅ Billing Security - Good Practices

• Proper separation of checkout creation from payment processing
• Status-based workflow with appropriate error handling
• No sensitive payment data stored in client models

✅ Authentication - Secure Implementation

• Proper API key handling with X-API-Key header
• Token validation and error handling
• No credentials logged or exposed

⚠️ Input Validation Considerations

• The flexible additional_properties pattern in billing models could benefit from stricter validation
• Agent execution accepts arbitrary context data - ensure backend validates this appropriately

---

📊 API Consistency Assessment

✅ Breaking Changes - Well Documented

The PR description accurately identifies potential breaking changes:

• New execution strategy parameters (backward compatible via defaults)
• Enhanced checkout models (additive changes)
• Credit transaction API enhancements (additive filtering)

✅ Response Format Consistency

• All endpoints follow consistent error response patterns
• Proper use of UNSET for optional fields
• Standardized pagination and filtering patterns

---

🧪 Testing Recommendations

1. Unit Tests Needed:

   • AgentClient response parsing logic
   • Error handling scenarios (auth failures, timeouts)
   • Billing checkout workflow edge cases

2. Integration Tests:

   • End-to-end agent execution with SSE monitoring
   • Checkout session creation and status tracking
   • Credit transaction filtering and pagination

3. Security Tests:

   • Authentication error scenarios
   • Invalid checkout configurations
   • Billing workflow security boundaries

---

📈 Performance Considerations

✅ Efficient Design

• Smart execution strategy selection minimizes unnecessary long-polling
• SSE streaming for medium-duration operations
• Proper async/await patterns for background processing

⚠️ Monitoring Recommendations

• Monitor SSE connection lifecycle and cleanup
• Track agent execution mode distribution
• Monitor billing API usage patterns and rate limiting

---

🎯 Final Recommendation: APPROVE with Minor Improvements

This PR introduces substantial valuable functionality with generally high code quality. The billing and agent execution enhancements are well-architected and properly documented.

Suggested Next Steps:

1. ✅ Merge after addressing: Extract duplicate response parsing logic in AgentClient
2. ✅ Follow-up: Add comprehensive test coverage for new AgentClient functionality
3. ✅ Monitor: Track execution strategy distribution and performance metrics post-deployment

The code is ready for production with the noted improvements implemented as follow-up work.

---