AI-powered cross-border contract risk assessment system built with FastAPI.

• FastAPI backend with automatic OpenAPI documentation
• Health check endpoints for monitoring
• Docker-compatible deployment
• Clean modular architecture
• Environment-based configuration

Our system employs a bounded, human-in-the-loop agentic architecture designed specifically for enterprise risk management. This approach fundamentally differs from generic AI agents by prioritizing control, explainability, and regulatory compliance.

Each agent operates within strictly defined boundaries:

• Contract Risk Scout: Analyzes clause deviations against historical baselines using rule-based logic only
• Client Intelligence Watcher: Monitors client risk signals with deterministic scoring algorithms
• Risk Simulation Agent: Runs what-if scenarios with mathematical models, optional Monte Carlo analysis
• Negotiation Strategy Agent: Generates template-based negotiation options with LLM assistance limited to language phrasing only
• Learning & Calibration Agent: Proposes model adjustments based on historical outcomes, never auto-updates

Every critical decision requires human approval:

• Risk Thresholds: Expected loss > 25% triggers mandatory CFO escalation
• Client Deterioration: Risk score increase > 15 points requires finance leadership review
• Multiple High-Risk Flags: Three or more critical issues demand executive approval
• Negotiation Actions: All recommendations require explicit human authorization before implementation

This governance framework ensures that AI augments human decision-making rather than replacing it.

Traditional AI agents operate with broad autonomy and opaque reasoning. Our approach differs fundamentally:

We increase trust by reducing uncontrolled behavior:

• Deterministic Core: All critical risk calculations use transparent mathematical models
• Explainable Decisions: Every recommendation includes clear reasoning and supporting evidence
• Immutable Audit Trail: Complete logging of all agent executions for regulatory compliance
• Governance Integration: Built-in escalation rules and approval workflows
• Template-Based Actions: Negotiation and calibration use predefined templates, not generative AI

This architecture ensures that our system enhances human expertise while maintaining human control over critical risk decisions. The result is an AI system that enterprise risk leaders can trust, regulators can audit, and stakeholders can understand.

contract_risk_system/
├── app/
│   ├── api/              # API layer
│   │   └── v1/
│   │       ├── endpoints/    # API endpoints
│   │       └── api.py        # API router
│   ├── core/             # Core configuration
│   ├── services/         # Business logic
│   └── utils/            # Utility functions
├── main.py               # FastAPI application entry point
├── requirements.txt      # Python dependencies
├── Dockerfile           # Docker configuration
├── docker-compose.yml   # Docker Compose setup
└── .env.example         # Environment variables template

1. Install dependencies:

   pip install -r requirements.txt

2. Run the application:

   python main.py

3. Access the API:

   • API Documentation: http://localhost:8000/docs
   • Health Check: http://localhost:8000/api/v1/health/health

1. Build and run with Docker Compose:

   docker-compose up --build

2. Access the API:

   • API Documentation: http://localhost:8000/docs
   • Health Check: http://localhost:8000/api/v1/health/health

• GET /api/v1/health/health - Service health status
• GET /api/v1/health/ping - Basic connectivity test

• GET / - Basic API information

Copy .env.example to .env and modify as needed:

cp .env.example .env

Key environment variables:

• HOST - Server host (default: 0.0.0.0)
• PORT - Server port (default: 8000)
• DEBUG - Debug mode (default: false)
• LOG_LEVEL - Logging level (default: INFO)

1. Create endpoint file in app/api/v1/endpoints/
2. Import and include router in app/api/v1/api.py
3. Add business logic in app/services/
4. Add utilities in app/utils/

# Install test dependencies
pip install pytest pytest-asyncio httpx

# Run tests
pytest

# Build image
docker build -t contract-risk-system .

# Run container
docker run -p 8000:8000 contract-risk-system

# Start services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

The application includes built-in health checks:

• Service status monitoring
• Component health checks
• Automatic health check endpoints

This project is licensed under the MIT License.