implementation_plan.md

Goal Description

Build the RevOps-Agent, an OpenEnv-compliant reinforcement learning environment that simulates a B2B Revenue Operations (RevOps) inbox. The agent must process inbound sales leads, perform qualification, and correctly route them based on business logic. The environment will support three tasks of increasing difficulty, utilize trajectory-shaped rewards, and be deployed to Hugging Face Spaces via Docker.

User Review Required

The OpenEnv framework allows scaffolding via openenv init. My plan is to manually create the intended project structure under the /home/jyo/Desktop/Projects/OpenEnv/ directory based on the file layout defined in project.md, but we can also use openenv init if you prefer. Please let me know your preference. We must also install the required dependencies (e.g., openenv-core>=0.2.0, fastapi, uvicorn, openai, pydantic) using uv or pip.

Proposed Changes

Configuration

[NEW] openenv.yaml

• Meta information about the OpenEnv environment, task IDs, definitions, and references to models. Required for spec compliance.

API Models

[NEW] models.py

• Pydantic generic models defining RevOpsAction, RevOpsObservation, RevOpsState, and RevOpsReward.
• Action schema: discrete operations like enrich_lead, check_crm, update_lead_score, route_to_rep, merge_with_account, flag_reengagement, disqualify, etc.

Server-side Logic

[NEW] server/data_generator.py

• Generates synthetic leads for the three tasks (Easy, Medium, Hard) without needing external APIs.

[NEW] server/graders.py

• Implementation of the deterministic graders for the three tasks to evaluate the final score (0.0 to 1.0) based on episode trajectories, partial successes, and operational violations.

[NEW] server/environment.py

• Implements the core RevOpsEnvironment(Environment) with state transitions, actions matching, observations, and shaped rewards.

[NEW] server/app.py

• FastAPI server to expose endpoints: standard step, reset, state, plus the additional hackathon endpoints /baseline, /grader, /tasks.

[NEW] server/Dockerfile

• Container metadata to run the environment via port 8000 using uvicorn and python 3.11-slim.

Client-side Logic & Baseline

[NEW] client.py

• RevOpsEnv(HTTPEnvClient) wrapping API calls to interact programmatically with the environment server.

[NEW] baseline.py

• Inference script utilizing the OpenAI API client (via OPENAI_API_KEY) to run an LLM agent through all 3 tasks and output Grader scores.

Miscellanea

[NEW] pyproject.toml

• Package dependencies setup.

[NEW] README.md

• Complete environment documentation covering action/observation spaces, task difficulty, setup instructions, and reasoning scenarios.

Open Questions

Do you have an OpenAI API Key configured locally? It will be required for running the baseline.py script. Do you have uv installed, or should we use pip for dependency management inside a standard venv? Is there a specific HF space repo already prepared that we'll eventually deploy to using openenv push?

Verification Plan

Automated Tests

• Run openenv validate from the terminal to ensure spec and YAML compliance.
• Run docker build -t revops-env -f server/Dockerfile . to verify container build correctness.

Manual Verification

• Start the server uv run server (or standard python -m server.app) and query the endpoints.
• Execute python baseline.py and confirm the baseline LLM achieves the required scores (Task 1: ≥ 0.80, Task 2: ≥ 0.75, Task 3: ≥ 0.70).