docs/IMPLEMENTATION_HANDOFF.md

# EthicsGuard Implementation Handoff

This document is for continuing EthicsGuard development on a new machine with minimal context loss.

It describes:

- what is already implemented
- what was and was not verified on the current machine
- the highest-priority next steps
- the exact commands to run next
- known risks and likely follow-up fixes

This file should be treated as the working handoff state for the next implementation session.

## 1. Current Project State

The repository started nearly empty except for the design docs in `docs/` and an empty `README.md`.

The following implementation has now been added:

- `pyproject.toml`
  - Python package metadata
  - runtime deps for FastAPI, OpenAI client, Pydantic, Uvicorn
  - optional extras for `pytest` and `openenv-core`
- `.gitignore`
- `.dockerignore`
- `.env.example`
- `ethicsguard/`
  - `__init__.py`
  - `models.py`
  - `policy.py`
  - `generator.py`
  - `reward.py`
  - `grader.py`
  - `baselines.py`
  - `env.py`
- `server/`
  - `__init__.py`
  - `environment.py`
  - `app.py`
  - `requirements.txt`
- `inference.py`
- `openenv.yaml`
- `Dockerfile`
- `tests/`
  - `test_generator.py`
  - `test_env.py`
  - `test_grader.py`
  - `test_baselines.py`
- `README.md`

## 2. Implementation Decisions Already Made

These decisions were made intentionally and should not be changed casually.

### 2.1 Skip behavior

`skip` keeps the item in the queue and rotates it to the end.

Reason:

- this matches the original product idea better than removing skipped items
- it preserves the "come back to it later" semantics
- it makes the environment more realistic for triage

Relevant file:

- `ethicsguard/env.py`

### 2.2 Ground-truth visibility

The agent only sees `VisibleQueueItem`, not internal fields such as:

- `ground_truth_action`
- `priority_tier`
- `severity_level`
- `violation_category`

Reason:

- avoids leaking answer labels into the observation

Relevant files:

- `ethicsguard/models.py`
- `ethicsguard/env.py`

### 2.3 Tier and severity are separate

The implementation keeps:

- `priority_tier`
- `severity_level`

as separate concepts.

Reason:

- the source docs distinguish ordering tiers from severity metadata
- collapsing them would make future reward/grader tuning harder

Relevant files:

- `ethicsguard/models.py`
- `ethicsguard/policy.py`
- `ethicsguard/generator.py`

### 2.4 No secrets are stored in repo files

The Hugging Face token is not written into code or config files.

Reason:

- security
- easier transfer across machines

Action still required:

- rotate any token that was previously shared in chat or notes

## 3. What Has Been Verified

### 3.1 Completed verification

The following was successfully verified on the current machine:

- all Python source files can be parsed as valid Python AST
- the repo structure is consistent
- all planned files exist

### 3.2 Verification that could not be completed here

The following was not fully verified on the current machine:

- dependency installation
- runtime imports
- unit tests
- inference execution
- FastAPI server execution
- `openenv validate`
- Docker build

Reason:

- this machine does not have the required Python packages installed
- runtime import failed immediately because `pydantic` was missing
- Docker is not available on this machine

### 3.3 Important note on compile checks

A compile attempt was made, but Windows permission issues prevented `.pyc` file writes inside `__pycache__`.

That failure was environmental, not necessarily a source-code problem.

To work around that, AST parsing was used instead and succeeded.

## 4. Files Most Likely To Need Follow-Up Work

These files are the most likely to need adjustments on the new machine:

- `ethicsguard/env.py`
  - queue semantics
  - end-of-episode reward/grader interactions
  - invalid-action handling
- `ethicsguard/grader.py`
  - score calibration
  - order-compliance logic
  - efficiency interpretation
- `ethicsguard/baselines.py`
  - baseline behavior realism
  - calibration against target thresholds
- `server/app.py`
  - API contract details
  - compatibility with OpenEnv expectations
- `server/environment.py`
  - adapter shape may need to change depending on validator/runtime needs
- `openenv.yaml`
  - may need updates after actual validator feedback
- `inference.py`
  - must be checked carefully against required stdout formatting
  - may need task-loop or action-format changes
- `Dockerfile`
  - may need dependency/install optimization after the first real build
- `README.md`
  - baseline score table still needs real numbers

## 5. Highest-Priority Next Steps

Do these in this order on the new machine.

### Step 1: install and verify dependencies

Goal:

- get the project importing and running locally

### Step 2: run unit tests

Goal:

- catch structural or runtime issues quickly

### Step 3: run generator and environment smoke tests

Goal:

- verify deterministic queue generation
- verify `reset()` and `step()` behavior

### Step 4: run `inference.py`

Goal:

- verify the logging format and end-to-end environment loop

### Step 5: run `openenv validate`

Goal:

- discover the real integration gaps

### Step 6: build Docker

Goal:

- make sure the repo is deployable in the submission path

### Step 7: run baselines and calibrate

Goal:

- produce actual mean/std values
- ensure audit agents are below threshold
- ensure easy-task random agent is not too strong

### Step 8: finalize README

Goal:

- replace placeholder baseline description with real measured results

## 6. Commands To Run On The New Machine

Clone and enter the repo:

```bash
git clone <YOUR_GITHUB_REPO_URL>
cd scaler
```

Check versions:

```bash
python --version
uv --version
docker --version
```

Create env file:

```bash
cp .env.example .env
```

Then edit `.env` and set:

- `HF_TOKEN=...`
- optionally `API_BASE_URL`
- optionally `MODEL_NAME`

Install runtime and dev dependencies:

```bash
uv sync --extra dev
```

If OpenEnv validation is needed:

```bash
uv sync --extra dev --extra openenv
```

Run tests:

```bash
uv run pytest
```

Run generator smoke test:

```bash
uv run python -m ethicsguard.generator
```

Quick environment smoke test:

```bash
uv run python -c "from ethicsguard.env import EthicsGuardEnv; from ethicsguard.models import EthicsGuardAction; import asyncio; env=EthicsGuardEnv('easy',1000); r=asyncio.run(env.reset()); print(len(r.observation.remaining_queue)); first=r.observation.remaining_queue[0].id; r=asyncio.run(env.step(EthicsGuardAction(item_id=first, action_type='skip'))); print(r.done, len(r.observation.remaining_queue))"
```

Run inference:

```bash
uv run python inference.py
```

Run local API:

```bash
uv run uvicorn server.app:app --host 0.0.0.0 --port 7860
```

In another terminal, test endpoints:

```bash
curl -X POST http://localhost:7860/reset -H "Content-Type: application/json" -d "{\"task\":\"easy\",\"seed\":1000}"
curl http://localhost:7860/state
```

Run OpenEnv validator:

```bash
uv run openenv validate
```

Run baselines:

```bash
uv run python -c "from ethicsguard.baselines import run_all_baselines; import pprint; pprint.pp(run_all_baselines())"
```

Build Docker:

```bash
docker build -t ethicsguard .
docker run -p 7860:7860 ethicsguard
```

## 7. Expected Follow-Up Work After First Real Run

These are the most likely tasks after the first full verification pass.

### 7.1 Fix dependency or import issues

Possible causes:

- missing packages
- version mismatches
- FastAPI/OpenAI/Pydantic compatibility issues

### 7.2 Fix test failures

Likely categories:

- reward math mismatches
- grader interpretation mismatches
- queue semantics edge cases

### 7.3 Tighten OpenEnv compatibility

The current `server/` implementation is a practical thin wrapper, but it has not yet been confirmed against the real validator.

Possible follow-up:

- update `openenv.yaml`
- reshape adapter classes
- change endpoint payloads or response types

### 7.4 Tighten inference log compliance

The docs require exact `[START]`, `[STEP]`, and `[END]` formatting.

The current implementation aims to match that, but this must be checked against actual evaluation expectations.

### 7.5 Calibrate baselines

Per the source docs, audit targets matter:

- always-escalate average score should be below `0.35`
- always-approve average score should be below `0.35`
- easy-task random behavior should not be too strong

If these thresholds fail:

- adjust reward shaping
- adjust generator difficulty
- possibly adjust grader strictness

### 7.6 Replace README placeholders with real data

The README currently has structure and explanations, but not final measured baseline numbers.

Still needed:

- baseline score table
- final usage examples after actual validation
- any corrected OpenEnv deployment instructions

## 8. Known Risks

### Risk 1: OpenEnv assumptions may be incomplete

The docs were used to infer parts of the integration, but the actual validator may expect a slightly different format or object model.

### Risk 2: Reward and grader may need tuning

The implementation follows the docs at a high level, but behavior may need adjustment after baseline runs.

### Risk 3: Server layer may be more than needed or shaped incorrectly

The current design uses a separate FastAPI wrapper. This may be correct for deployment, but could need simplification or adaptation after validator feedback.

### Risk 4: Baseline agents are scaffolds, not guaranteed-final benchmark implementations

They are useful for initial calibration, but may need refinement to better represent the intended baselines.

## 9. Recommended Working Rule For The Next Session

When resuming work on the new machine:

1. Do not start by rewriting architecture.
2. First run the commands in Section 6 exactly.
3. Let actual test/runtime/validator failures drive the next edits.
4. Preserve the current package split unless validator feedback forces a change.
5. Update this handoff document if major design changes are made.

## 10. Short Resume Prompt For The Next AI Session

Use something close to this:

> Read `docs/IMPLEMENTATION_HANDOFF.md` first, then inspect the repo and continue EthicsGuard from the current implementation. Start by running the verification commands listed in the handoff document, fix failures in priority order, and do not rewrite the architecture unless validation requires it.