Merge pull request #32 from ArshVermaGit/main

feat: CodeLens. v1.0.0 — Production-Grade Suite (Docker, CI/CD, Security & Cloud)

.dockerignore

@@ -0,0 +1,64 @@
+# Python Artifacts
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+*.egg
+MANIFEST
+
+# Node.js / Dashboard (Exclude sources, only keep builds)
+node_modules/
+dashboard/node_modules/
+dashboard/src/
+dashboard/public/
+dashboard/tests/
+dashboard/*.json
+dashboard/*.config.js
+dashboard/*.config.ts
+
+# Virtual Environment
+venv/
+.venv/
+env/
+
+# Testing & Coverage
+tests/
+.pytest_cache/
+coverage.xml
+.coverage
+htmlcov/
+pytest.ini
+
+# Git
+.git/
+.gitignore
+
+# Environment & Private Files
+.env
+.env.*
+*.env.local
+.history/
+Roadmap.html
+
+# Data Persistence (Ensures no local DB leaks into image)
+data/
+codelens.db
+*.sqlite3
+
+# OS Specific
+.DS_Store
+.DS_Store?
+**/._*
+**/.DS_Store
+Thumbs.db
+ehthumbs.db
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo

.env.example

@@ -1,17 +1,25 @@
-# AgentOrg CodeReview — Environment Variables
+# CodeLens. — Configuration Template
 # Copy this file to .env and fill in your values.
 
-# API Configuration
+# API Profile
 APP_HOST=0.0.0.0
 APP_PORT=7860
 APP_ENV=development          # development | production
+APP_PORT=7860
+
+# Security (X-API-Key header)
+API_KEY=changeme             
+API_KEY_ENABLED=false
+
+# Persistence & State
+DATABASE_URL=sqlite+aiosqlite:///./data/codelens.db
+EPISODE_TTL=3600             # Auto-cleanup time in seconds (1hr)
 
-# Security
-API_KEY=changeme             # Required in production; sent as X-API-Key header
-API_KEY_ENABLED=false        # Set to true in production
+# Rate Limiting (Requests per minute)
+RATE_LIMIT_DEFAULT=60
 
 # Leaderboard
-LEADERBOARD_MAX_ENTRIES=10   # Top-N entries to keep per task
+LEADERBOARD_LIMIT=10         # Default entries per task page
 
 # Logging
 LOG_LEVEL=INFO               # DEBUG | INFO | WARNING | ERROR

.github/workflows/ci.yml

@@ -0,0 +1,135 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop, "feat/**", "fix/**", "test/**", "docs/**" ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  # ── Job 1: Lint ────────────────────────────────────────────────
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - run: pip install pylint
+      - run: pylint --fail-under=7 $(git ls-files '*.py') || true
+        # Soft fail: warn but don't block on lint score
+
+  # ── Job 2: Test ────────────────────────────────────────────────
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install dependencies
+        run: pip install -r requirements.txt pytest pytest-cov
+      - name: Run tests with coverage
+        run: |
+          PYTHONPATH=. python -m pytest tests/ -v \
+            --cov=codelens_env \
+            --cov=app \
+            --cov-report=xml \
+            --cov-report=term-missing \
+            --tb=short
+        env:
+          APP_ENV: test
+          TESTING: true
+      - name: Upload coverage report
+        uses: codecov/codecov-action@v4
+        if: matrix.python-version == '3.11'
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false
+
+  # ── Job 3: Validate environment ────────────────────────────────
+  validate:
+    name: Validate All Scenarios
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - run: pip install -r requirements.txt
+      - name: Validate all scenarios reachable
+        run: PYTHONPATH=. python scripts/validate.py
+
+  # ── Job 4: Docker build ────────────────────────────────────────
+  docker-build:
+    name: Docker Build
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - name: Build Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          target: production
+          push: false
+          load: true
+          tags: codelens-env:ci-${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+      - name: Test container health
+        run: |
+          docker run -d --name test-container -p 7860:7860 codelens-env:ci-${{ github.sha }}
+          # Poll the /health endpoint with retries
+          for i in {1..15}; do
+            if curl -s -f http://localhost:7860/health > /dev/null; then
+              echo "Health check passed!"
+              docker stop test-container
+              exit 0
+            fi
+            echo "Waiting for app to start... (retry $i/15)"
+            sleep 2
+          done
+          echo "Health check FAILED. Showing container logs:"
+          docker logs test-container
+          docker stop test-container
+          exit 1
+
+  # ── Job 5: Publish (on main push only) ────────────────────────
+  publish:
+    name: Publish to GHCR
+    runs-on: ubuntu-latest
+    needs: [test, docker-build]
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          target: production
+          push: true
+          tags: |
+            ghcr.io/${{ github.repository }}:latest
+            ghcr.io/${{ github.repository }}:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/pylint.yml

@@ -1,23 +0,0 @@
-name: Pylint
-
-on: [push]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ["3.8", "3.9", "3.10"]
-    steps:
-    - uses: actions/checkout@v4
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v3
-      with:
-        python-version: ${{ matrix.python-version }}
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install pylint
-    - name: Analysing the code with pylint
-      run: |
-        pylint $(git ls-files '*.py')

CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [1.0.0] - 2026-04-05
+
+### Added
+- **Models**: Complete Pydantic v2 models (`TaskId`, `Action`, `Scenario`, `EpisodeResult`, etc.)
+- **Scenarios**: 30 synthetic PR scenarios (10 per task) with realistic Python diffs
+- **Env**: Full episode state machine with noise budget, reward calculation, and history tracking
+- **Graders**: 
+  - `bug_grader.py`: Coverage + precision + severity-weighted scoring
+  - `security_grader.py`: Severity-accuracy-weighted scoring (CRITICAL misclassification penalized)
+  - `arch_grader.py`: Binary issue detection + verdict scoring + detail quality bonus
+- **Config**: Pydantic-settings config with all options documented in `.env.example`
+- **Database**: SQLModel persistence (`EpisodeRecord`, `LeaderboardRecord`, helpers)
+- **API Endpoints**:
+  - `GET /stats`: Aggregate metrics across all recorded episodes
+  - `GET /episodes/{id}/replay`: Full action-by-action replay for completed episodes
+  - `GET /episodes`: List active episodes with metadata
+  - `GET /dashboard`: Web dashboard (dark theme, live leaderboard, WebSocket event feed, stats cards)
+- **Security**:
+  - Rate limiting via `slowapi`: 60 req/min per IP (configurable)
+  - API key authentication: optional, off by default, enabled via `API_KEY_ENABLED=true`
+  - Added `TrustedHostMiddleware` and `Security Headers` (XSS, Frame protection)
+- **Episode Lifecycle**: Auto-cleanup of expired episodes every 5 minutes (default 1hr)
+- **Leaderboard**: Paginated `/leaderboard?limit=N&offset=M&task_id=X`
+- **Baseline Agent**: Full rewrite with argparse CLI, `KeywordAgent` (35 rules), `LLMAgent` (Claude)
+- **Evaluation**: `scripts/evaluate.py` for batch evaluation of all 30 scenarios with summary report and progress bars
+- **Testing**: 155+ parametrized tests with full coverage reporting.
+- **Dockerization**: Multi-stage `builder` + `production` builds with non-root user security.
+- **CI/CD**: Unified 5-job pipeline (`lint`, `test`, `validate`, `docker-build`, `publish` to GHCR).
+- **Branding**: Full rebrand to **CodeLens.**, including signature iconography.
+
+### Fixed
+- **CLI**: Port mismatch in `baseline.py` (8000 → 7860) and added `--url`, `--task`, `--seed` CLI flags.
+- **Crash Fixes**: Leaderboard submit crash after list slicing (captured rank before slice).
+- **WebSocket**: Disconnect now handled with typed `WebSocketDisconnect` and `clients.discard()`.
+- **Metadata**: Incoherent weight structure in `codelens.yaml` replaced with named, accurate pairs.
+- **Security**: Implemented `TrustedHostMiddleware` and hardened headers.
+
+## [0.1.0] - Initial Baseline Fork
+- Initial FastAPI skeleton.
+- In-memory episode storage.
+- Basic Dockerfile and Pylint-only CI.

CONTRIBUTING.md

@@ -0,0 +1,99 @@
+# Contributing to CodeLens
+
+Welcome! We appreciate contributions of all kinds. Here's how to get started.
+
+---
+
+## 🏗️ Development Setup
+
+To get started with local development:
+
+1.  **Clone and Install**:
+    ```bash
+    git clone https://github.com/ArshVermaGit/open-ev-code-handler.git
+    cd open-ev-code-handler
+    python3 -m venv venv && source venv/bin/activate
+    pip install -r requirements.txt
+    ```
+
+2.  **Initialize**:
+    ```bash
+    cp .env.example .env
+    python scripts/migrate.py init
+    ```
+
+3.  **Run Tests**:
+    ```bash
+    PYTHONPATH=. pytest tests/ -v
+    ```
+
+---
+
+## 📝 Adding a New Scenario
+
+Scenarios live in `codelens_env/scenarios.py`. Each scenario needs:
+
+**Step 1**: Choose a task type and next sequential hash (e.g., `bug_011`).
+
+**Step 2**: Write a realistic unified diff. The diff must:
+- Start with `--- a/filename` and `+++ b/filename`
+- Include `@@ -N,M +N,M @@` hunk headers
+- Show a few lines of context (unchanged lines)
+- Include the problematic line prefixed with `+`
+
+Example patch:
+```python
+patch="""--- a/api/users.py
++++ b/api/users.py
+@@ -10,6 +10,6 @@ def get_users(page, size):
+     offset = page * size
+-    return items[offset:offset + size]
++    return items[offset:offset + size - 1]
+"""
+```
+
+**Step 3**: Define at least one `GroundTruthIssue` with:
+- `keywords`: 2+ specific terms an agent body must contain (case-insensitive)
+- `line_number`: the line in the diff where the issue occurs (±3 tolerance for bugs/security, ±5 for arch)
+- `severity`: appropriate level (`critical` only for RCE/auth bypass/data loss)
+
+**Step 4**: Add to `ALL_SCENARIOS` list and verify:
+```bash
+PYTHONPATH=. python -m pytest tests/test_scenarios.py -v
+```
+All 30 (or more) scenarios must pass validation.
+
+---
+
+## 🚀 Pull Request Process
+
+1. Fork the repo and create a branch: `feat/my-feature`, `fix/my-bug`, `test/more-tests`
+2. Make your changes
+3. Run the full test suite: `PYTHONPATH=. python -m pytest tests/ -v`
+4. Run the linter: `pylint codelens_env/ app.py` (target score ≥ 7.0)
+5. Open a PR against `main` with a clear description
+
+---
+
+## 📄 Code Style
+
+- **Type hints** on all public functions and methods
+- **Docstrings** on all public classes and non-trivial functions
+- **pylint score** ≥ 7.0
+- **Line length** ≤ 100 characters
+- No bare `except:` clauses — always specify the exception type
+
+---
+
+## 📝 Commit Message Format
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add rate limiting to /reset endpoint
+fix: correct leaderboard rank calculation after slice
+test: add parametrized tests for all 30 scenarios
+docs: update README quick start commands
+refactor: extract episode cleanup into separate module
+chore: upgrade pydantic to 2.6.1
+```

DEPLOYMENT.md

@@ -0,0 +1,63 @@
+# CodeLens. Deployment Guide (Production)
+
+Follow this guide to deploy **CodeLens. v1.0.0** to the professional cloud. This configuration uses **Vercel** for the frontend, **Render** for the backend, and **Supabase/Neon** for the PostgreSQL database.
+
+---
+
+## 1. 🗄️ Setup the Database (PostgreSQL)
+
+Since SQLite is disk-based and will be deleted at every restart on Render/Vercel, you **must** use a managed PostgreSQL service.
+
+1.  **Go to [Supabase](https://supabase.com)** or [Neon](https://neon.tech).
+2.  **Create a new Project** called "CodeLens".
+3.  **Copy your Connection String** (it should look like `postgres://user:pass@host:5432/dbname`).
+4.  **Important**: Keep this URL safe—it is your `DATABASE_URL`.
+
+---
+
+## 2. 🚀 Setup the Backend (Render)
+
+Render will host your FastAPI API and your Dockerized environment.
+
+1.  **Go to [Render Dashboard](https://dashboard.render.com)**.
+2.  **New -> Web Service** and connect your GitHub repository.
+3.  **Configure**:
+    -   **Runtime**: `Docker`.
+    -   **Environment Variables**:
+        -   `DATABASE_URL`: (Paste your Supabase/Neon URL here).
+        -   `API_KEY_ENABLED`: `true` (highly recommended for production).
+        -   `API_KEY`: A strong secret password.
+        -   `APP_ENV`: `production`.
+4.  **Deploy**: Render will automatically build the `Dockerfile` in the root and start the service.
+5.  **Identify**: Copy your Render URL (e.g., `https://codelens-api.onrender.com`).
+
+---
+
+## 3. 🎨 Setup the Frontend (Vercel)
+
+Vercel will host your React/Vite dashboard.
+
+1.  **Go to [Vercel](https://vercel.com)**.
+2.  **Import** your `dashboard` folder (or the whole repository and set the root directory to `dashboard`).
+3.  **Update `vercel.json`**:
+    -   Open [`dashboard/vercel.json`](file:///Users/arshverma/GitHub/open-ev-code-handler/dashboard/vercel.json).
+    -   Replace `https://YOUR_BACKEND_URL.render.com` with your **real** Render URL.
+4.  **Deploy**: Vercel will build the React application and provide a global dashboard link.
+
+---
+
+## 4. 🤖 Running Remote Evaluations
+
+Once deployed, you can run the benchmark script from your local machine (or any CI) against your **production** instance:
+
+```bash
+python scripts/evaluate.py --url https://your-render-url.com --api-key YOUR_SECRET_KEY
+```
+
+---
+
+> [!CAUTION]
+> **Database Migrations**: When you first deploy to a new PostgreSQL instance, the tables will be empty. The first request to the API will automatically trigger `create_db_and_tables()` via the lifespan hook—no manual SQL is required.
+
+> [!TIP]
+> **Vercel Rewrites**: The `vercel.json` rewrite rule is what allows the frontend to talk to the backend without CORS issues. Ensure the URL is exactly correct.

Dockerfile

@@ -1,20 +1,52 @@
-FROM python:3.11-slim
+# ── Stage 1: Builder ──────────────────────────────────────────
+FROM python:3.11-slim AS builder
 
-WORKDIR /app
+WORKDIR /build
 
-RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
 
+# Install Python dependencies into /build/venv
 COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
+RUN python -m venv /build/venv \
+    && /build/venv/bin/pip install --upgrade pip \
+    && /build/venv/bin/pip install --no-cache-dir -r requirements.txt
 
-COPY . .
+# ── Stage 2: Production ───────────────────────────────────────
+FROM python:3.11-slim AS production
 
-EXPOSE 7860
+# Security: run as non-root user
+RUN useradd --create-home --shell /bin/bash appuser
+
+WORKDIR /app
+
+# Install runtime system dependencies only
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy virtualenv from builder
+COPY --from=builder /build/venv /app/venv
 
-ENV PYTHONPATH=/app
-ENV PORT=7860
+# Copy application code
+COPY --chown=appuser:appuser . .
+
+# Create data directory for SQLite DB
+RUN mkdir -p /app/data && chown appuser:appuser /app/data
+
+# Switch to non-root user
+USER appuser
+
+# Use venv python
+ENV PATH="/app/venv/bin:$PATH"
+ENV PYTHONPATH="/app"
+ENV APP_PORT=7860
+
+EXPOSE 7860
 
-HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
-  CMD curl -f http://localhost:7860/health || exit 1
+HEALTHCHECK --interval=30s --timeout=10s --start-period=15s --retries=3 \
+    CMD curl -f http://localhost:7860/health || exit 1
 
-CMD ["python", "app.py"]
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]

GET_STARTED.md

@@ -5,6 +5,7 @@ Welcome to **CodeLens.**, a production-grade AI agent evaluation environment. Th
 ---
 
 ## 1. Setup your Environment
+
 First, create a virtual environment and install the required Python dependencies.
 
 ```bash
@@ -18,7 +19,8 @@ pip install -r requirements.txt
 ---
 
 ## 2. Initialize the Database
-CodeLens uses SQLite for persistence. You must initialize the database before running the server for the first time.
+
+CodeLens uses SQLite for persistent episode and leaderboard data. You must initialize the database before running the server for the first time.
 
 ```bash
 # Initialize the codelens.db with 30 baseline scenarios
@@ -28,6 +30,7 @@ python scripts/migrate.py init
 ---
 
 ## 3. Launch the System
+
 Start the FastAPI server. This serves both the **Agent API** and the **Interactive Dashboard**.
 
 ```bash
@@ -38,15 +41,17 @@ PYTHONPATH=. python app.py
 ---
 
 ## 4. Open the Dashboard
+
 Once the server is running, you can access the CodeLens Dashboard at:
 
 👉 **[http://localhost:7860/dashboard](http://localhost:7860/dashboard)**
 
-From here, you can see the top-10 leaderboard and monitor live agent evaluations.
+From here, you can see the top-10 leaderboard and monitor real-time agent evaluations via the live event feed.
 
 ---
 
 ## 5. Run your First Evaluation
+
 While keeping the server running in one terminal, open a **new terminal** and run the built-in Keyword agent to see results populated on the dashboard.
 
 ```bash
@@ -60,6 +65,7 @@ python scripts/evaluate.py --agent keyword
 ---
 
 ## 🧪 Running Tests
+
 To verify everything is working perfectly, you can run the full 155-test suite:
 
 ```bash
@@ -68,7 +74,7 @@ PYTHONPATH=. pytest tests/ -v
 
 ---
 
-## \ud83d\udee0 Troubleshooting Common Errors
+## 🛠️ Troubleshooting
 
 ### 1. `ModuleNotFoundError: No module named 'requests'`
 This happens if you haven't activated the virtual environment in your current terminal tab.
@@ -80,7 +86,15 @@ The migration script requires an argument to proceed.
 
 ### 3. Logo not appearing in Dashboard
 If the logo shows a broken image placeholder:
-- **Fix**: Re-run the server with `PYTHONPATH=. python app.py`. The backend now has optimized routing to serve the `logo.svg`.
+- **Fix**: Re-run the server with `PYTHONPATH=. python app.py`. The backend has optimized routing to serve the brand iconography from the root.
+
+---
+
+## 🤝 Next Steps
+
+- **Add Scenarios**: Learn how to author new code review benchmarks in **[CONTRIBUTING.md](CONTRIBUTING.md)**.
+- **Batch Evaluation**: Scale up from single evaluations to full 30-scenario reports using `scripts/evaluate.py`.
+- **Docker Deployment**: Deploy a production-ready container with `docker compose up`.
 
 ---
 

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Arsh Verma, Divyansh Rawat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -2,205 +2,220 @@
   <img src="assets/codelens-brand-v2.svg" width="400" alt="CodeLens." />
 </p>
 
-# CodeLens
+# CodeLens Environment
 
-> **Can an AI agent catch the SQL injection that caused the $100M breach — before it ships?**
+![CI](https://github.com/ArshVermaGit/open-ev-code-handler/actions/workflows/ci.yml/badge.svg)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Docker](https://img.shields.io/badge/docker-ghcr.io-blue)
 
-This environment trains and evaluates agents on realistic Python code reviews grounded in real-world incident patterns. Unlike toy examples, every scenario is calibrated against actual production failure modes: payment mutations without idempotency keys, JWT verification bypassed for "dev convenience," pickle deserialization opening RCE vectors.
+> **AI evaluation environment for benchmarking code review agents on 30 synthetic pull requests.**
 
-[![CodeLens](https://img.shields.io/badge/CodeLens-1.0-blue)](https://huggingface.co/) [![Python 3.11](https://img.shields.io/badge/python-3.11-green)](https://python.org) [![FastAPI](https://img.shields.io/badge/FastAPI-0.109-red)](https://fastapi.tiangolo.com)
+CodeLens is a high-fidelity evaluation environment where AI agents act as senior code reviewers. They analyze pull request diffs to identify bugs, security vulnerabilities, and architectural issues before providing a final verdict.
+
+Designed for researchers and developers building the next generation of AI code assistants, CodeLens provides 30 realistic Python scenarios with ground-truth labels and deterministic, reproducible scoring.
 
 ---
 
-## Tasks
+## 🚀 Quick Start
 
-| Task | Difficulty | Max Steps | Scenarios | Focus |
-|------|-----------|-----------|-----------|-------|
-| `bug_detection` | Easy | 10 | 10 | Off-by-one, race conditions, None deref, type mismatches |
-| `security_audit` | Medium | 15 | 10 | SQL injection, XSS, JWT bypass, pickle RCE, timing attacks |
-| `architectural_review` | Hard | 20 | 10 | N+1 queries, god objects, missing idempotency, SRP violations |
+Get up and running locally in under 2 minutes:
 
----
+```bash
+git clone https://github.com/ArshVermaGit/open-ev-code-handler.git
+cd open-ev-code-handler
+cp .env.example .env
+python3 -m venv venv && source venv/bin/activate
+pip install -r requirements.txt
+python scripts/migrate.py init
+PYTHONPATH=. python app.py
+```
 
-## Observation Space
-
-Each step the agent receives an `Observation` object:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `task_id` | `enum` | `bug_detection`, `security_audit`, or `architectural_review` |
-| `pr_title` | `str` | Pull request title (incident-inspired framing) |
-| `pr_description` | `str` | PR description from the author |
-| `diff` | `str` | Unified diff of the PR |
-| `files_changed` | `list[FileChange]` | Structured list of changed files |
-| `step_count` | `int` | Current step (0-indexed start after reset) |
-| `max_steps` | `int` | Maximum allowed steps for this task |
-| `history` | `list[ActionRecord]` | All actions taken so far this episode |
-| `noise_budget` | `int` | Remaining false-positive allowance (starts at 5) |
-| `service_name` | `str` | Name of the service being reviewed |
-| `service_criticality` | `"low"\|"medium"\|"high"\|"critical"` | How critical this service is to infrastructure |
-| `blast_radius` | `"low"\|"medium"\|"high"\|"critical"` | How many users/systems a bug here would affect |
-| `affected_users` | `int` | Estimated number of users impacted by a failure |
+- **Dashboard**: [http://localhost:7860/dashboard](http://localhost:7860/dashboard)
+- **API Docs**: [http://localhost:7860/docs](http://localhost:7860/docs)
 
 ---
 
-## Action Space
-
-The agent submits one action per step as a typed `Action` object:
+## 📋 Evaluation Tasks
 
-| `action_type` | Required Fields | Description |
-|--------------|----------------|-------------|
-| `flag_issue` | `body`, `filename`, `line_number`, `severity`, `category` | Flag a specific issue in the diff |
-| `approve` | `body`, `verdict="LGTM"` | Approve the PR — no issues or all caught |
-| `request_changes` | `body`, `verdict="REQUEST_CHANGES"` | Block merge — issues must be fixed |
-| `comment` | `body` | Leave a general comment (no reward signal) |
-| `ask_question` | `body` | Ask a clarifying question (no reward signal) |
+CodeLens benchmarks agents across three critical engineering domains:
 
-**Valid severities:** `low`, `medium`, `high`, `critical`  
-**Valid categories:** `bug`, `security`, `architecture`, `performance`, `style`, `design`
+| Task                   | Scenarios | Max Steps | Focus Area                                                                 |
+| ---------------------- | --------- | --------- | -------------------------------------------------------------------------- |
+| `bug_detection`        | 10        | 10        | Off-by-one errors, null dereferences, race conditions, exception handling  |
+| `security_audit`       | 10        | 15        | SQL injection, hardcoded secrets, path traversal, insecure deserialization |
+| `architectural_review` | 10        | 20        | N+1 queries, god classes, blocking async calls, circular imports           |
 
 ---
 
-## Reward Function
+## 📈 Scoring System
 
-Rewards are **incremental per step** (not end-of-episode):
+### Bug Detection
 
-| Event | Reward Delta |
-|-------|-------------|
-| Correctly flag a ground-truth issue | `+0.1` to `+0.7` (depends on full grader recalculation) |
-| False positive flag | `-0.05` (consumes noise budget) |
-| Correct terminal verdict (approve/request_changes) | Final grader score delta |
-| Noise budget exhausted (5 FPs) | Episode terminates |
+Score = `0.4 × coverage + 0.6 × avg_issue_score − 0.1 × false_positive_rate`
+Issues are scored on **keyword accuracy** (50%) and **severity matching** (50%).
 
-**Grader formulas:**
-- **Bug:** `0.7 × recall + 0.3 × precision`
-- **Security:** `0.7 × severity_accuracy + 0.3 × keyword_overlap` (normalized by GT issues)
-- **Architecture:** `0.6 × issue_score + 0.2 × verdict_score + min(0.2, quality_bonus)`
+### Security Audit
 
----
+Score = `avg(per_issue_score)` where each issue = `0.7 × severity_accuracy + 0.3 × keyword_coverage`.
+Severity accuracy is distance-weighted: misclassifying a **CRITICAL** issue as **LOW** incurs a major penalty.
 
-## API Endpoints
+### Architectural Review
 
-```
-POST /reset                    → ResetResponse (episode_id + initial observation)
-POST /step/{episode_id}        → StepResult   (observation, reward, done, info)
-GET  /state/{episode_id}       → StateResult  (step, score, issues_found, done)
-GET  /result/{episode_id}      → EpisodeResult (final_score, issues_found/missed)
-GET  /health                   → {"status": "ok", ...}
-GET  /leaderboard              → top-10 per task
-POST /submit                   → submit agent score to leaderboard
-WS   /ws/events                → real-time step event stream
-```
+Score = `0.6 × detection_rate + 0.2 × verdict_accuracy + 0.2 × detail_quality`.
+Detail quality rewards technical explanations that provide actionable developer feedback.
+
+### 🛑 Noise Budget
+
+Every episode permits **5 false positive credits**. Flagging non-existent code paths spends one credit. Reaching zero terminates the episode immediately to prevent agent hallucination loops.
 
 ---
 
-## Project Structure
+## 🔌 API Reference
 
-```
-.
-├── inference.py              # Root inference script (CodeLens spec required)
-├── app.py                    # FastAPI entry point
-├── codelens.yaml              # CodeLens spec manifest
-├── Dockerfile                # HuggingFace Spaces deployment
-├── requirements.txt
-├── codelens_env/
-│   ├── env.py                # Episode state machine with incremental rewards
-│   ├── models.py             # Pydantic models (Observation, Action, StateResult...)
-│   ├── scenario_bank.py      # 30 scenarios with service metadata
-│   └── graders/
-│       ├── bug_grader.py     # Recall × Precision scoring
-│       ├── security_grader.py # Severity accuracy + keyword overlap
-│       ├── arch_grader.py    # Issue + verdict + quality scoring
-│       └── grader_utils.py   # Line-number match + keyword overlap
-└── tests/
-    ├── test_env.py           # State machine + get_state() + reward tests
-    └── test_graders.py       # Grader unit tests
-```
+| Method | Endpoint                | Auth     | Description                                   |
+| :----- | :---------------------- | :------- | :-------------------------------------------- |
+| `POST` | `/reset`                | Optional | Start a new evaluation episode                |
+| `POST` | `/step/{id}`            | Optional | Submit a review action (flag_issue, approve)  |
+| `GET`  | `/result/{id}`          | Optional | Retrieve final scores and logs for an episode |
+| `GET`  | `/leaderboard`          | None     | Paginated performance rankings                |
+| `POST` | `/submit`               | Optional | Persist an episode result to the leaderboard  |
+| `GET`  | `/stats`                | None     | Aggregate statistics across all agents        |
+| `GET`  | `/episodes/{id}/replay` | Optional | Full event-by-event history replay            |
+| `GET`  | `/dashboard`            | None     | Interactive Real-time Dashboard               |
+| `GET`  | `/health`               | None     | System status and health check                |
+
+Authentication is disabled by default. Set `API_KEY_ENABLED=true` in `.env` for production parity.
 
 ---
 
-## \ud83d\ude80 Quick Start
+## 🐳 Running with Docker
+
+### Production Mode
 
-### 1. Setup Environment
 ```bash
-python3 -m venv venv && source venv/bin/activate
-pip install -r requirements.txt
+docker compose up -d
+# View logs: docker compose logs -f
 ```
 
-### 2. Initialize Database
+### Direct Pull
+
 ```bash
-# This creates the codelens.db with all standard scenarios
-python scripts/migrate.py init
+docker run -p 7860:7860 ghcr.io/ArshVermaGit/open-ev-code-handler:latest
 ```
 
-### 3. Launch CodeLens
+### Automated Testing
+
 ```bash
-PYTHONPATH=. python app.py
-# API and Dashboard are now live at http://localhost:7860/dashboard
+docker compose -f docker-compose.test.yml up
 ```
 
-### 4. Run Evaluation (Baseline)
-In a new terminal:
+---
+
+## 🤖 Baseline Agent & Evaluation
+
+### Single Scenario Trial
+
 ```bash
-python scripts/evaluate.py --agent keyword
+python scripts/baseline.py --task bug_detection --seed 3 --verbose
 ```
 
-```bash
-export API_BASE_URL="https://api.openai.com/v1"
-export MODEL_NAME="gpt-4o"
-export HF_TOKEN="your-openai-key"
-export ENV_URL="http://localhost:7860"
+### Full Benchmark (All 30 Scenarios)
 
-PYTHONPATH=. python inference.py
-```
+```bash
+# Keyword-based baseline
+python scripts/evaluate.py --agent keyword --output results.json
 
-Output format:
-```
-[START] task=bug_detection env=http://localhost:7860 model=gpt-4o
-[STEP] step=1 action='flag_issue' reward=0.7000 done=False error=None
-[STEP] step=2 action='approve' reward=0.0000 done=True error=None
-[END] success=True steps=2 score=0.7000 rewards=[0.7, 0.0]
+# LLM-powered reviewer (e.g. Claude)
+python scripts/evaluate.py --agent llm --api-key $ANTHROPIC_API_KEY
 ```
 
 ---
 
-## Baseline Scores
+## 🧠 Writing Your Own Agent
+
+CodeLens is designed to be agent-agnostic. Use standard HTTP requests to build your reviewer:
+
+```python
+import requests
+
+API = "http://localhost:7860"
+
+# Start new episode
+resp = requests.post(f"{API}/reset", json={"task_id": "bug_detection", "seed": 0})
+episode_id = resp.json()["episode_id"]
 
-*Run `python inference.py` after starting the server to reproduce.*
+done = False
+while not done:
+    # Your agent logic analyzes the diff
+    action = {
+        "action_type": "flag_issue",
+        "body": "Identified a vulnerability line 14",
+        "filename": "api/search.py",
+        "line_number": 14,
+        "severity": "critical",
+        "category": "security"
+    }
 
-| Task | Model | Avg Score | Success Rate |
-|------|-------|-----------|-------------|
-| `bug_detection` | gpt-3.5-turbo | ~0.52 | ~60% |
-| `security_audit` | gpt-3.5-turbo | ~0.38 | ~40% |
-| `architectural_review` | gpt-3.5-turbo | ~0.28 | ~30% |
-| `bug_detection` | gpt-4o | ~0.74 | ~80% |
-| `security_audit` | gpt-4o | ~0.61 | ~70% |
-| `architectural_review` | gpt-4o | ~0.45 | ~50% |
+    result = requests.post(f"{API}/step/{episode_id}", json=action).json()
+    done = result["done"]
 
-> `architectural_review` is intentionally hard — frontier models score below 0.5 on average due to the need to reason about blast radius, idempotency, and service encapsulation simultaneously.
+# Get final results
+final = requests.get(f"{API}/result/{episode_id}").json()
+print(f"Final Score: {final['final_score']}")
+```
+
+---
+
+## 📂 Project Structure
+
+```text
+open-ev-code-handler/
+├── app.py                      # FastAPI application (9 endpoints)
+├── codelens_env/               # Core evaluation logic
+│   ├── database.py             # SQLModel persistence layer
+│   ├── env.py                  # Episode state machine
+│   ├── models.py               # Pydantic v2 data models
+│   ├── scenarios.py            # 30 Synthetic PR scenarios
+│   └── graders/                # Grader implementations (Bug, Sec, Arch)
+├── scripts/                    # CLI tools (baseline, evaluate, migrate)
+├── static/                     # Compiled dashboard assets
+├── tests/                      # 155+ Parametrized tests
+├── Dockerfile                  # Multi-stage, non-root build
+├── docker-compose.yml          # Production orchestration
+└── codelens.yaml               # CodeLens v2 specification
+```
 
 ---
 
-## Docker / HuggingFace Spaces
+## 🛠️ Development
 
 ```bash
-docker build -t codelens-env .
-docker run -p 7860:7860 \
-  -e PYTHONPATH=/app \
-  codelens-env
+# Setup
+python -m venv venv && source venv/bin/activate
+pip install -r requirements.txt
+
+# Automated Tests
+PYTHONPATH=. pytest tests/ -v --cov=codelens_env
+
+# Linter Check
+pylint codelens_env/ app.py
+
+# Scenario Sanity Check
+PYTHONPATH=. python scripts/validate.py
 ```
 
-The server starts automatically via `python app.py`.
+## 👥 Authors & Maintainers
+
+CodeLens is authored and maintained by:
+
+- **Arsh Verma** — [GitHub](https://github.com/ArshVermaGit)
+- **Divyansh Rawat** — [GitHub](https://github.com/DsThakurRawat)
 
 ---
 
-## Features
+## 📄 Contributing & License
+
+Please see **[CONTRIBUTING.md](CONTRIBUTING.md)** for details on authoring new scenarios and submission standards.
 
-- **30 Realistic Scenarios** — Incident-inspired PR titles tied to real service names, affected user counts, and blast radius labels
-- **Deterministic Grading** — MoE-style confidence-weighted matching with explainable per-issue scoring rubrics  
-- **Incremental Rewards** — Step-level reward signals (`+δ` per correct flag, `-0.05` per FP) enable proper RL training
-- **Noise Budget** — Penalizes false positives to prevent reward gaming; episode terminates at 5 FPs
-- **Blast Radius Context** — `affected_users`, `service_criticality`, `blast_radius` in every observation
-- **WebSocket Stream** — Real-time step event broadcasting on `/ws/events`
-- **Leaderboard** — In-memory top-10 tracking per task
-- **Full CodeLens Spec** — `/reset`, `/step`, `/state`, `/result` + `[START]`/`[STEP]`/`[END]` stdout format
+This project is licensed under the **[MIT License](LICENSE)**.

app.py

@@ -42,9 +42,13 @@ logger = logging.getLogger("codelens_env")
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     # Startup
-    create_db_and_tables()
+    if not os.getenv("TESTING"):
+        create_db_and_tables()
+        logger.info(f"CodeLens API started — DB at {settings.db_path}")
+    else:
+        logger.info("CodeLens API running in TESTING mode — DB initialization skipped")
+
     cleanup_task = asyncio.create_task(cleanup_expired_episodes())
-    logger.info(f"CodeLens API started — DB at {settings.db_path}")
     
     yield
     
@@ -68,7 +72,20 @@ app = FastAPI(
     lifespan=lifespan,
 )
 
-# ── CORS Middleware ───────────────────────────────────────────────────────────
+# ── Security & Middleware ──────────────────────────────────────────────────
+from fastapi.middleware.trustedhost import TrustedHostMiddleware
+from uvicorn.middleware.proxy_headers import ProxyHeadersMiddleware
+
+# 1. Trusted Host (Prevent Host-header injection)
+app.add_middleware(
+    TrustedHostMiddleware, 
+    allowed_hosts=["*"] if settings.app_env in ("development", "test") else [f"localhost", "127.0.0.1", "*.github.io", "testserver"] 
+)
+
+# 2. Proxy Headers (Support Docker/Reverse-proxy)
+app.add_middleware(ProxyHeadersMiddleware, trusted_hosts="*")
+
+# 3. CORS
 app.add_middleware(
     CORSMiddleware,
     allow_origins=["*"] if settings.app_env == "development" else [f"http://localhost:{settings.app_port}"],
@@ -77,7 +94,18 @@ app.add_middleware(
     allow_headers=["*"],
 )
 
-# ── Rate Limiting ─────────────────────────────────────────────────────────────
+# 4. Security Headers Middleware
+@app.middleware("http")
+async def add_security_headers(request: Request, call_next):
+    response = await call_next(request)
+    response.headers["X-Content-Type-Options"] = "nosniff"
+    response.headers["X-Frame-Options"] = "DENY"
+    response.headers["X-XSS-Protection"] = "1; mode=block"
+    response.headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains"
+    response.headers["Content-Security-Policy"] = "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self' ws: wss:;"
+    return response
+
+# 5. Rate Limiting
 limiter = Limiter(key_func=get_remote_address, default_limits=[f"{settings.rate_limit_per_minute}/minute"])
 app.state.limiter = limiter
 app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)

codelens.yaml

@@ -1,54 +1,77 @@
-version: "1.0"
-name: "codelens-codelens"
+version: "1.0.0"
+name: "agentorg-codereview"
+owners: ["Arsh Verma", "Divyansh Rawat"]
 description: >
-  AI Senior Code Reviewer evaluation environment — trains agents to detect bugs,
-  security vulnerabilities, and architectural issues in realistic Python PRs.
-  Grounded in real-world incident patterns (payment systems, auth layers, microservices).
+  AI Senior Code Reviewer evaluation environment for CodeLens.
+  Benchmarks agents on 30 synthetic pull requests across Bug Detection,
+  Security Audit, and Architectural Review tasks.
+  
 entry_point: "app:app"
-base_url: "http://localhost:7860"
-api_version: "v1"
-
-tags:
-  - codelens
-  - code-review
-  - security
-  - software-engineering
+dashboard: "/dashboard"
+api_docs: "/docs"
 
 tasks:
   - id: "bug_detection"
-    difficulty: easy
+    description: "Identify logical errors and edge cases in Python code"
     max_steps: 10
     scenarios: 10
-    description: >
-      Identify logical errors, off-by-one bugs, mutable default arguments,
-      None dereferences, race conditions, and type mismatches in Python snippets.
-      Agents must FLAG issues with correct category/severity and submit a final verdict.
+    difficulty_distribution:
+      easy: 2
+      medium: 6
+      hard: 2
 
   - id: "security_audit"
-    difficulty: medium
+    description: "Detect OWASP Top 10 vulnerabilities in Python code"
     max_steps: 15
     scenarios: 10
-    description: >
-      Detect OWASP Top-10 vulnerabilities: SQL injection, XSS, hardcoded secrets,
-      JWT bypass, insecure deserialization (pickle RCE), path traversal, timing attacks,
-      CORS misconfiguration, and missing rate limits in a payment-adjacent Python codebase.
+    difficulty_distribution:
+      easy: 1
+      medium: 7
+      hard: 2
 
   - id: "architectural_review"
-    difficulty: hard
+    description: "Evaluate design patterns, coupling, and system constraints"
     max_steps: 20
     scenarios: 10
-    description: >
-      Evaluate system design quality: SRP violations, direct DB access bypassing API layers,
-      synchronous blocking calls in event loops, missing idempotency keys on payment mutations,
-      N+1 query patterns, god object anti-patterns, and shared mutable state between microservices.
-      Requires reasoning about blast radius and service criticality in addition to code issues.
+    difficulty_distribution:
+      easy: 0
+      medium: 7
+      hard: 3
+
+environment:
+  noise_budget: 5
+  line_tolerance_bug: 3
+  line_tolerance_arch: 5
+  keyword_match: "any"       # agent body must contain ANY listed keyword
+  case_sensitive: false
 
 grading:
   type: "deterministic"
-  issue_matching:
+  
+  bug_detection:
     coverage_weight: 0.4
-    precision_weight: 0.6
-  quality_scoring:
-    severity_weight: 0.7
-    keyword_weight: 0.3
+    avg_issue_score_weight: 0.6
+    issue_score:
+      keyword_weight: 0.5
+      severity_weight: 0.5
+    false_positive_penalty: 0.1
+
+  security_audit:
+    formula: "avg_issue_score"
+    issue_score:
+      severity_weight: 0.7
+      keyword_weight: 0.3
+    severity_scale:
+      critical: 4
+      high: 3
+      medium: 2
+      low: 1
+      info: 0
+    severity_penalty_per_level: 0.3
 
+  architectural_review:
+    issue_detection_weight: 0.6
+    verdict_weight: 0.2
+    quality_weight: 0.2
+    quality_min_body_length: 20
+    quality_max_body_length: 200

codelens_env/config.py

@@ -1,4 +1,5 @@
 from functools import lru_cache
+from typing import Optional
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 class Settings(BaseSettings):
@@ -19,6 +20,7 @@ class Settings(BaseSettings):
     rate_limit_per_minute: int = 60        # requests per minute per IP
     
     # Persistence
+    database_url: Optional[str] = None
     db_path: str = "./data/codelens.db"
     db_echo: bool = False    # Set True to log all SQL queries
 

codelens_env/database.py

@@ -7,6 +7,20 @@ from codelens_env.models import EpisodeResult, TaskId
 
 def get_engine():
     settings = get_settings()
+    
+    if settings.database_url:
+        # Support Render/Heroku 'postgres://' URLs by converting to 'postgresql://'
+        url = settings.database_url
+        if url.startswith("postgres://"):
+            url = url.replace("postgres://", "postgresql://", 1)
+        
+        return create_engine(
+            url,
+            echo=settings.db_echo,
+            pool_pre_ping=True,  # Ensure connections are alive
+        )
+    
+    # Fallback to local SQLite
     Path(settings.db_path).parent.mkdir(parents=True, exist_ok=True)
     return create_engine(
         f"sqlite:///{settings.db_path}",

dashboard/package.json

@@ -1,7 +1,9 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "codelens-dashboard",
+  "version": "1.0.0",
   "private": true,
-  "version": "0.1.0",
+  "author": "Arsh Verma, Divyansh Rawat",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -10,21 +12,21 @@
   },
   "dependencies": {
     "@fontsource/inter": "^5.1.0",
-    "@tanstack/react-query": "^5.0.0",
-    "clsx": "^2.1.0",
+    "@tanstack/react-query": "^5.62.0",
+    "clsx": "^2.1.1",
     "lucide-react": "^0.475.0",
-    "react": "^18.3.0",
-    "react-dom": "^18.3.0",
-    "zustand": "^5.0.0"
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "zustand": "^5.0.3"
   },
   "devDependencies": {
-    "@tailwindcss/vite": "^4.1.0",
-    "@types/node": "^25.5.2",
-    "@types/react": "^18.3.0",
-    "@types/react-dom": "^18.3.0",
-    "@vitejs/plugin-react": "^4.3.0",
-    "tailwindcss": "^4.1.0",
+    "@tailwindcss/vite": "^4.0.0",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "tailwindcss": "^4.0.0",
     "typescript": "^5.7.0",
-    "vite": "^6.2.0"
+    "vite": "^6.0.0"
   }
 }

dashboard/tsconfig.json

@@ -1,16 +1,28 @@
 {
+  "$schema": "https://json.schemastore.org/tsconfig",
   "compilerOptions": {
-    "target": "ES2022",
-    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "composite": true,
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
     "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
     "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
     "jsx": "react-jsx",
+
+    /* Linting */
     "strict": true,
     "noUnusedLocals": true,
     "noUnusedParameters": true,
-    "noFallthroughCasesInSwitch": true,
-    "skipLibCheck": true,
-    "types": ["vite/client", "node"]
+    "noFallthroughCasesInSwitch": true
   },
   "include": ["src"]
 }

dashboard/vercel.json

@@ -0,0 +1,15 @@
+{
+  "rewrites": [
+    {
+      "source": "/api/(.*)",
+      "destination": "https://YOUR_BACKEND_URL.render.com/$1"
+    },
+    {
+      "source": "/ws/(.*)",
+      "destination": "wss://YOUR_BACKEND_URL.render.com/ws/$1"
+    }
+  ],
+  "framework": "vite",
+  "buildCommand": "npm run build",
+  "outputDirectory": "dist"
+}

docker-compose.test.yml

@@ -0,0 +1,15 @@
+version: "3.9"
+
+services:
+  test:
+    build:
+      context: .
+      target: builder
+    container_name: codelens-test
+    command: >
+      sh -c "/build/venv/bin/pip install pytest pytest-cov &&
+             PYTHONPATH=/app /build/venv/bin/python -m pytest tests/ -v --tb=short"
+    volumes:
+      - .:/app
+    environment:
+      - APP_ENV=test

docker-compose.yml

@@ -0,0 +1,28 @@
+version: "3.9"
+
+services:
+  api:
+    build:
+      context: .
+      target: production
+    container_name: codelens-api
+    ports:
+      - "${APP_PORT:-7860}:7860"
+    env_file:
+      - .env
+    environment:
+      - APP_ENV=${APP_ENV:-development}
+      - LOG_LEVEL=${LOG_LEVEL:-INFO}
+    volumes:
+      - codelens-data:/app/data
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:7860/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 15s
+
+volumes:
+  codelens-data:
+    driver: local

requirements.txt

@@ -1,15 +1,16 @@
-fastapi>=0.109.0
-uvicorn>=0.27.0
-pydantic>=2.6.1
+fastapi>=0.115.0
+uvicorn>=0.30.0
+pydantic>=2.10.0
 pytest>=8.0.0
-requests>=2.31.0
-websockets>=12.0
-httpx<0.28.0
-openai>=1.0.0
-pydantic-settings==2.2.1
-slowapi==0.1.9
-python-dotenv==1.0.1
-sqlmodel==0.0.16
-aiosqlite==0.20.0
-pytest-cov==4.1.0
-aiofiles==23.2.1
+requests>=2.32.0
+websockets>=13.0
+httpx>=0.28.0
+openai>=1.50.0
+pydantic-settings>=2.6.0
+slowapi>=0.1.9
+python-dotenv>=1.0.1
+sqlmodel>=0.0.22
+aiosqlite>=0.20.0
+pytest-cov>=5.0.0
+aiofiles>=24.0.0
+PyYAML>=6.0.1

results.json

@@ -1,6 +1,6 @@
 [
   {
-    "episode_id": "0d8d0a22-2a81-48a1-8dbe-c9662da7dc2b",
+    "episode_id": "27c65a00-9315-4d7d-b457-f8d64b0da466",
     "task_id": "bug_detection",
     "seed": 0,
     "final_score": 0.0,
@@ -9,10 +9,10 @@
     "issues_total": 1,
     "noise_penalties": 0,
     "terminated_reason": "terminal_action",
-    "duration_seconds": 0.03
+    "duration_seconds": 0.02
   },
   {
-    "episode_id": "6ddc5a56-86c1-43f2-8839-b6ad9eac2ad9",
+    "episode_id": "8bdcee56-8a56-4ec8-88fc-a70e78ab48f2",
     "task_id": "bug_detection",
     "seed": 1,
     "final_score": 0.0,
@@ -24,7 +24,7 @@
     "duration_seconds": 0.02
   },
   {
-    "episode_id": "df00496e-0e19-4049-82d9-6a0f2a1e8f2a",
+    "episode_id": "d3dcda88-ce7e-4965-9409-4e97c98cf444",
     "task_id": "bug_detection",
     "seed": 2,
     "final_score": 0.9167,
@@ -33,10 +33,10 @@
     "issues_total": 1,
     "noise_penalties": 5,
     "terminated_reason": "noise_exhausted",
-    "duration_seconds": 0.06
+    "duration_seconds": 0.04
   },
   {
-    "episode_id": "26837a97-d3ad-4fd7-8e74-d0d713b9b137",
+    "episode_id": "822dfb7d-d67b-4dc9-9cfe-866665a9e5b9",
     "task_id": "bug_detection",
     "seed": 3,
     "final_score": 0.9167,
@@ -45,10 +45,10 @@
     "issues_total": 1,
     "noise_penalties": 5,
     "terminated_reason": "noise_exhausted",
-    "duration_seconds": 0.04
+    "duration_seconds": 0.03
   },
   {
-    "episode_id": "41b3e01d-5498-42a1-a3f9-44bb87f542b6",
+    "episode_id": "c35c2096-b7b8-4a54-b0c7-d8fa1e1538bf",
     "task_id": "bug_detection",
     "seed": 4,
     "final_score": 0.8267,
@@ -60,7 +60,7 @@
     "duration_seconds": 0.03
   },
   {
-    "episode_id": "8331b8bf-f397-49be-bc07-62bb0bdddd5c",
+    "episode_id": "9b4e5191-57da-4b10-b31e-5b8236b9b1f4",
     "task_id": "bug_detection",
     "seed": 5,
     "final_score": 0.0,
@@ -69,10 +69,10 @@
     "issues_total": 1,
     "noise_penalties": 0,
     "terminated_reason": "terminal_action",
-    "duration_seconds": 0.02
+    "duration_seconds": 0.01
   },
   {
-    "episode_id": "22341ab4-ea27-416b-ba40-53f93b6090c9",
+    "episode_id": "c1e64a16-512a-4716-b0f9-5d9fe14a142d",
     "task_id": "bug_detection",
     "seed": 6,
     "final_score": 0.0,
@@ -84,7 +84,7 @@
     "duration_seconds": 0.02
   },
   {
-    "episode_id": "9fc11809-6ba4-4bf6-b00e-9b8ffc61218f",
+    "episode_id": "cc8bd066-506e-46de-ba0f-0a446f045945",
     "task_id": "bug_detection",
     "seed": 7,
     "final_score": 0.0,
@@ -96,7 +96,7 @@
     "duration_seconds": 0.02
   },
   {
-    "episode_id": "dce54792-7fba-4e8c-8feb-404aa655172f",
+    "episode_id": "20dd7158-a49f-4b6c-adcd-6b76b4274e94",
     "task_id": "bug_detection",
     "seed": 8,
     "final_score": 0.9167,
@@ -105,10 +105,10 @@
     "issues_total": 1,
     "noise_penalties": 5,
     "terminated_reason": "noise_exhausted",
-    "duration_seconds": 0.04
+    "duration_seconds": 0.03
   },
   {
-    "episode_id": "be559f48-b216-49b9-8f3d-ad9b50da3751",
+    "episode_id": "14b9d1a5-03b7-45b2-8b23-b6c387bced5b",
     "task_id": "bug_detection",
     "seed": 9,
     "final_score": 0.0,
@@ -120,7 +120,7 @@
     "duration_seconds": 0.03
   },
   {
-    "episode_id": "b2029cb1-c72e-438a-bd96-98a0aa9bc141",
+    "episode_id": "2b1c4b7f-cf05-4312-89d2-49883b9ed6c1",
     "task_id": "security_audit",
     "seed": 0,
     "final_score": 0.0,
@@ -132,7 +132,7 @@
     "duration_seconds": 0.03
   },
   {
-    "episode_id": "e383f50e-5797-40d9-9f54-aa4142247a6e",
+    "episode_id": "47145114-7a99-4c81-baa9-1f9c4221f48a",
     "task_id": "security_audit",
     "seed": 1,
     "final_score": 1.0,
@@ -141,10 +141,10 @@
     "issues_total": 1,
     "noise_penalties": 5,
     "terminated_reason": "noise_exhausted",
-    "duration_seconds": 0.04
+    "duration_seconds": 0.03
   },
   {
-    "episode_id": "6560439d-9050-4c94-96b1-c31111081c2e",
+    "episode_id": "5d9d3f74-a127-46b2-a331-45f30f0d2f6f",
     "task_id": "security_audit",
     "seed": 2,
     "final_score": 0.0,
@@ -156,7 +156,7 @@
     "duration_seconds": 0.03
   },
   {
-    "episode_id": "d9a9d12d-384c-4dd2-86cb-b55ea7604e60",
+    "episode_id": "f383afc4-df2d-4a60-abd1-a583cb2de538",
     "task_id": "security_audit",
     "seed": 3,
     "final_score": 0.85,
@@ -165,10 +165,10 @@
     "issues_total": 1,
     "noise_penalties": 5,
     "terminated_reason": "noise_exhausted",
-    "duration_seconds": 0.04
+    "duration_seconds": 0.03
   },
   {
-    "episode_id": "463b8d96-ad63-472f-ad93-f20c99afe96e",
+    "episode_id": "df23e18b-c21a-4390-9afa-f77eb1b8050b",
     "task_id": "security_audit",
     "seed": 4,
     "final_score": 0.0,
@@ -180,7 +180,7 @@
     "duration_seconds": 0.03
   },
   {
-    "episode_id": "15e9c92a-559a-4ba6-b75b-b12ac6055f91",
+    "episode_id": "bcec83af-4aaf-4997-922a-1556ca63fcf3",
     "task_id": "security_audit",
     "seed": 5,
     "final_score": 0.0,
@@ -189,10 +189,10 @@
     "issues_total": 1,
     "noise_penalties": 5,
     "terminated_reason": "noise_exhausted",
-    "duration_seconds": 0.06
+    "duration_seconds": 0.03
   },
   {
-    "episode_id": "38bd8513-7511-4a2f-8642-fc23f50b61bd",
+    "episode_id": "65afedd0-9ad1-45f7-9615-dafeaa390338",
     "task_id": "security_audit",
     "seed": 6,
     "final_score": 0.0,
@@ -204,7 +204,7 @@
     "duration_seconds": 0.03
   },
   {
-    "episode_id": "8a6e48fd-1b17-475f-b495-a1cd8ce2e70c",
+    "episode_id": "0e8b65e5-d59c-41fb-8038-1f3b1d4b657b",
     "task_id": "security_audit",
     "seed": 7,
     "final_score": 0.0,
@@ -216,7 +216,7 @@
     "duration_seconds": 0.03
   },
   {
-    "episode_id": "3ec40833-ce55-4a63-ad90-55b2e35370d1",
+    "episode_id": "ae477e21-2718-477e-8a11-e46bda49bea7",
     "task_id": "security_audit",
     "seed": 8,
     "final_score": 0.0,
@@ -225,10 +225,10 @@
     "issues_total": 1,
     "noise_penalties": 5,
     "terminated_reason": "noise_exhausted",
-    "duration_seconds": 0.03
+    "duration_seconds": 0.04
   },
   {
-    "episode_id": "87fa57a3-27f3-4f9b-a0ad-008ff9b4c7f2",
+    "episode_id": "0cd3d18c-cdf6-4752-9dc8-cade848cee0e",
     "task_id": "security_audit",
     "seed": 9,
     "final_score": 0.0,
@@ -240,7 +240,7 @@
     "duration_seconds": 0.03
   },
   {
-    "episode_id": "8a878e69-51c2-4992-8276-616cbc798efd",
+    "episode_id": "d9f79316-57ea-42ad-b191-797ea895951b",
     "task_id": "architectural_review",
     "seed": 0,
     "final_score": 0.0,
@@ -249,10 +249,10 @@
     "issues_total": 1,
     "noise_penalties": 0,
     "terminated_reason": "terminal_action",
-    "duration_seconds": 0.02
+    "duration_seconds": 0.01
   },
   {
-    "episode_id": "c85766aa-d231-4998-8d95-b4dbbfd5aea6",
+    "episode_id": "65112da3-d319-4eb3-9774-1c43313fe1ec",
     "task_id": "architectural_review",
     "seed": 1,
     "final_score": 0.059,
@@ -261,10 +261,10 @@
     "issues_total": 1,
     "noise_penalties": 5,
     "terminated_reason": "noise_exhausted",
-    "duration_seconds": 0.04
+    "duration_seconds": 0.03
   },
   {
-    "episode_id": "29122fdb-ed30-4a46-8b04-4aa8c2025e6c",
+    "episode_id": "c1d6bd63-1abf-403b-97be-cf1962959910",
     "task_id": "architectural_review",
     "seed": 2,
     "final_score": 0.661,
@@ -273,10 +273,10 @@
     "issues_total": 1,
     "noise_penalties": 5,
     "terminated_reason": "noise_exhausted",
-    "duration_seconds": 0.04
+    "duration_seconds": 0.03
   },
   {
-    "episode_id": "1388c816-8e96-4014-b255-81382e9353ba",
+    "episode_id": "fab56551-f2ae-42be-88eb-854ef236b29a",
     "task_id": "architectural_review",
     "seed": 3,
     "final_score": 0.658,
@@ -288,7 +288,7 @@
     "duration_seconds": 0.03
   },
   {
-    "episode_id": "adee24d2-cb77-48b6-b00b-72c39d7d7c7e",
+    "episode_id": "8f4b8fa9-f281-4bb2-ae71-7ad6c7ca7fc9",
     "task_id": "architectural_review",
     "seed": 4,
     "final_score": 0.058,
@@ -300,7 +300,7 @@
     "duration_seconds": 0.03
   },
   {
-    "episode_id": "12508a15-eb46-4628-b750-cde1b5f91828",
+    "episode_id": "7eaa445d-774d-44b1-80d9-06e978b022df",
     "task_id": "architectural_review",
     "seed": 5,
     "final_score": 0.657,
@@ -309,10 +309,10 @@
     "issues_total": 1,
     "noise_penalties": 5,
     "terminated_reason": "noise_exhausted",
-    "duration_seconds": 0.04
+    "duration_seconds": 0.03
   },
   {
-    "episode_id": "520fb8ad-58fe-48fa-8a96-89e552e12924",
+    "episode_id": "103d6e2b-e40d-49ff-8f36-6910d463b48b",
     "task_id": "architectural_review",
     "seed": 6,
     "final_score": 0.059,
@@ -324,7 +324,7 @@
     "duration_seconds": 0.03
   },
   {
-    "episode_id": "86982fa4-cee7-48fc-b8d1-347a2f650f6d",
+    "episode_id": "5206e9d8-0ee0-482c-ad3d-34adf2ce57a7",
     "task_id": "architectural_review",
     "seed": 7,
     "final_score": 0.664,
@@ -333,10 +333,10 @@
     "issues_total": 1,
     "noise_penalties": 5,
     "terminated_reason": "noise_exhausted",
-    "duration_seconds": 0.04
+    "duration_seconds": 0.03
   },
   {
-    "episode_id": "086e541a-776e-4ac6-b44e-1eeb76d88b4e",
+    "episode_id": "c147abd7-f887-44a2-b166-5382e292d793",
     "task_id": "architectural_review",
     "seed": 8,
     "final_score": 0.039,
@@ -345,10 +345,10 @@
     "issues_total": 1,
     "noise_penalties": 5,
     "terminated_reason": "noise_exhausted",
-    "duration_seconds": 0.03
+    "duration_seconds": 0.08
   },
   {
-    "episode_id": "3bcd91ce-0d0d-48c5-ab25-bc8534906f5b",
+    "episode_id": "6fe54153-a878-47d7-a521-5cd70f55f6b8",
     "task_id": "architectural_review",
     "seed": 9,
     "final_score": 0.075,
@@ -357,6 +357,6 @@
     "issues_total": 1,
     "noise_penalties": 5,
     "terminated_reason": "noise_exhausted",
-    "duration_seconds": 0.03
+    "duration_seconds": 0.09
   }
 ]

scripts/reset_db.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""
+Reset the CodeLens database: deletes the SQLite file and re-initializes tables.
+Useful for clearing test data and starting fresh evaluation benchmarks.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+# Add project root to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from codelens_env.config import get_settings
+from codelens_env.database import create_db_and_tables
+
+def reset_db():
+    settings = get_settings()
+    db_path = Path(settings.db_path)
+    
+    # 1. Delete existing database file
+    if db_path.exists():
+        print(f"Removing existing database at: {db_path}")
+        try:
+            os.remove(db_path)
+            print("Successfully deleted old records.")
+        except Exception as e:
+            print(f"Error deleting file: {e}")
+            sys.exit(1)
+    else:
+        print(f"No existing database found at {db_path}")
+
+    # 2. Re-initialize
+    print(f"Re-initializing schema...")
+    try:
+        create_db_and_tables()
+        print("Database reset successfully. You now have a clean dashboard.")
+    except Exception as e:
+        print(f"Error re-initializing: {e}")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    confirm = input("This will permanently delete all leaderboard and episode data. Proceed? [y/N]: ")
+    if confirm.lower() == 'y':
+        reset_db()
+    else:
+        print("Reset aborted.")

tests/conftest.py

@@ -1,4 +1,7 @@
 import pytest
+import os
+os.environ["TESTING"] = "true"
+os.environ["APP_ENV"] = "test"
 from fastapi.testclient import TestClient
 from sqlmodel import SQLModel, Session, create_engine
 from sqlmodel.pool import StaticPool

tests/test_api.py

@@ -3,15 +3,13 @@ from fastapi.testclient import TestClient
 from app import app
 from codelens_env.models import TaskId, ActionType, Category, Severity, Verdict
 
-def test_api_health():
-    client = TestClient(app)
+def test_api_health(client):
     response = client.get("/health")
     assert response.status_code == 200
     assert response.json()["status"] == "ok"
     assert response.json()["env_ready"] is True
 
-def test_api_workflow():
-    client = TestClient(app)
+def test_api_workflow(client):
     
     # 1. Reset
     reset_resp = client.post("/reset", json={"task_id": "bug_detection", "seed": 1})
@@ -34,8 +32,7 @@ def test_api_workflow():
     assert result_resp.status_code == 200
     assert result_resp.json()["final_score"] >= 0
 
-def test_api_leaderboard():
-    client = TestClient(app)
+def test_api_leaderboard(client):
     # Submit a score
     sub = {
         "agent_name": "test_agent",
@@ -55,8 +52,7 @@ def test_api_leaderboard():
     assert len(bug_entries) > 0
     assert bug_entries[0]["agent_name"] == "test_agent"
 
-def test_api_invalid_episode():
-    client = TestClient(app)
+def test_api_invalid_episode(client):
     response = client.post("/step/nonexistent-id", json={
         "action_type": "comment",
         "body": "hello"