securelend 0.1.0__py3-none-any.whl

securelend/__init__.py

@@ -0,0 +1,31 @@
+"""
+SecureLend SDK for Python
+
+Official SDK for SecureLend - Financial services infrastructure for AI
+"""
+
+__version__ = "0.1.0"
+
+from .client import SecureLend
+from .utils.errors import (
+    AuthenticationError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    SecureLendError,
+    ServerError,
+    ValidationError,
+)
+from . import types
+
+__all__ = [
+    "SecureLend",
+    "SecureLendError",
+    "AuthenticationError",
+    "RateLimitError",
+    "ValidationError",
+    "NotFoundError",
+    "NetworkError",
+    "ServerError",
+    "types",
+]

securelend/client.py

@@ -0,0 +1,348 @@
+import json
+from typing import Any, Dict, Optional, Type, TypeVar
+
+from pydantic import BaseModel, ValidationError as PydanticValidationError
+
+from . import types
+from .utils.errors import SecureLendError, ValidationError
+from .utils.mcp import MCPClient
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class SecureLend:
+    """
+    SecureLend MCP-native SDK Client
+
+    Example:
+        >>> import asyncio
+        >>> from securelend import SecureLend
+        >>>
+        >>> async def main():
+        ...     securelend = SecureLend(api_key="sk_test_...")
+        ...     loans = await securelend.compare_business_loans({
+        ...         "loanAmount": 200000,
+        ...         "purpose": "equipment",
+        ...         "annualRevenue": 1200000,
+        ...     })
+        ...     print(loans)
+    """
+
+    def __init__(
+        self, *, api_key: Optional[str] = None, server_url: Optional[str] = None
+    ):
+        mcp_url = server_url or "https://mcp.securelend.ai/mcp"
+        self._mcp_client = MCPClient(api_key=api_key or "", mcp_url=mcp_url)
+
+    # --- Loan Comparison ---
+
+    async def compare_personal_loans(
+        self, request: Dict[str, Any]
+    ) -> types.LoanComparisonResponse:
+        return await self._validated_call_tool(
+            "compare_personal_loans",
+            request,
+            types.PersonalLoanSearchParams,
+            types.LoanComparisonResponse,
+        )
+
+    async def compare_business_loans(
+        self, request: Dict[str, Any]
+    ) -> types.LoanComparisonResponse:
+        return await self._validated_call_tool(
+            "compare_business_loans",
+            request,
+            types.BusinessLoanSearchParams,
+            types.LoanComparisonResponse,
+        )
+
+    async def compare_personal_mortgages(
+        self, request: Dict[str, Any]
+    ) -> types.LoanComparisonResponse:
+        return await self._validated_call_tool(
+            "compare_personal_mortgages",
+            request,
+            types.MortgageSearchParams,
+            types.LoanComparisonResponse,
+        )
+
+    async def compare_business_mortgages(
+        self, request: Dict[str, Any]
+    ) -> types.LoanComparisonResponse:
+        return await self._validated_call_tool(
+            "compare_business_mortgages",
+            request,
+            types.MortgageSearchParams,
+            types.LoanComparisonResponse,
+        )
+
+    async def compare_car_loans(
+        self, request: Dict[str, Any]
+    ) -> types.LoanComparisonResponse:
+        return await self._validated_call_tool(
+            "compare_car_loans",
+            request,
+            types.AutoLoanSearchParams,
+            types.LoanComparisonResponse,
+        )
+
+    async def compare_student_loans(
+        self, request: Dict[str, Any]
+    ) -> types.LoanComparisonResponse:
+        return await self._validated_call_tool(
+            "compare_student_loans",
+            request,
+            types.StudentLoanSearchParams,
+            types.LoanComparisonResponse,
+        )
+
+    # --- Banking & Credit Cards ---
+
+    async def compare_business_banking(
+        self, request: Dict[str, Any]
+    ) -> types.BusinessBankingComparisonResponse:
+        return await self._validated_call_tool(
+            "compare_business_banking",
+            request,
+            types.BusinessBankingSearchSchema,
+            types.BusinessBankingComparisonResponse,
+        )
+
+    async def compare_personal_banking(
+        self, request: Dict[str, Any]
+    ) -> types.PersonalBankingComparisonResponse:
+        return await self._validated_call_tool(
+            "compare_personal_banking",
+            request,
+            types.PersonalBankingSearchSchema,
+            types.PersonalBankingComparisonResponse,
+        )
+
+    async def compare_savings_accounts(
+        self, request: Dict[str, Any]
+    ) -> types.SavingsAccountComparisonResponse:
+        return await self._validated_call_tool(
+            "compare_savings_accounts",
+            request,
+            types.SavingsSearchSchema,
+            types.SavingsAccountComparisonResponse,
+        )
+
+    async def compare_business_credit_cards(
+        self, request: Dict[str, Any]
+    ) -> types.BusinessCreditCardComparisonResponse:
+        return await self._validated_call_tool(
+            "compare_business_credit_cards",
+            request,
+            types.BusinessCreditCardSearchParams,
+            types.BusinessCreditCardComparisonResponse,
+        )
+
+    async def compare_personal_credit_cards(
+        self, request: Dict[str, Any]
+    ) -> types.PersonalCreditCardComparisonResponse:
+        return await self._validated_call_tool(
+            "compare_personal_credit_cards",
+            request,
+            types.PersonalCreditCardSearchSchema,
+            types.PersonalCreditCardComparisonResponse,
+        )
+
+    # --- Financial Calculators ---
+
+    async def calculate_loan_payment(
+        self, request: Dict[str, Any]
+    ) -> types.LoanCalculationResponse:
+        return await self._validated_call_tool(
+            "calculate_loan_payment",
+            request,
+            types.LoanPaymentParams,
+            types.LoanCalculationResponse,
+        )
+
+    async def calculate_mortgage_payment(
+        self, request: Dict[str, Any]
+    ) -> types.MortgageCalculationResponse:
+        return await self._validated_call_tool(
+            "calculate_mortgage_payment",
+            request,
+            types.MortgagePaymentParams,
+            types.MortgageCalculationResponse,
+        )
+
+    async def compare_lease_vs_purchase(
+        self, request: Dict[str, Any]
+    ) -> types.LeaseVsPurchaseResponse:
+        return await self._validated_call_tool(
+            "compare_lease_vs_purchase",
+            request,
+            types.LeaseVsPurchaseParams,
+            types.LeaseVsPurchaseResponse,
+        )
+
+    # --- Application Management ---
+
+    async def get_offer(self, request: Dict[str, Any]) -> types.PersonalApplication:
+        return await self._validated_call_tool(
+            "get_offer", request, types.GetOfferParams, types.PersonalApplication
+        )
+
+    async def get_multiple_offers(
+        self, request: Dict[str, Any]
+    ) -> types.PersonalApplication:
+        return await self._validated_call_tool(
+            "get_multiple_offers",
+            request,
+            types.GetMultipleOffersParams,
+            types.PersonalApplication,
+        )
+
+    async def display_offer_form(
+        self, request: Dict[str, Any]
+    ) -> types.DisplayOfferFormResponse:
+        return await self._validated_call_tool(
+            "display_offer_form",
+            request,
+            types.DisplayOfferFormParams,
+            types.DisplayOfferFormResponse,
+        )
+
+    async def track_offer_status(
+        self, request: Dict[str, Any]
+    ) -> types.TrackOfferStatusResponse:
+        return await self._validated_call_tool(
+            "track_offer_status",
+            request,
+            types.TrackOfferStatusParams,
+            types.TrackOfferStatusResponse,
+        )
+
+    async def display_upload_documents_form(
+        self, request: Dict[str, Any]
+    ) -> types.DisplayUploadDocumentsFormResponse:
+        return await self._validated_call_tool(
+            "display_upload_documents_form",
+            request,
+            types.DisplayUploadDocumentsFormParams,
+            types.DisplayUploadDocumentsFormResponse,
+        )
+
+    async def submit_documents(
+        self, request: Dict[str, Any]
+    ) -> types.SubmitDocumentsResponse:
+        return await self._validated_call_tool(
+            "submit_documents",
+            request,
+            types.SubmitDocumentsParams,
+            types.SubmitDocumentsResponse,
+        )
+
+    # --- Core Methods ---
+
+    async def connect(self) -> None:
+        """Manually connect to the MCP server."""
+        await self._mcp_client.connect()
+
+    def set_api_key(self, api_key: str) -> None:
+        """Update API key for multi-tenant applications."""
+        self._mcp_client.set_api_key(api_key)
+
+    def enable_debug(self) -> None:
+        """Enable debug logging."""
+        self._mcp_client.enable_debug()
+
+    def disable_debug(self) -> None:
+        """Disable debug logging."""
+        self._mcp_client.disable_debug()
+
+    async def aclose(self):
+        """Gracefully close the connection to the MCP server."""
+        await self._mcp_client.close()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.aclose()
+
+    # --- Private Helpers ---
+
+    async def _validated_call_tool(
+        self,
+        tool_name: str,
+        request_data: Dict[str, Any],
+        request_cls: Type[BaseModel],
+        response_cls: Type[T],
+    ) -> T:
+        try:
+            validated_request = request_cls.model_validate(request_data)
+        except PydanticValidationError as e:
+            raise ValidationError("Invalid request parameters", errors=e.errors()) from e
+        return await self._call_tool(tool_name, validated_request, response_cls)
+
+    async def _call_tool(
+        self, tool_name: str, request: BaseModel, response_cls: Type[T]
+    ) -> T:
+        # Pydantic models are passed in, dump to dict for MCP call
+        request_data = request.model_dump(by_alias=True, exclude_none=True)
+        tool_result_dict = await self._mcp_client.call_tool(tool_name, request_data)
+        tool_result = types.ToolResult.model_validate(tool_result_dict)
+        data = self._parse_json_response(tool_result)
+        data["widget"] = self._get_widget(tool_result)
+
+        try:
+            return response_cls.model_validate(data)
+        except PydanticValidationError as e:
+            raise ValidationError(
+                f"Invalid response from MCP server: failed to validate JSON content for tool '{tool_name}'",
+                errors=e.errors(),
+            ) from e
+
+    def _parse_json_response(self, tool_result: types.ToolResult) -> Dict[str, Any]:
+        if tool_result.structured_content:
+            return tool_result.structured_content
+
+        content_list = tool_result.content
+        if not isinstance(content_list, list):
+            raise SecureLendError(
+                "Invalid response: content is not a list", "server_error"
+            )
+
+        for item in content_list:
+            if item.type == "text" and item.text:
+                try:
+                    return json.loads(item.text)
+                except json.JSONDecodeError as e:
+                    raise SecureLendError(
+                        f"Failed to parse JSON response: {e}", "server_error"
+                    ) from e
+            elif (
+                item.type == "resource"
+                and item.resource
+                and item.resource.mime_type == "application/json"
+                and item.resource.text
+            ):
+                try:
+                    return json.loads(item.resource.text)
+                except json.JSONDecodeError as e:
+                    raise SecureLendError(
+                        f"Failed to parse JSON response: {e}", "server_error"
+                    ) from e
+
+        raise SecureLendError(
+            "Invalid response from MCP server: missing JSON content", "server_error"
+        )
+
+    def _get_widget(self, tool_result: types.ToolResult) -> Optional[str]:
+        content_list = tool_result.content
+        if not isinstance(content_list, list):
+            return None
+
+        for item in content_list:
+            if (
+                item.type == "resource"
+                and item.resource
+                and item.resource.mime_type == "text/html"
+            ):
+                return item.resource.text
+        return None

securelend/types.py

@@ -0,0 +1,475 @@
+from __future__ import annotations
+from typing import List, Literal, Optional, Union, Dict, Any
+from pydantic import BaseModel, Field, model_validator
+from enum import Enum
+
+# ============================================================================
+# Enums
+# ============================================================================
+
+class CreditTier(str, Enum):
+    PRIME = "PRIME"
+    NEAR_PRIME = "NEAR_PRIME"
+    SUBPRIME = "SUBPRIME"
+    DEEP_SUBPRIME = "DEEP_SUBPRIME"
+    UNKNOWN = "UNKNOWN"
+
+class ProductType(str, Enum):
+    INSTALLMENT_LOAN = "INSTALLMENT_LOAN"
+    LINE_OF_CREDIT = "LINE_OF_CREDIT"
+    SHORT_TERM_CREDIT = "SHORT_TERM_CREDIT"
+    BNPL = "BNPL"
+    MORTGAGE = "MORTGAGE"
+    AUTO_LOAN = "AUTO_LOAN"
+    AUTO_REFINANCE = "AUTO_REFINANCE"
+    STUDENT_LOAN = "STUDENT_LOAN"
+    STUDENT_LOAN_REFINANCE = "STUDENT_LOAN_REFINANCE"
+    BUSINESS_LOAN = "BUSINESS_LOAN"
+    BUSINESS_BANKING = "BUSINESS_BANKING"
+    BUSINESS_CREDIT_CARD = "BUSINESS_CREDIT_CARD"
+    PERSONAL_BANKING = "PERSONAL_BANKING"
+    SAVINGS_ACCOUNT = "SAVINGS_ACCOUNT"
+    PERSONAL_CREDIT_CARD = "PERSONAL_CREDIT_CARD"
+
+class ApplicationType(str, Enum):
+    PERSONAL = "PERSONAL"
+    BUSINESS = "BUSINESS"
+
+class ApplicationStatus(str, Enum):
+    DRAFT = "DRAFT"
+    SUBMITTED = "SUBMITTED"
+    IN_REVIEW = "IN_REVIEW"
+    ACTION_REQUIRED = "ACTION_REQUIRED"
+    APPROVED = "APPROVED"
+    DECLINED = "DECLINED"
+    CLOSED = "CLOSED"
+
+class ProviderStatus(str, Enum):
+    PENDING = "PENDING"
+    SUBMITTED = "SUBMITTED"
+    REFERRED = "REFERRED"
+    ERROR = "ERROR"
+    RECEIVED = "RECEIVED"
+
+# ============================================================================
+# Common & Base Types
+# ============================================================================
+
+class Money(BaseModel):
+    amount: float
+    currency: Optional[str] = None
+
+class Resource(BaseModel):
+    mime_type: Optional[str] = Field(None, alias="mimeType")
+    text: Optional[str] = None
+
+class ContentItem(BaseModel):
+    type: Optional[str] = None
+    resource: Optional[Resource] = None
+    text: Optional[str] = None
+
+class ToolResult(BaseModel):
+    content: List[ContentItem] = []
+    structured_content: Optional[Any] = Field(None, alias="structuredContent")
+    request_id: Optional[str] = Field(None, alias="requestId")
+
+class SecureLendConfig(BaseModel):
+    api_key: Optional[str] = Field(None, alias="apiKey")
+    server_url: Optional[str] = Field(None, alias="serverUrl")
+
+# ============================================================================
+# Loan Comparison
+# ============================================================================
+
+class PersonalLoanSearchParams(BaseModel):
+    loan_amount: float = Field(..., alias="loanAmount", description="The desired loan amount in USD (e.g., 25000).")
+    purpose: Literal["debt_consolidation", "home_improvement", "major_purchase", "medical", "vacation", "other"] = Field(..., description="The purpose of the loan.")
+    credit_score: Optional[int] = Field(None, alias="creditScore", description="The applicant's estimated credit score (300-850).")
+    monthly_income: Optional[float] = Field(None, alias="monthlyIncome", description="Applicant's gross monthly income in USD.")
+    employment_status: Optional[Literal["employed", "self_employed", "retired", "unemployed"]] = Field(None, alias="employmentStatus", description="The applicant's employment status.")
+    state: Optional[str] = Field(None, description="The applicant's state of residence (2-letter code).")
+
+class BusinessLoanSearchParams(BaseModel):
+    loan_amount: float = Field(..., alias="loanAmount", description="The desired loan amount, e.g., 50000 for $50,000.")
+    purpose: str = Field(..., description="The reason for the loan, e.g., 'working capital'.")
+    annual_revenue: Optional[float] = Field(None, alias="annualRevenue", description="The business's gross annual revenue in USD.")
+    industry: Optional[str] = Field(None, description="The industry the business operates in, e.g., 'technology'.")
+    state: Optional[str] = Field(None, description="The state where the business is located (2-letter code).")
+
+class MortgageSearchParams(BaseModel):
+    loan_amount: float = Field(..., alias="loanAmount", description="The desired mortgage loan amount in USD.")
+    home_price: Optional[float] = Field(None, alias="homePrice", description="The purchase price of the home in USD.")
+    down_payment: Optional[float] = Field(None, alias="downPayment", description="The amount of the down payment in USD.")
+    credit_score: Optional[int] = Field(None, alias="creditScore", description="The applicant's estimated credit score (500-850).")
+    loan_type: Literal["conventional", "fha", "va", "jumbo", "refinance"] = Field(..., alias="loanType", description="The type of mortgage loan.")
+    property_type: Optional[Literal["primary", "secondary", "investment"]] = Field(None, alias="propertyType", description="The intended use of the property.")
+    state: Optional[str] = Field(None, description="The state where the property is located (2-letter code).")
+
+class AutoLoanSearchParams(BaseModel):
+    loan_amount: float = Field(..., alias="loanAmount", description="The desired auto loan amount in USD.")
+    credit_score: Optional[int] = Field(None, alias="creditScore", description="The applicant's estimated credit score (300-850).")
+    is_new: bool = Field(..., alias="isNew", description="Specifies if the vehicle is new (true) or used (false).")
+    state: Optional[str] = Field(None, description="The applicant's state of residence (2-letter code).")
+
+class StudentLoanSearchParams(BaseModel):
+    loan_amount: float = Field(..., alias="loanAmount", description="The total amount needed for the student loan in USD.")
+    credit_score: Optional[int] = Field(None, alias="creditScore", description="The student's estimated credit score (300-850).")
+    co_signer_credit_score: Optional[int] = Field(None, alias="coSignerCreditScore", description="The co-signer's estimated credit score (300-850), if applicable.")
+    degree_type: Literal["undergraduate", "graduate", "mba", "medical", "law"] = Field(..., alias="degreeType", description="The type of degree the loan is for.")
+    state: Optional[str] = Field(None, description="The student's state of residence (2-letter code).")
+
+class Lender(BaseModel):
+    id: str
+    name: str
+    type: str
+    logo_url: Optional[str] = Field(None, alias="logoUrl")
+
+class Product(BaseModel):
+    name: str
+    type: str
+    description: Optional[str] = None
+
+class InterestRate(BaseModel):
+    type: Literal["fixed", "variable"]
+    rate: Optional[float] = None
+    apr: float
+
+class Payment(BaseModel):
+    frequency: Optional[str] = None
+    amount: Money
+
+class Repayment(BaseModel):
+    total_repayment_amount: float = Field(..., alias="totalRepaymentAmount")
+    cost_of_financing: float = Field(..., alias="costOfFinancing")
+
+class LoanTerms(BaseModel):
+    amount: Money
+    interest_rate: InterestRate = Field(..., alias="interestRate")
+    term_months: int = Field(..., alias="termMonths")
+    payment: Payment
+    total_cost: Optional[Money] = Field(None, alias="totalCost")
+    repayment: Optional[Repayment] = None
+
+class OriginationFee(BaseModel):
+    amount: Optional[Money] = None
+    percentage: Optional[float] = None
+
+class LoanFees(BaseModel):
+    origination: Optional[OriginationFee] = None
+
+class Matching(BaseModel):
+    approval_probability: Optional[float] = Field(None, alias="approvalProbability")
+    match_score: Optional[float] = Field(None, alias="matchScore")
+    match_reasons: Optional[List[str]] = Field(None, alias="matchReasons")
+
+class FundingSpeed(BaseModel):
+    description: str
+
+class Process(BaseModel):
+    application_method: str = Field(..., alias="applicationMethod")
+    application_url: Optional[str] = Field(None, alias="applicationUrl")
+    funding_speed: Optional[FundingSpeed] = Field(None, alias="fundingSpeed")
+
+class LoanOffer(BaseModel):
+    offer_id: str = Field(..., alias="offerId")
+    lender: Lender
+    product: Product
+    terms: LoanTerms
+    fees: Optional[LoanFees] = None
+    matching: Optional[Matching] = None
+    process: Optional[Process] = None
+    lender_info: Optional[str] = Field(None, alias="lenderInfo")
+    badges: Optional[List[str]] = None
+    is_secure_lend_tenant: Optional[bool] = Field(None, alias="isSecureLendTenant")
+
+class LoanComparisonSummary(BaseModel):
+    total_offers: int = Field(..., alias="totalOffers")
+    best_rate: float = Field(..., alias="bestRate")
+    best_approval_probability: Optional[float] = Field(None, alias="bestApprovalProbability")
+    fastest_funding: Optional[str] = Field(None, alias="fastestFunding")
+
+class Metadata(BaseModel):
+    query_id: str = Field(..., alias="queryId")
+    timestamp: str
+    session_id: Optional[str] = Field(None, alias="sessionId")
+
+class LoanComparisonResponse(BaseModel):
+    offers: List[LoanOffer]
+    summary: LoanComparisonSummary
+    search_criteria: Optional[Union[PersonalLoanSearchParams, BusinessLoanSearchParams, MortgageSearchParams, AutoLoanSearchParams, StudentLoanSearchParams]] = Field(None, alias="searchCriteria")
+    metadata: Metadata
+    widget: Optional[str] = None
+
+# ============================================================================
+# Banking & Credit Cards
+# ============================================================================
+
+class BusinessBankingSearchSchema(BaseModel):
+    industry: Optional[str] = Field(None, description="The business's industry.")
+    monthly_transactions: Optional[int] = Field(None, alias="monthlyTransactions", description="Estimated number of monthly transactions.")
+
+class BusinessBankingOffer(BaseModel):
+    account_id: str = Field(..., alias="accountId")
+    name: str
+    issuer: str
+    image_url: str = Field(..., alias="imageUrl")
+    rating: float
+    best_for: str = Field(..., alias="bestFor")
+    apy: str
+    interest_rate: Optional[str] = Field(None, alias="interestRate")
+    monthly_fee: str = Field(..., alias="monthlyFee")
+    bonus: str
+
+class BusinessBankingComparisonResponse(BaseModel):
+    offers: List[BusinessBankingOffer]
+    search_criteria: Optional[BusinessBankingSearchSchema] = Field(None, alias="searchCriteria")
+    metadata: Metadata
+    widget: Optional[str] = None
+
+class PersonalBankingSearchSchema(BaseModel):
+    features: Optional[List[str]] = Field(None, description="Desired account features.")
+
+class PersonalBankingOffer(BaseModel):
+    account_id: str = Field(..., alias="accountId")
+    name: str
+    issuer: str
+    image_url: str = Field(..., alias="imageUrl")
+    rating: float
+    best_for: str = Field(..., alias="bestFor")
+    apy: str
+    interest_rate: Optional[str] = Field(None, alias="interestRate")
+    bonus: str
+    monthly_fee: str = Field(..., alias="monthlyFee")
+    overdraft_rating: float = Field(..., alias="overdraftRating")
+
+class PersonalBankingComparisonResponse(BaseModel):
+    offers: List[PersonalBankingOffer]
+    search_criteria: Optional[PersonalBankingSearchSchema] = Field(None, alias="searchCriteria")
+    metadata: Metadata
+    widget: Optional[str] = None
+
+class SavingsSearchSchema(BaseModel):
+    initial_deposit: Optional[float] = Field(None, alias="initialDeposit", description="The initial deposit amount in USD.")
+
+class SavingsOffer(BaseModel):
+    account_id: str = Field(..., alias="accountId")
+    name: str
+    issuer: str
+    image_url: str = Field(..., alias="imageUrl")
+    rating: float
+    apy: str
+    interest_rate: Optional[str] = Field(None, alias="interestRate")
+    min_balance_for_apy: str = Field(..., alias="minBalanceForApy")
+    monthly_fee: str = Field(..., alias="monthlyFee")
+
+class SavingsAccountComparisonResponse(BaseModel):
+    offers: List[SavingsOffer]
+    search_criteria: Optional[SavingsSearchSchema] = Field(None, alias="searchCriteria")
+    metadata: Metadata
+    widget: Optional[str] = None
+
+class BusinessCreditCardSearchParams(BaseModel):
+    credit_score: Optional[int] = Field(None, alias="creditScore", description="The applicant's estimated credit score (300-850).")
+    annual_revenue: Optional[float] = Field(None, alias="annualRevenue", description="The business's annual revenue in USD.")
+    business_age_in_years: Optional[float] = Field(None, alias="businessAgeInYears", description="The age of the business in years.")
+
+class BusinessCreditCardTerms(BaseModel):
+    apr: float
+    annual_fee: float = Field(..., alias="annualFee")
+    credit_limit: Money = Field(..., alias="creditLimit")
+
+class BusinessCreditCardOffer(BaseModel):
+    card_id: str = Field(..., alias="cardId")
+    name: str
+    issuer: str
+    image_url: str = Field(..., alias="imageUrl")
+    rating: float
+    credit_score_range: str = Field(..., alias="creditScoreRange")
+    welcome_bonus: str = Field(..., alias="welcomeBonus")
+    terms: BusinessCreditCardTerms
+
+class BusinessCreditCardComparisonResponse(BaseModel):
+    offers: List[BusinessCreditCardOffer]
+    search_criteria: Optional[BusinessCreditCardSearchParams] = Field(None, alias="searchCriteria")
+    metadata: Metadata
+    widget: Optional[str] = None
+
+class PersonalCreditCardSearchSchema(BaseModel):
+    credit_score: Optional[int] = Field(None, alias="creditScore", description="The applicant's estimated credit score (300-850).")
+    rewards_type: Optional[Literal["cash_back", "travel", "points"]] = Field(None, alias="rewardsType", description="Preferred rewards type.")
+
+class PersonalCreditCardAPRs(BaseModel):
+    purchase: float
+    balance_transfer: float = Field(..., alias="balanceTransfer")
+    penalty: Optional[float] = None
+
+class PersonalCreditCardFees(BaseModel):
+    annual: float
+
+class PersonalCreditCardTerms(BaseModel):
+    apr: PersonalCreditCardAPRs
+    fees: PersonalCreditCardFees
+
+class PersonalCreditCardOffer(BaseModel):
+    card_id: str = Field(..., alias="cardId")
+    name: str
+    issuer: str
+    image_url: str = Field(..., alias="imageUrl")
+    rating: float
+    best_for: str = Field(..., alias="bestFor")
+    rewards_rate: str = Field(..., alias="rewardsRate")
+    intro_offer: str = Field(..., alias="introOffer")
+    recommended_credit_score: str = Field(..., alias="recommendedCreditScore")
+    terms: PersonalCreditCardTerms
+    application_url: Optional[str] = Field(None, alias="applicationUrl")
+
+class PersonalCreditCardComparisonResponse(BaseModel):
+    offers: List[PersonalCreditCardOffer]
+    search_criteria: Optional[PersonalCreditCardSearchSchema] = Field(None, alias="searchCriteria")
+    metadata: Metadata
+    widget: Optional[str] = None
+
+# ============================================================================
+# Financial Calculators
+# ============================================================================
+
+class LoanPaymentParams(BaseModel):
+    loan_amount: float = Field(..., alias="loanAmount")
+    interest_rate: float = Field(..., alias="interestRate")
+    loan_term_in_months: int = Field(..., alias="loanTermInMonths")
+
+class LoanCalculationResponse(BaseModel):
+    monthly_payment: float = Field(..., alias="monthlyPayment")
+    total_payment: float = Field(..., alias="totalPayment")
+    total_interest: float = Field(..., alias="totalInterest")
+    widget: Optional[str] = None
+
+class MortgagePaymentParams(BaseModel):
+    property_value: float = Field(..., alias="propertyValue")
+    down_payment: float = Field(..., alias="downPayment")
+    interest_rate: float = Field(..., alias="interestRate")
+    loan_term_in_years: int = Field(..., alias="loanTermInYears")
+    property_tax_rate: float = Field(..., alias="propertyTaxRate")
+    home_insurance: float = Field(..., alias="homeInsurance")
+
+class MortgageCalculationResponse(BaseModel):
+    loan_amount: float = Field(..., alias="loanAmount")
+    principal_and_interest: float = Field(..., alias="principalAndInterest")
+    monthly_property_tax: float = Field(..., alias="monthlyPropertyTax")
+    monthly_home_insurance: float = Field(..., alias="monthlyHomeInsurance")
+    total_monthly_payment: float = Field(..., alias="totalMonthlyPayment")
+    widget: Optional[str] = None
+
+class LeaseVsPurchaseParams(BaseModel):
+    purchase_price: float = Field(..., alias="purchasePrice")
+    down_payment: float = Field(..., alias="downPayment")
+    loan_term_in_months: int = Field(..., alias="loanTermInMonths")
+    interest_rate: float = Field(..., alias="interestRate")
+    sales_tax_rate: float = Field(..., alias="salesTaxRate")
+    lease_term_in_months: int = Field(..., alias="leaseTermInMonths")
+    monthly_lease_payment: float = Field(..., alias="monthlyLeasePayment")
+    money_factor: float = Field(..., alias="moneyFactor")
+    acquisition_fee: float = Field(..., alias="acquisitionFee")
+    security_deposit: float = Field(..., alias="securityDeposit")
+    residual_value_percentage: float = Field(..., alias="residualValuePercentage")
+    expected_ownership_in_months: int = Field(..., alias="expectedOwnershipInMonths")
+
+class LeaseVsPurchaseResponse(BaseModel):
+    purchase_analysis: Dict[str, Any] = Field(..., alias="purchaseAnalysis")
+    lease_analysis: Dict[str, Any] = Field(..., alias="leaseAnalysis")
+    comparison: Dict[str, Any]
+    widget: Optional[str] = None
+
+# ============================================================================
+# Application Management
+# ============================================================================
+
+class PersonalApplicant(BaseModel):
+    first_name: str = Field(..., alias="firstName", description="The applicant's first name.")
+    last_name: str = Field(..., alias="lastName", description="The applicant's last name.")
+    email: str = Field(..., description="The applicant's email address.")
+    phone: Optional[str] = Field(None, description="The applicant's phone number.")
+
+class Provider(BaseModel):
+    provider_id: str = Field(..., alias="providerId", description="The ID of the selected provider.")
+    provider_name: str = Field(..., alias="providerName", description="The name of the selected provider.")
+
+class GetOfferParams(BaseModel):
+    product_type: ProductType = Field(..., alias="productType", description="The type of financial product being applied for.")
+    applicant: PersonalApplicant = Field(..., description="Personal details of the applicant.")
+    application_data: Dict[str, Any] = Field(..., alias="applicationData", description="The original search parameters or form data for the application.")
+    provider: Provider = Field(..., description="The selected provider to submit the application to.")
+
+class GetMultipleOffersParams(BaseModel):
+    product_type: ProductType = Field(..., alias="productType", description="The type of financial product being applied for.")
+    applicant: PersonalApplicant = Field(..., description="Personal details of the applicant.")
+    application_data: Dict[str, Any] = Field(..., alias="applicationData", description="The original search parameters or form data for the application.")
+    providers: List[Provider] = Field(..., min_length=1, description="The list of selected providers to submit the application to.")
+
+class ApplicationProvider(BaseModel):
+    provider_id: str = Field(..., alias="providerId")
+    provider_name: str = Field(..., alias="providerName")
+    status: ProviderStatus
+    submitted_at: Optional[str] = Field(None, alias="submittedAt")
+    provider_application_id: Optional[str] = Field(None, alias="providerApplicationId")
+    referral_url: Optional[str] = Field(None, alias="referralUrl")
+    error: Optional[str] = None
+
+class PersonalApplication(BaseModel):
+    id: str
+    created_at: str = Field(..., alias="createdAt")
+    updated_at: str = Field(..., alias="updatedAt")
+    application_type: ApplicationType = Field(..., alias="applicationType")
+    product_type: Union[ProductType, str] = Field(..., alias="productType")
+    status: ApplicationStatus
+    applicant: PersonalApplicant
+    application_data: Dict[str, Any] = Field(..., alias="applicationData")
+    providers: List[ApplicationProvider]
+    email: str
+    widget: Optional[str] = None
+
+class DisplayOfferFormParams(BaseModel):
+    session_id: Optional[str] = Field(None, alias="sessionId")
+    offer_id: Optional[str] = Field(None, alias="offerId")
+
+AnyOffer = Union[LoanOffer, BusinessCreditCardOffer, BusinessBankingOffer, PersonalBankingOffer, SavingsOffer, PersonalCreditCardOffer]
+
+class DisplayOfferFormResponse(BaseModel):
+    offer: AnyOffer
+    all_offers: List[AnyOffer] = Field(..., alias="allOffers")
+    application_data: Dict[str, Any] = Field(..., alias="applicationData")
+    product_type: str = Field(..., alias="productType")
+    widget: Optional[str] = None
+
+class TrackOfferStatusParams(BaseModel):
+    application_id: Optional[str] = Field(None, alias="applicationId")
+    email: Optional[str] = None
+
+    @model_validator(mode="after")
+    def check_application_id_or_email(self) -> "TrackOfferStatusParams":
+        if not self.application_id and not self.email:
+            raise ValueError("Either applicationId or email must be provided.")
+        return self
+
+class TrackOfferStatusResponse(BaseModel):
+    applications: List[PersonalApplication]
+    widget: Optional[str] = None
+
+class DisplayUploadDocumentsFormParams(BaseModel):
+    application_id: Optional[str] = Field(None, alias="applicationId")
+
+class DisplayUploadDocumentsFormResponse(BaseModel):
+    widget: Optional[str] = None
+
+class SubmitDocumentsParams(BaseModel):
+    application_id: str = Field(..., alias="applicationId")
+    file_name: str = Field(..., alias="fileName")
+    document_type: str = Field(..., alias="documentType")
+
+class SubmitDocumentsResponse(BaseModel):
+    success: bool
+    message: str
+    upload_url: Optional[str] = Field(None, alias="uploadUrl")
+    upload_fields: Optional[Dict[str, str]] = Field(None, alias="uploadFields")
+    document_id: Optional[str] = Field(None, alias="documentId")
+    widget: Optional[str] = None

securelend/utils/__init__.py

@@ -0,0 +1 @@
+# This file makes the `utils` directory a Python package.

securelend/utils/errors.py

@@ -0,0 +1,38 @@
+class SecureLendError(Exception):
+    """Base exception for all SecureLend SDK errors."""
+
+    def __init__(self, message: str, error_type: str, details: any = None):
+        super().__init__(message)
+        self.type = error_type
+        self.details = details
+
+
+class AuthenticationError(SecureLendError):
+    def __init__(self, message: str):
+        super().__init__(message, "authentication_error")
+
+
+class RateLimitError(SecureLendError):
+    def __init__(self, message: str, retry_after: int | None = None):
+        super().__init__(message, "rate_limit_error")
+        self.retry_after = retry_after
+
+
+class ValidationError(SecureLendError):
+    def __init__(self, message: str, errors: any = None):
+        super().__init__(message, "validation_error", errors)
+
+
+class NotFoundError(SecureLendError):
+    def __init__(self, message: str):
+        super().__init__(message, "not_found")
+
+
+class NetworkError(SecureLendError):
+    def __init__(self, message: str):
+        super().__init__(message, "network_error")
+
+
+class ServerError(SecureLendError):
+    def __init__(self, message: str):
+        super().__init__(message, "server_error")

securelend/utils/mcp.py

@@ -0,0 +1,115 @@
+from contextlib import AsyncExitStack
+from typing import Any, Dict, Optional
+
+import httpx
+from mcp import ClientSession, McpError
+from mcp.client.streamable_http import streamablehttp_client
+
+from ..utils.errors import (
+    AuthenticationError,
+    NetworkError,
+    RateLimitError,
+    ServerError,
+)
+
+
+class MCPClient:
+    def __init__(self, *, api_key: str, mcp_url: str):
+        self._api_key = api_key
+        self._mcp_url = mcp_url
+        self._debug = False
+        self._session: Optional[ClientSession] = None
+        self._exit_stack = AsyncExitStack()
+        self._reconnect_required = False
+
+    async def _get_session(self) -> ClientSession:
+        if self._session is None or self._reconnect_required:
+            await self.connect()
+            self._reconnect_required = False
+        assert self._session is not None
+        return self._session
+
+    async def connect(self) -> None:
+        if self._session:
+            await self.close()
+
+        self._exit_stack = AsyncExitStack()
+        headers = {
+            "User-Agent": f"securelend-python/{__import__('securelend').__version__}",
+        }
+        if self._api_key:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+
+        if self._debug:
+            print(f"[SecureLend SDK] Connecting to MCP server at {self._mcp_url}")
+
+        try:
+            transport_context = streamablehttp_client(
+                url=self._mcp_url, headers=headers
+            )
+            read_stream, write_stream, _ = await self._exit_stack.enter_async_context(
+                transport_context
+            )
+            session_context = ClientSession(read_stream, write_stream)
+            self._session = await self._exit_stack.enter_async_context(session_context)
+            await self._session.initialize()
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code in (401, 403):
+                raise AuthenticationError("Authentication failed.") from e
+            if e.response.status_code == 429:
+                retry_after_header = e.response.headers.get("Retry-After")
+                retry_after = None
+                if retry_after_header and retry_after_header.isdigit():
+                    retry_after = int(retry_after_header)
+                raise RateLimitError(
+                    "Rate limit exceeded.", retry_after=retry_after
+                ) from e
+            if e.response.status_code >= 500:
+                raise ServerError(f"Server error: {e.response.text}") from e
+            raise NetworkError(f"HTTP error: {e}") from e
+        except httpx.RequestError as e:
+            raise NetworkError(f"Network error: {e}") from e
+        except Exception as e:
+            raise NetworkError(f"Failed to connect to MCP server: {e}") from e
+
+    async def call_tool(self, name: str, args: Dict[str, Any]) -> Dict[str, Any]:
+        session = await self._get_session()
+        try:
+            if self._debug:
+                print(f"[SecureLend SDK] Calling tool '{name}' with args: {args}")
+
+            result = await session.call_tool(name, args)
+
+            content_list = []
+            for item in result.content:
+                content_item = {"type": item.type, "text": getattr(item, "text", None)}
+                if hasattr(item, "resource") and item.resource:
+                    content_item["resource"] = {
+                        "mimeType": item.resource.mimeType,
+                        "text": item.resource.text,
+                    }
+                content_list.append(content_item)
+
+            return {
+                "content": content_list,
+                "structuredContent": getattr(result, "structuredContent", None),
+                "requestId": getattr(result, "requestId", None),
+            }
+        except McpError as e:
+            raise ServerError(f"MCP tool call failed: {e.message}") from e
+
+    async def close(self):
+        if self._session:
+            await self._exit_stack.aclose()
+        self._session = None
+        self._exit_stack = AsyncExitStack()
+
+    def set_api_key(self, api_key: str) -> None:
+        self._api_key = api_key
+        self._reconnect_required = True
+
+    def enable_debug(self) -> None:
+        self._debug = True
+
+    def disable_debug(self) -> None:
+        self._debug = False

securelend-0.1.0.dist-info/METADATA

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: securelend
+Version: 0.1.0
+Summary: SecureLend SDK for Python
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SecureLend/sdk/tree/main/packages/python
+Project-URL: Bug Tracker, https://github.com/SecureLend/sdk/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.20; extra == "test"
+
+# SecureLend SDK for Python [![PyPI version](https://img.shields.io/pypi/v/securelend.svg)](https://pypi.org/project/securelend/)
+
+The official Python SDK for SecureLend - Financial services infrastructure for AI assistants.
+
+## Installation
+
+```bash
+pip install securelend
+```
+
+## Quick Start
+
+```python
+import asyncio
+import os
+from securelend import SecureLend
+
+async def main():
+    # The API server is public and does not require an API key.
+    # A key can optionally be provided for usage tracking.
+    async with SecureLend(api_key=os.environ.get("SECURELEND_API_KEY")) as securelend:
+        response = await securelend.compare_business_loans({
+            "loanAmount": 200000,
+            "purpose": "equipment",
+            "annualRevenue": 1200000,
+        })
+
+        print(f"Found {response.summary.total_offers} loan offers.")
+
+        if response.offers:
+            top_offer = response.offers[0]
+            apr = top_offer.terms.interest_rate.apr * 100
+            print(f"Top offer from {top_offer.lender.name} with {apr:.2f}% APR.")
+
+            # Calculate payment details for the top offer
+            payment_details = await securelend.calculate_loan_payment({
+                "loanAmount": top_offer.terms.amount.amount,
+                "interestRate": apr,
+                "loanTermInMonths": top_offer.terms.term_months,
+            })
+            print(f"  - Estimated Monthly Payment: ${payment_details.monthly_payment:,.2f}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Documentation
+
+- [Full Documentation](https://docs.securelend.ai)
+- [API Reference](https://docs.securelend.ai/api)
+- [Guides](https://docs.securelend.ai/guides)

securelend-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+securelend/__init__.py,sha256=HIaVtRuOEOiTKDxnYFIKyuwNtuPivfWzp9whktUb-Og,553
+securelend/client.py,sha256=WdmIH_LnBk9F20SPXx0pZ9JJqjkZwjQEUD33EL0uQEs,11660
+securelend/types.py,sha256=-f43TX5oNaJ-16jeoH3S6AMHRO_cVJCV-rYO_bjiLGs,21899
+securelend/utils/__init__.py,sha256=1IwFDtwJ76i1O7_iM4LLGqwgtt11y0PIV0DWubh8nLU,58
+securelend/utils/errors.py,sha256=rPT22bGnPKM8sYubDjI2Mx3VQ_mMGcsYd5pONwMSzLI,1150
+securelend/utils/mcp.py,sha256=1yvEweKcvmrOhd1iHp13uEx67ANLJF1CUY4uElEq_ls,4296
+securelend-0.1.0.dist-info/METADATA,sha256=HgutbST1RKPcLUC7qbY7lA_ezVx4CGtaMblwPoIdVkE,2304
+securelend-0.1.0.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+securelend-0.1.0.dist-info/top_level.txt,sha256=my2T0PhysHbgmRHqTy7ZaLnHpLFa9o9zB9rJQZWE9BI,11
+securelend-0.1.0.dist-info/RECORD,,

securelend-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

securelend-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+securelend