From c5175f8e83f02113362df3c1e16e927d4bbd836d Mon Sep 17 00:00:00 2001 From: niksacdev Date: Wed, 20 Aug 2025 12:44:39 -0400 Subject: [PATCH 1/5] docs: add security and contribution guidelines for public release MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add SECURITY.md with vulnerability reporting policy - Add CONTRIBUTING.md with development guidelines - Add .pre-commit-config.yaml for automated security checks - Add .github/dependabot.yml for dependency updates - Enhance .gitignore with comprehensive project-specific exclusions - Include results folders and temporary files in .gitignore - Add security best practices and compliance information Prepares repository for public release with proper security policies, contribution guidelines, and automated dependency management. ๐Ÿค– Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .github/dependabot.yml | 55 ++++++++ .gitignore | 45 +++++- .pre-commit-config.yaml | 73 ++++++++++ CONTRIBUTING.md | 297 ++++++++++++++++++++++++++++++++++++++++ SECURITY.md | 123 +++++++++++++++++ 5 files changed, 592 insertions(+), 1 deletion(-) create mode 100644 .github/dependabot.yml create mode 100644 .pre-commit-config.yaml create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..2707605 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,55 @@ +# Dependabot configuration for automated dependency updates +# Documentation: https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates + +version: 2 +updates: + # Python dependencies via pip/uv + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" + day: "monday" + time: "03:00" + open-pull-requests-limit: 5 + reviewers: + - "niksacdev" + labels: + - "dependencies" + - "python" + commit-message: + prefix: "chore" + prefix-development: "chore" + include: "scope" + groups: + development: + patterns: + - "pytest*" + - "mypy*" + - "ruff*" + - "black*" + - "pre-commit*" + openai: + patterns: + - "openai*" + - "agents*" + documentation: + patterns: + - "mkdocs*" + - "sphinx*" + + # GitHub Actions + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + day: "monday" + time: "03:00" + open-pull-requests-limit: 3 + reviewers: + - "niksacdev" + labels: + - "dependencies" + - "github-actions" + commit-message: + prefix: "ci" + include: "scope" \ No newline at end of file diff --git a/.gitignore b/.gitignore index b491021..69a54db 100644 --- a/.gitignore +++ b/.gitignore @@ -209,6 +209,49 @@ __marimo__/ # SpecStory (AI code documentation) .specstory/ -# Application results and logs +# ============================================================================ +# Project-Specific Ignores +# ============================================================================ + +# Results and output files results/ console_app/results/ +loan_processing/results/ +*.result.json +*.decision.json + +# Temporary files +*.tmp +*.temp +*.bak +*.swp +*.swo +*~ + +# Local development +.env.local +.env.*.local +local_notes.md +scratch/ + +# MCP Server data +mcp_server_data/ +*.db +*.sqlite + +# Generated documentation +docs/_build/ +docs/generated/ + +# Performance profiling +*.prof +*.pstats +profile_output/ + +# Test coverage reports (duplicates removed as they're already above) + +# IDE specific files +.idea/ +.vscode/ +*.sublime-* +.DS_Store diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..750bdcb --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,73 @@ +# Pre-commit hooks for security and code quality +# Install: pip install pre-commit && pre-commit install + +repos: + # Security - Detect secrets + - repo: https://github.com/Yelp/detect-secrets + rev: v1.4.0 + hooks: + - id: detect-secrets + args: ['--baseline', '.secrets.baseline'] + exclude: .*\.lock|package-lock\.json + + # Python code quality + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.4.4 + hooks: + - id: ruff + args: [--fix] + - id: ruff-format + + # Python type checking + - repo: https://github.com/pre-commit/mirrors-mypy + rev: v1.10.0 + hooks: + - id: mypy + additional_dependencies: [types-all] + args: [--ignore-missing-imports] + + # Check for common issues + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.6.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + - id: check-added-large-files + args: ['--maxkb=1000'] + - id: check-case-conflict + - id: check-merge-conflict + - id: check-json + - id: check-toml + - id: detect-private-key + - id: no-commit-to-branch + args: ['--branch', 'main'] + + # Markdown formatting + - repo: https://github.com/igorshubovych/markdownlint-cli + rev: v0.39.0 + hooks: + - id: markdownlint + args: ['--fix'] + + # Security - Safety check + - repo: https://github.com/Lucas-C/pre-commit-hooks-safety + rev: v1.3.3 + hooks: + - id: python-safety-dependencies-check + +# Additional local hooks +- repo: local + hooks: + - id: no-env-files + name: Block .env files + entry: .env files must not be committed + language: fail + files: '^\.env$' + + - id: no-api-keys + name: Check for API keys + entry: 'sk-[a-zA-Z0-9]{48}|AKIA[0-9A-Z]{16}' + language: pygrep + types: [text] + exclude: \.env\.example|SECURITY\.md \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..18aaa53 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,297 @@ +# Contributing to Multi-Agent Loan Processing System + +Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to the project. + +## ๐Ÿš€ Getting Started + +### Prerequisites + +- Python 3.10 or higher +- `uv` package manager (`pip install uv`) +- OpenAI API key (or Azure OpenAI credentials) + +### Development Setup + +1. **Fork and clone the repository** + ```bash + git clone https://github.com/your-username/multi-agent-system.git + cd multi-agent-system + ``` + +2. **Install dependencies with uv** + ```bash + uv sync + ``` + +3. **Set up environment variables** + ```bash + cp .env.example .env + # Edit .env with your API keys + ``` + +4. **Install pre-commit hooks** + ```bash + uv pip install pre-commit + pre-commit install + ``` + +5. **Run tests to verify setup** + ```bash + uv run pytest tests/test_agent_registry.py -v + ``` + +## ๐Ÿ“ Development Workflow + +### 1. Create a Feature Branch + +```bash +git checkout -b feature/your-feature-name +``` + +### 2. Make Your Changes + +Follow these guidelines: +- Write clean, readable code following PEP 8 +- Add type hints to all functions +- Include docstrings for modules, classes, and functions +- Keep functions focused and small +- Follow existing patterns in the codebase + +### 3. Write Tests + +- Add tests for new functionality +- Ensure existing tests pass +- Maintain >80% code coverage + +```bash +# Run specific tests +uv run pytest tests/test_your_feature.py -v + +# Run with coverage +uv run pytest tests/ --cov=loan_processing --cov-report=term-missing +``` + +### 4. Run Quality Checks + +Before committing, run all quality checks: + +```bash +# Linting +uv run ruff check . --fix +uv run ruff format . + +# Type checking +uv run mypy loan_processing/ + +# Tests +uv run pytest tests/test_agent_registry.py tests/test_safe_evaluator.py -v +``` + +### 5. Commit Your Changes + +Write clear, descriptive commit messages: + +```bash +git commit -m "feat: add income trend analysis to income agent" +``` + +Commit message format: +- `feat:` New feature +- `fix:` Bug fix +- `docs:` Documentation changes +- `test:` Test additions or changes +- `refactor:` Code refactoring +- `chore:` Maintenance tasks + +### 6. Push and Create PR + +```bash +git push origin feature/your-feature-name +``` + +Then create a Pull Request on GitHub with: +- Clear description of changes +- Link to related issues +- Screenshots/examples if applicable +- Test results + +## ๐Ÿ—๏ธ Architecture Guidelines + +### Agent Development + +When adding new agents: + +1. **Create persona file**: `loan_processing/agents/agent-persona/your-agent-persona.md` +2. **Update configuration**: Add to `loan_processing/config/agents.yaml` +3. **Define output format**: Specify structured output requirements +4. **Add tests**: Create `tests/test_your_agent.py` + +### MCP Server Development + +When adding MCP servers: + +1. **Create server module**: `loan_processing/tools/mcp_servers/your_server/` +2. **Implement server.py**: Follow existing server patterns +3. **Add to configuration**: Update `agents.yaml` with server details +4. **Document tools**: List all tools the server provides + +## ๐Ÿ“‹ Code Style + +### Python Style Guide + +- Use `ruff` for linting and formatting +- Follow PEP 8 with 120 character line limit +- Use descriptive variable names +- Add type hints for all functions +- Write comprehensive docstrings + +### Example Function: + +```python +def calculate_debt_to_income_ratio( + monthly_debt: Decimal, + monthly_income: Decimal, + include_proposed_payment: bool = True +) -> float: + """ + Calculate the debt-to-income ratio for loan qualification. + + Args: + monthly_debt: Total monthly debt payments + monthly_income: Gross monthly income + include_proposed_payment: Whether to include proposed loan payment + + Returns: + DTI ratio as a percentage (0-100) + + Raises: + ValueError: If monthly_income is zero or negative + """ + if monthly_income <= 0: + raise ValueError("Monthly income must be positive") + + return float((monthly_debt / monthly_income) * 100) +``` + +## ๐Ÿงช Testing Guidelines + +### Test Structure + +- Unit tests: `tests/test_*.py` +- Integration tests: `tests/test_integration_*.py` +- Use pytest fixtures for common test data +- Mock external dependencies +- Test both success and failure cases + +### Example Test: + +```python +def test_agent_creation(): + """Test that agents are created with correct configuration.""" + agent = AgentRegistry.create_agent("intake", model="gpt-4") + + assert agent.name == "Intake Agent" + assert agent.model == "gpt-4" + assert len(agent.mcp_servers) == 0 # Optimized for speed +``` + +## ๐Ÿ“š Documentation + +### Documentation Requirements + +- Update README.md for user-facing changes +- Update CLAUDE.md for AI development instructions +- Add docstrings to all new code +- Create ADRs for architectural decisions +- Update configuration examples + +### ADR Format + +Create `docs/decisions/adr-XXX-title.md`: + +```markdown +# ADR-XXX: Title + +## Status +Accepted/Proposed/Deprecated + +## Context +Why this decision is needed + +## Decision +What we're doing + +## Consequences +What happens as a result +``` + +## ๐Ÿ› Reporting Issues + +### Bug Reports + +Include: +- Python version +- Steps to reproduce +- Expected behavior +- Actual behavior +- Error messages/logs +- Environment details + +### Feature Requests + +Include: +- Use case description +- Proposed solution +- Alternative approaches considered +- Impact on existing functionality + +## ๐Ÿ”’ Security + +- Never commit secrets or API keys +- Report security issues privately (see SECURITY.md) +- Use secure coding practices +- Validate all inputs +- Follow principle of least privilege + +## ๐Ÿ“Š Performance + +- Profile code for bottlenecks +- Optimize database queries +- Use async operations where appropriate +- Cache expensive computations +- Monitor memory usage + +## ๐ŸŽฏ Pull Request Checklist + +Before submitting a PR, ensure: + +- [ ] Code follows style guidelines +- [ ] Tests pass locally +- [ ] Coverage maintained >80% +- [ ] Documentation updated +- [ ] Pre-commit hooks pass +- [ ] No hardcoded values +- [ ] No sensitive data exposed +- [ ] Commit messages follow format +- [ ] PR description is complete + +## ๐Ÿ’ฌ Getting Help + +- Open an issue for bugs/features +- Check existing issues first +- Join discussions in issues/PRs +- Review documentation thoroughly +- Ask questions - we're here to help! + +## ๐Ÿ† Recognition + +Contributors will be recognized in: +- README.md contributors section +- Release notes +- Project documentation + +Thank you for contributing to make loan processing more efficient and accessible! + +--- + +*By contributing, you agree that your contributions will be licensed under the MIT License.* \ No newline at end of file diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..2bf5ed8 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,123 @@ +# Security Policy + +## ๐Ÿ”’ Security Best Practices + +This repository demonstrates secure coding practices for AI-powered loan processing systems. + +### API Key Security + +**NEVER commit API keys or secrets to version control!** + +1. Copy `.env.example` to `.env` +2. Add your API keys to `.env` +3. Ensure `.env` is in `.gitignore` (already configured) +4. Use environment variables for all sensitive configuration + +### Data Privacy + +This system implements privacy-by-design principles: + +- **No Real SSNs**: The system uses UUID-based `applicant_id` instead of SSNs +- **No PII in Logs**: Sensitive data is never logged +- **Secure Parameters**: All MCP server calls use secure identifiers +- **Data Minimization**: Only necessary data is collected and processed + +### Secure Development + +- All dependencies are managed through `uv` with lock files +- Regular security audits with `uv pip audit` +- Comprehensive test coverage (>83%) +- Type checking with mypy +- Linting with ruff + +## ๐Ÿ› Reporting Security Vulnerabilities + +We take security seriously. If you discover a security vulnerability, please follow responsible disclosure: + +1. **DO NOT** create a public GitHub issue +2. Email security concerns to: [your-email@example.com] +3. Include: + - Description of the vulnerability + - Steps to reproduce + - Potential impact + - Suggested fix (if any) + +We will acknowledge receipt within 48 hours and provide a detailed response within 5 business days. + +## ๐Ÿ›ก๏ธ Security Features + +### Authentication & Authorization +- API key-based authentication for AI services +- Secure MCP server communication +- Role-based agent permissions + +### Data Protection +- Applicant IDs (UUIDs) instead of SSNs +- Encrypted sensitive data in transit +- Audit logging for compliance + +### Input Validation +- Pydantic models for data validation +- Regex patterns for format verification +- Boundary checking for numerical inputs + +## ๐Ÿ“‹ Security Checklist for Contributors + +Before submitting a PR: + +- [ ] No hardcoded credentials +- [ ] No real PII in test data +- [ ] All inputs validated +- [ ] Error messages don't leak sensitive info +- [ ] Dependencies updated and audited +- [ ] Tests pass with >80% coverage + +## ๐Ÿ”„ Dependency Management + +Regular dependency updates: +```bash +# Update dependencies +uv sync + +# Audit for vulnerabilities +uv pip audit + +# Update to latest secure versions +uv update +``` + +## ๐Ÿ“œ Compliance + +This system is designed with compliance in mind: + +- **FCRA**: Fair Credit Reporting Act compliance +- **ECOA**: Equal Credit Opportunity Act adherence +- **GDPR**: Privacy-by-design principles +- **SOC2**: Audit trail and access controls + +## ๐Ÿšจ Known Security Considerations + +1. **MCP Servers**: Currently run on localhost without authentication. In production: + - Add authentication to MCP servers + - Use TLS for MCP communications + - Implement rate limiting + +2. **API Keys**: Currently single API key for all agents. In production: + - Use separate keys per agent + - Implement key rotation + - Add usage monitoring + +3. **Audit Logging**: Basic logging implemented. In production: + - Send logs to SIEM + - Implement tamper-proof audit trail + - Add compliance reporting + +## ๐Ÿ“ž Contact + +Security Team: [your-email@example.com] +Project Maintainer: [your-github-username] + +--- + +*Last Updated: August 2025* +*Security Policy Version: 1.0* \ No newline at end of file From c0bb9faa827550ecf42ba3acf9b1001d54c34edb Mon Sep 17 00:00:00 2001 From: niksacdev Date: Mon, 25 Aug 2025 14:36:16 -0400 Subject: [PATCH 2/5] security: restrict Claude AI assistant to repository owner only - Modified claude.yml to only allow @niksacdev to trigger Claude - Added claude-restricted-message.yml to notify other users about restriction - Updated SECURITY.md with AI assistant usage policy (v1.1) - Prevents API abuse while maintaining public repository access This ensures responsible API usage and cost management for the public repository. --- .../workflows/claude-restricted-message.yml | 42 +++++++++++++++++++ .github/workflows/claude.yml | 12 ++++-- SECURITY.md | 13 +++++- 3 files changed, 61 insertions(+), 6 deletions(-) create mode 100644 .github/workflows/claude-restricted-message.yml 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/SECURITY.md b/SECURITY.md index 2bf5ed8..7c0676d 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* \ No newline at end of file From 0ab8c1d59795e53d4e30fe6d5924899f42388028 Mon Sep 17 00:00:00 2001 From: niksacdev Date: Mon, 25 Aug 2025 14:45:47 -0400 Subject: [PATCH 3/5] fix: handle Dependabot PRs properly in workflows - Skip Claude Code Review for Dependabot PRs (no access to secrets) - Add dedicated Dependabot auto-merge workflow - Auto-approve and merge Dependabot version updates - Prevents CI failures on dependency update PRs --- .github/workflows/claude-code-review.yml | 7 ++-- .github/workflows/dependabot-auto-merge.yml | 36 +++++++++++++++++++++ 2 files changed, 38 insertions(+), 5 deletions(-) create mode 100644 .github/workflows/dependabot-auto-merge.yml 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/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 From fd94721b1fe7e7e8c14c59844f026cd87f955602 Mon Sep 17 00:00:00 2001 From: niksacdev Date: Mon, 25 Aug 2025 14:50:25 -0400 Subject: [PATCH 4/5] chore: replace github_issues.md with actual GitHub issues Created proper GitHub issues (#19-#28) for: - Future MCP server implementations (OCR, fraud detection, credit bureaus, etc.) - Agent enhancements (parallel processing, ML risk scoring, appeals agent) - Each issue has acceptance criteria, technical details, and priorities --- github_issues.md | 530 ----------------------------------------------- 1 file changed, 530 deletions(-) delete mode 100644 github_issues.md 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 - ---- - From 4dcbd6049c6be5bb0da96c16fb30db8e78960134 Mon Sep 17 00:00:00 2001 From: niksacdev Date: Mon, 25 Aug 2025 14:55:36 -0400 Subject: [PATCH 5/5] docs: add branch management rules to CLAUDE.md - Always delete branches after PR merge - Create new branches for new work - Use descriptive branch naming conventions - Keep main branch clean --- CLAUDE.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 462329c..1ebb36c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -201,6 +201,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