diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml index a12225a..5e84209 100644 --- a/.github/workflows/claude-code-review.yml +++ b/.github/workflows/claude-code-review.yml @@ -12,11 +12,8 @@ on: jobs: claude-review: - # Optional: Filter by PR author - # if: | - # github.event.pull_request.user.login == 'external-contributor' || - # github.event.pull_request.user.login == 'new-developer' || - # github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR' + # Skip for Dependabot PRs as they don't have access to secrets + if: github.actor != 'dependabot[bot]' runs-on: ubuntu-latest permissions: diff --git a/.github/workflows/claude-restricted-message.yml b/.github/workflows/claude-restricted-message.yml new file mode 100644 index 0000000..f58803f --- /dev/null +++ b/.github/workflows/claude-restricted-message.yml @@ -0,0 +1,42 @@ +name: Claude Restricted Message + +on: + issue_comment: + types: [created] + issues: + types: [opened] + +jobs: + notify-restriction: + # Only run if someone other than the owner tries to use @claude + if: | + github.actor != 'niksacdev' && + ( + (github.event_name == 'issues' && contains(github.event.issue.body, '@claude')) || + (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) + ) + runs-on: ubuntu-latest + permissions: + issues: write + steps: + - name: Post restriction message + uses: actions/github-script@v7 + with: + script: | + const issueNumber = context.issue.number; + const actor = context.actor; + + const message = `🤖 **Claude AI Assistant Notice** + + Thank you for your interest in using Claude, @${actor}! + + The Claude AI assistant is currently restricted to repository maintainers only to ensure responsible API usage and cost management. + + Please describe your issue or question in detail, and a maintainer will review and assist you. We appreciate your understanding and contribution to the project!`; + + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: issueNumber, + body: message + }); \ No newline at end of file diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml index bc77307..24870a1 100644 --- a/.github/workflows/claude.yml +++ b/.github/workflows/claude.yml @@ -12,11 +12,15 @@ on: jobs: claude: + # Only allow repository owner to trigger Claude if: | - (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) || - (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) || - (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) || - (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude'))) + github.actor == 'niksacdev' && + ( + (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) || + (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude'))) + ) runs-on: ubuntu-latest permissions: contents: read diff --git a/.github/workflows/dependabot-auto-merge.yml b/.github/workflows/dependabot-auto-merge.yml new file mode 100644 index 0000000..1a4bac5 --- /dev/null +++ b/.github/workflows/dependabot-auto-merge.yml @@ -0,0 +1,36 @@ +name: Dependabot Auto-Merge + +on: + pull_request: + types: [opened, synchronize] + +permissions: + contents: write + pull-requests: write + +jobs: + dependabot: + runs-on: ubuntu-latest + if: github.actor == 'dependabot[bot]' + steps: + - name: Dependabot metadata + id: metadata + uses: dependabot/fetch-metadata@v2 + with: + github-token: "${{ secrets.GITHUB_TOKEN }}" + + - name: Auto-approve Dependabot PRs + run: gh pr review --approve "$PR_URL" + env: + PR_URL: ${{ github.event.pull_request.html_url }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Enable auto-merge for Dependabot PRs + if: | + steps.metadata.outputs.update-type == 'version-update:semver-minor' || + steps.metadata.outputs.update-type == 'version-update:semver-patch' || + steps.metadata.outputs.update-type == 'version-update:semver-major' + run: gh pr merge --auto --squash "$PR_URL" + env: + PR_URL: ${{ github.event.pull_request.html_url }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index d8fc1b9..7aec4e4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -203,6 +203,12 @@ uv run python scripts/validate_ci_fix.py ### Commit Best Practices +#### Branch Management (CRITICAL) +- **Always delete branches after PR merge**: Clean up both local and remote branches +- **Create new branch for new work**: Never reuse old feature branches +- **Branch naming**: Use descriptive names like `feat/feature-name` or `fix/bug-description` +- **Keep main clean**: Always work in feature branches, never commit directly to main + #### Commit Frequency (CRITICAL) - **Commit often**: After each logical change (not after hours of work) - **Atomic commits**: One logical change per commit diff --git a/SECURITY.md b/SECURITY.md index 2bf5ed8..4d7b147 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -112,12 +112,21 @@ This system is designed with compliance in mind: - Implement tamper-proof audit trail - Add compliance reporting +## 🤖 AI Assistant + +This repository uses Claude AI for automated assistance, but it is **restricted to repository maintainers only** to ensure responsible API usage and cost management. + +If you need help with an issue: +1. Create a detailed issue describing your problem +2. A maintainer will review and assist you +3. Do not mention @claude in your issues or comments as it will not trigger the assistant + ## 📞 Contact Security Team: [your-email@example.com] -Project Maintainer: [your-github-username] +Project Maintainer: @niksacdev --- *Last Updated: August 2025* -*Security Policy Version: 1.0* \ No newline at end of file +*Security Policy Version: 1.1* diff --git a/github_issues.md b/github_issues.md deleted file mode 100644 index bd99048..0000000 --- a/github_issues.md +++ /dev/null @@ -1,530 +0,0 @@ -# GitHub Issues for Multi-Agent Loan Processing System - -## Instructions -1. Copy each issue below -2. Create new issue in GitHub -3. Add the specified labels -4. For completed features, close the issue after creation - ---- - -## Completed Features (Create and Close) - -### Issue 1: Document and Reference Configuration-Driven Agent Management Implementation - -**Labels:** documentation, completed-feature, architecture, enhancement - -## Completed Feature Documentation - -This issue documents our configuration-driven agent management system implementation. - -### Implementation References -- **Core Implementation:** `loan_processing/agents/providers/openai/agentregistry.py` -- **Configuration:** `loan_processing/agents/shared/config/agents.yaml` -- **Utils:** `loan_processing/utils/` -- **Key Commits:** - - `567bc4a` - Updated tests and CI to match optimized configuration - - `5850ec2` - Configuration cleanup and optimization - -### What This Provides -- YAML-based agent definitions with MCP server mappings -- Dynamic agent creation via `AgentRegistry.create_agent()` -- Persona-driven agent instructions from markdown files -- MCP server factory with caching for tool selection -- Type-safe configuration validation - -### Why This Matters -- Enables rapid agent type addition without code changes -- Supports experimental agent configurations -- Maintains agent autonomy in tool selection -- Clear separation between orchestration and agent logic - -### Acceptance Criteria -- [x] Agent registry supports configuration-driven creation -- [x] YAML configuration defines all agent types and capabilities -- [x] MCP server factory manages tool availability -- [x] Persona loader supports markdown-based instructions -- [x] Output format generator adds structured response requirements - ---- - -### Issue 2: Reference Sequential Multi-Agent Orchestration Pattern - -**Labels:** completed-feature, orchestration, architecture, experimental - -## Completed Feature Documentation - -Sequential orchestration pattern implementation for multi-agent loan processing. - -### Implementation References -- **Core:** `loan_processing/agents/providers/openai/orchestration/sequential.py` -- **Base Classes:** `loan_processing/agents/providers/openai/orchestration/base.py` -- **Engine:** `loan_processing/agents/providers/openai/orchestration/engine.py` -- **Tests:** `tests/test_sequential_orchestration.py` -- **Key Commits:** - - `44d162c` - Added comprehensive orchestration tests - - `779898c` - Enhanced test scenarios for decision differentiation - -### What This Provides -- Sequential agent execution with context passing -- Handoff condition validation between agents -- Audit trail and session management -- Error handling and workflow interruption -- Configurable agent dependencies - -### User Journey -1. Application enters intake agent for initial validation -2. Credit agent evaluates creditworthiness using previous context -3. Income agent verifies employment and income -4. Risk agent synthesizes all assessments for final decision - -### Acceptance Criteria -- [x] Sequential execution with context accumulation -- [x] Handoff validation between agents -- [x] Comprehensive audit trail -- [x] Error handling and recovery -- [x] Configuration-driven agent selection - ---- - -### Issue 3: Reference OpenAI Agents SDK Integration with MCP Tools - -**Labels:** completed-feature, integration, mcp-servers, tools - -## Completed Feature Documentation - -Integration with OpenAI Agents SDK and MCP (Model Context Protocol) servers. - -### Implementation References -- **MCP Servers:** - - `loan_processing/tools/mcp_servers/application_verification/` - - `loan_processing/tools/mcp_servers/document_processing/` - - `loan_processing/tools/mcp_servers/financial_calculations/` -- **Service Layer:** `loan_processing/tools/services/` -- **Tests:** `tests/mcp_servers/` (83 tests) -- **Key Commit:** `c319ab5` - Restored MCP server tests and updated CI - -### What This Provides -- Three specialized MCP servers for loan processing tools -- Agent-autonomous tool selection based on task requirements -- Secure parameter handling (applicant_id instead of SSN) -- Service layer abstraction for business logic -- RESTful tool interfaces via MCP protocol - -### Available Tools -- **Identity & Employment:** verify_identity, verify_employment, check_fraud_indicators -- **Document Processing:** extract_text, classify_documents, validate_formats -- **Financial Calculations:** calculate_dti, loan_affordability, risk_scoring - -### Acceptance Criteria -- [x] MCP servers implement tool protocols -- [x] Agents autonomously select appropriate tools -- [x] Secure parameter handling enforced -- [x] Service layer abstracts business logic -- [x] Comprehensive test coverage (83 tests) - ---- - -### Issue 4: Reference Type-Safe Data Model Implementation with Pydantic - -**Labels:** completed-feature, data-models, type-safety - -## Completed Feature Documentation - -Comprehensive Pydantic models for type-safe loan processing data structures. - -### Implementation References -- **Models:** `loan_processing/agents/shared/models/` - - `application.py` - Loan application data structures - - `assessment.py` - Agent assessment result models - - `decision.py` - Final decision and recommendation models -- **Integration:** Used throughout agent registry and orchestration - -### What This Provides -- Runtime data validation for all loan processing entities -- Type hints for better developer experience -- Serialization/deserialization for API integration -- Clear data contracts between system components -- Input sanitization and constraint enforcement - -### Key Models -- `LoanApplication` - Core application data with validation rules -- `AgentAssessment` - Standardized assessment output format -- `LoanDecision` - Final decision with reasoning and conditions - -### Acceptance Criteria -- [x] Pydantic models for all core entities -- [x] Runtime validation enforced -- [x] Type hints throughout codebase -- [x] Serialization for API readiness -- [x] Comprehensive field validation - ---- - -### Issue 5: Reference AI-Assisted Development Workflow Integration - -**Labels:** completed-feature, developer-experience, ai-assisted, workflow - -## Completed Feature Documentation - -Integration of AI development agents for architecture, code quality, and product guidance. - -### Implementation References -- **Documentation:** `CLAUDE.md` - Development workflow and agent usage -- **ADRs:** `docs/decisions/` - Architecture decisions with agent feedback -- **Integration:** Development agents used throughout the project - -### Available Development Agents -- **system-architecture-reviewer** - Architecture validation and design review -- **code-reviewer** - Code quality and alignment checks -- **product-manager-advisor** - Requirements and business value alignment -- **ux-ui-designer** - User experience validation - -### Development Workflow -1. Feature planning with product-manager-advisor -2. Architecture validation with system-architecture-reviewer -3. Implementation with continuous code-reviewer feedback -4. UI/UX validation with ux-ui-designer - -### Acceptance Criteria -- [x] Development agent integration documented -- [x] Workflow guidelines established -- [x] ADRs created for agent feedback -- [x] Integration with Claude Code, GitHub Copilot, Cursor - ---- - -### Issue 6: Reference Agent Observability with OpenTelemetry - -**Labels:** completed-feature, observability, monitoring, experimental - -## Completed Feature Documentation - -OTEL-based observability for monitoring agent communications and decisions. - -### Implementation References -- **Observability Module:** `loan_processing/utils/observability.py` -- **Integration:** Throughout orchestration and agent execution -- **Configuration:** Environment-based OTEL configuration - -### What This Provides -- Agent communication tracing -- Decision-making audit trail -- Performance metrics collection -- Context correlation across agents -- Structured logging with correlation IDs - -### Observability Features -- Trace agent handoffs and context passing -- Monitor MCP server tool usage -- Track agent execution times -- Log decision reasoning -- Capture error propagation - -### Acceptance Criteria -- [x] OTEL integration implemented -- [x] Correlation context tracking -- [x] Structured logging format -- [x] Agent communication visibility -- [x] Performance metrics collection - ---- - -## Future Features (Leave Open) - -### Issue 7: Implement Parallel Agent Processing for Independent Assessments - -**Labels:** enhancement, orchestration, experimental, performance - -## Enhancement: Parallel Orchestration Pattern - -Enable simultaneous agent processing when assessments are independent. - -### User Story -As a loan processor, I want credit and income verification to happen simultaneously so that loan decisions can be made faster when agents don't depend on each other's results. - -### Why This Matters -- Reduces loan processing time for time-sensitive applications -- Improves system throughput for high-volume scenarios -- Enables more responsive user experience -- Maintains audit trail even with concurrent processing - -### Acceptance Criteria -- [ ] Create `ParallelPatternExecutor` similar to sequential pattern -- [ ] Implement agent dependency analysis -- [ ] Add parallel configuration support in YAML -- [ ] Ensure thread-safe context management -- [ ] Maintain audit trail for concurrent execution -- [ ] Add timeout handling for parallel agents -- [ ] Create configuration validation - -### Technical Approach -- Build on existing orchestration base classes -- Reuse MCP server factory for concurrent access -- Extend OrchestrationContext for thread safety -- Add parallel-specific configuration validation - ---- - -### Issue 8: Implement Dynamic Agent Routing Based on Assessment Results - -**Labels:** enhancement, orchestration, business-logic, experimental - -## Enhancement: Conditional Routing - -Enable dynamic agent routing based on previous assessment results. - -### User Story -As a risk manager, I want loan applications to follow different processing paths based on initial risk indicators so that low-risk applications can be fast-tracked while high-risk ones get enhanced scrutiny. - -### Why This Matters -- Optimizes processing time based on application risk profile -- Enables fast-track processing for qualified applications -- Provides enhanced review path for complex cases -- Improves operational efficiency through smart routing - -### Acceptance Criteria -- [ ] Design conditional routing configuration schema -- [ ] Implement `ConditionalRoutingExecutor` -- [ ] Add routing rule evaluation engine -- [ ] Support multiple routing paths -- [ ] Enable rule-based agent selection -- [ ] Add routing decision audit logging -- [ ] Create routing configuration validation - -### Routing Examples -- High credit score → Skip enhanced credit checks -- Complex income sources → Add specialized income verification -- Fraud indicators → Add manual review step - ---- - -### Issue 9: Add Microsoft Autogen Provider Support - -**Labels:** enhancement, integration, framework-support, experimental - -## Enhancement: Autogen Framework Integration - -Implement Microsoft Autogen as an alternative multi-agent framework provider. - -### User Story -As a developer, I want to experiment with different multi-agent frameworks so that I can compare approaches and choose the most suitable solution for specific use cases. - -### Why This Matters -- Provides framework flexibility for different use cases -- Enables comparative analysis of multi-agent approaches -- Reduces vendor lock-in risk -- Supports diverse team preferences and expertise - -### Acceptance Criteria -- [ ] Create Autogen provider implementation -- [ ] Add Autogen-specific configuration support -- [ ] Implement agent registry integration for Autogen -- [ ] Support MCP server integration with Autogen agents -- [ ] Add provider-specific orchestration patterns -- [ ] Create comparative testing framework -- [ ] Document framework selection guidelines - -### Technical Approach -- Extend existing provider architecture -- Reuse MCP server implementations -- Maintain configuration-driven approach -- Support provider-specific optimizations - ---- - -### Issue 10: Implement LangChain Agents Framework Support - -**Labels:** enhancement, integration, framework-support, experimental - -## Enhancement: LangChain Integration - -Add LangChain Agents integration for additional framework flexibility. - -### User Story -As a developer familiar with LangChain, I want to use LangChain agents in the loan processing system so that I can use existing LangChain tools and expertise. - -### Why This Matters -- Uses extensive LangChain tool ecosystem -- Supports developers with LangChain expertise -- Enables integration with existing LangChain applications -- Provides additional framework comparison data - -### Acceptance Criteria -- [ ] Implement LangChain provider integration -- [ ] Add LangChain-specific agent configuration -- [ ] Support LangChain tool integration with MCP servers -- [ ] Create LangChain orchestration pattern adapters -- [ ] Add LangChain memory management integration -- [ ] Support LangChain callback systems -- [ ] Document LangChain-specific optimizations - ---- - -### Issue 11: Create REST API for Loan Processing Operations - -**Labels:** enhancement, api, integration, experimental - -## Enhancement: REST API Interface - -Implement RESTful API for external system integration. - -### User Story -As an application developer, I want a REST API for loan processing so that I can integrate loan decisions into web applications and mobile apps. - -### Why This Matters -- Enables external system integration -- Supports web and mobile application development -- Provides standardized access interface -- Enables API-driven loan processing workflows - -### Acceptance Criteria -- [ ] Design REST API schema for loan operations -- [ ] Implement FastAPI or similar framework -- [ ] Add authentication and authorization -- [ ] Support async processing with status endpoints -- [ ] Add API documentation and OpenAPI spec -- [ ] Implement rate limiting and error handling -- [ ] Add API monitoring and logging - -### API Endpoints -- `POST /applications` - Submit loan application -- `GET /applications/{id}/status` - Check processing status -- `GET /applications/{id}/decision` - Retrieve final decision -- `POST /applications/{id}/reprocess` - Trigger reprocessing -- `GET /agents/types` - List available agent types - ---- - -### Issue 12: Add GraphQL Interface for Complex Data Queries - -**Labels:** enhancement, api, graphql, experimental - -## Enhancement: GraphQL Interface - -Implement GraphQL for flexible data queries and real-time updates. - -### User Story -As a frontend developer, I want a GraphQL API so that I can efficiently query exactly the loan processing data I need and receive real-time updates. - -### Why This Matters -- Enables efficient data fetching for complex UIs -- Provides real-time processing status updates -- Reduces API calls through flexible querying -- Supports modern frontend development patterns - -### Acceptance Criteria -- [ ] Design GraphQL schema for loan domain -- [ ] Implement GraphQL server with async resolvers -- [ ] Add subscription support for real-time updates -- [ ] Create data loaders for efficient access -- [ ] Add authentication and authorization -- [ ] Support complex queries across entities -- [ ] Add GraphQL playground and documentation - ---- - -### Issue 13: Build React-Based Web Application UI - -**Labels:** enhancement, frontend, ui, experimental - -## Enhancement: Web Application Interface - -Create modern web UI for loan application submission and tracking. - -### User Story -As a loan applicant, I want a web interface to submit my loan application and track its status so that I can complete the process online. - -### Why This Matters -- Provides user-friendly application interface -- Enables self-service loan applications -- Reduces manual data entry -- Improves customer experience - -### Acceptance Criteria -- [ ] Design responsive web UI with React -- [ ] Implement application submission forms -- [ ] Add real-time status tracking -- [ ] Create document upload interface -- [ ] Add decision visualization -- [ ] Implement user authentication -- [ ] Support mobile-responsive design - -### UI Components -- Application form with validation -- Document upload with preview -- Status timeline visualization -- Decision explanation display -- Agent assessment details view - ---- - -### Issue 14: Implement Enhanced Agent Communication Tracing - -**Labels:** enhancement, observability, tracing, experimental - -## Enhancement: Distributed Tracing - -Enhance observability with comprehensive distributed tracing. - -### User Story -As a system operator, I want detailed tracing of agent communications so that I can debug complex loan processing issues and optimize agent performance. - -### Why This Matters -- Enables debugging of complex multi-agent workflows -- Provides performance optimization insights -- Supports compliance auditing requirements -- Improves system reliability through better observability - -### Acceptance Criteria -- [ ] Extend OTEL integration for distributed tracing -- [ ] Add trace correlation across agent handoffs -- [ ] Implement communication span tracking -- [ ] Add trace visualization integration -- [ ] Support trace sampling for high volume -- [ ] Add trace-based performance metrics -- [ ] Create trace analysis dashboards - -### Trace Information -- Agent execution times and dependencies -- MCP server tool usage patterns -- Context passing between agents -- Decision reasoning chains -- Error propagation paths - ---- - -### Issue 15: Implement A/B Testing Framework for Agent Configurations - -**Labels:** enhancement, experimentation, testing, experimental - -## Enhancement: A/B Testing Framework - -Enable safe experimentation with different agent configurations. - -### User Story -As a product manager, I want to A/B test different agent configurations so that I can optimize loan processing performance while maintaining risk controls. - -### Why This Matters -- Enables data-driven agent optimization -- Reduces risk of experimental configuration deployment -- Provides quantitative comparison of agent approaches -- Supports continuous improvement of loan processing - -### Acceptance Criteria -- [ ] Design A/B testing configuration schema -- [ ] Implement experiment assignment logic -- [ ] Add metric collection for analysis -- [ ] Create experiment result analysis tools -- [ ] Support gradual rollout of winning configs -- [ ] Add statistical significance testing -- [ ] Enable experiment safety controls - -### A/B Test Examples -- Different credit scoring models -- Alternative orchestration patterns -- Varying agent timeout configurations -- Different persona instructions for agents - ---- -