server/app.py

"""FastAPI server wrapping the ClaimSense adjudication gym.

Used when the package is imported as ``server.app`` (the original layout).
HF Spaces deployment runs through ``space_app.py`` instead, which adds
a UI dashboard on top.
"""

from __future__ import annotations

from openenv.core.env_server import create_fastapi_app

try:  # package import
    from ..models import AdjudicatorAction, AdjudicatorObservation
    from .claims_environment import AdjudicationGym
except ImportError:  # flat import (e.g. inside a Spaces image)
    from models import AdjudicatorAction, AdjudicatorObservation  # type: ignore[no-redef]
    from server.claims_environment import AdjudicationGym  # type: ignore[no-redef]


# create_fastapi_app expects the *class* (not an instance) so it can spin
# up a fresh gym per session.
app = create_fastapi_app(AdjudicationGym, AdjudicatorAction, AdjudicatorObservation)


@app.get("/info")
async def get_info() -> dict[str, object]:
    """Static metadata describing the environment surface."""
    return {
        "name": "ClaimSense Adjudication Gym",
        "version": "1.1.0",
        "description": (
            "Multi-step RL environment that simulates an insurance "
            "adjudication desk with partial observability, fraud signals "
            "and bank-transaction verification."
        ),
        "problem_statement": "3.1 - Professional Tasks (World Modeling)",
        "partner_theme": "Scaler AI Labs - Enterprise Workflows",
        "valid_actions": list(AdjudicationGym.VALID_ACTIONS),
        "action_costs_minutes": AdjudicationGym.ACTION_TIME_COSTS,
        "reward_structure": {
            "correct_decision": "+10",
            "wrong_decision": "-5",
            "fraud_caught": "+5",
            "fraud_missed": "-10",
            "query_cost": "-0.1 to -0.5",
            "fast_resolution_bonus": "+1 (≤ 4 steps)",
            "slow_resolution_penalty": "-0.2 per step beyond 8",
        },
    }


@app.get("/scenarios")
async def get_scenarios() -> dict[str, object]:
    """List the canonical case library (handy for debugging)."""
    try:
        from .mock_systems import CASE_LIBRARY
    except ImportError:  # flat layout
        from server.mock_systems import CASE_LIBRARY  # type: ignore[no-redef]

    return {
        "total_scenarios": len(CASE_LIBRARY),
        "scenarios": [
            {
                "claim_id": case.claim_id,
                "claim_type": case.claim_type,
                "complexity": case.complexity,
                "amount": case.claim_amount,
            }
            for case in CASE_LIBRARY
        ],
    }