# HR Productivity Environment — AgentX-AgentBeats

## Overview
A fully-implemented HR simulation environment (OpenEnv-compliant) where an LLM agent serves as Chief Human Capital Officer (CHCO), managing a simulated company over 6 quarters. The agent uses Fitz-enz HR Analytics frameworks to optimize human capital metrics through strategic hiring, training, compensation, and retention decisions.

## Repository Structure
```
/tmp/autoresearch/
├── hr_env/
│   └── server/
│       ├── environment.py    # Main simulation loop (OpenEnv Environment)
│       ├── company.py        # Company + Department models (Cobb-Douglas production)
│       ├── employee.py       # Employee dataclass with lifecycle methods
│       ├── metrics.py        # Fitz-enz metrics: HCVA, HCROI, QIPS, Five Indexes
│       ├── scoring.py        # Reward computation + final score (normalized [0,1])
│       ├── phases.py         # HCM:21 phase management (Scanning→Planning→Producing→Controlling)
│       ├── events.py         # Stochastic quarterly events (market, competitor, etc.)
│       ├── data_gen.py       # Synthetic company generation (Faker + numpy)
│       └── app.py            # OpenEnv server entrypoint
├── agent/
│   ├── hr_agent.py           # Claude-based CHCO agent with phase-aware prompting
│   ├── prompts.py            # System prompt, phase prompts, summary prompts
│   └── run.py                # Agent runner script
├── tests/                    # Test suite
├── openenv.yaml              # OpenEnv configuration
├── pyproject.toml             # Python project config (uv)
└── Dockerfile                 # Container build
```

## Development Commands
```bash
# Install dependencies
uv sync

# Run tests
uv run pytest tests/ -v

# Start OpenEnv server
uv run python -m hr_env.server.app

# Run agent against server
uv run python -m agent.run

# Docker build
docker build -t hr-productivity-env .
```

## Architecture

### Simulation Engine
- **Company Model**: 5 departments (Engineering, Sales, Operations, HR, Finance) with Cobb-Douglas production functions
- **Employee Model**: 17 tracked attributes including performance, engagement, flight_risk, promotability
- **Revenue**: `A * headcount^alpha * avg_skill^beta * engagement_mult * market_modifier` per department
- **Turnover**: Stochastic based on flight_risk (logistic function of pay, engagement, tenure, market)

### Fitz-enz Metrics
- **HCVA**: (Revenue - Non-Employment Costs) / FTE
- **HCROI**: Revenue / Employment Cost
- **QIPS**: Quality(0.25) + Innovation(0.25) + Productivity(0.30) + Service(0.20)
- **Five Indexes**: Cost, Time, Quantity, Quality, Human Reactions (% change vs prior quarter)
- **Employee Value**: avg(Productivity + Promotability + Transferability + Retainability)

### HCM:21 Phase System (per quarter)
1. **Scanning** (min 2 actions): query_department, query_employees, calculate_metric, review_financials
2. **Planning** (min 1): set_hiring_target, set_training_budget, set_compensation_policy, set_retention_program
3. **Producing** (min 1): execute_hiring, execute_promotion, execute_transfer, execute_training, execute_termination
4. **Controlling** (min 1): submit_report, calculate_metric → then advance_quarter

### Scoring
- **Quarterly reward**: HCVA improvement (40%) + HCROI (20%) + QIPS (20%) + Five Indexes (20%)
- **Final score** [0,1]: HCVA trajectory (25%) + HCROI improvement (20%) + Employee Value (20%) + QIPS consistency (15%) + Five Indexes cumulative (10%) + Financial health (10%)

### Stochastic Events
MarketDownturn, CompetitorPoaching, ProductLaunch, ExecDeparture, MinWageIncrease, EmployerAward, BudgetCut, TrainingBreakthrough — each with independent probability per quarter, max 2 per quarter.

## Databricks Integration
The simulation is adapted into a Databricks notebook (`/tmp/AimpointDigital/01_agentic_wikipedia_aimpoint_interview.ipynb`) with:
- **Wikipedia knowledge layer**: HR theory articles (Fitz-enz, HCM, talent management) indexed into FAISS via BGE-Large embeddings
- **LangGraph orchestration**: StateGraph with 5 nodes (initialize → agent_decide → execute_tools → check_done → summarize)
- **RAG bridge**: `consult_hr_knowledge` tool lets the agent ground decisions in Wikipedia-sourced HR theory
- **Databricks LLM**: `databricks-meta-llama-3-1-8b-instruct` for agent reasoning

## Key Conventions
- Pydantic models for OpenEnv; plain dataclasses/dicts for Databricks adaptation
- Phase-gated action space prevents random action sequences
- Company generation uses Faker (names) + numpy (distributions) with deterministic seeds
- Salary distributions: lognormal; tenure: exponential; engagement: beta(7,3)
- Level distribution: pyramid [0.35, 0.30, 0.20, 0.10, 0.05] for levels 1-5
- Recruiting cost: $8,000/hire; Benefits: 30% of salary; Training: $50/hr/employee

## Databricks Deployment

### Workspace
- **URL**: `https://dbc-c005fe3a-5584.cloud.databricks.com`
- **Org ID**: `7474655330631867`
- **Target Folder ID**: `1876640772048528`
- **Folder URL**: `https://dbc-c005fe3a-5584.cloud.databricks.com/browse/folders/1876640772048528?o=7474655330631867`
- **PAT**: (stored in env / .databrickscfg — not committed)
- **User**: `n8.mauer@gmail.com`
- **Edition**: Community Edition (Free)
- **LLM endpoint**: `databricks-meta-llama-3-1-8b-instruct`
- **Embedding endpoint**: `databricks-bge-large-en`

### .env file (for local development)
```
DATABRICKS_HOST=https://dbc-c005fe3a-5584.cloud.databricks.com
DATABRICKS_TOKEN=<your-token>
DATABRICKS_ORG_ID=7474655330631867
```

### Cold-Start Setup
1. `pip install databricks-cli`
2. Write `~/.databrickscfg`:
   ```ini
   [DEFAULT]
   host = https://dbc-c005fe3a-5584.cloud.databricks.com
   token = <your-token>
   ```
3. Deploy notebook:
   ```bash
   databricks workspace import \
     "/tmp/AimpointDigital/01_agentic_wikipedia_aimpoint_interview.ipynb" \
     /Users/n8.mauer@gmail.com/01_agentic_wikipedia_aimpoint_interview \
     --format JUPYTER --language PYTHON --overwrite
   ```
4. Open workspace URL → attach cluster → Run All

### Deploy Script
```bash
./deploy.sh   # from /tmp/AimpointDigital/
```

### Runtime Fixes Applied
- **Rate limiting**: `agent_decide` LLM calls wrapped with `backoff.on_exception` (exponential, max 8 retries, 120s) + 1.5s proactive delay between calls. Community Edition has low QPS for foundation model endpoints.
- **MLflow tracing**: `mlflow.langchain.autolog()` added at top of Cell A2 to enable tracing and suppress Databricks "Enhance GenAI observability" hint. `mlflow-skinny[databricks]` already in pip install cell.

### GitHub Repo
- URL: `https://github.com/n8mauer/AimpointDigital`
- Contains: notebook, build script, deploy script, README (runbook + talk track), assignment PDF

## TRL/GRPO Training (`notebooks/hcm21_trl_training.ipynb`)

### Architecture
- **Model**: `unsloth/Qwen3-0.6B` with LoRA (r=16, 4-bit quantization)
- **Method**: GRPO (Group Relative Policy Optimization) via TRL's `GRPOTrainer`
- **Environment**: HCM:21 OpenEnv on HF Spaces (`https://paretooptimal-hcm21.hf.space`)
- **Colab URL**: `https://colab.research.google.com/github/n8mauer/autoresearch/blob/main/notebooks/hcm21_trl_training.ipynb`

### GRPO Reward Strategy (JSON action parsing — no environment_factory)
The model generates text completions containing JSON action objects (one per line).
`reward_func` parses these with regex (`\{[^{}]*"action_type"[^{}]*\}`), executes
them in a fresh `HCM21Env` instance, and returns the environment's final score.

**Why not `environment_factory`?**
- TRL's `environment_factory` exposes env methods as tools for tool-calling, but a 0.6B model can't reliably generate structured tool calls
- `environment_factory` requires `transformers>=5.2.0` which conflicts with Unsloth patches
- Disabling Qwen3 thinking mode via `chat_template.replace("enable_thinking", "")` may break tool-calling templates
- Direct JSON parsing in `reward_func` is simpler, more robust, and works with Unsloth

### Key Implementation Details
- `SYSTEM_PROMPT` instructs the model to output 20-40 JSON action objects covering 6 quarters
- `reward_func(completions, **kwargs)` — no `environments` param (environments created internally)
- `GRPOTrainer` has NO `environment_factory` argument
- Evaluation (cell 20) generates one completion per seed, parses all actions, executes them
- `tokenizer.apply_chat_template()` may return `BatchEncoding` — extract `.input_ids` before using `.shape`

### Training Config
- `per_device_train_batch_size=2`, `gradient_accumulation_steps=4`, `num_generations=4`
- `max_completion_length=2048`, `learning_rate=5e-6`, `fp16=True`
- Dataset: 20 prompts with different episode seeds

### Verification Checklist
After running in Colab, confirm:
- `reward` column shows **non-zero values**
- `reward_std` is **non-zero** (learning signal exists)
- `Training Loss` is **non-zero** (GRPO has gradients)
- Rewards trend upward over training steps