Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,88 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local OpenEnv sources)
+# - Standalone environments (with openenv from PyPI/Git)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Ensure git is available (required for installing dependencies from VCS)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=citeGuardian
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already vendored in the build context
+# For standalone builds, openenv will be installed via pyproject.toml
+WORKDIR /app/env
+
+# Ensure Python is installed
+RUN apt-get update && apt-get install -y python3 python3-venv
+
+# Create the virtual environment
+RUN python3 -m venv /app/env/.venv
+
+# If uv.lock exists, use it; otherwise resolve on the fly
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+# Install dependencies using uv sync
+# If uv.lock exists, use it; otherwise resolve on the fly
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+ENV ENABLE_WEB_INTERFACE=true
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

README.md

@@ -1,10 +1,255 @@
 ---
-title: CiteGuardian
-emoji: 👁
-colorFrom: gray
-colorTo: pink
+title: Citeguardian Environment Server
+emoji: 📺
+colorFrom: green
+colorTo: blue
 sdk: docker
 pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Citeguardian Environment
+
+A simple test environment that echoes back messages. Perfect for testing the env APIs as well as demonstrating environment usage patterns.
+
+## Quick Start
+
+The simplest way to use the Citeguardian environment is through the `CiteguardianEnv` class:
+
+```python
+from citeGuardian import CiteguardianAction, CiteguardianEnv
+
+try:
+    # Create environment from Docker image
+    citeGuardianenv = CiteguardianEnv.from_docker_image("citeGuardian-env:latest")
+
+    # Reset
+    result = citeGuardianenv.reset()
+    print(f"Reset: {result.observation.echoed_message}")
+
+    # Send multiple messages
+    messages = ["Hello, World!", "Testing echo", "Final message"]
+
+    for msg in messages:
+        result = citeGuardianenv.step(CiteguardianAction(message=msg))
+        print(f"Sent: '{msg}'")
+        print(f"  → Echoed: '{result.observation.echoed_message}'")
+        print(f"  → Length: {result.observation.message_length}")
+        print(f"  → Reward: {result.reward}")
+
+finally:
+    # Always clean up
+    citeGuardianenv.close()
+```
+
+That's it! The `CiteguardianEnv.from_docker_image()` method handles:
+- Starting the Docker container
+- Waiting for the server to be ready
+- Connecting to the environment
+- Container cleanup when you call `close()`
+
+## Building the Docker Image
+
+Before using the environment, you need to build the Docker image:
+
+```bash
+# From project root
+docker build -t citeGuardian-env:latest -f server/Dockerfile .
+```
+
+## Deploying to Hugging Face Spaces
+
+You can easily deploy your OpenEnv environment to Hugging Face Spaces using the `openenv push` command:
+
+```bash
+# From the environment directory (where openenv.yaml is located)
+openenv push
+
+# Or specify options
+openenv push --namespace my-org --private
+```
+
+The `openenv push` command will:
+1. Validate that the directory is an OpenEnv environment (checks for `openenv.yaml`)
+2. Prepare a custom build for Hugging Face Docker space (enables web interface)
+3. Upload to Hugging Face (ensuring you're logged in)
+
+### Prerequisites
+
+- Authenticate with Hugging Face: The command will prompt for login if not already authenticated
+
+### Options
+
+- `--directory`, `-d`: Directory containing the OpenEnv environment (defaults to current directory)
+- `--repo-id`, `-r`: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)
+- `--base-image`, `-b`: Base Docker image to use (overrides Dockerfile FROM)
+- `--private`: Deploy the space as private (default: public)
+
+### Examples
+
+```bash
+# Push to your personal namespace (defaults to username/env-name from openenv.yaml)
+openenv push
+
+# Push to a specific repository
+openenv push --repo-id my-org/my-env
+
+# Push with a custom base image
+openenv push --base-image ghcr.io/meta-pytorch/openenv-base:latest
+
+# Push as a private space
+openenv push --private
+
+# Combine options
+openenv push --repo-id my-org/my-env --base-image custom-base:latest --private
+```
+
+After deployment, your space will be available at:
+`https://huggingface.co/spaces/<repo-id>`
+
+The deployed space includes:
+- **Web Interface** at `/web` - Interactive UI for exploring the environment
+- **API Documentation** at `/docs` - Full OpenAPI/Swagger interface
+- **Health Check** at `/health` - Container health monitoring
+- **WebSocket** at `/ws` - Persistent session endpoint for low-latency interactions
+
+## Environment Details
+
+### Action
+**CiteguardianAction**: Contains a single field
+- `message` (str) - The message to echo back
+
+### Observation
+**CiteguardianObservation**: Contains the echo response and metadata
+- `echoed_message` (str) - The message echoed back
+- `message_length` (int) - Length of the message
+- `reward` (float) - Reward based on message length (length × 0.1)
+- `done` (bool) - Always False for echo environment
+- `metadata` (dict) - Additional info like step count
+
+### Reward
+The reward is calculated as: `message_length × 0.1`
+- "Hi" → reward: 0.2
+- "Hello, World!" → reward: 1.3
+- Empty message → reward: 0.0
+
+## Advanced Usage
+
+### Connecting to an Existing Server
+
+If you already have a Citeguardian environment server running, you can connect directly:
+
+```python
+from citeGuardian import CiteguardianEnv
+
+# Connect to existing server
+citeGuardianenv = CiteguardianEnv(base_url="<ENV_HTTP_URL_HERE>")
+
+# Use as normal
+result = citeGuardianenv.reset()
+result = citeGuardianenv.step(CiteguardianAction(message="Hello!"))
+```
+
+Note: When connecting to an existing server, `citeGuardianenv.close()` will NOT stop the server.
+
+### Using the Context Manager
+
+The client supports context manager usage for automatic connection management:
+
+```python
+from citeGuardian import CiteguardianAction, CiteguardianEnv
+
+# Connect with context manager (auto-connects and closes)
+with CiteguardianEnv(base_url="http://localhost:8000") as env:
+    result = env.reset()
+    print(f"Reset: {result.observation.echoed_message}")
+    # Multiple steps with low latency
+    for msg in ["Hello", "World", "!"]:
+        result = env.step(CiteguardianAction(message=msg))
+        print(f"Echoed: {result.observation.echoed_message}")
+```
+
+The client uses WebSocket connections for:
+- **Lower latency**: No HTTP connection overhead per request
+- **Persistent session**: Server maintains your environment state
+- **Efficient for episodes**: Better for many sequential steps
+
+### Concurrent WebSocket Sessions
+
+The server supports multiple concurrent WebSocket connections. To enable this,
+modify `server/app.py` to use factory mode:
+
+```python
+# In server/app.py - use factory mode for concurrent sessions
+app = create_app(
+    CiteguardianEnvironment,  # Pass class, not instance
+    CiteguardianAction,
+    CiteguardianObservation,
+    max_concurrent_envs=4,  # Allow 4 concurrent sessions
+)
+```
+
+Then multiple clients can connect simultaneously:
+
+```python
+from citeGuardian import CiteguardianAction, CiteguardianEnv
+from concurrent.futures import ThreadPoolExecutor
+
+def run_episode(client_id: int):
+    with CiteguardianEnv(base_url="http://localhost:8000") as env:
+        result = env.reset()
+        for i in range(10):
+            result = env.step(CiteguardianAction(message=f"Client {client_id}, step {i}"))
+        return client_id, result.observation.message_length
+
+# Run 4 episodes concurrently
+with ThreadPoolExecutor(max_workers=4) as executor:
+    results = list(executor.map(run_episode, range(4)))
+```
+
+## Development & Testing
+
+### Direct Environment Testing
+
+Test the environment logic directly without starting the HTTP server:
+
+```bash
+# From the server directory
+python3 server/citeGuardian_environment.py
+```
+
+This verifies that:
+- Environment resets correctly
+- Step executes actions properly
+- State tracking works
+- Rewards are calculated correctly
+
+### Running Locally
+
+Run the server locally for development:
+
+```bash
+uvicorn server.app:app --reload
+```
+
+## Project Structure
+
+```
+citeGuardian/
+├── .dockerignore         # Docker build exclusions
+├── __init__.py            # Module exports
+├── README.md              # This file
+├── openenv.yaml           # OpenEnv manifest
+├── pyproject.toml         # Project metadata and dependencies
+├── uv.lock                # Locked dependencies (generated)
+├── client.py              # CiteguardianEnv client
+├── models.py              # Action and Observation models
+└── server/
+    ├── __init__.py        # Server module exports
+    ├── citeGuardian_environment.py  # Core environment logic
+    ├── app.py             # FastAPI application (HTTP + WebSocket endpoints)
+    └── Dockerfile         # Container image definition
+```

__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Citeguardian Environment."""
+
+from .client import CiteguardianEnv
+from .models import CiteguardianAction, CiteguardianObservation
+
+__all__ = [
+    "CiteguardianAction",
+    "CiteguardianObservation",
+    "CiteguardianEnv",
+]

client.py

@@ -0,0 +1,75 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Citeguardian Environment Client."""
+
+from typing import Dict
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+from openenv.core.env_server.types import State
+
+from .models import CiteguardianAction, CiteguardianObservation
+
+
+class CiteguardianEnv(
+    EnvClient[CiteguardianAction, CiteguardianObservation, State]
+):
+    """
+    Client for the CiteGuardian Environment.
+
+    Maintains a persistent WebSocket connection to the environment server.
+    Each instance gets its own dedicated session on the server.
+
+    Example:
+        >>> async with CiteguardianEnv(base_url="http://localhost:8000") as client:
+        ...     result = await client.reset()
+        ...     result = await client.step(CiteguardianAction(action_type="SUBMIT"))
+
+    Example with Docker:
+        >>> client = await CiteguardianEnv.from_docker_image("openenv-citeguardian")
+        >>> result = await client.reset()
+        >>> result = await client.step(CiteguardianAction(action_type="GO_TO", section_name="Methods"))
+    """
+
+    def _step_payload(self, action: CiteguardianAction) -> Dict:
+        """Convert CiteguardianAction to JSON payload for the step request."""
+        return action.model_dump(exclude_none=True)
+
+    def _parse_result(self, payload: Dict) -> StepResult[CiteguardianObservation]:
+        """Parse server response into StepResult[CiteguardianObservation]."""
+        obs_data = payload.get("observation", payload)
+        observation = CiteguardianObservation(
+            current_view=obs_data.get("current_view", ""),
+            metadata=obs_data.get("metadata", {}),
+            audit_log=obs_data.get("audit_log", []),
+            tool_result=obs_data.get("tool_result"),
+            message=obs_data.get("message", ""),
+            task_level=obs_data.get("task_level", "A"),
+            done=payload.get("done", obs_data.get("done", False)),
+            reward=payload.get("reward", obs_data.get("reward", 0.0)),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward", obs_data.get("reward", 0.0)),
+            done=payload.get("done", obs_data.get("done", False)),
+        )
+
+    def _parse_state(self, payload: Dict) -> State:
+        """
+        Parse server response into State object.
+
+        Args:
+            payload: JSON response from state request
+
+        Returns:
+            State object with episode_id and step_count
+        """
+        return State(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+        )

inference.py

@@ -0,0 +1,266 @@
+"""
+Inference Script — CiteGuardian
+===================================
+MANDATORY
+- Before submitting, ensure the following variables are defined in your environment:
+    API_BASE_URL        The API endpoint for the LLM.
+    MODEL_NAME          The model identifier to use for inference.
+    HF_TOKEN            Your Hugging Face / API key.
+    LOCAL_IMAGE_NAME    Docker image name (if using from_docker_image())
+
+STDOUT FORMAT
+    [START] task=<task_name> env=<benchmark> model=<model_name>
+    [STEP]  step=<n> action=<action_str> reward=<0.00> done=<true|false> error=<msg|null>
+    [END]   success=<true|false> steps=<n> score=<score> rewards=<r1,r2,...,rn>
+"""
+
+import asyncio
+import json
+import os
+import textwrap
+from typing import List, Optional
+
+from dotenv import load_dotenv
+from openai import OpenAI
+
+load_dotenv()
+
+from citeGuardian import CiteguardianAction, CiteguardianEnv
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+IMAGE_NAME = os.getenv("LOCAL_IMAGE_NAME")
+API_KEY = os.getenv("HF_TOKEN") or os.getenv("API_KEY")
+API_BASE_URL = os.getenv("API_BASE_URL") or "https://router.huggingface.co/v1"
+MODEL_NAME = os.getenv("MODEL_NAME") or "Qwen/Qwen2.5-72B-Instruct"
+TASK_NAME = os.getenv("CITEGUARDIAN_TASK", "audit")
+BENCHMARK = os.getenv("CITEGUARDIAN_BENCHMARK", "citeGuardian")
+
+MAX_STEPS = 30          # enough headroom for a full audit
+TEMPERATURE = 0.2       # low temp for precise reasoning
+MAX_TOKENS = 256
+SUCCESS_SCORE_THRESHOLD = 0.5   # final reward >= 0.5 counts as success
+
+# ---------------------------------------------------------------------------
+# Prompts
+# ---------------------------------------------------------------------------
+SYSTEM_PROMPT = textwrap.dedent("""
+    You are an expert academic peer-reviewer auditing a research paper.
+    You have access to the following tools. Respond with EXACTLY one JSON object per turn.
+
+    TOOLS:
+    {"action_type": "GO_TO", "section_name": "<name>"}
+        Navigate to a section. Use metadata.available_sections to see what exists.
+
+    {"action_type": "SCAN_CITATIONS"}
+        Returns all citation markers (e.g. [1], [2]) found in the current section.
+
+    {"action_type": "COMPARE_VALUES", "val1": "<v1>", "val2": "<v2>"}
+        Checks if two values conflict. Use for numeric mismatches between sections.
+
+    {"action_type": "FLAG_ERROR", "error_type": "<type>", "text_snippet": "<snippet>"}
+        Flag a confirmed error. Types:
+          STRUCTURAL_ERROR      — a mandatory section (Abstract/Introduction/Methods/Results/Discussion/References) is missing
+          ORPHAN_CITATION       — a [N] marker cited in text has no entry in References, OR a References entry is never cited
+          LOGICAL_INCONSISTENCY — a numeric/factual value in one section contradicts another
+
+    {"action_type": "SUBMIT"}
+        End the audit. Call this only after you have flagged all errors you are confident about.
+
+    MANDATORY SECTIONS: Abstract, Introduction, Methods, Results, Discussion, References
+
+    STRATEGY BY TASK LEVEL (shown in observation as task_level):
+
+    Task A — Structural Integrity:
+      1. Use GO_TO on every mandatory section name.
+      2. If a section is NOT in metadata.available_sections, it is missing.
+      3. FLAG_ERROR with error_type=STRUCTURAL_ERROR and text_snippet=<missing section name>.
+      4. SUBMIT immediately after flagging.
+
+    Task B — Citation Synchronization:
+      1. GO_TO each body section (Abstract, Introduction, Methods, Results, Discussion).
+      2. SCAN_CITATIONS in each to collect all [N] markers used in the text.
+      3. GO_TO References and SCAN_CITATIONS to collect all [N] markers defined there.
+      4. Any [N] cited in text but absent from References → FLAG_ERROR ORPHAN_CITATION, snippet="[N]".
+      5. Any [N] in References but never cited in text → FLAG_ERROR ORPHAN_CITATION, snippet="[N]".
+      6. SUBMIT after all orphans are flagged.
+
+    Task C — Factual Contradiction:
+      1. GO_TO Methods, note any numeric claims (subject counts, sample sizes).
+      2. GO_TO Results, note the same numeric claims.
+      3. COMPARE_VALUES with the two numbers.
+      4. If conflict_detected=true → FLAG_ERROR LOGICAL_INCONSISTENCY, snippet must contain the number from Results (e.g. "85").
+      5. SUBMIT after flagging.
+
+    CRITICAL RULES:
+    - False positives cost -0.10 each. Only flag when certain.
+    - Do NOT flag the same error twice.
+    - Do NOT flag a LOGICAL_INCONSISTENCY on Task A or B.
+    - The text_snippet for FLAG_ERROR must contain the key value/marker that identifies the error.
+    - Respond with ONLY a valid JSON object — no markdown, no explanation.
+""").strip()
+
+
+def _obs_to_user_prompt(step: int, obs) -> str:
+    """Convert an observation into a concise user-facing prompt for the LLM."""
+    o = obs.observation if hasattr(obs, "observation") else obs
+    recent_log = o.audit_log[-5:] if o.audit_log else []
+    available = o.metadata.get("available_sections", [])
+    visited = o.metadata.get("visited_sections", [])
+    missing = [s for s in ["Abstract","Introduction","Methods","Results","Discussion","References"] if s not in available]
+
+    return textwrap.dedent(f"""
+        Step: {step}
+        Task level: {o.task_level}  ← use the strategy for this task level
+        Current section: {o.metadata.get('current_section', '?')}
+        Available sections: {available}
+        MISSING mandatory sections: {missing if missing else 'none'}
+        Visited sections: {visited}
+        Citation markers in current view: {o.metadata.get('citation_markers_in_view', [])}
+        All citation markers across paper: {o.metadata.get('all_paper_citations', [])}
+        Flags raised so far: {o.metadata.get('flags_raised', 0)}
+        Last tool result: {json.dumps(o.tool_result)}
+        Environment message: {o.message}
+        Current view:
+        {o.current_view[:800]}
+        Recent audit log:
+        {json.dumps(recent_log, indent=2)}
+        What is your next action?
+    """).strip()
+
+
+# ---------------------------------------------------------------------------
+# Logging helpers
+# ---------------------------------------------------------------------------
+
+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:
+    print(
+        f"[STEP] step={step} action={action} reward={reward:.2f} "
+        f"done={str(done).lower()} error={error or 'null'}",
+        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} "
+        f"score={score:.3f} rewards={rewards_str}",
+        flush=True,
+    )
+
+
+# ---------------------------------------------------------------------------
+# LLM call
+# ---------------------------------------------------------------------------
+
+def get_model_action(
+    client: OpenAI,
+    step: int,
+    obs,
+    messages: List[dict],
+) -> CiteguardianAction:
+    """Ask the LLM for the next action and parse it into a CiteguardianAction."""
+    user_content = _obs_to_user_prompt(step, obs)
+    messages.append({"role": "user", "content": user_content})
+
+    try:
+        completion = client.chat.completions.create(
+            model=MODEL_NAME,
+            messages=messages,
+            temperature=TEMPERATURE,
+            max_tokens=MAX_TOKENS,
+            stream=False,
+        )
+        raw = (completion.choices[0].message.content or "").strip()
+        messages.append({"role": "assistant", "content": raw})
+
+        # Strip markdown fences if present
+        if raw.startswith("```"):
+            raw = raw.split("```")[1]
+            if raw.startswith("json"):
+                raw = raw[4:]
+        data = json.loads(raw)
+        return CiteguardianAction(**data)
+
+    except Exception as exc:
+        print(f"[DEBUG] Model/parse error at step {step}: {exc}", flush=True)
+        # Safe fallback: navigate to first unvisited section or submit
+        return CiteguardianAction(action_type="SUBMIT")
+
+
+# ---------------------------------------------------------------------------
+# Main loop
+# ---------------------------------------------------------------------------
+
+async def main() -> None:
+    client_api = OpenAI(base_url=API_BASE_URL, api_key=API_KEY)
+    env = await CiteguardianEnv.from_docker_image(IMAGE_NAME)
+
+    rewards: List[float] = []
+    steps_taken = 0
+    score = 0.0
+    success = False
+
+    # Persistent conversation history for the LLM
+    messages: List[dict] = [{"role": "system", "content": SYSTEM_PROMPT}]
+
+    log_start(task=TASK_NAME, env=BENCHMARK, model=MODEL_NAME)
+
+    try:
+        result = await env.reset()
+        obs = result.observation if hasattr(result, "observation") else result
+
+        for step in range(1, MAX_STEPS + 1):
+            done = getattr(result, "done", False) or getattr(obs, "done", False)
+            if done:
+                break
+
+            action = get_model_action(client_api, step, result, messages)
+            action_str = action.model_dump_json(exclude_none=True)
+
+            try:
+                result = await env.step(action)
+                obs = result.observation if hasattr(result, "observation") else result
+                reward = float(getattr(result, "reward", None) or getattr(obs, "reward", 0.0))
+                done = getattr(result, "done", False) or getattr(obs, "done", False)
+                error_msg = None
+            except Exception as step_exc:
+                print(f"[DEBUG] Step {step} error: {step_exc}", flush=True)
+                reward = 0.0
+                done = True
+                error_msg = str(step_exc)
+
+            rewards.append(reward)
+            steps_taken = step
+            log_step(step=step, action=action_str, reward=reward, done=done, error=error_msg)
+
+            if done:
+                break
+
+        # Final score: use the observation's reward field from the last step
+        # (cumulative env reward, already in [0,1] after SUBMIT clamp)
+        final_obs = obs if "obs" in dir() else None
+        obs_reward = float(getattr(final_obs, "reward", 0.0)) if final_obs else 0.0
+        score = max(obs_reward, rewards[-1] if rewards else 0.0)
+        score = min(max(score, 0.0), 1.0)
+        success = score >= SUCCESS_SCORE_THRESHOLD
+
+    except Exception as exc:
+        print(f"[DEBUG] Episode error: {exc}", flush=True)
+
+    finally:
+        try:
+            await env.close()
+        except Exception as e:
+            print(f"[DEBUG] env.close() error: {e}", flush=True)
+        log_end(success=success, steps=steps_taken, score=score, rewards=rewards)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

models.py

@@ -0,0 +1,106 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Data models for the CiteGuardian Environment.
+
+CiteGuardian simulates a peer-review / journal-editing workflow where an agent
+audits a research paper for structural omissions, citation orphans, and
+factual contradictions.
+"""
+
+from typing import Any, Literal, Optional
+from openenv.core.env_server.types import Action, Observation
+from pydantic import ConfigDict, Field
+
+
+# ---------------------------------------------------------------------------
+# Action types
+# ---------------------------------------------------------------------------
+
+ActionType = Literal[
+    "GO_TO",
+    "SCAN_CITATIONS",
+    "COMPARE_VALUES",
+    "FLAG_ERROR",
+    "SUBMIT",
+]
+
+ErrorType = Literal[
+    "STRUCTURAL_ERROR",
+    "ORPHAN_CITATION",
+    "LOGICAL_INCONSISTENCY",
+]
+
+
+class CiteguardianAction(Action):
+    """
+    Unified action for the CiteGuardian environment.
+
+    Depending on `action_type`, only the relevant fields are used:
+      - GO_TO          → section_name
+      - SCAN_CITATIONS → (no extra fields)
+      - COMPARE_VALUES → val1, val2
+      - FLAG_ERROR     → error_type, text_snippet
+      - SUBMIT         → (no extra fields)
+    """
+
+    action_type: ActionType = Field(..., description="Which tool the agent is invoking")
+
+    # GO_TO
+    section_name: Optional[str] = Field(
+        default=None, description="Target section name for GO_TO"
+    )
+
+    # COMPARE_VALUES
+    val1: Optional[str] = Field(
+        default=None, description="First value for COMPARE_VALUES"
+    )
+    val2: Optional[str] = Field(
+        default=None, description="Second value for COMPARE_VALUES"
+    )
+
+    # FLAG_ERROR
+    error_type: Optional[ErrorType] = Field(
+        default=None, description="Category of error being flagged"
+    )
+    text_snippet: Optional[str] = Field(
+        default=None, description="Relevant text excerpt supporting the flag"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Observation
+# ---------------------------------------------------------------------------
+
+
+class CiteguardianObservation(Observation):
+    model_config = ConfigDict(extra="ignore")
+
+    """
+    Observation returned after each step.
+
+    current_view   – up to ~1000 chars of the current section text.
+    metadata       – word count, detected citation markers, available sections.
+    audit_log      – list of (step, action_type, detail) tuples already taken.
+    tool_result    – output of SCAN_CITATIONS or COMPARE_VALUES, if applicable.
+    message        – human-readable feedback from the environment.
+    task_level     – 'A', 'B', or 'C' (difficulty).
+    """
+
+    current_view: str = Field(default="", description="Text window of the current section")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="word_count, citation_markers, available_sections",
+    )
+    audit_log: list[dict[str, Any]] = Field(
+        default_factory=list, description="History of actions taken this episode"
+    )
+    tool_result: Optional[Any] = Field(
+        default=None, description="Output of SCAN_CITATIONS or COMPARE_VALUES"
+    )
+    message: str = Field(default="", description="Environment feedback message")
+    task_level: str = Field(default="A", description="Task difficulty: A, B, or C")

openenv.yaml

@@ -0,0 +1,7 @@
+spec_version: 1
+name: citeGuardian
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000
+

openenv_citeGuardian.egg-info/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: openenv-citeGuardian
+Version: 0.1.0
+Summary: Citeguardian environment for OpenEnv
+Requires-Python: >=3.10
+Requires-Dist: openai>=2.30.0
+Requires-Dist: openenv-core[core]>=0.2.2
+Requires-Dist: python-dotenv>=1.2.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"

openenv_citeGuardian.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+README.md
+__init__.py
+client.py
+inference.py
+models.py
+pyproject.toml
+./__init__.py
+./client.py
+./inference.py
+./models.py
+openenv_citeGuardian.egg-info/PKG-INFO
+openenv_citeGuardian.egg-info/SOURCES.txt
+openenv_citeGuardian.egg-info/dependency_links.txt
+openenv_citeGuardian.egg-info/entry_points.txt
+openenv_citeGuardian.egg-info/requires.txt
+openenv_citeGuardian.egg-info/top_level.txt
+server/__init__.py
+server/app.py
+server/citeGuardian_environment.py

openenv_citeGuardian.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openenv_citeGuardian.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+server = citeGuardian.server.app:main

openenv_citeGuardian.egg-info/requires.txt

@@ -0,0 +1,7 @@
+openai>=2.30.0
+openenv-core[core]>=0.2.2
+python-dotenv>=1.2.2
+
+[dev]
+pytest>=8.0.0
+pytest-cov>=4.0.0

openenv_citeGuardian.egg-info/top_level.txt

@@ -0,0 +1 @@
+citeGuardian

pyproject.toml

@@ -0,0 +1,47 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-citeGuardian"
+version = "0.1.0"
+description = "Citeguardian environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    "openai>=2.30.0",
+    # Core OpenEnv runtime (provides FastAPI server + HTTP client types)
+    # install from github
+    # "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git",
+    "openenv-core[core]>=0.2.2",
+    # Environment-specific dependencies
+    # Add all dependencies needed for your environment here
+    # Examples:
+    # "numpy>=1.19.0",
+    # "torch>=2.0.0",
+    # "gymnasium>=0.29.0",
+    # "openspiel>=1.0.0",
+    # "smolagents>=1.22.0,<2",
+    "python-dotenv>=1.2.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m citeGuardian.server.app
+server = "citeGuardian.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["citeGuardian", "citeGuardian.server"]
+package-dir = { "citeGuardian" = ".", "citeGuardian.server" = "server" }

server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Citeguardian environment server components."""
+
+from .citeGuardian_environment import CiteguardianEnvironment
+
+__all__ = ["CiteguardianEnvironment"]

server/app.py

@@ -0,0 +1,84 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the Citeguardian Environment.
+
+This module creates an HTTP server that exposes the CiteguardianEnvironment
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Endpoints:
+    - POST /reset: Reset the environment
+    - POST /step: Execute an action
+    - GET /state: Get current environment state
+    - GET /schema: Get action/observation schemas
+    - WS /ws: WebSocket endpoint for persistent sessions
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    python -m server.app
+"""
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as e:  # pragma: no cover
+    raise ImportError(
+        "openenv is required for the web interface. Install dependencies with '\n    uv sync\n'"
+    ) from e
+
+try:
+    from citeGuardian.models import CiteguardianAction, CiteguardianObservation
+    from .citeGuardian_environment import CiteguardianEnvironment
+except ModuleNotFoundError:
+    from models import CiteguardianAction, CiteguardianObservation
+    from server.citeGuardian_environment import CiteguardianEnvironment
+
+
+# Create the app with web interface and README integration
+app = create_app(
+    CiteguardianEnvironment,
+    CiteguardianAction,
+    CiteguardianObservation,
+    env_name="citeGuardian",
+    max_concurrent_envs=1,  # increase this number to allow more concurrent WebSocket sessions
+)
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        uv run --project . server --port 8001
+        python -m citeGuardian.server.app
+
+    Args:
+        host: Host address to bind to (default: "0.0.0.0")
+        port: Port number to listen on (default: 8000)
+
+    For production deployments, consider using uvicorn directly with
+    multiple workers:
+        uvicorn citeGuardian.server.app:app --workers 4
+    """
+    import uvicorn
+
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--port", type=int, default=8000)
+    args = parser.parse_args()
+    main(port=args.port)

server/citeGuardian_environment.py

@@ -0,0 +1,466 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+CiteGuardian Environment Implementation.
+
+Simulates a professional peer-review / journal-editing workflow.
+The agent audits a research paper for:
+  Task A (Easy)   – Structural omissions (missing mandatory section)
+  Task B (Medium) – Citation orphans (cited but not in References, or vice-versa)
+  Task C (Hard)   – Factual contradictions across sections (numeric mismatches)
+
+Reward structure (cumulative, max 1.0):
+  +0.02  Exploration  – first visit to each required section
+  +0.30  Accuracy     – correct FLAG_ERROR on a seeded mistake
+  -0.10  False Pos.   – FLAG_ERROR where no error exists
+  -0.01  Efficiency   – every step taken
+  +0.10–0.40 Completion – SUBMIT after finding all errors (scales with recall)
+  Clamped to 1.0 on perfect run (100 % recall, 0 false positives).
+"""
+
+import random
+import re
+from uuid import uuid4
+
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import State
+
+try:
+    from ..models import CiteguardianAction, CiteguardianObservation
+except ImportError:
+    from models import CiteguardianAction, CiteguardianObservation
+
+
+# ---------------------------------------------------------------------------
+# Paper templates
+# ---------------------------------------------------------------------------
+
+_TASK_A_PAPER = {
+    "Abstract": (
+        "We present a novel deep-learning approach for protein folding prediction. "
+        "Our model achieves state-of-the-art accuracy on the CASP14 benchmark. [1][3]"
+    ),
+    "Introduction": (
+        "Protein structure prediction has long been a grand challenge in biology. "
+        "Recent advances in transformer architectures [1] have enabled breakthroughs. "
+        "This paper extends the work of Jumper et al. (2021) [2] by incorporating "
+        "multi-scale attention. We recruited 120 domain experts to evaluate outputs."
+    ),
+    "Methods": (
+        "We trained a 48-layer transformer on the UniRef90 database. "
+        "Training used 128 TPU-v4 chips for 14 days. "
+        "Hyperparameters were tuned via Bayesian optimisation [3]. "
+        "We recruited 120 subjects for the human-evaluation study."
+    ),
+    # "Results" section intentionally MISSING — this is the seeded error
+    "Discussion": (
+        "Our approach outperforms prior methods on all benchmarks. "
+        "Limitations include high compute cost and limited generalisation to "
+        "intrinsically disordered proteins."
+    ),
+    "References": (
+        "[1] Vaswani et al. (2017) Attention is All You Need. NeurIPS.\n"
+        "[2] Jumper et al. (2021) Highly accurate protein structure prediction. Nature.\n"
+        "[3] Snoek et al. (2012) Practical Bayesian Optimization. NeurIPS."
+    ),
+}
+
+_TASK_A_ERRORS = [
+    {
+        "id": "err_A1",
+        "error_type": "STRUCTURAL_ERROR",
+        "section": None,  # not section-specific
+        "hint": "Results",  # the missing section name
+        "description": "The mandatory 'Results' section is absent from the paper.",
+    }
+]
+
+# ----
+
+_TASK_B_PAPER = {
+    "Abstract": (
+        "We introduce CiteNet, a citation-graph neural network. "
+        "Experiments on three benchmarks confirm superior performance [1][2]."
+    ),
+    "Introduction": (
+        "Citation networks encode rich relational information [1]. "
+        "Prior work by Kipf & Welling (2017) [2] used GCNs; we extend this "
+        "with dynamic edge weighting. See also the survey by Hamilton et al. [4]."
+        # [4] is cited here but NOT in References — orphan citation
+    ),
+    "Methods": (
+        "Our model stacks three graph-attention layers [3]. "
+        "We use the Adam optimiser with lr=0.001. "
+        "Datasets: Cora, Citeseer, PubMed."
+    ),
+    "Results": (
+        "CiteNet achieves 89.2 % accuracy on Cora, surpassing all baselines. "
+        "Full results are in Table 1."
+    ),
+    "Discussion": (
+        "The dynamic edge weighting is the key contributor to performance gains. "
+        "Future work will explore temporal citation graphs."
+    ),
+    "References": (
+        "[1] Perozzi et al. (2014) DeepWalk. KDD.\n"
+        "[2] Kipf & Welling (2017) Semi-supervised classification with GCNs. ICLR.\n"
+        "[3] Velickovic et al. (2018) Graph Attention Networks. ICLR.\n"
+        # [4] Hamilton et al. intentionally MISSING from References
+        # [5] listed here but never cited in text — extra orphan
+        "[5] Xu et al. (2019) How Powerful are Graph Neural Networks? ICLR."
+    ),
+}
+
+_TASK_B_ERRORS = [
+    {
+        "id": "err_B1",
+        "error_type": "ORPHAN_CITATION",
+        "section": "Introduction",
+        "hint": "[4]",
+        "description": "[4] is cited in Introduction but has no entry in References.",
+    },
+    {
+        "id": "err_B2",
+        "error_type": "ORPHAN_CITATION",
+        "section": "References",
+        "hint": "[5]",
+        "description": "[5] appears in References but is never cited in the paper body.",
+    },
+]
+
+# ----
+
+_TASK_C_PAPER = {
+    "Abstract": (
+        "We conduct a randomised controlled trial on a novel cognitive training "
+        "programme. Results show significant improvement in working memory. [1][2]"
+    ),
+    "Introduction": (
+        "Cognitive decline affects millions worldwide [1]. "
+        "Intervention studies [2] show promise but lack rigorous controls. "
+        "We address this gap with a pre-registered RCT."
+    ),
+    "Methods": (
+        "We recruited 100 subjects aged 60–75 from three urban clinics. "
+        "Participants were randomised 1:1 to treatment and control arms (50 each). "
+        "Primary outcome: digit-span score at 12 weeks."
+    ),
+    "Results": (
+        # Contradiction: Methods says 100 subjects, Results says 85
+        "Table 1 shows data for 85 subjects who completed the 12-week assessment. "
+        "The treatment group (n=44) showed a mean improvement of 2.3 points (p<0.001). "
+        "No adverse events were recorded."
+        # No explanation for the 15-subject drop — this is the seeded error
+    ),
+    "Discussion": (
+        "The significant improvement supports the efficacy of the programme. "
+        "Limitations include the urban-only sample and short follow-up period."
+    ),
+    "References": (
+        "[1] WHO (2023) Global status report on the public health response to dementia.\n"
+        "[2] Smith et al. (2021) Cognitive interventions in older adults. Lancet."
+    ),
+}
+
+_TASK_C_ERRORS = [
+    {
+        "id": "err_C1",
+        "error_type": "LOGICAL_INCONSISTENCY",
+        "section": "Results",
+        "hint": "85",
+        "description": (
+            "Methods states 100 subjects were recruited, but Results reports data "
+            "for only 85 subjects with no explanation for the 15-subject discrepancy."
+        ),
+    }
+]
+
+_TASKS = [
+    ("A", _TASK_A_PAPER, _TASK_A_ERRORS),
+    ("B", _TASK_B_PAPER, _TASK_B_ERRORS),
+    ("C", _TASK_C_PAPER, _TASK_C_ERRORS),
+]
+
+MANDATORY_SECTIONS = ["Abstract", "Introduction", "Methods", "Results", "Discussion", "References"]
+
+# Reward constants
+_EXPLORATION_REWARD = 0.02
+_ACCURACY_REWARD = 0.30
+_FALSE_POSITIVE_PENALTY = -0.10
+_STEP_PENALTY = -0.01
+_MAX_COMPLETION_BONUS = 0.40
+_MIN_COMPLETION_BONUS = 0.10
+_VIEW_MAX_CHARS = 1000
+
+
+def _extract_citations(text: str) -> list[str]:
+    """Return all citation markers like [1], [2], [12] found in text."""
+    return list(dict.fromkeys(re.findall(r"\[\d+\]", text)))
+
+
+class CiteguardianEnvironment(Environment):
+    """
+    CiteGuardian: a peer-review RL environment.
+
+    The agent navigates a research paper, uses audit tools, flags errors,
+    and submits when done. Rewards are cumulative and capped at 1.0.
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self):
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        # These are set properly in reset()
+        self._task_level: str = "A"
+        self._paper: dict[str, str] = {}
+        self._hidden_errors: list[dict] = []
+        self._current_section: str = ""
+        self._visited_sections: set[str] = set()
+        self._flagged_errors: list[dict] = []  # what the agent has flagged
+        self._cumulative_reward: float = 0.0
+        self._done: bool = False
+        self._audit_log: list[dict] = []
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def reset(self) -> CiteguardianObservation:
+        level, paper, errors = random.choice(_TASKS)
+        self._task_level = level
+        self._paper = dict(paper)
+        self._hidden_errors = list(errors)
+        self._current_section = list(self._paper.keys())[0]
+        self._visited_sections = set()
+        self._flagged_errors = []
+        self._cumulative_reward = 0.0
+        self._done = False
+        self._audit_log = []
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+
+        return self._make_observation(
+            message=f"[Task {level}] Paper loaded. Begin your audit. "
+                    f"Available sections: {list(self._paper.keys())}",
+            tool_result=None,
+        )
+
+    def step(self, action: CiteguardianAction) -> CiteguardianObservation:  # type: ignore[override]
+        if self._done:
+            return self._make_observation(
+                message="Episode already finished. Call reset() to start a new one.",
+                tool_result=None,
+            )
+
+        self._state.step_count += 1
+        # Step penalty every action
+        self._cumulative_reward += _STEP_PENALTY
+
+        atype = action.action_type
+        tool_result = None
+        message = ""
+
+        if atype == "GO_TO":
+            message, tool_result = self._handle_go_to(action)
+
+        elif atype == "SCAN_CITATIONS":
+            message, tool_result = self._handle_scan_citations()
+
+        elif atype == "COMPARE_VALUES":
+            message, tool_result = self._handle_compare_values(action)
+
+        elif atype == "FLAG_ERROR":
+            message, tool_result = self._handle_flag_error(action)
+
+        elif atype == "SUBMIT":
+            message, tool_result = self._handle_submit()
+
+        else:
+            message = f"Unknown action_type '{atype}'."
+
+        self._audit_log.append(
+            {"step": self._state.step_count, "action": atype, "detail": message}
+        )
+
+        obs = self._make_observation(message=message, tool_result=tool_result)
+        obs.reward = round(self._cumulative_reward, 4)
+        return obs
+
+    @property
+    def state(self) -> State:
+        return self._state
+
+    # ------------------------------------------------------------------
+    # Action handlers
+    # ------------------------------------------------------------------
+
+    def _handle_go_to(self, action: CiteguardianAction):
+        section = action.section_name or ""
+        if section not in self._paper:
+            return (
+                f"Section '{section}' not found. "
+                f"Available: {list(self._paper.keys())}",
+                None,
+            )
+        self._current_section = section
+        # Exploration reward — first visit only
+        if section not in self._visited_sections:
+            self._visited_sections.add(section)
+            self._cumulative_reward += _EXPLORATION_REWARD
+            extra = f" [+{_EXPLORATION_REWARD} exploration reward]"
+        else:
+            extra = ""
+        return f"Navigated to '{section}'.{extra}", None
+
+    def _handle_scan_citations(self):
+        text = self._paper.get(self._current_section, "")
+        citations = _extract_citations(text)
+        return (
+            f"SCAN_CITATIONS in '{self._current_section}': found {len(citations)} marker(s).",
+            citations,
+        )
+
+    def _handle_compare_values(self, action: CiteguardianAction):
+        v1 = str(action.val1 or "").strip()
+        v2 = str(action.val2 or "").strip()
+        try:
+            n1, n2 = float(v1), float(v2)
+            conflict = abs(n1 - n2) > 1e-9
+        except ValueError:
+            conflict = v1.lower() != v2.lower()
+
+        result = {
+            "val1": v1,
+            "val2": v2,
+            "conflict_detected": conflict,
+        }
+        msg = (
+            f"COMPARE_VALUES: '{v1}' vs '{v2}' → "
+            f"{'CONFLICT DETECTED' if conflict else 'no conflict'}."
+        )
+        return msg, result
+
+    def _handle_flag_error(self, action: CiteguardianAction):
+        etype = action.error_type or ""
+        snippet = action.text_snippet or ""
+
+        # Check against hidden errors
+        matched = self._match_hidden_error(etype, snippet)
+
+        if matched:
+            if matched["id"] in [f["matched_id"] for f in self._flagged_errors if "matched_id" in f]:
+                # Already flagged this one — treat as redundant false positive
+                self._cumulative_reward += _FALSE_POSITIVE_PENALTY
+                return (
+                    f"FLAG_ERROR: '{etype}' — already flagged. "
+                    f"Duplicate flag penalised ({_FALSE_POSITIVE_PENALTY}).",
+                    None,
+                )
+            self._cumulative_reward += _ACCURACY_REWARD
+            self._flagged_errors.append(
+                {"error_type": etype, "snippet": snippet, "matched_id": matched["id"]}
+            )
+            return (
+                f"FLAG_ERROR: '{etype}' — CORRECT. "
+                f"Matched seeded error '{matched['id']}'. "
+                f"[+{_ACCURACY_REWARD} accuracy reward]",
+                None,
+            )
+        else:
+            self._cumulative_reward += _FALSE_POSITIVE_PENALTY
+            self._flagged_errors.append(
+                {"error_type": etype, "snippet": snippet, "matched_id": None}
+            )
+            return (
+                f"FLAG_ERROR: '{etype}' — FALSE POSITIVE. "
+                f"No matching seeded error found. [{_FALSE_POSITIVE_PENALTY} penalty]",
+                None,
+            )
+
+    def _handle_submit(self):
+        self._done = True
+        total_errors = len(self._hidden_errors)
+        correct_flags = len([f for f in self._flagged_errors if f.get("matched_id")])
+        false_positives = len([f for f in self._flagged_errors if not f.get("matched_id")])
+
+        recall = correct_flags / total_errors if total_errors > 0 else 0.0
+
+        # Completion bonus scales linearly with recall
+        bonus = _MIN_COMPLETION_BONUS + recall * (_MAX_COMPLETION_BONUS - _MIN_COMPLETION_BONUS)
+        self._cumulative_reward += bonus
+
+        # Perfect run clamp
+        if recall == 1.0 and false_positives == 0:
+            self._cumulative_reward = 1.0
+            verdict = "PERFECT AUDIT"
+        else:
+            self._cumulative_reward = min(self._cumulative_reward, 1.0)
+            verdict = "AUDIT COMPLETE"
+
+        msg = (
+            f"SUBMIT — {verdict}. "
+            f"Errors found: {correct_flags}/{total_errors}. "
+            f"False positives: {false_positives}. "
+            f"Final reward: {round(self._cumulative_reward, 4)}."
+        )
+        return msg, {
+            "recall": recall,
+            "false_positives": false_positives,
+            "completion_bonus": round(bonus, 4),
+            "final_reward": round(self._cumulative_reward, 4),
+        }
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _match_hidden_error(self, etype: str, snippet: str) -> dict | None:
+        """
+        Try to match a FLAG_ERROR call against the hidden error list.
+        Matching rules:
+          - error_type must match exactly.
+          - snippet must contain the error's hint string (case-insensitive).
+        """
+        for err in self._hidden_errors:
+            if err["error_type"] != etype:
+                continue
+            hint = err.get("hint", "")
+            if hint and hint.lower() not in snippet.lower():
+                continue
+            return err
+        return None
+
+    def _make_observation(self, message: str, tool_result) -> CiteguardianObservation:
+        section_text = self._paper.get(self._current_section, "")
+        view = section_text[:_VIEW_MAX_CHARS]
+
+        # Build full-paper citation index for metadata
+        all_citations: list[str] = []
+        for text in self._paper.values():
+            all_citations.extend(_extract_citations(text))
+        all_citations = list(dict.fromkeys(all_citations))
+
+        metadata = {
+            "current_section": self._current_section,
+            "available_sections": list(self._paper.keys()),
+            "word_count": len(section_text.split()),
+            "citation_markers_in_view": _extract_citations(section_text),
+            "all_paper_citations": all_citations,
+            "visited_sections": list(self._visited_sections),
+            "flags_raised": len(self._flagged_errors),
+            "step": self._state.step_count,
+        }
+
+        return CiteguardianObservation(
+            current_view=view,
+            metadata=metadata,
+            audit_log=list(self._audit_log),
+            tool_result=tool_result,
+            message=message,
+            task_level=self._task_level,
+            done=self._done,
+            reward=round(self._cumulative_reward, 4),
+        )

server/requirements.txt

@@ -0,0 +1,6 @@
+openenv[core]>=0.2.0
+fastapi>=0.115.0
+uvicorn>=0.24.0
+
+
+