ARCHITECTURE.md

Architecture

System Overview

Agent (inference.py)
    │
    │  POST /reset, POST /step
    ▼
FastAPI Server (app.py)
    │
    │  reset(), step()
    ▼
MLOpsEnvironment (mlops_environment.py)
    │
    ├── ArtifactGenerator (artifact_generator.py)
    │   └── BUG_CATALOGUE: 9 bug specs across 3 tiers
    │   └── Procedural generation: config, logs, stats, code, eval, model card
    │
    ├── Sanity Check Engine (artifact_generator.py)
    │   └── 8 computed diagnostics grounded in generated artifacts
    │
    ├── Grader (_handle_submit)
    │   └── 4-component scoring: category + file + field + fix
    │
    └── Models (models.py)
        └── MLOpsAction, MLOpsObservation, MLOpsState, ArtifactMeta

Data Flow

Episode Lifecycle

1. reset(task_id, seed)
   ├── Random(seed) selects bug from task pool
   ├── ArtifactGenerator creates 6 consistent artifacts with planted fault
   └── Returns: MLOpsObservation with task description + artifact metadata

2. step(action) × N
   ├── read_* actions → return artifact content (reward: +0.02 new, -0.02 duplicate)
   ├── run_sanity_check → compute diagnostic from artifacts (reward: +0.01 new)
   ├── query_artifact → return specific field via dot notation
   └── submit_diagnosis → grade against ground truth (terminal)

3. Grading (_handle_submit)
   ├── Compare 4 components against BugSpec ground truth
   ├── Apply hard task penalty if score < 0.70
   └── Return: score ∈ (0.01, 0.99), breakdown, ground truth

Determinism Guarantees

• random.Random(seed) for bug selection and artifact variation
• np.random.RandomState(seed) for numeric distributions
• No external state, no network calls during generation
• Same (task_id, seed) always produces identical episode

Component Responsibilities

app.py — API Layer

• FastAPI server on port 7860
• REST endpoints: /reset, /step, /state, /health, /tasks
• WebSocket endpoint: /ws for streaming interaction
• Stateless request handling; delegates to MLOpsEnvironment

mlops_environment.py — Core Logic

• Episode state management (step count, artifacts read, score)
• Action routing to handlers
• Grading logic with 4-component scoring
• grade_task() standalone grader for OpenEnv validation

artifact_generator.py — Content Generation

• BugSpec dataclass: category, file, field, gold_fix, difficulty
• BUG_CATALOGUE: 9 bug specifications
• ArtifactGenerator: produces 6 artifacts per episode
• run_sanity_check(): 8 computed diagnostic checks

models.py — Data Models

• MLOpsAction: 8 action types with typed parameters
• MLOpsObservation: full agent observation per step
• MLOpsState: internal state for debugging/RL harness
• ArtifactMeta: artifact metadata (name, description, size hint)

inference.py — Baseline Agent

• LLM-powered agent using Gemini via OpenAI-compatible API
• Investigation phase: reads artifacts, runs sanity checks
• Diagnosis phase: submits structured diagnosis
• Fallback logic for unparseable LLM output
• Rate limiting with exponential backoff

client.py — Client Library

• MLOpsDebugEnv: async httpx client
• SyncMLOpsDebugEnv: synchronous wrapper
• Context manager support for connection lifecycle

API Endpoints

Method	Path	Description
GET	/	API info
GET	/health	Health check
GET	/tasks	List available tasks
POST	/reset	Start new episode
POST	/step	Execute action
GET	/state	Current episode state
GET	/openenv/state	OpenEnv framework state
WS	/ws	WebSocket interface

Reward Architecture

The reward function has two layers:

Per-step (dense): Encourages systematic investigation

• New artifact read: +0.02 (explore broadly)
• Duplicate read: -0.02 (don't brute force)
• New sanity check: +0.01 (use diagnostics)

Terminal (graded): Evaluates diagnosis quality

• 4 independent components sum to max 1.0
• Keyword/substring matching (no LLM judge)
• Hard task asymmetric penalty (1.5x on missed components)

This two-layer design means an agent that investigates thoroughly but diagnoses wrong still earns per-step rewards, while an agent that submits immediately with a lucky guess earns terminal reward but misses exploration bonuses.