Upload folder using huggingface_hub

README.md

@@ -1,255 +1,107 @@
 ---
-title: Sql Env Environment Server
-emoji: 🗜️
+title: SQLEnv - SQL Query Writing Environment
+emoji: 🗃️
 colorFrom: blue
-colorTo: gray
+colorTo: green
 sdk: docker
 pinned: false
-app_port: 8000
-base_path: /web
+app_port: 7860
 tags:
   - openenv
 ---
 
-# Sql Env Environment
+# SQLEnv — SQL Query Writing Environment for AI Agents
 
-A simple test environment that echoes back messages. Perfect for testing the env APIs as well as demonstrating environment usage patterns.
+An OpenEnv-compatible reinforcement learning environment where an AI agent learns to write correct SQL queries from natural language questions against a realistic e-commerce database.
 
-## Quick Start
+## Overview
 
-The simplest way to use the Sql Env environment is through the `SqlEnv` class:
+The agent receives a database schema and a natural language question, submits SQL queries, and gets graded with rich partial-credit scoring.
 
-```python
-from sql_env import SqlAction, SqlEnv
+**3 difficulty levels, 5 questions each:**
 
-try:
-    # Create environment from Docker image
-    sql_envenv = SqlEnv.from_docker_image("sql_env-env:latest")
+| Task | Difficulty | SQL Features |
+|---|---|---|
+| `basic_select` | Easy | WHERE, ORDER BY, LIMIT, COUNT |
+| `join_aggregate` | Medium | JOIN, GROUP BY, HAVING, AVG, SUM |
+| `advanced_analytics` | Hard | Subqueries, RANK(), LAG(), PARTITION BY |
 
-    # Reset
-    result = sql_envenv.reset()
-    print(f"Reset: {result.observation.echoed_message}")
+## API Endpoints
 
-    # Send multiple messages
-    messages = ["Hello, World!", "Testing echo", "Final message"]
+| Endpoint | Method | Description |
+|---|---|---|
+| `/health` | GET | Health check |
+| `/reset` | POST | Reset environment, get first question |
+| `/step` | POST | Submit SQL query, get graded result |
+| `/state` | GET | Current episode state |
+| `/docs` | GET | Interactive API documentation |
 
-    for msg in messages:
-        result = sql_envenv.step(SqlAction(message=msg))
-        print(f"Sent: '{msg}'")
-        print(f"  → Echoed: '{result.observation.echoed_message}'")
-        print(f"  → Length: {result.observation.message_length}")
-        print(f"  → Reward: {result.reward}")
+## Action Space
 
-finally:
-    # Always clean up
-    sql_envenv.close()
+```json
+{"action": {"query": "SELECT name, age FROM customers WHERE age > 30 ORDER BY age DESC"}}
 ```
 
-That's it! The `SqlEnv.from_docker_image()` method handles:
-- Starting the Docker container
-- Waiting for the server to be ready
-- Connecting to the environment
-- Container cleanup when you call `close()`
-
-## Building the Docker Image
-
-Before using the environment, you need to build the Docker image:
-
-```bash
-# From project root
-docker build -t sql_env-env:latest -f server/Dockerfile .
-```
-
-## Deploying to Hugging Face Spaces
-
-You can easily deploy your OpenEnv environment to Hugging Face Spaces using the `openenv push` command:
-
-```bash
-# From the environment directory (where openenv.yaml is located)
-openenv push
-
-# Or specify options
-openenv push --namespace my-org --private
-```
-
-The `openenv push` command will:
-1. Validate that the directory is an OpenEnv environment (checks for `openenv.yaml`)
-2. Prepare a custom build for Hugging Face Docker space (enables web interface)
-3. Upload to Hugging Face (ensuring you're logged in)
-
-### Prerequisites
-
-- Authenticate with Hugging Face: The command will prompt for login if not already authenticated
-
-### Options
-
-- `--directory`, `-d`: Directory containing the OpenEnv environment (defaults to current directory)
-- `--repo-id`, `-r`: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)
-- `--base-image`, `-b`: Base Docker image to use (overrides Dockerfile FROM)
-- `--private`: Deploy the space as private (default: public)
-
-### Examples
-
-```bash
-# Push to your personal namespace (defaults to username/env-name from openenv.yaml)
-openenv push
-
-# Push to a specific repository
-openenv push --repo-id my-org/my-env
-
-# Push with a custom base image
-openenv push --base-image ghcr.io/meta-pytorch/openenv-base:latest
-
-# Push as a private space
-openenv push --private
-
-# Combine options
-openenv push --repo-id my-org/my-env --base-image custom-base:latest --private
-```
-
-After deployment, your space will be available at:
-`https://huggingface.co/spaces/<repo-id>`
-
-The deployed space includes:
-- **Web Interface** at `/web` - Interactive UI for exploring the environment
-- **API Documentation** at `/docs` - Full OpenAPI/Swagger interface
-- **Health Check** at `/health` - Container health monitoring
-- **WebSocket** at `/ws` - Persistent session endpoint for low-latency interactions
-
-## Environment Details
-
-### Action
-**SqlAction**: Contains a single field
-- `message` (str) - The message to echo back
-
-### Observation
-**SqlObservation**: Contains the echo response and metadata
-- `echoed_message` (str) - The message echoed back
-- `message_length` (int) - Length of the message
-- `reward` (float) - Reward based on message length (length × 0.1)
-- `done` (bool) - Always False for echo environment
-- `metadata` (dict) - Additional info like step count
-
-### Reward
-The reward is calculated as: `message_length × 0.1`
-- "Hi" → reward: 0.2
-- "Hello, World!" → reward: 1.3
-- Empty message → reward: 0.0
-
-## Advanced Usage
-
-### Connecting to an Existing Server
-
-If you already have a Sql Env environment server running, you can connect directly:
-
-```python
-from sql_env import SqlEnv
-
-# Connect to existing server
-sql_envenv = SqlEnv(base_url="<ENV_HTTP_URL_HERE>")
-
-# Use as normal
-result = sql_envenv.reset()
-result = sql_envenv.step(SqlAction(message="Hello!"))
+## Observation Space
+
+```json
+{
+  "observation": {
+    "task_name": "basic_select",
+    "question": "Find all customers older than 30...",
+    "schema_description": "=== DATABASE SCHEMA === ...",
+    "query_result": "name | age ...",
+    "error": "",
+    "steps_remaining": 2,
+    "question_index": 1,
+    "total_questions": 5
+  },
+  "reward": 1.0,
+  "done": false
+}
 ```
 
-Note: When connecting to an existing server, `sql_envenv.close()` will NOT stop the server.
+## Reward Function
 
-### Using the Context Manager
+Multi-component partial credit scoring (0.0 to 1.0):
 
-The client supports context manager usage for automatic connection management:
+| Component | Weight | What It Measures |
+|---|---|---|
+| Syntax | 0.1 | Query executes without error |
+| Columns | 0.2 | Expected columns present |
+| Rows | 0.3 | Expected rows match |
+| Exact | 0.4 | Full result set matches ground truth |
 
-```python
-from sql_env import SqlAction, SqlEnv
-
-# Connect with context manager (auto-connects and closes)
-with SqlEnv(base_url="http://localhost:8000") as env:
-    result = env.reset()
-    print(f"Reset: {result.observation.echoed_message}")
-    # Multiple steps with low latency
-    for msg in ["Hello", "World", "!"]:
-        result = env.step(SqlAction(message=msg))
-        print(f"Echoed: {result.observation.echoed_message}")
-```
+## Database
 
-The client uses WebSocket connections for:
-- **Lower latency**: No HTTP connection overhead per request
-- **Persistent session**: Server maintains your environment state
-- **Efficient for episodes**: Better for many sequential steps
+Realistic e-commerce database with 5 tables:
+- **customers** (20 rows) - name, email, age, city, signup_date
+- **products** (15 rows) - name, category, price, stock
+- **orders** (30 rows) - customer_id, order_date, status, total_amount
+- **order_items** (46 rows) - order_id, product_id, quantity, unit_price
+- **reviews** (25 rows) - product_id, customer_id, rating, review_text
 
-### Concurrent WebSocket Sessions
-
-The server supports multiple concurrent WebSocket connections. To enable this,
-modify `server/app.py` to use factory mode:
-
-```python
-# In server/app.py - use factory mode for concurrent sessions
-app = create_app(
-    SqlEnvironment,  # Pass class, not instance
-    SqlAction,
-    SqlObservation,
-    max_concurrent_envs=4,  # Allow 4 concurrent sessions
-)
-```
+## Baseline Scores
 
-Then multiple clients can connect simultaneously:
+Tested with Llama 3.3 70B (via Groq):
 
-```python
-from sql_env import SqlAction, SqlEnv
-from concurrent.futures import ThreadPoolExecutor
+| Task | Score |
+|---|---|
+| basic_select | 1.000 |
+| join_aggregate | 1.000 |
+| advanced_analytics | 0.969 |
 
-def run_episode(client_id: int):
-    with SqlEnv(base_url="http://localhost:8000") as env:
-        result = env.reset()
-        for i in range(10):
-            result = env.step(SqlAction(message=f"Client {client_id}, step {i}"))
-        return client_id, result.observation.message_length
-
-# Run 4 episodes concurrently
-with ThreadPoolExecutor(max_workers=4) as executor:
-    results = list(executor.map(run_episode, range(4)))
-```
-
-## Development & Testing
-
-### Direct Environment Testing
-
-Test the environment logic directly without starting the HTTP server:
+## Setup
 
 ```bash
-# From the server directory
-python3 server/sql_env_environment.py
+pip install openenv-core
+cd sql_env
+uvicorn server.app:app --host 0.0.0.0 --port 7860
 ```
 
-This verifies that:
-- Environment resets correctly
-- Step executes actions properly
-- State tracking works
-- Rewards are calculated correctly
-
-### Running Locally
-
-Run the server locally for development:
+## Environment Variables
 
-```bash
-uvicorn server.app:app --reload
-```
-
-## Project Structure
-
-```
-sql_env/
-├── .dockerignore         # Docker build exclusions
-├── __init__.py            # Module exports
-├── README.md              # This file
-├── openenv.yaml           # OpenEnv manifest
-├── pyproject.toml         # Project metadata and dependencies
-├── uv.lock                # Locked dependencies (generated)
-├── client.py              # SqlEnv client
-├── models.py              # Action and Observation models
-└── server/
-    ├── __init__.py        # Server module exports
-    ├── sql_env_environment.py  # Core environment logic
-    ├── app.py             # FastAPI application (HTTP + WebSocket endpoints)
-    └── Dockerfile         # Container image definition
-```
+| Variable | Default | Description |
+|---|---|---|
+| SQL_ENV_TASK | basic_select | Task to load |
+| SQL_ENV_MAX_STEPS | 15 | Max steps per episode |