raikarr/pds-ration-env

PDSRationEnv

Environment Description & Motivation

PDSRationEnv simulates a crucial, real-world task performed daily in India — the Public Distribution System (PDS) fair-price-shop reconciliation. At the end of every day, dealers logs are inspected to ensure fair ration distribution for NFSA (National Food Security Act) beneficiaries.

What is the PDS? The Public Distribution System (PDS) is India's national food security network, providing subsidized grain to hundreds of millions of citizens. A "fair price shop dealer" receives a bulk shipment of wheat and distributes it to families based on their official category, keeping logs to prevent fraud.

Why this matters for agents: It is a high-stakes real-world information extraction and arithmetic task. An AI agent is tasked with parsing unstructured dealer logs, computing the correct grain entitlements, detecting and reporting ghost/fraudulent records, and validating matching stock balances, exactly modeling a human audit process. The task is deterministic but requires complex reasoning over both unstructured text and tabular data without explicit instructions in the data layout.

Observation Space (PDSRationObservation)

At each step, the environment provides the agent with:

• —dealer_log (str): A human-readable text log containing beneficiary lists, opening stock, outcomes, and spoilage.
• —raw_beneficiaries (List[Dict]): A structured list of beneficiaries extracted from the log.
• —opening_stock_kg (float): Stock available at the beginning of the day.
• —task_name (str) & task_description (str): Description of the difficulty.
• —step_number (int): The current step index.
• —Feedback fields: Provide step-level partial progress scores (partial_score_beneficiaries, partial_score_stock, partial_score_fraud).

Action Space (PDSRationAction)

The agent must reply with a highly structured JSON dictionary via the API:

• —reconciled_records (List[Dict[str, Any]]): Processed list of each beneficiary, requiring keys: aadhaar_id, category, members, wheat_kg, auth_method, is_ghost, is_duplicate.
• —stock_opening_kg (float): As interpreted by the agent.
• —stock_closing_kg (float): The final grain count after distributions and spoilage.
• —total_distributed_kg (float): Total grain given out to legitimate users.
• —spoilage_kg (float): Identified grain damage.
• —fraud_ids (List[str]): List of Aadhaar cards identified as fraudulent/ghost cards.

Tasks & Difficulty

Reward Function (Grader Formula)

The evaluation is deterministically computed based on exact math and flag catching, with no LLM-as-a-judge subjectivity. The agent receives a final trajectory score calculated as:

score = (0.40 * beneficiaries_correct) + (0.40 * stock_balance_correct) + (0.20 * frauds_detected)

• —beneficiaries_correct: Exactly matching the calculated entitlement (math computation) per beneficiary.
• —stock_balance_correct: Perfect accounting of closing weights, correctly dropping spoilage bases.
• —frauds_detected: Zeroing out ghost-cards' entitlements cleanly and tagging them inside fraud_ids.

Setup and Usage Instructions

Prerequisites: You must have Docker installed locally to test the standalone deployment.

1. 1.Install dependencies:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   pip install uv openenv-core
   openenv validate  # Checks your configuration internally

1. 1.Run the Environment via Docker:

   docker build -t pds_ration_env:latest .
   # Test inference with an LLM of your choice
   export API_BASE_URL="https://api.openai.com/v1"
   export MODEL_NAME="gpt-4o-mini"
   export HF_TOKEN="your-api-key"
   export IMAGE_NAME="pds_ration_env:latest"
   python inference.py

1. 1.Deploy to Hugging Face Spaces:

   openenv push --repo-id your-hf-username/pds-ration-env

Baseline Scores

Running baseline inference on gpt-4o-mini (or gemini-1.5-flash unthrottled):

• —Easy: ~1.000 Score
• —Medium: ~0.940 Score
• —Hard: ~0.830 Score (Spoilage and duplicate complexities often result in minor token math deviations).