Apppublic

abhishekd17/spreadsheet-formula-env

sourceHugging Faceupdated 6mo agoView on Hugging Face

0likes

App README

Spreadsheet Formula Environment

An OpenEnv RL environment where AI agents learn to write spreadsheet formulas from natural-language instructions.

Overview

Given a data grid and a task description, the agent must produce the correct spreadsheet formula (e.g., =SUM(B2:B5), =VLOOKUP(D2,A2:B5,2,FALSE)). The environment evaluates formulas using a safe, sandboxed evaluator and provides partial-credit scoring.

Action Space

Field	Type	Description
`formula`	`str`	A spreadsheet formula string starting with `=`

Example: =SUMIF(A2:A7,"East",D2:D7)

Observation Space

Field	Type	Description
`grid`	`List[List[str]]`	2D grid of cell values (row 0 = headers)
`task_description`	`str`	Natural language instruction
`target_cell`	`str`	Cell where formula should go (e.g., `C6`)
`feedback`	`str`	Feedback on last submission
`expected_type`	`str`	Expected result type: `number`, `text`, or `boolean`
`task_id`	`str`	Current task identifier
`difficulty`	`str`	`easy`, `medium`, or `hard`
`done`	`bool`	Whether all tasks are complete
`reward`	`float`	Score for the current step

Tasks (3 Difficulty Levels)

Easy (4 tasks)

Basic aggregation formulas:

—SUM — total sales across rows
—AVERAGE — average quantity
—COUNT — count numeric entries
—MAX — find maximum value

Medium (4 tasks)

Conditional and lookup formulas:

—SUMIF — sum with single condition
—IF — conditional text output
—COUNTIF — count matching criteria
—SUMPRODUCT — weighted average calculation

Hard (4 tasks)

Advanced multi-step formulas:

—Nested IF — grade assignment with 5 tiers
—INDEX/MATCH or VLOOKUP — lookup from a table
—SUMPRODUCT with conditions — conditional revenue calculation
—COUNTIFS — multi-criteria counting

Grading (0.0 – 1.0 with Partial Credit)

Score	Meaning
0.0	Empty or unparseable formula
0.1	Valid formula syntax (starts with `=`)
0.15	Uses correct function family but crashes
0.3	Formula parses and produces a result
0.4	Correct function + produces a result
0.5–0.6	Result is in the right ballpark
0.8	Result within 5% of expected
1.0	Exact match

The agent gets up to 3 attempts per task. Best score per task is kept.

Supported Formula Functions

SUM, AVERAGE, COUNT, COUNTA, MAX, MIN, IF, SUMIF, COUNTIF, COUNTIFS, SUMIFS, VLOOKUP, INDEX, MATCH, XLOOKUP, SUMPRODUCT, ROUND, ABS, CONCATENATE, LEN, UPPER, LOWER

Plus arithmetic (+, -, *, /), comparisons (>, <, >=, <=, <>, =), and string concatenation (&).

Setup

bash

# Install dependencies
pip install openenv-core[core] openai requests

# Or with uv
cd spreadsheet_formula_env
uv sync

Run Locally

bash

# Start the environment server
cd spreadsheet_formula_env
uv run server

# In another terminal, run inference
export API_BASE_URL="https://api.openai.com/v1"
export MODEL_NAME="gpt-4o-mini"
export HF_TOKEN="your-api-key"
export ENV_URL="http://localhost:8000"
python inference.py

Run with Docker

bash

cd spreadsheet_formula_env
docker build -t spreadsheet-formula-env -f server/Dockerfile .
docker run -p 8000:8000 spreadsheet-formula-env

Deploy to Hugging Face Spaces

bash

openenv push --repo-id your-username/spreadsheet-formula-env

Environment Variables

Variable	Description
`API_BASE_URL`	LLM API endpoint
`MODEL_NAME`	Model identifier for inference
`HF_TOKEN`	Hugging Face / API key

Architecture

spreadsheet_formula_env/
├── models.py              ← Pydantic types: Action, Observation, State
├── client.py              ← WebSocket client
├── server/
│   ├── environment.py     ← Core reset/step/state logic
│   ├── app.py             ← FastAPI server
│   ├── tasks.py           ← 12 task definitions with grids
│   ├── evaluator.py       ← Safe formula parser & evaluator
│   ├── graders.py         ← Partial-credit grading logic
│   └── Dockerfile
├── inference.py           ← LLM agent script
├── openenv.yaml           ← OpenEnv manifest
└── README.md