# 📄 TECH_STACK.md — Technology Choices & Justification

---

## 🧠 Overview

This document defines the **technology stack** used to build the AI Community Moderation Environment.

The stack is chosen to:

* ensure **OpenEnv compliance**
* enable **fast development**
* support **deterministic execution**
* allow seamless **Docker + Hugging Face deployment**

---

## 🧱 Core Language

### 🐍 Python 3.10+

**Why:**

* native ecosystem for OpenEnv
* strong support for RL + APIs
* rapid prototyping and debugging

---

## 🌐 Backend Framework

### ⚡ FastAPI

**Why:**

* lightweight and high-performance
* built-in request validation (via Pydantic)
* async support
* ideal for exposing `/reset`, `/step`, `/grader`, etc.
* easily deployable on Hugging Face Spaces

---

## 🧾 Data Validation & Models

### 📦 Pydantic

**Why:**

* strict typing for OpenEnv compliance
* automatic validation of API inputs/outputs
* seamless integration with FastAPI
* ensures deterministic schema handling

---

## 🧠 Environment Logic

### 🧩 Custom Python Modules

* `env/` → environment core
* `policy_engine.py` → rule evaluation
* `reward_engine.py` → step rewards
* `data_generator.py` → synthetic data

**Why:**

* full control over logic
* deterministic execution
* no external dependencies

---

## 🤖 Baseline Agent

### 🪶 Rule-based Agent (`baseline/agent.py`)

Heuristic agent using keyword matching — no LLM, fully reproducible.

---

## 🧠 LLM Agent — 🔹 Added

### Gemini 2.5 Flash via `google-genai` SDK

**Why:**

* state-of-the-art reasoning on structured tasks
* multi-turn chat with system prompt support
* deterministic temperature=0.0 setting minimises variance
* `google-genai` SDK is the latest official Google AI Python SDK

**Key files:**

```
agent/gemini_agent.py   — GeminiAgent class, multi-turn loop
agent/prompts.py        — system prompt + per-turn prompt builder
```

**SDK:**

```python
from google import genai
client = genai.Client(api_key=GOOGLE_API_KEY)
chat = client.chats.create(model="gemini-2.5-flash", config=...)
response = chat.send_message(turn_prompt)
```

**Design constraint:** LLM is ONLY the decision layer. Policy, reward, and grading remain deterministic in `env/`.

---

## 📦 API Communication

### JSON over HTTP

**Why:**

* simple and standard
* compatible with OpenEnv expectations
* easy debugging and logging

---

## 🐳 Containerization

### 🐳 Docker

**Why:**

* mandatory for evaluation pipeline
* ensures consistent runtime environment
* required for Hugging Face Spaces deployment

---

## ☁️ Deployment Platform

### 🤗 Hugging Face Spaces (Docker-based)

**Why:**

* required by competition
* easy container deployment
* public endpoint for validation
* integrates well with OpenEnv ecosystem

---

## 🧪 Testing & Validation

### ✅ Pytest (optional but recommended)

**Why:**

* quick validation of:

  * policy engine
  * reward logic
  * graders

---

### 🔍 OpenEnv Validator

**Why:**

* ensures compliance with:

  * API schema
  * openenv.yaml
  * required endpoints

---

## 📊 Logging (Optional)

### Python Logging

**Why:**

* debug environment flow
* trace agent decisions
* inspect reward calculations

---

## 📦 Dependency Summary

```txt
fastapi
uvicorn[standard]
pydantic>=2.6
google-genai>=1.0
openai          # optional / legacy
pytest
httpx           # TestClient
```

---

## ⚙️ Runtime Setup

| Component  | Tool      |
| ---------- | --------- |
| API Server | Uvicorn   |
| Backend    | FastAPI   |
| Models     | Pydantic  |
| Container  | Docker    |
| Deployment | HF Spaces |

---

## 🧠 Design Principles

### 1. Minimalism

Only essential tools used

---

### 2. Determinism

No external APIs for core logic

---

### 3. Reproducibility

Same input → same output

---

### 4. Fast Iteration

Simple stack = quick debugging

---

## ⚠️ What We Avoid (Important)

* ❌ heavy ML frameworks (TensorFlow, PyTorch)
* ❌ databases (not needed for MVP)
* ❌ microservices complexity
* ❌ external APIs for environment logic

---

## 🧠 One-Line Summary

> A lightweight Python-based stack using FastAPI and Pydantic to build a deterministic, OpenEnv-compliant environment with Docker-based deployment.

---