Final hackathon submission

Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# Install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy project files
+COPY . .
+
+# Expose the default Hugging Face Space port
+EXPOSE 7860
+
+# Run the FastAPI server
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,30 @@
+# OpenEnv: Blockchain Certificate Administrator
+
+## 🌍 Environment Description & Motivation
+The **Blockchain Certificate Administrator** environment simulates a real-world Web3 operations task. As educational institutions move toward blockchain-based credentialing, automated agents are needed to act as smart contract gatekeepers. 
+
+Instead of a toy game, this environment challenges the agent to process messy, real-world student data, strictly enforce business logic (grades >= 70, valid 42-character 0x wallet addresses), and manage a finite resource (gas balance) to successfully mint certificates without wasting funds.
+
+## 📊 Observation and Action Spaces
+
+### Observation Space
+The agent observes the current state of the blockchain administration queue:
+* `pending_requests` (List): A batch of student requests containing `request_id`, `student_name`, `course_name`, `final_score`, and `wallet_address`.
+* `gas_balance` (Float): The remaining gas in the administrative wallet.
+* `current_step` (Int): The current episode step.
+* `last_error` (String | Null): Feedback if the previous JSON action was malformed.
+
+### Action Space
+The agent must output a strictly typed JSON list of decisions:
+* `decisions` (List): Contains objects with `request_id`, `decision` (strictly "mint" or "reject"), and a brief `reason`.
+
+## 🏆 Task Descriptions & Difficulty
+1. **Easy (`easy_mint`)**: The agent must successfully read the state and execute basic 'mint' actions without formatting errors, achieving at least a 30% success rate.
+2. **Medium (`medium_filter`)**: The agent must accurately filter out invalid requests (e.g., scores < 70, malformed wallets like missing '0x' or wrong length).
+3. **Hard (`hard_gas_management`)**: The agent must process consecutive batches of requests perfectly. Any invalid mints waste gas, which causes early termination and a score of 0.0.
+
+## 🚀 Setup and Usage Instructions
+
+**1. Install Dependencies**
+```bash
+pip install -r requirements.txt

env.py

@@ -0,0 +1,128 @@
+import random
+import string
+from pydantic import BaseModel
+from typing import List, Optional
+
+# Import our schemas from models.py
+from models import (
+    CertificateRequest, ActionDecision, BlockchainObservation,
+    BlockchainAction, BlockchainReward
+)
+
+# OpenEnv typically expects a return object with these fields for step/reset
+class EnvResult(BaseModel):
+    observation: BlockchainObservation
+    reward: float = 0.0
+    done: bool = False
+    info: dict = {}
+
+class BlockchainEnv:
+    def __init__(self, max_steps: int = 5):
+        self.max_steps = max_steps
+        self.current_step = 0
+        self.gas_balance = 0.0
+        self.pending_requests: List[CertificateRequest] = []
+        self.last_error: Optional[str] = None
+        self.gas_cost_per_mint = 0.1
+
+    def _generate_mock_wallet(self, valid: bool) -> str:
+        """Helper to generate realistic wallets to trick the agent."""
+        chars = ''.join(random.choices(string.ascii_lowercase + string.digits, k=40))
+        if valid:
+            return f"0x{chars}"
+        else:
+            # Invalid wallets: might be missing '0x', or wrong length
+            return random.choice([f"0x{chars[:30]}", f"1x{chars}", chars])
+
+    def _generate_requests(self, batch_size: int = 3) -> List[CertificateRequest]:
+        """Generates a mix of valid and invalid requests for the agent to process."""
+        requests = []
+        for i in range(batch_size):
+            is_valid = random.choice([True, False])
+            score = random.uniform(70.0, 99.0) if is_valid else random.uniform(40.0, 69.9)
+            wallet = self._generate_mock_wallet(is_valid)
+            
+            requests.append(CertificateRequest(
+                request_id=f"REQ-{random.randint(1000, 9999)}",
+                student_name=f"Student_{i}",
+                course_name="Intro to Web3",
+                final_score=round(score, 2),
+                wallet_address=wallet
+            ))
+        return requests
+
+    def state(self) -> BlockchainObservation:
+        """Returns the current state without advancing the environment."""
+        return BlockchainObservation(
+            pending_requests=self.pending_requests,
+            gas_balance=round(self.gas_balance, 2),
+            current_step=self.current_step,
+            last_error=self.last_error
+        )
+
+    def reset(self) -> EnvResult:
+        """Resets the environment for a new episode."""
+        self.current_step = 0
+        self.gas_balance = 2.0  # Enough for roughly 20 valid mints
+        self.last_error = None
+        self.pending_requests = self._generate_requests(batch_size=3)
+        
+        return EnvResult(observation=self.state())
+
+    def step(self, action: BlockchainAction) -> EnvResult:
+        """Processes the agent's action, updates state, and calculates reward."""
+        self.current_step += 1
+        self.last_error = None
+        step_reward = 0.0
+        correct_decisions = 0
+        total_requests = len(self.pending_requests)
+
+        # Create a dictionary of actions for easy lookup
+        decision_map = {dec.request_id: dec.decision for dec in action.decisions}
+
+        for req in self.pending_requests:
+            # Ground truth validation logic
+            is_valid_score = req.final_score >= 70.0
+            is_valid_wallet = req.wallet_address.startswith("0x") and len(req.wallet_address) == 42
+            should_mint = is_valid_score and is_valid_wallet
+
+            agent_decision = decision_map.get(req.request_id)
+
+            if agent_decision == "mint":
+                if should_mint and self.gas_balance >= self.gas_cost_per_mint:
+                    self.gas_balance -= self.gas_cost_per_mint
+                    correct_decisions += 1
+                else:
+                    # Penalize for minting invalid certs or trying to mint without gas
+                    step_reward -= 0.5 
+            elif agent_decision == "reject":
+                if not should_mint:
+                    correct_decisions += 1
+                else:
+                    # Penalize for rejecting a valid student
+                    step_reward -= 0.5
+            else:
+                self.last_error = f"Missing or invalid decision for {req.request_id}"
+
+        # Calculate partial reward for this step (max 1.0 per step for perfect batch)
+        if total_requests > 0:
+            step_reward += (correct_decisions / total_requests)
+
+        # Clamp reward to ensure it stays somewhat bounded
+        step_reward = max(0.0, min(1.0, step_reward))
+
+        # Check if episode is done
+        done = self.current_step >= self.max_steps or self.gas_balance <= 0
+
+        # Generate next batch if not done
+        if not done:
+            self.pending_requests = self._generate_requests(batch_size=3)
+        else:
+            self.pending_requests = []
+
+        return EnvResult(
+            observation=self.state(),
+            reward=step_reward,
+            done=done,
+            info={"correct_decisions": correct_decisions, "total_batch": total_requests}
+        )

graders.py

@@ -0,0 +1,53 @@
+from typing import List, Any
+
+# A trajectory is typically passed as a list of dictionaries containing step data
+# e.g., [{"reward": 0.5, "done": False, "info": {"correct_decisions": 2, "total_batch": 3}}, ...]
+
+def _calculate_base_score(trajectory: List[dict]) -> float:
+    """Helper function to calculate the average reward across all steps."""
+    if not trajectory:
+        return 0.0
+    
+    total_reward = sum(step.get("reward", 0.0) for step in trajectory)
+    max_possible_reward = len(trajectory) * 1.0  # 1.0 is max reward per step
+    
+    if max_possible_reward == 0:
+        return 0.0
+        
+    score = total_reward / max_possible_reward
+    return max(0.0, min(1.0, score)) # Clamp between 0.0 and 1.0
+
+def grade_easy(trajectory: List[dict], env_state: Any = None) -> float:
+    """
+    Easy Task: Did the agent manage to get at least a 30% success rate?
+    This proves it understands the basic JSON schema and can make a 'mint' decision.
+    """
+    score = _calculate_base_score(trajectory)
+    # If they hit 30% efficiency, we give them full marks for the easy task
+    return 1.0 if score >= 0.3 else (score / 0.3)
+
+def grade_medium(trajectory: List[dict], env_state: Any = None) -> float:
+    """
+    Medium Task: The agent needs to successfully filter out the bad wallets/scores.
+    Requires at least 60% overall efficiency.
+    """
+    score = _calculate_base_score(trajectory)
+    # Scales up to 1.0 based on hitting the 60% benchmark
+    if score >= 0.6:
+        return 1.0
+    return max(0.0, score)
+
+def grade_hard(trajectory: List[dict], env_state: Any = None) -> float:
+    """
+    Hard Task: Strict grading. 
+    The agent must achieve near perfection (90%+) and not run out of gas 
+    (which would result in a premature 'done' flag with low rewards).
+    """
+    score = _calculate_base_score(trajectory)
+    
+    # If the episode ended early because they wasted gas on bad mints, penalize heavily
+    if len(trajectory) < 5 and trajectory[-1].get("reward", 0.0) < 0:
+        return 0.0
+        
+    # Standard raw score, very hard to get 1.0 unless the agent is flawless
+    return score

inference.py

@@ -0,0 +1,116 @@
+import os
+import json
+import textwrap
+from typing import List, Optional
+from openai import OpenAI
+
+from models import BlockchainAction
+from env import BlockchainEnv
+
+# --- Mandatory Hackathon Variables ---
+API_KEY = os.getenv("HF_TOKEN") or os.getenv("OPENAI_API_KEY")
+API_BASE_URL = os.getenv("API_BASE_URL", "https://api.openai.com/v1")
+MODEL_NAME = os.getenv("MODEL_NAME", "gpt-4o-mini") # Swap to your active model
+TASK_NAME = os.getenv("MY_ENV_TASK", "hard_gas_management")
+BENCHMARK = "blockchain_certificate_admin"
+MAX_STEPS = 5
+
+SYSTEM_PROMPT = textwrap.dedent(
+    """
+    You are a Smart Contract Administrator AI. 
+    You will receive a list of student certificate requests and your current gas balance.
+    Rules:
+    1. Only 'mint' if final_score >= 70 AND wallet_address is exactly 42 chars starting with '0x'.
+    2. Otherwise, 'reject'.
+    3. Minting costs 0.1 gas. Do not mint if gas balance is insufficient.
+    
+    You MUST respond with valid JSON matching this schema exactly:
+    {
+      "decisions": [
+        {"request_id": "REQ-1234", "decision": "mint", "reason": "Valid score and wallet"},
+        {"request_id": "REQ-5678", "decision": "reject", "reason": "Invalid wallet length"}
+      ]
+    }
+    Output ONLY JSON. No markdown formatting, no backticks.
+    """
+).strip()
+
+def log_start(task: str, env: str, model: str) -> None:
+    print(f"[START] task={task} env={env} model={model}", flush=True)
+
+def log_step(step: int, action: str, reward: float, done: bool, error: Optional[str]) -> None:
+    error_val = error if error else "null"
+    print(f"[STEP] step={step} action={action} reward={reward:.2f} done={str(done).lower()} error={error_val}", flush=True)
+
+def log_end(success: bool, steps: int, score: float, rewards: List[float]) -> None:
+    rewards_str = ",".join(f"{r:.2f}" for r in rewards)
+    print(f"[END] success={str(success).lower()} steps={steps} score={score:.3f} rewards={rewards_str}", flush=True)
+
+def main():
+    client = OpenAI(base_url=API_BASE_URL, api_key=API_KEY)
+    env = BlockchainEnv(max_steps=MAX_STEPS)
+    
+    history: List[str] = []
+    rewards: List[float] = []
+    steps_taken = 0
+    score = 0.0
+    
+    log_start(task=TASK_NAME, env=BENCHMARK, model=MODEL_NAME)
+    
+    # Initialize Environment
+    result = env.reset()
+    
+    try:
+        for step in range(1, MAX_STEPS + 1):
+            if result.done:
+                break
+                
+            obs = result.observation
+            user_prompt = f"Pending Requests: {obs.pending_requests}\nGas Balance: {obs.gas_balance}\nStep: {step}"
+            
+            try:
+                # Call LLM
+                completion = client.chat.completions.create(
+                    model=MODEL_NAME,
+                    messages=[
+                        {"role": "system", "content": SYSTEM_PROMPT},
+                        {"role": "user", "content": user_prompt},
+                    ],
+                    temperature=0.0, # Deterministic logic preferred here
+                )
+                raw_response = (completion.choices[0].message.content or "").strip()
+                
+                # Parse JSON and execute action
+                action_dict = json.loads(raw_response)
+                action = BlockchainAction(**action_dict)
+                result = env.step(action)
+                
+                reward = result.reward
+                error = None
+                action_str = json.dumps(action_dict).replace(" ", "") # Compress for STDOUT
+                
+            except Exception as e:
+                # If the LLM hallucinates or JSON parsing fails
+                reward = -1.0 
+                error = str(e).replace("\n", " ")
+                action_str = "invalid_format"
+                result.done = True # End episode on fatal format error
+                
+            rewards.append(reward)
+            steps_taken = step
+            
+            log_step(step=step, action=action_str, reward=reward, done=result.done, error=error)
+            
+            if result.done:
+                break
+                
+        # Calculate final normalized score
+        score = sum(rewards) / steps_taken if steps_taken > 0 else 0.0
+        score = max(0.0, min(1.0, score))
+        success = score >= 0.6
+        
+    finally:
+        log_end(success=success, steps=steps_taken, score=score, rewards=rewards)
+
+if __name__ == "__main__":
+    main()

models.py

@@ -0,0 +1,53 @@
+from pydantic import BaseModel, Field
+from typing import List, Optional, Literal
+
+# --- Nested Models for cleaner structure ---
+class CertificateRequest(BaseModel):
+    request_id: str
+    student_name: str
+    course_name: str
+    final_score: float = Field(description="Score out of 100. Must be >= 70 to pass.")
+    wallet_address: str = Field(description="Must start with '0x' and be exactly 42 characters long.")
+
+class ActionDecision(BaseModel):
+    request_id: str
+    decision: Literal["mint", "reject"] = Field(description="Whether to mint the certificate or reject the request.")
+    reason: str = Field(description="Short explanation of why it was minted or rejected.")
+
+# ---------------------------------------------------------
+# OBSERVATION SPACE (What the agent sees)
+# ---------------------------------------------------------
+class BlockchainObservation(BaseModel):
+    pending_requests: List[CertificateRequest] = Field(
+        description="List of student certificate requests awaiting processing."
+    )
+    gas_balance: float = Field(
+        description="Remaining gas balance in the admin wallet to pay for minting."
+    )
+    current_step: int = Field(
+        description="The current step in the episode."
+    )
+    last_error: Optional[str] = Field(
+        default=None, 
+        description="Error message if the previous action was invalid."
+    )
+
+# ---------------------------------------------------------
+# ACTION SPACE (What the agent can do)
+# ---------------------------------------------------------
+class BlockchainAction(BaseModel):
+    decisions: List[ActionDecision] = Field(
+        description="The agent's decisions for the pending requests."
+    )
+
+# ---------------------------------------------------------
+# REWARD SPACE (How the agent is scored)
+# ---------------------------------------------------------
+class BlockchainReward(BaseModel):
+    score: float = Field(
+        ge=0.0, le=1.0, 
+        description="Normalized score between 0.0 and 1.0 based on correct mints and rejections."
+    )
+    feedback: str = Field(
+        description="Feedback detailing gas wasted, incorrect mints, or missed valid certificates."
+    )

openenv.yaml

@@ -0,0 +1,25 @@
+version: "1.0"
+name: "blockchain_certificate_admin"
+description: "An agent acts as a smart contract administrator, processing student certificates. It must validate scores, check for 42-character 0x wallet addresses, and manage its gas balance to successfully mint."
+
+# Pointers to the Pydantic models we wrote in Step 2
+observation_space: "models:BlockchainObservation"
+action_space: "models:BlockchainAction"
+reward_space: "models:BlockchainReward"
+
+# Pointer to the core engine we wrote in Step 3
+environment: "env:BlockchainEnv"
+
+# The 3 mandatory tasks ranging from Easy to Hard
+tasks:
+  - name: "easy_mint"
+    description: "Mint completely valid certificates without making syntax errors."
+    grader: "graders:grade_easy"
+  
+  - name: "medium_filter"
+    description: "Successfully identify and reject invalid requests (e.g., scores under 70, malformed wallets)."
+    grader: "graders:grade_medium"
+    
+  - name: "hard_gas_management"
+    description: "Process a full batch of complex requests over multiple steps without running out of gas due to penalizations."
+    grader: "graders:grade_hard"

pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "blockchain_certificate_admin"
+version = "1.0.0"
+description = "OpenEnv Blockchain Certificate environment"
+dependencies = [
+    "pydantic>=2.0.0",
+    "openenv-core",
+    "openai",
+    "fastapi",
+    "uvicorn"
+]
+
+[project.scripts]
+server = "server.app:main"

requirements.txt

@@ -0,0 +1,5 @@
+openenv-core
+pydantic>=2.0.0
+openai
+fastapi
+uvicorn

server/app.py

@@ -0,0 +1,40 @@
+import sys
+import os
+import uvicorn
+from fastapi import FastAPI
+
+# Ensure the server can find your root models.py and env.py
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from env import BlockchainEnv
+from models import BlockchainAction
+
+app = FastAPI()
+env = BlockchainEnv()
+
+@app.post("/reset")
+def reset_env():
+    result = env.reset()
+    return {"status": "ok", "observation": result.observation.model_dump()}
+
+@app.post("/step")
+def step_env(action: BlockchainAction):
+    result = env.step(action)
+    return {
+        "observation": result.observation.model_dump(),
+        "reward": result.reward,
+        "done": result.done,
+        "info": result.info
+    }
+
+@app.get("/state")
+def get_state():
+    return env.state().model_dump()
+
+# The entry point the validator is looking for
+# The entry point the validator is looking for
+def main():
+    uvicorn.run("server.app:app", host="0.0.0.0", port=7860)
+
+if __name__ == "__main__":
+    main()