.cursor.tar

.cursor/0000777000000000000000000000000015127012706007344 5ustar  .cursor/rules/0000777000000000000000000000000015127014717010502 5ustar  .cursor/rules/api-routing.mdc0000666000000000000000000002445115127014500013421 0ustar  ---
description: API and Routing Rules : CreditNexus uses FastAPI with dependency injection, Pydantic validation, and comprehensive error handling.
alwaysApply: false
---
# API and Routing Rules

## FastAPI Route Patterns

CreditNexus uses FastAPI with dependency injection, Pydantic validation, and comprehensive error handling.

## Route Definition

### Route Decorators
- **ALWAYS** use `@router.post()`, `@router.get()`, etc. for route definition
- **ALWAYS** include response models for type safety
- **ALWAYS** include status codes for non-200 responses
- **ALWAYS** use descriptive route paths

```python
# ✅ CORRECT: Route definition
from fastapi import APIRouter, HTTPException, Depends, status
from pydantic import BaseModel

router = APIRouter(prefix="/api", tags=["documents"])

class CreateDocumentRequest(BaseModel):
    title: str
    borrower_name: str
    extracted_data: dict

@router.post(
    "/documents",
    response_model=DocumentResponse,
    status_code=status.HTTP_201_CREATED
)
async def create_document(
    request: CreateDocumentRequest,
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user)
):
    # Implementation
    pass
```

## Dependency Injection

### Standard Dependencies
- **ALWAYS** use `Depends(get_db)` for database sessions
- **ALWAYS** use `Depends(get_current_user)` for authentication
- **ALWAYS** use `Depends(get_policy_service)` for policy evaluation
- **ALWAYS** inject dependencies in function parameters

```python
# ✅ CORRECT: Dependency injection
@router.post("/extract")
async def extract_document(
    file: UploadFile = File(...),
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user),
    policy_service: PolicyService = Depends(get_policy_service)
):
    # Use injected dependencies
    pass
```

### Optional Dependencies
- Use `Depends(get_optional_user)` for optional authentication
- Use `Optional[User]` type hint for optional user
- Handle None case appropriately

```python
# ✅ CORRECT: Optional dependency
@router.get("/public-endpoint")
async def public_endpoint(
    current_user: Optional[User] = Depends(get_optional_user)
):
    if current_user:
        # Authenticated user
        pass
    else:
        # Anonymous user
        pass
```

## Request Validation

### Pydantic Models
- **ALWAYS** use Pydantic models for request validation
- **ALWAYS** use `Field()` for field descriptions and validation
- **ALWAYS** validate at API boundary
- **ALWAYS** return clear validation errors

```python
# ✅ CORRECT: Request validation
from pydantic import BaseModel, Field, EmailStr

class CreateDocumentRequest(BaseModel):
    title: str = Field(..., min_length=1, max_length=255, description="Document title")
    borrower_name: str = Field(..., min_length=1, description="Borrower name")
    extracted_data: dict = Field(..., description="Extracted CDM data")
    sustainability_linked: bool = Field(default=False, description="Is sustainability-linked")
```

### File Uploads
- **ALWAYS** use `UploadFile` for file uploads
- **ALWAYS** validate file types and sizes
- **ALWAYS** handle file reading errors

```python
# ✅ CORRECT: File upload
from fastapi import UploadFile, File

@router.post("/upload")
async def upload_document(
    file: UploadFile = File(...),
    db: Session = Depends(get_db)
):
    # Validate file type
    if not file.filename.endswith(('.pdf', '.txt')):
        raise HTTPException(400, detail="Only PDF and TXT files allowed")
    
    # Read file
    content = await file.read()
    text = content.decode('utf-8')
    
    # Process
    pass
```

## Response Patterns

### Success Responses
- **ALWAYS** return Pydantic models for structured responses
- **ALWAYS** include status codes (201 for creation, 200 for success)
- **ALWAYS** return consistent response structure

```python
# ✅ CORRECT: Success response
class DocumentResponse(BaseModel):
    id: int
    title: str
    status: str
    created_at: datetime

@router.post("/documents", response_model=DocumentResponse, status_code=201)
async def create_document(...):
    document = create_document_in_db(...)
    return DocumentResponse(
        id=document.id,
        title=document.title,
        status=document.workflow.state,
        created_at=document.created_at
    )
```

### Error Responses
- **ALWAYS** use `HTTPException` for error responses
- **ALWAYS** use appropriate status codes
- **ALWAYS** include detailed error messages
- **ALWAYS** log errors before raising

```python
# ✅ CORRECT: Error handling
@router.get("/documents/{doc_id}")
async def get_document(doc_id: int, db: Session = Depends(get_db)):
    document = db.query(Document).filter(Document.id == doc_id).first()
    
    if not document:
        logger.warning(f"Document {doc_id} not found")
        raise HTTPException(
            status_code=404,
            detail={"status": "not_found", "message": f"Document {doc_id} not found"}
        )
    
    return document
```

## Error Handling Hierarchy

### Exception Handling Order
1. **HTTPException**: Re-raise immediately (already formatted)
2. **ValueError**: Convert to HTTPException 422 (validation error)
3. **RuntimeError**: Convert to HTTPException 500 (configuration error)
4. **Exception**: Catch-all, convert to HTTPException 500

```python
# ✅ CORRECT: Error handling hierarchy
@router.post("/extract")
async def extract_document(...):
    try:
        result = extract_data_smart(text=text)
        return result
    except HTTPException:
        # Re-raise HTTP exceptions
        raise
    except ValueError as e:
        # Validation errors
        logger.warning(f"Validation error: {e}")
        raise HTTPException(
            status_code=422,
            detail={"status": "validation_error", "message": str(e)}
        )
    except Exception as e:
        # Unexpected errors
        logger.error(f"Unexpected error: {e}", exc_info=True)
        raise HTTPException(
            status_code=500,
            detail={"status": "error", "message": "Internal server error"}
        )
```

## Query Parameters

### Query Parameter Patterns
- **ALWAYS** use `Query()` for query parameters with validation
- **ALWAYS** provide defaults and constraints
- **ALWAYS** document query parameters

```python
# ✅ CORRECT: Query parameters
@router.get("/documents")
async def list_documents(
    search: Optional[str] = Query(None, description="Search term"),
    page: int = Query(1, ge=1, description="Page number"),
    limit: int = Query(50, ge=1, le=100, description="Items per page"),
    status: Optional[str] = Query(None, description="Filter by status"),
    db: Session = Depends(get_db)
):
    # Implementation
    pass
```

## Pagination

### Pagination Pattern
- **ALWAYS** implement pagination for list endpoints
- **ALWAYS** return pagination metadata
- **ALWAYS** use consistent pagination structure

```python
# ✅ CORRECT: Pagination
class PaginatedResponse(BaseModel):
    items: List[DocumentResponse]
    total: int
    page: int
    limit: int
    pages: int

@router.get("/documents", response_model=PaginatedResponse)
async def list_documents(
    page: int = Query(1, ge=1),
    limit: int = Query(50, ge=1, le=100),
    db: Session = Depends(get_db)
):
    offset = (page - 1) * limit
    documents = db.query(Document).limit(limit).offset(offset).all()
    total = db.query(Document).count()
    
    return PaginatedResponse(
        items=[doc.to_dict() for doc in documents],
        total=total,
        page=page,
        limit=limit,
        pages=(total + limit - 1) // limit
    )
```

## Authentication and Authorization

### Route Protection
- **ALWAYS** use `Depends(get_current_user)` for protected routes
- **ALWAYS** use `Depends(require_auth)` for routes requiring authentication
- **ALWAYS** check user roles for authorization

```python
# ✅ CORRECT: Route protection
from app.auth.dependencies import RoleChecker

require_admin = RoleChecker([UserRole.ADMIN.value])

@router.delete("/documents/{doc_id}")
async def delete_document(
    doc_id: int,
    db: Session = Depends(get_db),
    current_user: User = Depends(require_admin)
):
    # Only admins can delete
    pass
```

## Audit Logging

### Audit Pattern
- **ALWAYS** log state-changing operations
- **ALWAYS** use `log_audit_action()` helper
- **ALWAYS** include user, action, target, and metadata

```python
# ✅ CORRECT: Audit logging
from app.api.routes import log_audit_action
from app.db.models import AuditAction

@router.post("/documents/{doc_id}/workflow/approve")
async def approve_document(
    doc_id: int,
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user),
    request: Request = None
):
    workflow = db.query(Workflow).filter(Workflow.document_id == doc_id).first()
    workflow.state = WorkflowState.APPROVED
    db.commit()
    
    log_audit_action(
        db=db,
        action=AuditAction.APPROVE,
        target_type="document",
        target_id=doc_id,
        user_id=current_user.id,
        request=request
    )
    
    return {"status": "approved"}
```

## Response Streaming

### Streaming Responses
- **ALWAYS** use `StreamingResponse` for large files
- **ALWAYS** set appropriate content type
- **ALWAYS** handle streaming errors

```python
# ✅ CORRECT: Streaming response
from fastapi.responses import StreamingResponse
import io

@router.get("/documents/{doc_id}/export")
async def export_document(doc_id: int, format: str = "json"):
    document = get_document(doc_id)
    
    if format == "excel":
        buffer = io.BytesIO()
        # Generate Excel file
        buffer.seek(0)
        return StreamingResponse(
            buffer,
            media_type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
            headers={"Content-Disposition": f"attachment; filename=document_{doc_id}.xlsx"}
        )
```

## API Documentation

### OpenAPI Documentation
- **ALWAYS** use descriptive route summaries and descriptions
- **ALWAYS** document request/response models
- **ALWAYS** include example values
- **ALWAYS** tag routes appropriately

```python
# ✅ CORRECT: API documentation
@router.post(
    "/documents",
    response_model=DocumentResponse,
    status_code=201,
    summary="Create a new document",
    description="Creates a new document with extracted CDM data and initializes workflow",
    tags=["documents"]
)
async def create_document(...):
    """Create a new document from extracted credit agreement data."""
    pass
```
.cursor/rules/architecture.mdc0000666000000000000000000002145715127014032013650 0ustar  ---
description: System Architecture : CreditNexus follows a layered architecture with clear separation of concerns
alwaysApply: false
---
# CreditNexus Architecture Rules

## System Architecture

CreditNexus follows a layered architecture with clear separation of concerns:

```
Frontend (React/TypeScript) 
  ↕ HTTP/REST + WebSocket
Backend (FastAPI/Python)
  ↕
Cognitive Layer (LangChain + LLM)
  ↕
Validation Layer (Pydantic)
  ↕
Data Layer (PostgreSQL + SQLAlchemy)
```

## Core Design Principles

### 1. Dependency Injection Pattern
- **ALWAYS** use FastAPI's `Depends()` for dependency injection
- **ALWAYS** create dependency functions in appropriate modules:
  - Database: `app/db/__init__.py` → `get_db()`
  - Authentication: `app/auth/jwt_auth.py` → `get_current_user()`
  - Policy Service: `app/services/policy_service.py` → `get_policy_service()`
- **NEVER** create database sessions directly - always use `get_db()` dependency
- **NEVER** access global state directly - inject dependencies

```python
# ✅ CORRECT: Dependency injection
@router.post("/extract")
async def extract_document(
    file: UploadFile = File(...),
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user),
    policy_service: PolicyService = Depends(get_policy_service)
):
    # Use injected dependencies
    pass

# ❌ WRONG: Direct instantiation
@router.post("/extract")
async def extract_document():
    db = SessionLocal()  # DON'T DO THIS
    user = db.query(User).first()  # DON'T DO THIS
```

### 2. Service Layer Pattern
- **ALWAYS** create service classes for business logic
- **ALWAYS** keep services stateless (no instance variables)
- **ALWAYS** inject dependencies into service constructors
- **ALWAYS** use service layer between API routes and database models

```python
# ✅ CORRECT: Service layer
class PolicyService:
    def __init__(self, policy_engine: PolicyEngineInterface):
        self.engine = policy_engine
    
    def evaluate_facility_creation(self, agreement: CreditAgreement) -> PolicyDecision:
        # Business logic here
        pass

# ❌ WRONG: Business logic in routes
@router.post("/extract")
async def extract_document(...):
    # Complex business logic directly in route - DON'T DO THIS
    if agreement.parties[0].lei in SANCTIONED_LIST:
        raise HTTPException(403)
```

### 3. Repository Pattern (Implicit)
- Use SQLAlchemy models directly as repositories
- **ALWAYS** use `joinedload()` for eager loading relationships
- **ALWAYS** use query methods on models, not raw SQL
- **ALWAYS** handle transactions explicitly with `db.commit()` / `db.rollback()`

```python
# ✅ CORRECT: SQLAlchemy query patterns
document = db.query(Document)\
    .options(joinedload(Document.versions))\
    .options(joinedload(Document.workflow))\
    .filter(Document.id == doc_id)\
    .first()

# ❌ WRONG: N+1 queries
document = db.query(Document).filter(Document.id == doc_id).first()
versions = db.query(DocumentVersion).filter(DocumentVersion.document_id == doc_id).all()
```

### 4. Factory Pattern
- **ALWAYS** use factory functions for creating complex objects
- **ALWAYS** centralize configuration in factory functions
- Examples:
  - `get_chat_model()` - LLM client factory
  - `create_policy_engine()` - Policy engine factory
  - `create_extraction_chain()` - LangChain factory

```python
# ✅ CORRECT: Factory pattern
def get_chat_model(model: Optional[str] = None) -> BaseChatModel:
    """Factory function for creating LLM clients."""
    config = _get_llm_config()
    return create_chat_model(
        provider=config["provider"],
        model=model or config["model"],
        api_key=config["api_key"]
    )
```

### 5. Lifespan Management
- **ALWAYS** use FastAPI's `lifespan` context manager for startup/shutdown
- **ALWAYS** initialize global resources in `lifespan` function
- **ALWAYS** clean up resources in shutdown phase
- **ALWAYS** handle initialization errors gracefully

```python
# ✅ CORRECT: Lifespan pattern
@asynccontextmanager
async def lifespan(app: FastAPI):
    # Startup
    from app.core.llm_client import init_llm_config
    init_llm_config(settings)
    
    from app.services.policy_service import init_policy_engine
    init_policy_engine(settings)
    
    yield
    
    # Shutdown
    from app.services.policy_service import get_policy_config_loader
    loader = get_policy_config_loader()
    if loader:
        loader.stop_file_watcher()
```

## Module Organization

### Backend Module Structure
```
app/
├── core/           # Core configuration and utilities
├── models/         # Pydantic models (CDM, events)
├── db/             # Database models and session management
├── api/            # FastAPI routes
├── auth/           # Authentication and authorization
├── services/       # Business logic services
├── chains/         # LangChain extraction chains
├── agents/         # AI agents (analyzer, verifier, classifier)
└── policies/       # Policy rule YAML files
```

### Frontend Module Structure
```
client/src/
├── apps/           # Feature-specific applications
├── components/     # Reusable UI components
├── context/        # React context providers
├── hooks/          # Custom React hooks
└── lib/            # Utility functions
```

## Error Handling Patterns

### Exception Hierarchy
- **HTTPException**: For API errors (400, 401, 403, 404, 422, 500)
- **ValueError**: For validation errors (converted to HTTPException 422)
- **RuntimeError**: For configuration errors (converted to HTTPException 500)
- **Custom Exceptions**: For domain-specific errors

```python
# ✅ CORRECT: Error handling pattern
@router.post("/extract")
async def extract_document(...):
    try:
        result = extract_data_smart(text=text)
        return result
    except ValueError as e:
        # Validation errors
        logger.warning(f"Validation error: {e}")
        raise HTTPException(
            status_code=422,
            detail={"status": "validation_error", "message": str(e)}
        )
    except HTTPException:
        # Re-raise HTTP exceptions
        raise
    except Exception as e:
        # Unexpected errors
        logger.error(f"Unexpected error: {e}", exc_info=True)
        raise HTTPException(
            status_code=500,
            detail={"status": "error", "message": "Internal server error"}
        )
```

## Configuration Management

### Settings Pattern
- **ALWAYS** use Pydantic `BaseSettings` for configuration
- **ALWAYS** load from environment variables
- **ALWAYS** use `SecretStr` for sensitive values
- **ALWAYS** validate configuration at startup

```python
# ✅ CORRECT: Settings pattern
class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        case_sensitive=False
    )
    
    OPENAI_API_KEY: SecretStr
    LLM_PROVIDER: LLMProvider = LLMProvider.OPENAI
    POLICY_ENABLED: bool = True

settings = Settings()
```

## Logging Patterns

- **ALWAYS** use module-level loggers: `logger = logging.getLogger(__name__)`
- **ALWAYS** log at appropriate levels:
  - `logger.error()`: Errors requiring attention
  - `logger.warning()`: Warnings (validation failures, retries)
  - `logger.info()`: Important state changes
  - `logger.debug()`: Detailed debugging information
- **ALWAYS** include context in log messages
- **ALWAYS** use `exc_info=True` for exception logging

```python
# ✅ CORRECT: Logging pattern
logger = logging.getLogger(__name__)

try:
    result = extract_data(text)
    logger.info(f"Extraction successful for document {doc_id}")
except ValidationError as e:
    logger.warning(f"Validation failed for document {doc_id}: {e}")
    raise
except Exception as e:
    logger.error(f"Unexpected error extracting document {doc_id}: {e}", exc_info=True)
    raise
```

## State Management

### Backend State
- **ALWAYS** use dependency injection for state
- **ALWAYS** store global state in `app.state` (FastAPI)
- **NEVER** use global variables for mutable state
- **ALWAYS** initialize state in `lifespan` function

### Frontend State
- **ALWAYS** use React hooks for local state
- **ALWAYS** use Context API for global state
- **ALWAYS** use FDC3 for cross-app state synchronization
- **NEVER** use global variables

## Performance Guidelines

1. **Database**: Use `joinedload()` to avoid N+1 queries
2. **LLM Calls**: Use map-reduce for documents >50k characters
3. **Caching**: Cache expensive computations (embeddings, classifications)
4. **Async**: Use `async/await` for I/O operations
5. **Pagination**: Always paginate list endpoints
6. **Connection Pooling**: Configure SQLAlchemy connection pool

## Testing Architecture

- **Unit Tests**: Test individual functions/classes in isolation
- **Integration Tests**: Test API endpoints with test database
- **E2E Tests**: Test complete workflows
- **Mock External Services**: Mock LLM, satellite APIs in tests
.cursor/rules/cdm-compliance.mdc0000666000000000000000000002134615127014105014037 0ustar  ---
description: CDM Compliance Rules : CreditNexus MUST be fully CDM-compliant. All policy decisions, state transitions, and events MUST follow CDM standards.
alwaysApply: false
---
# CDM Compliance Rules

## FINOS Common Domain Model (CDM) Principles

CreditNexus MUST be fully CDM-compliant. All policy decisions, state transitions, and events MUST follow CDM standards.

## CDM Event Model

### Event Structure Requirements
- **ALWAYS** include `eventType` field (string enum)
- **ALWAYS** include `eventDate` field (ISO 8601 datetime)
- **ALWAYS** include `meta.globalKey` field (UUID string)
- **ALWAYS** include `relatedEventIdentifier` for event relationships
- **ALWAYS** use machine-readable and machine-executable format

### Event Types
1. **TradeExecution**: Initial trade creation
2. **Observation**: Satellite/ground truth verification
3. **TermsChange**: Interest rate adjustments
4. **PolicyEvaluation**: Policy engine decisions (CRITICAL)

### Policy Evaluation Events
- **ALWAYS** create `PolicyEvaluation` CDM event for every policy decision
- **ALWAYS** link to related events via `relatedEventIdentifier`
- **ALWAYS** include full evaluation trace for auditability
- **ALWAYS** store complete event structure in database (JSONB)

```python
# ✅ CORRECT: Policy evaluation CDM event
from app.models.cdm_events import generate_cdm_policy_evaluation

policy_event = generate_cdm_policy_evaluation(
    transaction_id=agreement.deal_id,
    transaction_type="facility_creation",
    decision="BLOCK",  # or "ALLOW", "FLAG"
    rule_applied="block_sanctioned_parties",
    related_event_identifiers=[
        {
            "eventIdentifier": {
                "issuer": "CreditNexus",
                "assignedIdentifier": [{"identifier": {"value": trade_event_id}}]
            }
        }
    ],
    evaluation_trace=[...],
    matched_rules=["block_sanctioned_parties"]
)

# Store in database
db.add(PolicyDecision(
    transaction_id=agreement.deal_id,
    decision="BLOCK",
    cdm_events=[policy_event]  # Store full CDM event
))
```

## CDM Process Model

### Validation → Calculation → Event Creation
- **Step 1: VALIDATION**: Validate CDM event structure and data
- **Step 2: CALCULATION**: Perform policy evaluation or business logic
- **Step 3: EVENT CREATION**: Create CDM-compliant event

```python
# ✅ CORRECT: CDM process model
def evaluate_with_cdm_process(
    self,
    cdm_event: Dict[str, Any],
    credit_agreement: Optional[CreditAgreement] = None
) -> Dict[str, Any]:
    # STEP 1: VALIDATION
    self._validate_cdm_event(cdm_event)
    
    # STEP 2: CALCULATION
    policy_transaction = self._cdm_to_policy_transaction(cdm_event, credit_agreement)
    evaluation_result = self.engine.evaluate(policy_transaction)
    
    # STEP 3: EVENT CREATION
    policy_event = generate_cdm_policy_evaluation(
        transaction_id=...,
        transaction_type=...,
        decision=evaluation_result["decision"],
        rule_applied=evaluation_result.get("rule"),
        related_event_identifiers=[...],
        evaluation_trace=evaluation_result.get("trace", [])
    )
    
    return {
        "policy_evaluation_event": policy_event,
        "decision": evaluation_result["decision"],
        "rule_applied": evaluation_result.get("rule")
    }
```

## CDM Model Validation

### Validation at Point of Creation
- **ALWAYS** validate policy compliance at model instantiation
- **ALWAYS** use Pydantic `@model_validator` for embedded validation
- **ALWAYS** raise `ValueError` for validation failures
- **ALWAYS** validate before database persistence

```python
# ✅ CORRECT: Embedded validation in CDM model
from pydantic import model_validator

class CreditAgreement(BaseModel):
    # ... fields ...
    
    @model_validator(mode='after')
    def validate_policy_compliance(self) -> 'CreditAgreement':
        """CDM-compliant validation at point of creation."""
        # Check sanctioned parties
        if self.parties:
            for party in self.parties:
                if party.lei and self._is_sanctioned(party.lei):
                    raise ValueError(f"Party {party.name} is sanctioned")
        
        # Check ESG compliance
        if self.sustainability_linked and not self.esg_kpi_targets:
            raise ValueError("Sustainability-linked loans must have ESG KPI targets")
        
        return self
```

## CDM State Machine

### State Transition Logic
- **ALWAYS** use CDM-compliant state machine for policy decisions
- **ALWAYS** validate state transitions before applying
- **ALWAYS** create state transition events

```python
# ✅ CORRECT: CDM state machine
class PolicyDecisionState(str, Enum):
    PENDING = "PENDING"
    ALLOWED = "ALLOWED"
    BLOCKED = "BLOCKED"
    FLAGGED = "FLAGGED"

class CDMPolicyStateMachine:
    TRANSITIONS = {
        PolicyDecisionState.PENDING: [
            PolicyDecisionState.ALLOWED,
            PolicyDecisionState.BLOCKED,
            PolicyDecisionState.FLAGGED
        ],
        PolicyDecisionState.FLAGGED: [
            PolicyDecisionState.ALLOWED,
            PolicyDecisionState.BLOCKED
        ],
        PolicyDecisionState.ALLOWED: [],  # Terminal
        PolicyDecisionState.BLOCKED: [],  # Terminal
    }
    
    @classmethod
    def can_transition(cls, from_state: PolicyDecisionState, to_state: PolicyDecisionState) -> bool:
        return to_state in cls.TRANSITIONS.get(from_state, [])
```

## CDM Event Storage

### Database Storage
- **ALWAYS** store complete CDM events in JSONB columns
- **ALWAYS** store event relationships for querying
- **ALWAYS** index event metadata for performance
- **NEVER** store only decision strings - store full events

```python
# ✅ CORRECT: CDM event storage
class PolicyDecision(Base):
    __tablename__ = "policy_decisions"
    
    id: Mapped[int] = mapped_column(primary_key=True)
    transaction_id: Mapped[str] = mapped_column(String(255))
    decision: Mapped[str] = mapped_column(String(10))  # ALLOW/BLOCK/FLAG
    cdm_events: Mapped[dict] = mapped_column(JSONB)  # Full CDM events
    trace_id: Mapped[str] = mapped_column(String(255), unique=True)
    created_at: Mapped[datetime] = mapped_column(default=datetime.utcnow)
```

## CDM Event Relationships

### Linking Events
- **ALWAYS** use `relatedEventIdentifier` to link related events
- **ALWAYS** include issuer and assignedIdentifier in event identifiers
- **ALWAYS** maintain event chain for auditability

```python
# ✅ CORRECT: Event relationships
policy_event = generate_cdm_policy_evaluation(
    transaction_id=...,
    transaction_type=...,
    decision=...,
    related_event_identifiers=[
        {
            "eventIdentifier": {
                "issuer": "CreditNexus",
                "assignedIdentifier": [
                    {
                        "identifier": {
                            "value": trade_event["meta"]["globalKey"]
                        }
                    }
                ]
            }
        }
    ]
)
```

## CDM Compliance Checklist

When implementing features:
- [ ] All policy decisions create PolicyEvaluation CDM events
- [ ] All events include required fields (eventType, eventDate, meta.globalKey)
- [ ] All events link to related events via relatedEventIdentifier
- [ ] All CDM models validate at point of creation
- [ ] All state transitions use CDM-compliant state machine
- [ ] All events stored in database as complete JSONB structures
- [ ] All event relationships queryable

## CDM Event Generators

### Location: `app/models/cdm_events.py`
- **ALWAYS** use generator functions for CDM events
- **ALWAYS** follow CDM event structure exactly
- **ALWAYS** generate unique globalKey for each event
- **ALWAYS** include source system metadata

```python
# ✅ CORRECT: CDM event generator
def generate_cdm_policy_evaluation(
    transaction_id: str,
    transaction_type: str,
    decision: str,
    rule_applied: Optional[str] = None,
    related_event_identifiers: List[Dict[str, Any]] = None,
    evaluation_trace: List[Dict[str, Any]] = None
) -> Dict[str, Any]:
    return {
        "eventType": "PolicyEvaluation",
        "eventDate": datetime.datetime.now().isoformat(),
        "policyEvaluation": {
            "transactionIdentifier": {
                "issuer": "CreditNexus_PolicyEngine",
                "assignedIdentifier": [{"identifier": {"value": transaction_id}}]
            },
            "transactionType": transaction_type,
            "decision": {"value": decision, "unit": "POLICY_DECISION"},
            "ruleApplied": rule_applied,
            "evaluationTrace": evaluation_trace or [],
            "evaluationDate": {"date": datetime.date.today().isoformat()}
        },
        "relatedEventIdentifier": related_event_identifiers or [],
        "meta": {
            "globalKey": str(uuid.uuid4()),
            "sourceSystem": "CreditNexus_PolicyEngine_v1",
            "version": 1
        }
    }
```
.cursor/rules/data-validation.mdc0000666000000000000000000002622715127014560014235 0ustar  ---
description: Data Validation Rules : CreditNexus uses Pydantic 2.0 for all data validation with embedded business logic validation.
alwaysApply: false
---
# Data Validation Rules

## Pydantic Validation Patterns

CreditNexus uses Pydantic 2.0 for all data validation with embedded business logic validation.

## Model Validation

### Field Validation
- **ALWAYS** use Pydantic `Field()` for field constraints
- **ALWAYS** use type hints for all fields
- **ALWAYS** provide field descriptions
- **ALWAYS** use appropriate validators

```python
# ✅ CORRECT: Field validation
from pydantic import BaseModel, Field, field_validator

class Party(BaseModel):
    id: str = Field(..., min_length=1, description="Unique party identifier")
    name: str = Field(..., min_length=1, max_length=255, description="Legal name")
    lei: Optional[str] = Field(
        None,
        min_length=20,
        max_length=20,
        description="Legal Entity Identifier (20 characters)"
    )
    
    @field_validator('lei')
    @classmethod
    def validate_lei(cls, v: Optional[str]) -> Optional[str]:
        if v and not v.isalnum():
            raise ValueError("LEI must be alphanumeric")
        return v
```

### Model Validators
- **ALWAYS** use `@model_validator` for cross-field validation
- **ALWAYS** validate at point of creation (CDM principle)
- **ALWAYS** raise `ValueError` for validation failures
- **ALWAYS** use `mode='after'` for validation after field assignment

```python
# ✅ CORRECT: Model validator
from pydantic import model_validator

class CreditAgreement(BaseModel):
    agreement_date: date
    facilities: List[LoanFacility]
    
    @model_validator(mode='after')
    def validate_currency_consistency(self) -> 'CreditAgreement':
        """Ensure all facilities use the same currency."""
        if not self.facilities:
            return self
        
        first_currency = self.facilities[0].commitment_amount.currency
        for facility in self.facilities[1:]:
            if facility.commitment_amount.currency != first_currency:
                raise ValueError(
                    f"Currency mismatch: facility '{facility.facility_name}' uses "
                    f"{facility.commitment_amount.currency}, expected {first_currency}"
                )
        return self
    
    @model_validator(mode='after')
    def validate_dates(self) -> 'CreditAgreement':
        """Ensure dates are valid and in correct order."""
        if self.agreement_date > date.today():
            raise ValueError("Agreement date cannot be in the future")
        
        for facility in self.facilities:
            if facility.maturity_date <= self.agreement_date:
                raise ValueError(
                    f"Facility '{facility.facility_name}' maturity date must be after agreement date"
                )
        return self
```

## Data Normalization

### Monetary Amounts
- **ALWAYS** use `Decimal` for monetary amounts
- **NEVER** use `float` for money (precision issues)
- **ALWAYS** normalize to smallest unit when needed

```python
# ✅ CORRECT: Monetary amounts
from decimal import Decimal

class Money(BaseModel):
    amount: Decimal = Field(..., description="Monetary amount")
    currency: Currency = Field(..., description="Currency code")
    
    @field_validator('amount')
    @classmethod
    def validate_amount(cls, v: Decimal) -> Decimal:
        if v < 0:
            raise ValueError("Amount cannot be negative")
        return v
```

### Date Normalization
- **ALWAYS** use ISO 8601 format (`YYYY-MM-DD`)
- **ALWAYS** use `date` type from `datetime` module
- **ALWAYS** validate date ranges

```python
# ✅ CORRECT: Date handling
from datetime import date

class CreditAgreement(BaseModel):
    agreement_date: date = Field(..., description="Agreement date in ISO 8601 format")
    
    @field_validator('agreement_date')
    @classmethod
    def validate_agreement_date(cls, v: date) -> date:
        if v > date.today():
            raise ValueError("Agreement date cannot be in the future")
        return v
```

### Spread Normalization
- **ALWAYS** normalize spreads to basis points
- **ALWAYS** convert percentages to basis points (3.5% → 350.0)
- **ALWAYS** validate spread ranges

```python
# ✅ CORRECT: Spread normalization
class FloatingRateOption(BaseModel):
    benchmark: str = Field(..., description="Rate benchmark (SOFR, EURIBOR, etc.)")
    spread_bps: float = Field(..., description="Spread in basis points")
    
    @field_validator('spread_bps')
    @classmethod
    def validate_spread(cls, v: float) -> float:
        if not (-10000 <= v <= 10000):
            raise ValueError("Spread must be between -10000 and 10000 basis points")
        return v
    
    @classmethod
    def from_percentage(cls, benchmark: str, spread_pct: float) -> 'FloatingRateOption':
        """Create from percentage (e.g., 3.5% → 350.0 bps)."""
        return cls(
            benchmark=benchmark,
            spread_bps=spread_pct * 100
        )
```

## Business Logic Validation

### Policy Compliance Validation
- **ALWAYS** embed policy validation in CDM models
- **ALWAYS** validate at point of creation
- **ALWAYS** raise `ValueError` for policy violations

```python
# ✅ CORRECT: Policy compliance validation
class CreditAgreement(BaseModel):
    parties: List[Party]
    sustainability_linked: bool
    esg_kpi_targets: Optional[List[ESGKPITarget]]
    
    @model_validator(mode='after')
    def validate_policy_compliance(self) -> 'CreditAgreement':
        """CDM-compliant validation at point of creation."""
        # Check sanctioned parties
        if self.parties:
            for party in self.parties:
                if party.lei and self._is_sanctioned(party.lei):
                    raise ValueError(f"Party {party.name} is sanctioned")
        
        # Check ESG compliance
        if self.sustainability_linked and not self.esg_kpi_targets:
            raise ValueError("Sustainability-linked loans must have ESG KPI targets")
        
        return self
    
    def _is_sanctioned(self, lei: str) -> bool:
        """Check if LEI is on sanctions list."""
        # Implementation would query sanctions database
        return False
```

### Required Field Validation
- **ALWAYS** validate required fields based on business rules
- **ALWAYS** provide clear error messages
- **ALWAYS** validate relationships between fields

```python
# ✅ CORRECT: Required field validation
class CreditAgreement(BaseModel):
    parties: List[Party]
    facilities: List[LoanFacility]
    
    @model_validator(mode='after')
    def validate_required_fields(self) -> 'CreditAgreement':
        """Ensure required fields are present."""
        if not self.parties:
            raise ValueError("At least one party is required")
        
        borrower_exists = any("borrower" in p.role.lower() for p in self.parties)
        if not borrower_exists:
            raise ValueError("At least one party must be a Borrower")
        
        if not self.facilities:
            raise ValueError("At least one loan facility is required")
        
        return self
```

## API Request Validation

### Request Models
- **ALWAYS** use Pydantic models for API requests
- **ALWAYS** validate at API boundary
- **ALWAYS** return clear validation errors

```python
# ✅ CORRECT: API request validation
from pydantic import BaseModel, Field, EmailStr

class CreateDocumentRequest(BaseModel):
    title: str = Field(..., min_length=1, max_length=255)
    borrower_name: str = Field(..., min_length=1)
    extracted_data: dict = Field(..., description="CDM data")
    sustainability_linked: bool = Field(default=False)

@router.post("/documents")
async def create_document(
    request: CreateDocumentRequest,  # Validated automatically
    db: Session = Depends(get_db)
):
    # Request is already validated
    pass
```

### File Upload Validation
- **ALWAYS** validate file types
- **ALWAYS** validate file sizes
- **ALWAYS** handle file reading errors

```python
# ✅ CORRECT: File upload validation
from fastapi import UploadFile, File, HTTPException

MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB
ALLOWED_EXTENSIONS = {'.pdf', '.txt'}

@router.post("/upload")
async def upload_document(file: UploadFile = File(...)):
    # Validate file extension
    if not any(file.filename.endswith(ext) for ext in ALLOWED_EXTENSIONS):
        raise HTTPException(400, detail="Only PDF and TXT files allowed")
    
    # Validate file size
    content = await file.read()
    if len(content) > MAX_FILE_SIZE:
        raise HTTPException(400, detail="File too large (max 10MB)")
    
    # Process file
    pass
```

## Error Messages

### Validation Error Format
- **ALWAYS** provide clear, actionable error messages
- **ALWAYS** include field names in error messages
- **ALWAYS** suggest corrections when possible

```python
# ✅ CORRECT: Clear error messages
@field_validator('lei')
@classmethod
def validate_lei(cls, v: Optional[str]) -> Optional[str]:
    if v:
        if len(v) != 20:
            raise ValueError(
                f"LEI must be exactly 20 characters, got {len(v)}"
            )
        if not v.isalnum():
            raise ValueError(
                "LEI must contain only alphanumeric characters"
            )
    return v
```

## Validation at Multiple Layers

### Multi-Layer Validation
1. **Pydantic Model**: Type and field validation
2. **Model Validator**: Business logic validation
3. **API Layer**: Request validation
4. **Service Layer**: Business rule validation
5. **Database**: Constraint validation

```python
# ✅ CORRECT: Multi-layer validation
# Layer 1: Pydantic field validation
class CreditAgreement(BaseModel):
    agreement_date: date  # Type validated by Pydantic
    
    # Layer 2: Model validator
    @model_validator(mode='after')
    def validate_business_rules(self) -> 'CreditAgreement':
        # Business logic validation
        if self.agreement_date > date.today():
            raise ValueError("Agreement date cannot be in the future")
        return self

# Layer 3: API validation
@router.post("/documents")
async def create_document(
    request: CreateDocumentRequest,  # Validated by Pydantic
    db: Session = Depends(get_db)
):
    # Layer 4: Service layer validation
    agreement = CreditAgreement(**request.extracted_data)
    # Agreement is validated at creation
    
    # Layer 5: Database constraints
    document = Document(extracted_data=agreement.model_dump())
    db.add(document)
    db.commit()  # Database constraints validated
```

## Custom Validators

### Reusable Validators
- **ALWAYS** create reusable validators for common patterns
- **ALWAYS** use `@field_validator` for field-specific validation
- **ALWAYS** use `@model_validator` for cross-field validation

```python
# ✅ CORRECT: Reusable validators
def validate_lei_format(lei: Optional[str]) -> Optional[str]:
    """Validate LEI format."""
    if lei:
        if len(lei) != 20:
            raise ValueError("LEI must be exactly 20 characters")
        if not lei.isalnum():
            raise ValueError("LEI must be alphanumeric")
    return lei

class Party(BaseModel):
    lei: Optional[str] = Field(None, description="Legal Entity Identifier")
    
    @field_validator('lei')
    @classmethod
    def validate_lei(cls, v: Optional[str]) -> Optional[str]:
        return validate_lei_format(v)
```
.cursor/rules/database-orm.mdc0000666000000000000000000002210115127014453013517 0ustar  ---
description: Database and ORM Rules : SQLAlchemy 2.0 Patterns CreditNexus uses SQLAlchemy 2.0 with modern type hints and patterns.
alwaysApply: false
---
# Database and ORM Rules

## SQLAlchemy 2.0 Patterns

CreditNexus uses SQLAlchemy 2.0 with modern type hints and patterns.

## Database Session Management

### Session Dependency
- **ALWAYS** use `get_db()` dependency for database sessions
- **ALWAYS** use `yield` pattern for session lifecycle
- **ALWAYS** close sessions in `finally` block
- **NEVER** create sessions directly

```python
# ✅ CORRECT: Session dependency
from app.db import get_db

@router.post("/documents")
async def create_document(
    db: Session = Depends(get_db),
    current_user: User = Depends(get_current_user)
):
    document = Document(...)
    db.add(document)
    db.commit()
    db.refresh(document)
    return document

# ❌ WRONG: Direct session creation
@router.post("/documents")
async def create_document():
    db = SessionLocal()  # DON'T DO THIS
    # ...
```

### Session Lifecycle
- Sessions are created per request
- Sessions are automatically closed after request
- **ALWAYS** commit or rollback explicitly
- **ALWAYS** use `db.refresh()` after commit to get updated object

```python
# ✅ CORRECT: Session lifecycle
def create_document(db: Session, data: dict):
    document = Document(**data)
    db.add(document)
    try:
        db.commit()
        db.refresh(document)  # Get updated object with ID
        return document
    except Exception as e:
        db.rollback()
        raise
```

## Database Models

### Model Definition Pattern
- **ALWAYS** use SQLAlchemy 2.0 type hints (`Mapped[...]`)
- **ALWAYS** use `mapped_column()` for column definitions
- **ALWAYS** define relationships with `relationship()`
- **ALWAYS** use `__tablename__` explicitly

```python
# ✅ CORRECT: SQLAlchemy 2.0 model
from sqlalchemy.orm import Mapped, mapped_column, relationship
from sqlalchemy import String, Integer, JSONB, ForeignKey, DateTime
from datetime import datetime

class PolicyDecision(Base):
    __tablename__ = "policy_decisions"
    
    id: Mapped[int] = mapped_column(primary_key=True)
    transaction_id: Mapped[str] = mapped_column(String(255))
    decision: Mapped[str] = mapped_column(String(10))  # ALLOW/BLOCK/FLAG
    cdm_events: Mapped[dict] = mapped_column(JSONB)
    trace_id: Mapped[str] = mapped_column(String(255), unique=True)
    created_at: Mapped[datetime] = mapped_column(
        DateTime,
        default=datetime.utcnow,
        nullable=False
    )
    
    document_id: Mapped[Optional[int]] = mapped_column(
        ForeignKey("documents.id"),
        nullable=True
    )
    document: Mapped[Optional["Document"]] = relationship(
        back_populates="policy_decisions"
    )
```

### JSONB Columns
- **ALWAYS** use `JSONB` for storing CDM events and flexible data
- **ALWAYS** use `dict` type hint for JSONB columns
- **ALWAYS** validate JSONB data before storing

```python
# ✅ CORRECT: JSONB usage
from sqlalchemy.dialects.postgresql import JSONB

class DocumentVersion(Base):
    extracted_data: Mapped[dict] = mapped_column(JSONB)
    metadata: Mapped[dict] = mapped_column(JSONB, default=dict)
```

## Query Patterns

### Eager Loading
- **ALWAYS** use `joinedload()` to avoid N+1 queries
- **ALWAYS** eager load relationships that will be accessed
- **ALWAYS** use `options()` for multiple relationships

```python
# ✅ CORRECT: Eager loading
from sqlalchemy.orm import joinedload

document = db.query(Document)\
    .options(joinedload(Document.versions))\
    .options(joinedload(Document.workflow))\
    .options(joinedload(Document.uploaded_by_user))\
    .filter(Document.id == doc_id)\
    .first()

# ❌ WRONG: N+1 queries
document = db.query(Document).filter(Document.id == doc_id).first()
versions = db.query(DocumentVersion).filter(
    DocumentVersion.document_id == doc_id
).all()  # N+1 query!
```

### Query Filtering
- **ALWAYS** use SQLAlchemy filter methods, not raw SQL
- **ALWAYS** use type-safe filter expressions
- **ALWAYS** handle None values explicitly

```python
# ✅ CORRECT: Query filtering
documents = db.query(Document)\
    .filter(Document.borrower_name.ilike(f"%{search}%"))\
    .filter(Document.sustainability_linked == True)\
    .filter(Document.created_at >= start_date)\
    .order_by(Document.created_at.desc())\
    .limit(limit)\
    .offset(offset)\
    .all()
```

### Pagination
- **ALWAYS** implement pagination for list endpoints
- **ALWAYS** use `limit` and `offset` for pagination
- **ALWAYS** return total count for pagination metadata

```python
# ✅ CORRECT: Pagination
@router.get("/documents")
async def list_documents(
    page: int = Query(1, ge=1),
    limit: int = Query(50, ge=1, le=100),
    db: Session = Depends(get_db)
):
    offset = (page - 1) * limit
    
    documents = db.query(Document)\
        .order_by(Document.created_at.desc())\
        .limit(limit)\
        .offset(offset)\
        .all()
    
    total = db.query(Document).count()
    
    return {
        "items": [doc.to_dict() for doc in documents],
        "total": total,
        "page": page,
        "limit": limit,
        "pages": (total + limit - 1) // limit
    }
```

## Transactions

### Transaction Management
- **ALWAYS** use explicit transactions for multi-step operations
- **ALWAYS** rollback on errors
- **ALWAYS** commit only after all operations succeed

```python
# ✅ CORRECT: Transaction management
def create_document_with_workflow(db: Session, data: dict):
    try:
        # Create document
        document = Document(**data)
        db.add(document)
        db.flush()  # Get document.id without committing
        
        # Create workflow
        workflow = Workflow(document_id=document.id, state=WorkflowState.DRAFT)
        db.add(workflow)
        
        # Create version
        version = DocumentVersion(document_id=document.id, ...)
        db.add(version)
        
        db.commit()  # Commit all together
        return document
    except Exception as e:
        db.rollback()
        raise
```

## Database Migrations

### Alembic Patterns
- **ALWAYS** create Alembic migrations for schema changes
- **ALWAYS** test migrations on staging before production
- **ALWAYS** include both `upgrade()` and `downgrade()` functions
- **ALWAYS** use descriptive migration names

```python
# ✅ CORRECT: Alembic migration
def upgrade():
    op.create_table(
        'policy_decisions',
        sa.Column('id', sa.Integer(), nullable=False),
        sa.Column('transaction_id', sa.String(255), nullable=False),
        sa.Column('decision', sa.String(10), nullable=False),
        sa.Column('cdm_events', postgresql.JSONB(), nullable=True),
        sa.PrimaryKeyConstraint('id')
    )
    op.create_index('idx_policy_decisions_transaction', 'policy_decisions', ['transaction_id'])

def downgrade():
    op.drop_index('idx_policy_decisions_transaction', table_name='policy_decisions')
    op.drop_table('policy_decisions')
```

## Model Serialization

### to_dict() Pattern
- **ALWAYS** implement `to_dict()` method on models
- **ALWAYS** handle datetime serialization (ISO format)
- **ALWAYS** handle relationships (include or exclude)

```python
# ✅ CORRECT: Model serialization
class Document(Base):
    # ... fields ...
    
    def to_dict(self, include_versions: bool = False):
        data = {
            "id": self.id,
            "title": self.title,
            "borrower_name": self.borrower_name,
            "created_at": self.created_at.isoformat() if self.created_at else None,
        }
        
        if include_versions:
            data["versions"] = [v.to_dict() for v in self.versions]
        
        return data
```

## Database Connection Pooling

### Connection Configuration
- **ALWAYS** configure connection pooling
- **ALWAYS** use `pool_recycle` for long-running connections
- **ALWAYS** use `pool_pre_ping` for connection health checks

```python
# ✅ CORRECT: Connection pooling
engine = create_engine(
    DATABASE_URL,
    pool_recycle=300,  # Recycle connections after 5 minutes
    pool_pre_ping=True,  # Verify connections before use
    pool_size=10,
    max_overflow=20
)
```

## Audit Logging

### Audit Pattern
- **ALWAYS** log state-changing operations
- **ALWAYS** use `log_audit_action()` helper function
- **ALWAYS** include user, action, target, and metadata

```python
# ✅ CORRECT: Audit logging
from app.api.routes import log_audit_action
from app.db.models import AuditAction

def create_document(db: Session, data: dict, user: User):
    document = Document(**data)
    db.add(document)
    db.commit()
    
    log_audit_action(
        db=db,
        action=AuditAction.CREATE,
        target_type="document",
        target_id=document.id,
        user_id=user.id,
        metadata={"title": document.title}
    )
    
    return document
```

## Performance Optimization

### Query Optimization
- Use indexes on frequently queried columns
- Use `joinedload()` instead of lazy loading
- Use `selectinload()` for large relationship sets
- Avoid loading unnecessary columns

### Connection Management
- Reuse connection pools
- Close unused connections
- Monitor connection pool metrics
- Use read replicas for read-heavy operations (if available)
.cursor/rules/frontend.mdc0000666000000000000000000002263315127014526013012 0ustar  ---
description: Frontend Development Rules : CreditNexus frontend uses React 18, TypeScript, Vite, and Tailwind CSS with FDC3 desktop integration.
alwaysApply: false
---
# Frontend Development Rules

## React and TypeScript Patterns

CreditNexus frontend uses React 18, TypeScript, Vite, and Tailwind CSS with FDC3 desktop integration.

## Component Patterns

### Functional Components
- **ALWAYS** use functional components with hooks
- **ALWAYS** use TypeScript for all components
- **ALWAYS** define prop interfaces
- **NEVER** use `any` type

```typescript
// ✅ CORRECT: Functional component
import { useState, useEffect } from 'react';
import { Button } from '@/components/ui/button';

interface DocumentParserProps {
  onExtract: (data: CreditAgreement) => void;
  initialText?: string;
}

export function DocumentParser({ onExtract, initialText }: DocumentParserProps) {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);
  
  const handleExtract = async (file: File) => {
    setLoading(true);
    setError(null);
    try {
      // Extract logic
      const data = await extractDocument(file);
      onExtract(data);
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Extraction failed');
    } finally {
      setLoading(false);
    }
  };
  
  return (
    <div className="space-y-4">
      {error && <div className="text-red-600">{error}</div>}
      <Button onClick={handleExtract} disabled={loading}>
        {loading ? 'Extracting...' : 'Extract Document'}
      </Button>
    </div>
  );
}
```

### State Management
- **ALWAYS** use `useState` for local component state
- **ALWAYS** use Context API for global state
- **ALWAYS** use custom hooks for reusable state logic
- **ALWAYS** handle loading and error states

```typescript
// ✅ CORRECT: State management
const [loading, setLoading] = useState(false);
const [error, setError] = useState<string | null>(null);
const [data, setData] = useState<CreditAgreement | null>(null);

// Custom hook
function useDocumentExtraction() {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);
  
  const extract = async (file: File) => {
    setLoading(true);
    setError(null);
    try {
      const response = await fetch('/api/extract', {
        method: 'POST',
        body: formData
      });
      const data = await response.json();
      return data;
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Extraction failed');
      throw err;
    } finally {
      setLoading(false);
    }
  };
  
  return { extract, loading, error };
}
```

## Styling Patterns

### Tailwind CSS
- **ALWAYS** use Tailwind CSS utility classes
- **ALWAYS** use shadcn/ui components from `@/components/ui/`
- **NEVER** use inline styles
- **ALWAYS** use responsive design utilities

```typescript
// ✅ CORRECT: Tailwind styling
<div className="flex flex-col gap-4 p-6 bg-white rounded-lg shadow-md">
  <h2 className="text-2xl font-semibold text-gray-900">Document Parser</h2>
  <div className="flex items-center gap-2">
    <Button variant="outline" className="border-blue-500 text-blue-500">
      Upload
    </Button>
  </div>
</div>

// ❌ WRONG: Inline styles
<div style={{ padding: '24px', backgroundColor: 'white' }}>
  {/* DON'T DO THIS */}
</div>
```

### Component Composition
- **ALWAYS** compose components from smaller pieces
- **ALWAYS** use shadcn/ui components as base
- **ALWAYS** create reusable component variants

```typescript
// ✅ CORRECT: Component composition
import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card';
import { Button } from '@/components/ui/button';

export function DocumentCard({ document }: { document: Document }) {
  return (
    <Card>
      <CardHeader>
        <CardTitle>{document.title}</CardTitle>
      </CardHeader>
      <CardContent>
        <p>{document.borrower_name}</p>
        <Button>View Details</Button>
      </CardContent>
    </Card>
  );
}
```

## FDC3 Integration

### Context Broadcasting
- **ALWAYS** broadcast FDC3 context for state changes
- **ALWAYS** use `useFDC3` hook for FDC3 operations
- **ALWAYS** handle FDC3 availability checks

```typescript
// ✅ CORRECT: FDC3 integration
import { useFDC3 } from '@/hooks/useFDC3';

export function DocumentParser({ onExtract }: DocumentParserProps) {
  const { broadcast, isAvailable } = useFDC3();
  
  const handleExtract = async (file: File) => {
    const data = await extractDocument(file);
    onExtract(data);
    
    // Broadcast FDC3 context
    if (isAvailable) {
      await broadcast({
        type: 'fdc3.creditnexus.agreement',
        id: { dealId: data.deal_id },
        agreement: data
      });
    }
  };
  
  return (
    // Component JSX
  );
}
```

### Intent Handling
- **ALWAYS** listen for FDC3 intents
- **ALWAYS** handle intent context appropriately
- **ALWAYS** update UI based on received context

```typescript
// ✅ CORRECT: Intent handling
import { useFDC3 } from '@/hooks/useFDC3';

export function DocumentGenerator() {
  const { addIntentListener, isAvailable } = useFDC3();
  const [agreement, setAgreement] = useState<CreditAgreement | null>(null);
  
  useEffect(() => {
    if (!isAvailable) return;
    
    const listener = addIntentListener('GenerateLMATemplate', (context) => {
      if (context.cdm_data) {
        setAgreement(context.cdm_data);
      }
    });
    
    return () => listener?.unsubscribe();
  }, [isAvailable, addIntentListener]);
  
  return (
    // Component JSX
  );
}
```

## API Integration

### Fetch Patterns
- **ALWAYS** use `fetch` with proper error handling
- **ALWAYS** handle loading and error states
- **ALWAYS** use TypeScript types for API responses
- **ALWAYS** include authentication headers

```typescript
// ✅ CORRECT: API integration
async function fetchDocument(docId: number): Promise<Document> {
  const response = await fetch(`/api/documents/${docId}`, {
    headers: {
      'Authorization': `Bearer ${getAccessToken()}`,
      'Content-Type': 'application/json'
    }
  });
  
  if (!response.ok) {
    throw new Error(`Failed to fetch document: ${response.statusText}`);
  }
  
  return response.json();
}
```

### Error Handling
- **ALWAYS** handle network errors
- **ALWAYS** handle HTTP error status codes
- **ALWAYS** display user-friendly error messages
- **ALWAYS** log errors for debugging

```typescript
// ✅ CORRECT: Error handling
const [error, setError] = useState<string | null>(null);

try {
  const data = await fetchDocument(docId);
  setDocument(data);
} catch (err) {
  if (err instanceof Error) {
    setError(err.message);
    console.error('Failed to fetch document:', err);
  } else {
    setError('An unexpected error occurred');
  }
}
```

## Form Handling

### Form Patterns
- **ALWAYS** use controlled components for forms
- **ALWAYS** validate form inputs
- **ALWAYS** provide feedback for validation errors
- **ALWAYS** disable submit button during submission

```typescript
// ✅ CORRECT: Form handling
import { useState } from 'react';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';

export function DocumentForm() {
  const [title, setTitle] = useState('');
  const [errors, setErrors] = useState<Record<string, string>>({});
  const [submitting, setSubmitting] = useState(false);
  
  const validate = () => {
    const newErrors: Record<string, string> = {};
    if (!title.trim()) {
      newErrors.title = 'Title is required';
    }
    setErrors(newErrors);
    return Object.keys(newErrors).length === 0;
  };
  
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!validate()) return;
    
    setSubmitting(true);
    try {
      await createDocument({ title });
    } finally {
      setSubmitting(false);
    }
  };
  
  return (
    <form onSubmit={handleSubmit}>
      <Input
        value={title}
        onChange={(e) => setTitle(e.target.value)}
        error={errors.title}
      />
      <Button type="submit" disabled={submitting}>
        {submitting ? 'Creating...' : 'Create'}
      </Button>
    </form>
  );
}
```

## Performance Optimization

### React Optimization
- **ALWAYS** use `React.memo` for expensive components
- **ALWAYS** use `useMemo` for expensive computations
- **ALWAYS** use `useCallback` for event handlers passed to children
- **ALWAYS** avoid unnecessary re-renders

```typescript
// ✅ CORRECT: Performance optimization
import { memo, useMemo, useCallback } from 'react';

export const DocumentCard = memo(function DocumentCard({ 
  document,
  onSelect 
}: DocumentCardProps) {
  const formattedDate = useMemo(
    () => new Date(document.created_at).toLocaleDateString(),
    [document.created_at]
  );
  
  const handleClick = useCallback(() => {
    onSelect(document.id);
  }, [document.id, onSelect]);
  
  return (
    <div onClick={handleClick}>
      <h3>{document.title}</h3>
      <p>{formattedDate}</p>
    </div>
  );
});
```

## Type Safety

### TypeScript Patterns
- **ALWAYS** define interfaces for all props
- **ALWAYS** use type inference where possible
- **ALWAYS** use `as const` for literal types
- **NEVER** use `any` type

```typescript
// ✅ CORRECT: Type safety
interface CreditAgreement {
  deal_id: string;
  agreement_date: string;
  parties: Party[];
  facilities: LoanFacility[];
}

interface DocumentParserProps {
  onExtract: (data: CreditAgreement) => void;
  initialText?: string;
}

// ❌ WRONG: Using any
function DocumentParser(props: any) {  // DON'T DO THIS
  // ...
}
```
.cursor/rules/llm-client.mdc0000666000000000000000000001615415127014400013223 0ustar  ---
description: LLM Client Abstraction Rules : CreditNexus uses an abstraction layer to support multiple LLM providers (OpenAI, vLLM, HuggingFace) while maintaining LangChain compatibility.
alwaysApply: false
---
# LLM Client Abstraction Rules

## LLM Client Abstraction Pattern

CreditNexus uses an abstraction layer to support multiple LLM providers (OpenAI, vLLM, HuggingFace) while maintaining LangChain compatibility.

## Core Principle: Never Direct Instantiation

- **NEVER** directly instantiate `ChatOpenAI` or `OpenAIEmbeddings`
- **ALWAYS** use `get_chat_model()` and `get_embeddings_model()` from `app/core/llm_client.py`
- **ALWAYS** use the abstraction layer for all LLM operations

```python
# ✅ CORRECT: Use abstraction
from app.core.llm_client import get_chat_model, get_embeddings_model

def create_extraction_chain():
    llm = get_chat_model()  # Uses global configuration
    return llm.with_structured_output(ExtractionResult)

def get_embeddings():
    embeddings = get_embeddings_model()
    return embeddings

# ❌ WRONG: Direct instantiation
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o", api_key=...)  # DON'T DO THIS
```

## LLM Client Initialization

### Startup Configuration
- **ALWAYS** initialize LLM client configuration in `lifespan` function
- **ALWAYS** validate provider-specific settings at startup
- **ALWAYS** fail fast if required configuration is missing

```python
# ✅ CORRECT: LLM initialization
@asynccontextmanager
async def lifespan(app: FastAPI):
    from app.core.llm_client import init_llm_config
    from app.core.config import settings
    
    try:
        init_llm_config(settings)
        logger.info(
            f"LLM client configured: provider={settings.LLM_PROVIDER.value}, "
            f"model={settings.LLM_MODEL}"
        )
    except Exception as e:
        logger.error(f"Failed to initialize LLM client: {e}")
        raise
    
    yield
```

## Provider Support

### Supported Providers
1. **OpenAI** (default): Native OpenAI API
2. **vLLM**: Local vLLM server with OpenAI-compatible API
3. **HuggingFace**: HuggingFace Inference API or Inference Providers

### Provider Configuration
```env
# OpenAI (default)
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o
OPENAI_API_KEY=sk-...

# vLLM
LLM_PROVIDER=vllm
LLM_MODEL=meta-llama/Llama-2-7b-chat-hf
VLLM_BASE_URL=http://localhost:8000

# HuggingFace
LLM_PROVIDER=huggingface
LLM_MODEL=meta-llama/Meta-Llama-3-8B-Instruct
HUGGINGFACE_API_KEY=hf_...
HUGGINGFACE_BASE_URL=https://api-inference.huggingface.co/v1
```

## LLM Client Factory Functions

### get_chat_model()
- **ALWAYS** use `get_chat_model()` for chat model creation
- **ALWAYS** allow model and temperature overrides
- **ALWAYS** use global configuration by default

```python
# ✅ CORRECT: Chat model usage
from app.core.llm_client import get_chat_model

# Use default configuration
llm = get_chat_model()

# Override model
llm = get_chat_model(model="gpt-4-turbo")

# Override temperature
llm = get_chat_model(temperature=0.1)

# Override both
llm = get_chat_model(model="gpt-4-turbo", temperature=0.1)
```

### get_embeddings_model()
- **ALWAYS** use `get_embeddings_model()` for embeddings
- **ALWAYS** support separate embeddings provider
- **ALWAYS** use global configuration by default

```python
# ✅ CORRECT: Embeddings usage
from app.core.llm_client import get_embeddings_model

# Use default configuration
embeddings = get_embeddings_model()

# Override model
embeddings = get_embeddings_model(model="text-embedding-3-large")
```

## LangChain Integration

### Structured Outputs
- **ALWAYS** use LangChain's `with_structured_output()` for Pydantic models
- **ALWAYS** maintain compatibility with LangChain chains
- **ALWAYS** use `BaseChatModel` type hints

```python
# ✅ CORRECT: LangChain structured outputs
from langchain_core.language_models import BaseChatModel
from app.core.llm_client import get_chat_model
from app.models.cdm import ExtractionResult

def create_extraction_chain() -> BaseChatModel:
    llm = get_chat_model()
    return llm.with_structured_output(ExtractionResult)
```

## Provider-Specific Details

### OpenAI
- Uses `langchain_openai.ChatOpenAI` directly
- Requires `OPENAI_API_KEY`
- Model format: `"gpt-4o"`, `"gpt-4-turbo"`, etc.

### vLLM
- Uses `langchain_openai.ChatOpenAI` with custom `base_url`
- Requires `VLLM_BASE_URL` (e.g., `http://localhost:8000`)
- vLLM exposes OpenAI-compatible API at `/v1/chat/completions`
- Model format: HuggingFace model ID (e.g., `"meta-llama/Llama-2-7b-chat-hf"`)

### HuggingFace
- Uses `langchain_openai.ChatOpenAI` with HF endpoint
- Requires `HUGGINGFACE_API_KEY` (HF token)
- Supports direct HF models or Inference Providers router
- Model format: `"meta-llama/Meta-Llama-3-8B-Instruct"` or `"cohere/command-r-plus"`

## Embeddings Support

### Embeddings Providers
- **OpenAI**: `OpenAIEmbeddings` from `langchain_openai`
- **HuggingFace**: `HuggingFaceEmbeddings` from `langchain_huggingface` (preferred) or OpenAI-compatible endpoint
- **vLLM**: Does not provide embeddings - use separate provider

### Embeddings Configuration
```env
EMBEDDINGS_MODEL=text-embedding-3-small
EMBEDDINGS_PROVIDER=openai  # Optional, defaults to LLM_PROVIDER
```

## Error Handling

### Configuration Errors
- **ALWAYS** validate provider-specific settings at startup
- **ALWAYS** provide clear error messages for missing configuration
- **ALWAYS** fail fast if required settings are missing

```python
# ✅ CORRECT: Configuration validation
def init_llm_config(settings: Settings) -> None:
    if settings.LLM_PROVIDER == "vllm" and not settings.VLLM_BASE_URL:
        raise ValueError("VLLM_BASE_URL is required when LLM_PROVIDER=vllm")
    
    if settings.LLM_PROVIDER == "huggingface" and not settings.HUGGINGFACE_API_KEY:
        raise ValueError("HUGGINGFACE_API_KEY is required when LLM_PROVIDER=huggingface")
```

## Refactoring Existing Code

### Migration Pattern
- Replace all `ChatOpenAI(...)` instantiations with `get_chat_model()`
- Replace all `OpenAIEmbeddings(...)` instantiations with `get_embeddings_model()`
- Update type hints to use `BaseChatModel` and `Embeddings`

```python
# Before
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
    model="gpt-4o",
    temperature=0,
    api_key=settings.OPENAI_API_KEY.get_secret_value()
)

# After
from app.core.llm_client import get_chat_model
llm = get_chat_model()  # Uses global config
```

## Performance Considerations

### Client Instances
- LLM clients are lightweight (just configuration)
- Created on-demand, not cached globally
- Connection pooling handled by `httpx` (used by LangChain)

### Caching
- Consider caching embeddings for frequently used text
- Consider caching LLM responses for identical inputs (if appropriate)
- Do NOT cache policy evaluation results (must be deterministic)

## Testing

### Mock LLM Clients
- **ALWAYS** mock LLM clients in unit tests
- **ALWAYS** test provider switching
- **ALWAYS** test configuration validation

```python
# ✅ CORRECT: Testing with mocks
from unittest.mock import patch

@patch('app.core.llm_client.get_chat_model')
def test_extraction(mock_get_chat_model):
    mock_llm = Mock()
    mock_get_chat_model.return_value = mock_llm
    # Test extraction logic
```
.cursor/rules/policy-engine.mdc0000666000000000000000000002161215127014250013723 0ustar  ---
description: Policy Engine Integration Rules : The policy engine enforces financial regulations (MiCA, Basel III, FATF) in real-time using deterministic policy-as-code rules.
alwaysApply: false
---
# Policy Engine Integration Rules

## Policy Engine Architecture

The policy engine enforces financial regulations (MiCA, Basel III, FATF) in real-time using deterministic policy-as-code rules.

## Policy Service Layer

### Service Interface
- **ALWAYS** use `PolicyService` for all policy evaluations
- **ALWAYS** inject `PolicyService` via dependency injection
- **ALWAYS** return `PolicyDecision` objects, not raw dictionaries
- **ALWAYS** create CDM events for all policy decisions

```python
# ✅ CORRECT: Policy service usage
from app.services.policy_service import PolicyService
from app.models.cdm_events import generate_cdm_policy_evaluation

@router.post("/extract")
async def extract_document(
    ...,
    policy_service: PolicyService = Depends(get_policy_service)
):
    # Evaluate policy
    policy_result = policy_service.evaluate_facility_creation(
        credit_agreement=result.agreement,
        document_id=doc.id
    )
    
    # Create CDM event
    policy_event = generate_cdm_policy_evaluation(
        transaction_id=result.agreement.deal_id,
        transaction_type="facility_creation",
        decision=policy_result.decision,
        rule_applied=policy_result.rule_applied,
        related_event_identifiers=[],
        evaluation_trace=policy_result.trace
    )
    
    # Handle decision
    if policy_result.decision == "BLOCK":
        raise HTTPException(403, detail={
            "status": "blocked",
            "reason": policy_result.rule_applied,
            "cdm_event": policy_event
        })
```

## Policy Evaluation Methods

### Four Evaluation Types
1. **evaluate_facility_creation()**: For document extraction
2. **evaluate_trade_execution()**: For trade execution
3. **evaluate_loan_asset()**: For loan asset verification
4. **evaluate_terms_change()**: For interest rate changes

### Integration Points
- Document Extraction: After CDM extraction, before workflow approval
- Trade Execution: Before trade confirmation in Trade Blotter
- Loan Asset: After satellite verification, before asset finalization
- Terms Change: Before applying interest rate penalty

```python
# ✅ CORRECT: Integration in document extraction
@router.post("/extract")
async def extract_document(...):
    result = extract_data_smart(text=text)
    
    if result.agreement:
        # Policy evaluation
        policy_result = policy_service.evaluate_facility_creation(
            credit_agreement=result.agreement,
            document_id=document.id
        )
        
        if policy_result.decision == "BLOCK":
            raise HTTPException(403, detail=policy_result)
        elif policy_result.decision == "FLAG":
            workflow.priority = "high"
            workflow.state = WorkflowState.REQUIRES_REVIEW
```

## Policy Decision Handling

### Decision Priority
1. **BLOCK** (highest): Stop workflow, raise HTTPException 403
2. **FLAG** (medium): Continue with high priority/review
3. **ALLOW** (default): Continue normally

```python
# ✅ CORRECT: Decision handling
if policy_result.decision == "BLOCK":
    raise HTTPException(
        status_code=403,
        detail={
            "status": "blocked",
            "reason": policy_result.rule_applied,
            "trace_id": policy_result.trace_id,
            "cdm_event": policy_event
        }
    )
elif policy_result.decision == "FLAG":
    workflow.priority = "high"
    workflow.state = WorkflowState.REQUIRES_REVIEW
    # Continue with workflow
# ALLOW: Continue normally
```

## Policy Rules Configuration

### YAML Rule Format
- **ALWAYS** store rules in `app/policies/*.yaml` files
- **ALWAYS** use PolicyConfigLoader to load rules
- **ALWAYS** validate rule structure at startup
- **ALWAYS** support hot-reload in development (POLICY_AUTO_RELOAD=true)

```yaml
# ✅ CORRECT: Policy rule format
# app/policies/regulatory_compliance.yaml
- name: block_sanctioned_parties
  when:
    any:
      - field: originator.lei
        op: in
        value: ["SANCTIONED_LEI_LIST"]
      - field: beneficiary.lei
        op: in
        value: ["SANCTIONED_LEI_LIST"]
  action: block
  priority: 100
  description: "Block transactions with sanctioned entities"

- name: flag_high_risk_jurisdiction
  when:
    any:
      - field: originator.jurisdiction
        op: in
        value: ["HighRiskCountryList"]
  action: flag
  priority: 50
  description: "Flag transactions in high-risk jurisdictions"
```

## Policy Engine Initialization

### Startup Pattern
- **ALWAYS** initialize policy engine in `lifespan` function
- **ALWAYS** load rules from YAML files at startup
- **ALWAYS** validate rules before engine initialization
- **ALWAYS** handle initialization errors gracefully

```python
# ✅ CORRECT: Policy engine initialization
@asynccontextmanager
async def lifespan(app: FastAPI):
    from app.services.policy_service import init_policy_engine
    from app.core.config import settings
    
    try:
        init_policy_engine(settings)
        if settings.POLICY_ENABLED:
            logger.info("Policy engine initialized successfully")
    except Exception as e:
        logger.error(f"Failed to initialize policy engine: {e}")
        if settings.POLICY_ENABLED:
            raise  # Fail fast if policy is required
    
    yield
    
    # Cleanup
    from app.services.policy_service import get_policy_config_loader
    loader = get_policy_config_loader()
    if loader:
        loader.stop_file_watcher()
```

## Policy Engine Interface

### Vendor-Agnostic Design
- **ALWAYS** use `PolicyEngineInterface` abstract base class
- **ALWAYS** implement vendor-specific engines separately
- **ALWAYS** use factory pattern for engine creation
- **ALWAYS** support multiple vendors (default, aspasia, custom)

```python
# ✅ CORRECT: Policy engine interface
from abc import ABC, abstractmethod

class PolicyEngineInterface(ABC):
    @abstractmethod
    def evaluate(self, transaction: Dict[str, Any]) -> Dict[str, Any]:
        """Evaluate transaction against policy rules."""
        pass
    
    @abstractmethod
    def load_rules(self, rules_yaml: str) -> None:
        """Load policy rules from YAML."""
        pass
    
    @abstractmethod
    def get_stats(self) -> Dict[str, Any]:
        """Get engine statistics."""
        pass
```

## Policy Decision Storage

### Database Pattern
- **ALWAYS** store policy decisions in `policy_decisions` table
- **ALWAYS** store complete CDM events in JSONB column
- **ALWAYS** store trace_id for auditability
- **ALWAYS** link to related entities (document_id, loan_asset_id)

```python
# ✅ CORRECT: Policy decision storage
from app.db.models import PolicyDecision

policy_decision = PolicyDecision(
    transaction_id=agreement.deal_id,
    transaction_type="facility_creation",
    decision=policy_result.decision,
    rule_applied=policy_result.rule_applied,
    trace_id=policy_result.trace_id,
    trace=policy_result.trace,
    matched_rules=policy_result.matched_rules,
    cdm_events=[policy_event],  # Full CDM event
    document_id=document.id,
    user_id=current_user.id
)
db.add(policy_decision)
db.commit()
```

## Policy Configuration

### Environment Variables
```env
POLICY_ENABLED=true
POLICY_RULES_DIR=app/policies
POLICY_RULES_PATTERN=*.yaml
POLICY_ENGINE_VENDOR=default
POLICY_AUTO_RELOAD=false  # true for development
```

### Configuration Loading
- **ALWAYS** use `PolicyConfigLoader` for rule loading
- **ALWAYS** merge rules from multiple YAML files
- **ALWAYS** validate rule structure
- **ALWAYS** support hot-reload in development

## Policy Evaluation Performance

### Performance Requirements
- **MUST** complete evaluation in <100ms for real-time enforcement
- **MUST** support high throughput (1000+ transactions/second)
- **MUST** cache rule compilation results
- **MUST** optimize rule matching algorithms

## Policy Testing

### Test Patterns
- **ALWAYS** test each evaluation method
- **ALWAYS** test decision handling (BLOCK, FLAG, ALLOW)
- **ALWAYS** test CDM event creation
- **ALWAYS** test rule loading and validation

```python
# ✅ CORRECT: Policy testing
def test_evaluate_facility_creation_blocked():
    service = PolicyService(mock_engine)
    agreement = CreditAgreement(...)  # With sanctioned party
    
    result = service.evaluate_facility_creation(agreement)
    
    assert result.decision == "BLOCK"
    assert result.rule_applied == "block_sanctioned_parties"
    assert result.trace_id is not None
```

## Policy Rule Organization

### File Organization
- Group rules by domain: `regulatory_compliance.yaml`, `trade_execution.yaml`
- Group rules by priority: `high_priority_rules.yaml`, `default_rules.yaml`
- Group rules by transaction type: `facility_creation.yaml`, `loan_asset.yaml`

### Rule Priority
- Higher priority integers = higher precedence
- BLOCK actions typically priority 80-100
- FLAG actions typically priority 30-79
- ALLOW actions typically priority 0-29