fix: add server module, pyproject.toml scripts, uv.lock

README.md

@@ -1,3 +1,13 @@
+---
+title: Invoice Exception Handler
+emoji: 🧾
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
 # Invoice Exception Handler — OpenEnv
 
 > An AI agent learning environment that simulates accounts payable exception handling.

app.py

@@ -7,6 +7,7 @@ interactive Gradio UI (for judges and exploration) on port 7860.
 from __future__ import annotations
 
 import json
+import threading
 from typing import Any, Dict, Optional
 
 import gradio as gr
@@ -21,6 +22,7 @@ from env import InvoiceExceptionEnv, Action, ActionType, ALL_TASKS
 # ---------------------------------------------------------------------------
 
 env = InvoiceExceptionEnv(seed=42)
+env_lock = threading.Lock()
 
 # ---------------------------------------------------------------------------
 # FastAPI server
@@ -32,28 +34,32 @@ api = FastAPI(title="Invoice Exception Handler OpenEnv", version="1.0.0")
 @api.post("/reset")
 async def http_reset(body: dict = {}) -> JSONResponse:
     """Reset the environment. Optionally specify task_id."""
-    task_id = body.get("task_id", None)
-    obs = env.reset(task_id)
-    return JSONResponse(obs.model_dump(mode="json"))
+    with env_lock:
+        task_id = body.get("task_id", None)
+        obs = env.reset(task_id)
+        return JSONResponse(obs.model_dump(mode="json"))
 
 
 @api.post("/step")
 async def http_step(body: dict = {}) -> JSONResponse:
     """Execute one action."""
-    result = env.step(body)
-    return JSONResponse(result.model_dump(mode="json"))
+    with env_lock:
+        result = env.step(body)
+        return JSONResponse(result.model_dump(mode="json"))
 
 
 @api.get("/state")
 async def http_state() -> JSONResponse:
     """Return the current state without advancing."""
-    return JSONResponse(env.state().model_dump(mode="json"))
+    with env_lock:
+        return JSONResponse(env.state().model_dump(mode="json"))
 
 
 @api.post("/grade")
 async def http_grade() -> JSONResponse:
     """Grade the current episode."""
-    return JSONResponse(env.grade())
+    with env_lock:
+        return JSONResponse(env.grade())
 
 
 @api.get("/tasks")
@@ -181,7 +187,7 @@ def run_demo(task_name: str) -> str:
             Action.run_check("tax_calculation_verify"),
             Action.cross_check("tax_amount", "invoice", "payment_history"),
             Action.query_internal("finance", "Can you confirm the overpayment on INV-2024-819?"),
-            Action.query_supplier("Please clarify the relationship between INV-2024-891 and INV-2024-819.", "email"),
+            Action.query_supplier("Please clarify the relationship between INV-2024-891 and INV-2024-819.", "phone"),
             Action.apply_rule("partial_approval"),
             Action.apply_rule("credit_note_request"),
             Action.make_decision("partial_approve", "Duplicate detected. Tax error on original. Approve only 3,240 INR correction."),

inference.py

@@ -37,7 +37,14 @@ API_KEY = os.getenv("HF_TOKEN") or os.getenv("API_KEY", "")
 
 SYSTEM_PROMPT = """You are an expert Accounts Payable (AP) analyst handling flagged invoice exceptions.
 
-You have access to a document packet: Purchase Order (PO), Invoice, Goods Receipt Note (GRN), Supplier Master, and an Exception Flag explaining why this invoice was flagged.
+⚠️ CRITICAL RULE: If there is ANY suspicion of bank account fraud, BEC attack, or
+supplier impersonation, you MUST contact the supplier via PHONE (channel="phone"),
+NEVER via email. Emailing a potentially compromised account will contact the fraudster
+and incur a severe penalty.
+
+You have access to a document packet: Purchase Order (PO), Invoice, Goods Receipt Note
+(GRN), Supplier Master, and an Exception Flag explaining why this invoice was flagged.
+The actual document values are provided in each prompt — use them to reason.
 
 You must investigate the root cause, apply business rules, make a decision, and close the case.
 
@@ -56,7 +63,8 @@ You must investigate the root cause, apply business rules, make a decision, and
 **Rules:**
 - Always investigate before making a decision
 - Never approve without running checks first
-- If fraud is suspected, NEVER contact the supplier via email — use phone only
+- Compare document values carefully — look for mismatches between PO, Invoice, GRN, and Supplier Master
+- If bank account or email domain looks suspicious, use phone channel for supplier queries
 - Respond with ONLY a JSON object, no extra text
 """
 
@@ -66,17 +74,60 @@ You must investigate the root cause, apply business rules, make a decision, and
 # ---------------------------------------------------------------------------
 
 def build_prompt(obs, step: int, max_steps: int, history: list) -> str:
-    """Build the user prompt from the current observation state."""
+    """Build the user prompt from the current observation state, including document data."""
+
+    # Build GRN summary safely from the dict-based items_received
+    grn_items = obs.grn.items_received
+    grn_received = sum(item.get("quantity_received", 0) for item in grn_items)
+    grn_pending = sum(item.get("quantity_pending", 0) for item in grn_items)
+    grn_details = "; ".join(
+        f"{item.get('description', 'item')}: {item.get('quantity_received', '?')} received, {item.get('quantity_pending', 0)} pending"
+        for item in grn_items
+    )
+
     lines = [
         f"Step {step} of {max_steps}.",
         f"",
-        f"EXCEPTION FLAG: {obs.exception_flag.flag_code} — {obs.exception_flag.flag_description}",
+        f"EXCEPTION FLAG: {obs.exception_flag.flag_code}",
+        f"{obs.exception_flag.flag_description}",
+        f"",
+        f"=== DOCUMENT SUMMARY ===",
+        f"PO #{obs.purchase_order.po_number} | Total: INR {obs.purchase_order.total_amount:,.2f} | Terms: {obs.purchase_order.payment_terms}",
+        f"PO Line Items:",
+    ]
+    for item in obs.purchase_order.line_items:
+        lines.append(f"  - {item.description}: qty={item.quantity}, unit_price=INR {item.unit_price:,.2f}, total=INR {item.total:,.2f}")
+
+    lines.extend([
+        f"",
+        f"Invoice #{obs.invoice.invoice_number} | Date: {obs.invoice.invoice_date} | Total: INR {obs.invoice.total_amount:,.2f}",
+        f"Invoice Subtotal: INR {obs.invoice.subtotal:,.2f} | Tax ({obs.invoice.tax_rate}%): INR {obs.invoice.tax_amount:,.2f}",
+        f"Invoice Bank Account: {obs.invoice.bank_account} ({obs.invoice.bank_name})",
+        f"Invoice GSTIN: {obs.invoice.supplier_gstin}",
+        f"Invoice Email: {obs.invoice.supplier_email}",
+        f"Invoice Line Items:",
+    ])
+    for item in obs.invoice.line_items:
+        lines.append(f"  - {item.description}: qty={item.quantity}, unit_price=INR {item.unit_price:,.2f}, total=INR {item.total:,.2f}")
+
+    lines.extend([
+        f"",
+        f"GRN #{obs.grn.grn_number} | Date: {obs.grn.receipt_date}",
+        f"GRN Items: {grn_details}",
+        f"GRN Total received: {grn_received}, pending: {grn_pending}",
         f"",
+        f"Supplier Master: {obs.supplier_master.supplier_name} ({obs.supplier_master.supplier_id})",
+        f"Supplier Bank Account: {obs.supplier_master.bank_account} ({obs.supplier_master.bank_name})",
+        f"Supplier GSTIN: {obs.supplier_master.gstin}",
+        f"Supplier Email Domain: {obs.supplier_master.registered_domain}",
+        f"Supplier Phone: {obs.supplier_master.contact_phone}",
+        f"",
+        f"=== AVAILABLE ACTIONS ===",
         f"Available checks: {', '.join(obs.available_checks)}",
         f"Available rules: {', '.join(obs.available_rules)}",
         f"",
         f"Knowledge base:",
-    ]
+    ])
     for entry in obs.knowledge_base:
         lines.append(f"  - {entry}")
 
@@ -85,11 +136,17 @@ def build_prompt(obs, step: int, max_steps: int, history: list) -> str:
     lines.append(f"Case status: {obs.case_status}")
 
     if obs.checks_run:
-        lines.append(f"Checks already run: {', '.join(c.check_name for c in obs.checks_run)}")
+        lines.append(f"Checks already run:")
+        for c in obs.checks_run:
+            lines.append(f"  - {c.check_name}: {'PASSED' if c.passed else 'FAILED'} — {c.detail[:100]}")
     if obs.queries:
-        lines.append(f"Queries made: {', '.join(q.target for q in obs.queries)}")
+        lines.append(f"Queries made:")
+        for q in obs.queries:
+            lines.append(f"  - {q.target} (via {q.channel}): {q.response[:100]}...")
     if obs.inspections:
-        lines.append(f"Fields inspected: {', '.join(f'{i.document}.{i.field}' for i in obs.inspections)}")
+        lines.append(f"Fields inspected:")
+        for i in obs.inspections:
+            lines.append(f"  - {i.document}.{i.field}: {str(i.value)[:100]}")
     if obs.rules_applied:
         lines.append(f"Rules applied: {', '.join(obs.rules_applied)}")
     if obs.decision:
@@ -169,13 +226,14 @@ def parse_action(raw_text: str) -> dict:
 # Task runner
 # ---------------------------------------------------------------------------
 
-def run_task(client: OpenAI, env: InvoiceExceptionEnv, task_id: str, max_steps: int = 20) -> tuple:
+def run_task(client: OpenAI, env: InvoiceExceptionEnv, task_id: str) -> tuple:
     """Run one task episode and return (steps_taken, score, rewards)."""
     rewards = []
 
     print(f"[START] task={task_id} env=invoice-exception-handler model={MODEL_NAME}", flush=True)
 
     obs = env.reset(task_id)
+    max_steps = env._task.max_steps  # read from the task itself
     history = []
 
     for step in range(1, max_steps + 1):

pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.backends._legacy:_Backend"
+
+[project]
+name = "invoice-exception-handler"
+version = "1.0.0"
+description = "An AI agent learning environment simulating accounts payable exception handling."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Yusuf"},
+]
+dependencies = [
+    "pydantic>=2.7",
+    "fastapi>=0.111",
+    "uvicorn>=0.29",
+    "gradio>=4.36",
+    "openai>=1.35",
+    "pyyaml>=6.0",
+    "httpx>=0.27",
+    "python-multipart>=0.0.9",
+    "openenv-core>=0.2.0",
+]
+
+[project.scripts]
+server = "server.app:main"
+
+[tool.setuptools.packages.find]
+include = ["env*", "server*"]

server/__init__.py

@@ -0,0 +1 @@
+"""Server package for OpenEnv deployment."""

server/app.py

@@ -0,0 +1,25 @@
+"""
+Server entry point for OpenEnv deployment.
+
+This module re-exports the FastAPI app from the root app module
+and provides a main() function for the [project.scripts] entry point.
+"""
+from __future__ import annotations
+
+import sys
+import os
+
+# Add project root to path so env/ package is importable
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from app import app  # noqa: E402
+
+
+def main() -> None:
+    """Entry point for the serve script."""
+    import uvicorn
+    uvicorn.run("server.app:app", host="0.0.0.0", port=7860, reload=False)
+
+
+if __name__ == "__main__":
+    main()