Skip to content

README.md

Latest commit

 

History

History
208 lines (161 loc) · 4.8 KB

README.md

File metadata and controls

208 lines (161 loc) · 4.8 KB

ICC Rule Engine Python SDK

A comprehensive Python SDK for interacting with the ICC Rule Engine API.

Installation

pip install icc-rule-engine-sdk

Quick Start

from icc_rule_engine import ICCRuleEngineClient, Rule

# Initialize client
client = ICCRuleEngineClient(
    base_url="https://your-api.onrender.com",
    api_key="your-api-key"
)

# Check API health
health = client.health_check()
print(f"API Status: {health.status}")

# Create a rule
rule = Rule(
    source="UCP600",
    rule_id="TEST_RULE_001",
    article="14",
    title="Document Presentation Requirements",
    text="Documents must be presented within 21 days after shipment date.",
    condition={
        "type": "date_range_check",
        "left_path": "presentation_date",
        "right_path": "shipment_date",
        "max_days_difference": 21
    },
    expected_outcome={
        "action": "validate",
        "result": "compliant"
    },
    tags=["timing", "presentation"],
    severity="high"
)

created_rule = client.create_rule(rule)
print(f"Created rule: {created_rule.rule_id}")

# Validate a document
document = {
    "id": "LC_2024_001",
    "document_type": "letter_of_credit",
    "presentation_date": "2024-01-20",
    "shipment_date": "2024-01-15",
    "credit_amount": 100000
}

result = client.validate_document(
    document=document,
    ruleset={"source": "UCP600", "article": "14"}
)

print(f"Validation result: {result.ok}")
print(f"Score: {result.score}")
if result.violations:
    for violation in result.violations:
        print(f"Violation: {violation.message}")

Async Usage

import asyncio
from icc_rule_engine import AsyncICCRuleEngineClient

async def main():
    async with AsyncICCRuleEngineClient(
        base_url="https://your-api.onrender.com",
        api_key="your-api-key"
    ) as client:
        result = await client.validate_document(
            document=document,
            ruleset={"source": "UCP600"}
        )
        print(f"Async validation result: {result.ok}")

asyncio.run(main())

Features

  • Complete API Coverage: All ICC Rule Engine endpoints
  • Type Safety: Full Pydantic model validation
  • Async Support: Both sync and async clients
  • Error Handling: Comprehensive exception hierarchy
  • Retry Logic: Automatic retries with exponential backoff
  • Rate Limiting: Built-in rate limit handling
  • Authentication: API key authentication
  • Timeouts: Configurable request timeouts

API Reference

Client Methods

Rule Management

  • create_rule(rule) - Create a new rule
  • get_rule(rule_id) - Get rule by ID
  • update_rule(rule_id, rule) - Update existing rule
  • delete_rule(rule_id) - Delete rule
  • list_rules(**filters) - List rules with filters

Validation

  • validate_document(document, ruleset) - Validate single document
  • validate_batch(documents, ruleset, parallel=True) - Validate multiple documents

Monitoring

  • health_check() - Check API health
  • get_metrics() - Get API metrics

Models

Rule

Core rule model with all validation and metadata fields.

ValidationResult

Complete validation result including score, violations, and applied rules.

Exceptions

  • ICCRuleEngineError - Base exception
  • APIError - API-related errors
  • AuthenticationError - Authentication failures
  • ValidationError - Validation failures
  • NetworkError - Network-related errors
  • TimeoutError - Request timeouts
  • RateLimitError - Rate limit exceeded

Configuration

Environment Variables

ICC_RULE_ENGINE_BASE_URL=https://your-api.onrender.com
ICC_RULE_ENGINE_API_KEY=your-api-key
ICC_RULE_ENGINE_TIMEOUT=30.0
ICC_RULE_ENGINE_MAX_RETRIES=3

Client Configuration

client = ICCRuleEngineClient(
    base_url="https://your-api.onrender.com",
    api_key="your-api-key",
    timeout=30.0,           # Request timeout in seconds
    max_retries=3,          # Maximum retry attempts
    retry_delay=1.0         # Base delay between retries
)

Error Handling

from icc_rule_engine import ICCRuleEngineClient, APIError, AuthenticationError

try:
    result = client.validate_document(document, ruleset)
except AuthenticationError:
    print("Invalid API key")
except APIError as e:
    print(f"API error: {e.message} (status: {e.status_code})")
except Exception as e:
    print(f"Unexpected error: {e}")

Development

Running Tests

# Install development dependencies
pip install -e .[dev]

# Run tests
pytest

# Run tests with coverage
pytest --cov=icc_rule_engine --cov-report=html

Code Formatting

# Format code
black icc_rule_engine/
isort icc_rule_engine/

# Type checking
mypy icc_rule_engine/

License

MIT License - see LICENSE file for details.

Support

For support and bug reports, please visit: https://github.com/your-org/icc-rule-engine/issues