Upload folder using huggingface_hub

README.md

@@ -9,10 +9,11 @@ license: mit
 short_description: RL training env — natural language to constraint AST
 base_path: /web
 ---
-[Space ](https://huggingface.co/spaces/DecentSanage/constraint-env)
+[Space UI & Interface](https://huggingface.co/spaces/DecentSanage/constraint-env) 
+
 # Constraint Environment
 
-This is the environment for training LLMs to learn a specific DSL made for time table scheduling. Model can then directly output constraints from natural language. Why this is needed? Usually time table generation is an NP hard problem, for humans it could take weeks to generate a conflict free tiem table. To solve this problem, tools are created to generate them in reasonable time. One example of those tools is CP SAT. Users can write the hardcoded constraints and the solver will generate a time table based on those constraints. Well, what happens when you want to add new constraints? Yes, you have to directly change the code. What if there is a way to directly define constraints in natural language and the solver understands that automatically ? That's what we have tried to do with this project. LLM might not be good at scheduling time tables which have dozens of constraints but what it is good at is understanding natural language. For the specific purpose of defining constraints for university time tables a DSL was created whose specification is as follows: 
+This is the environment for training LLMs to learn a specific DSL made for time table scheduling. Model can then directly output constraints from natural language. Why this is needed? Usually time table generation is an NP hard problem, for humans it could take weeks to generate a conflict free time table. To solve this problem, tools are created to generate them in reasonable time. One example of those tools is CP SAT. Users can write the hardcoded constraints and the solver will generate a time table based on those constraints. Well, what happens when you want to add new constraints? Yes, you have to directly change the code. What if there is a way to directly define constraints in natural language and the solver understands that automatically? That's what we have tried to do with this project. LLM might not be good at scheduling time tables which have dozens of constraints but what it is good at is understanding natural language. For the specific purpose of defining constraints for university time tables a DSL was created whose specification is as follows: 
 
 ```
 program         ::= { constraint }
@@ -64,11 +65,10 @@ number          ::= digit { digit }
 
 ```
 
-The model outputs a json which follows the above format which can directly be converted into CP-SAT constraints. 
+The model outputs a json which follows the above format which can directly be converted into CP-SAT constraints. We have also included `generator.py` which implements the DSL compiler engine directly into the timetable matrix grid natively!
 
 ## Action and Observation
-
-The dataset for the training is in this format: 
+The dataset for the training operates using dynamic deep AST JSON nodes: 
 
 ```python
         {
@@ -79,32 +79,95 @@ The dataset for the training is in this format:
                 "type": "hard",
                 "name": "no_saturday_classes",
                 "forall": [
-                    {"var": "b", "domain": "branches"},
-                    {"var": "sub", "domain": "subjects"},
-                    {"var": "d", "domain": "days"},
-                    {"var": "s", "domain": "slots"},
+                    {"b": "branches"},
+                    {"sub": {"subjects": "b"}},
+                    {"d": "days"},
+                    {"s": "slots"},
                 ],
-                "where": "d == 5",
-                "assert": "schedule(b, sub, d, s) == 0",
+                "where": {
+                    "operator": "==",
+                    "left": "d",
+                    "right": 5
+                },
+                "assert": {
+                    "operator": "==",
+                    "left": {
+                        "target": "schedule",
+                        "args": [{"name": "b"}, {"name": "sub"}, "d", "s"]
+                    },
+                    "right": 0
+                }
             },
         }
 ```
 
-
-The model will get the prompt from the environment and will guess the target_ast. It will get the rewards based on how good the guess is. 
-
+The model will get the prompt from the environment and will guess the target_ast across a **multi-step interactive compiler loop**. It will get the rewards based on how good the guess is, suffering a `-0.05` penalty for every step required beyond the first attempting to compile invalid expressions!
 
 | Output              | Reward   |
 | ------------------- | -------- |
 | Valid Json          | 0.125    |
 | Correct Structure   | 0.250    |
 | Same as the target  | 0.625    |
+| **Step Penalty**    | **-0.05 per extra step** |
 
+**Final Reward Calculation:** `(Base Reward) - (Steps - 1) * 0.05`. Minimum reward is clamped at 0.01.
+## Task Descriptions, Graders, and Difficulty
+We implemented 3 deterministic tasks escalating in complexity. Each task is aggressively graded dynamically. Every step required by an LLM over a multi-turn compilation loop subtracts 0.05 points from the final step score. 
+
+1. **EASY (Direct Equality Match)**: Instructs the solver to block out a specific day/slot for an entity. Single assertions, direct variables. (Grader Threshold for Success: **0.80**)
+2. **MEDIUM (Aggregate Objectives)**: Requires the use of `sum` over sub-domains natively to assign specific frequencies to a property attribute check. (Grader Threshold for Success: **0.65**)
+3. **HARD (Deep Conditional Traversal)**: Requires tracking multiple parent nested variables with dense constraints, compound boolean logics in `where`, AND explicit NOT filters natively injected into the dataset arrays. (Grader Threshold for Success: **0.45** due to base LLM difficulty and step penalty accumulation).
 
 ## Development & Testing
 
-### Direct Environment Testing
+### Running Inference Baseline & Scores
+Our baseline framework queries `openai/gpt-oss-120b`. 
+**Current Baseline Scores (GPT OSS 120B):**
+- Easy: **0.900** (Success, 1 Step)
+- Medium: **0.800** (Success, 5 Steps)
+- Hard: **0.175** (Failure , 5 Steps)
+
+The model integrates exactly according to standard OpenEnv structures. When invoking the `inference.py` framework, the baseline `openai/gpt-oss-120b` navigates our compiler natively:
+
+```bash
+[START] task=easy env=constraint_env model=openai/gpt-oss-120b
+[STEP] step=1 action={"type":"hard","name":"cs_branch_no_classes_wed_12","forall":[{"b":"branches"},{"sub":{"subjects":"b"}},{"d":"days"},{"s":"slots"}],"where":{"operator":"AND","left":{"operator":"==","left":{"name":"b"},"right":"CS"},"right":{"operator":"AND","left":{"operator":"==","left":"d","right":2},"right":{"operator":"==","left":"s","right":3}}},"assert":{"operator":"==","left":{"target":"schedule","args":[{"name":"b"},{"name":"sub"},"d","s"]},"right":0}} reward=0.90 done=true error=null
+[END] success=true steps=1 score=0.900 rewards=0.90
+[START] task=medium env=constraint_env model=openai/gpt-oss-120b
+[STEP] step=1 action={"type":"hard","name":"subject_frequency_match","forall":[{"sub":"subjects"}],"assert":{"operator":"==","left":{"operator":"sum","over":[{"b":"branches"},{"d":"days"},{"s":"slots"}],"expression":{"target":"schedule","args":[{"name":"b"},{"name":"sub"},"d","s"]}},"right":{"frequency":"sub"}}} reward=0.01 done=false error=bad_structure
+[STEP] step=2 action={"type":"hard","name":"subject_frequency_match","forall":[{"b":"branches"},{"sub":{"subjects":"b"}},{"d":"days"},{"s":"slots"}],"assert":{"operator":"==","left":{"operator":"sum","over":[{"d":"days"},{"s":"slots"}],"expression":{"target":"schedule","args":[{"name":"b"},{"name":"sub"},"d","s"]}},"right":{"frequency":"sub"}}} reward=0.01 done=false error=bad_structure 
+[STEP] step=3 action={"type":"hard","name":"subject_frequency_match","forall":[{"sub":"subjects"}],"assert":{"operator":"==","left":{"operator":"sum","over":[{"b":"branches"},{"d":"days"},{"s":"slots"}],"expression":{"target":"schedule","args":[{"name":"b"},{"name":"sub"},"d","s"]}},"right":{"frequency":"sub"}}} reward=0.01 done=false error=bad_structure
+[STEP] step=4 action={"type":"hard","name":"subject_frequency_match","forall":[{"b":"branches"},{"sub":{"subjects":"b"}},{"d":"days"},{"s":"slots"}],"assert":{"operator":"==","left":{"operator":"sum","over":[{"d":"days"},{"s":"slots"}],"expression":{"target":"schedule","args":[{"name":"b"},{"name":"sub"},"d","s"]}},"right":{"frequency":"sub"}}} reward=0.01 done=false error=bad_structure 
+[STEP] step=5 action={"type":"hard","name":"subject_frequency_match","forall":[{"b":"branches"},{"sub":{"subjects":"b"}}],"assert":{"operator":"==","left":{"operator":"sum","over":[{"d":"days"},{"s":"slots"}],"expression":{"target":"schedule","args":[{"name":"b"},{"name":"sub"},"d","s"]}},"right":{"frequency":"sub"}}} reward=0.80 done=true error=null
+[END] success=true steps=5 score=0.800 rewards=0.01,0.01,0.01,0.01,0.80
+[START] task=hard env=constraint_env model=openai/gpt-oss-120b
+[STEP] step=1 action={"type":"hard","name":"no_classes_on_saturday","forall":[{"b":"branches"},{"sub":{"subjects":"b"}},{"d":"days"},{"s":"slots"}],"where":{"operator":"==","left":"d","right":5},"assert":{"operator":"==","left":{"target":"schedule","args":[{"name":"b"},{"name":"sub"},"d","s"]},"right":0}} reward=0.38 done=false error=logic_mismatch
+[STEP] step=2 action={"type":"hard","name":"no_classes_on_saturday","forall":[{"b":"branches"},{"sub":{"subjects":"b"}},{"d":"days"},{"s":"slots"}],"where":{"operator":"==","left":"d","right":5},"assert":{"operator":"==","left":{"target":"schedule","args":[{"name":"b"},{"name":"sub"},"d","s"]},"right":0}} reward=0.33 done=false error=logic_mismatch
+[STEP] step=3 action={"type":"hard","name":"no_classes_on_saturday","forall":[{"b":"branches"},{"sub":{"subjects":"b"}},{"d":"days"},{"s":"slots"}],"where":{"operator":"==","left":"d","right":5},"assert":{"operator":"==","left":{"target":"schedule","args":[{"name":"b"},{"name":"sub"},"d","s"]},"right":0}} reward=0.28 done=false error=logic_mismatch
+[STEP] step=4 action={"type":"hard","name":"no_classes_on_saturday","forall":[{"b":"branches"},{"sub":{"subjects":"b"}},{"d":"days"},{"s":"slots"}],"where":{"operator":"==","left":"d","right":5},"assert":{"operator":"==","left":{"target":"schedule","args":[{"name":"b"},{"name":"sub"},"d","s"]},"right":0}} reward=0.23 done=false error=logic_mismatch
+[STEP] step=5 action={"type":"hard","name":"no_classes_on_saturday","forall":[{"b":"branches"},{"sub":{"subjects":"b"}},{"d":"days"},{"s":"slots"}],"where":{"operator":"==","left":"d","right":5},"assert":{"operator":"==","left":{"target":"schedule","args":[{"name":"b"},{"name":"sub"},"d","s"]},"right":0}} reward=0.17 done=true error=logic_mismatch
+[END] success=true steps=5 score=0.175 rewards=0.38,0.33,0.28,0.23,0.17
+```
+
+> **Research Warning - Failure on Hard:** The baseline LLM fundamentally struggles with synthesizing deep AST networks iteratively for harder targets. It eventually fell back to terminal truncation (step 5 failure, penalty accumulation down to 0.175). In the future, solving these deep constraint synthesises dynamically will require **advanced RL tuning methodologies like PPO or GRPO (Group Relative Policy Optimization)**.
+
+### Submitting Models & Environment Checks
+
+Your `inference.py` must run natively in the root directory and absorb the base OpenEnv formats. 
 
+Ensure these environment variables are set during your model tests:
+- `API_BASE_URL` (default: `https://openrouter.ai/api/v1`)
+- `MODEL_NAME` (default: `openai/gpt-oss-120b`)
+- `HF_TOKEN` (Mandatory - execution fails without it, powering hosted inference queries).
+
+**Inference Output Pattern Expectation:**
+```
+[START] task=<task_name> env=<benchmark> model=<model_name>
+[STEP]  step=<n> action=<action_str> reward=<0.00> done=<true|false> error=<msg|null>
+[END]   success=<true|false> steps=<n> rewards=<r1,r2,...,rn>
+```
+
+### Direct Environment Testing
 Test the environment logic directly without starting the HTTP server:
 
 ```bash
@@ -112,19 +175,29 @@ Test the environment logic directly without starting the HTTP server:
 python3 server/constraint_env_environment.py
 ```
 
-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:
+Run the server locally via the main standard startup:
 
 ```bash
 uvicorn server.app:app --reload
 ```
+or 
+```bash
+$env:ENABLE_WEB_INTERFACE="true"; uv run server/app.py
+```
+
+**Known Good Execution Logs Example:**
+```bash
+===== Application Startup at 2026-04-12 16:53:42 =====
+INFO:     Started server process [7]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+INFO:     Uvicorn running on http://0.0.0.0:7860 (Press CTRL+C to quit)
+INFO:     10.16.24.44:32462 - "POST /web/gradio_api/queue/join HTTP/1.1" 200 OK
+INFO:     10.16.12.178:19351 - "GET /web HTTP/1.1" 307 Temporary Redirect
+INFO:     10.16.33.124:5187 - "GET /web HTTP/1.1" 307 Temporary Redirect
+INFO:     10.16.24.44:32462 - "GET /web/ HTTP/1.1" 200 OK
+```
 
 ## Project Structure
 
@@ -137,9 +210,11 @@ constraint_env/
 ├── pyproject.toml         # Project metadata and dependencies
 ├── uv.lock                # Locked dependencies (generated)
 ├── client.py              # ConstraintEnv client
+├── generator.py           # Native Time Table generator for target compiling
 ├── models.py              # Action and Observation models
 └── server/
     ├── __init__.py        # Server module exports
+    ├── graders.py         # Advanced threshold limits scaling for evaluations
     ├── constraint_env_environment.py  # Core environment logic
     ├── app.py             # FastAPI application (HTTP + WebSocket endpoints)
     └── Dockerfile         # Container image definition

server/constraint_env_environment.py

@@ -141,6 +141,8 @@ class ConstraintEnvironment(Environment):
         # ── 1. Parse JSON ────────────────────────────────────────────
         try:
             ast = json.loads(action.ast_output)
+            if isinstance(ast, str):
+                ast = json.loads(ast)
             is_valid_json = True
         except (json.JSONDecodeError, TypeError):
             info["error"] = "invalid_json"

server/graders.py

@@ -50,9 +50,9 @@ def check_passed(difficulty: str, score: float) -> bool:
     Temporary defaults to be calibrated dynamically.
     """
     thresholds = {
-        "easy": 0.15,
-        "medium": 0.15,
-        "hard": 0.15
+        "easy": 0.80,
+        "medium": 0.65,
+        "hard": 0.45
     }
     
     req_threshold = thresholds.get(difficulty, 0.8)