Metadata-Version: 2.4
Name: greenopt-ai-gym
Version: 0.1.0
Summary: A Gymnasium environment for intelligent greenhouse control and resource optimization.
Author-email: Iman Hindi <iman.hindi@htu.edu.jo>, Adham AlSharkawi <sharkawi.adham@gmail.com>
License-Expression: LicenseRef-GreenOpt-Research-Preview
Project-URL: Homepage, https://github.com/ImanHindi/greenopt-ai-gym
Project-URL: Repository, https://github.com/ImanHindi/greenopt-ai-gym
Project-URL: Documentation, https://github.com/ImanHindi/greenopt-ai-gym#readme
Project-URL: Issues, https://github.com/ImanHindi/greenopt-ai-gym/issues
Project-URL: Paper, https://doi.org/10.1371/journal.pone.0344946
Keywords: gymnasium,reinforcement-learning,greenhouse,smart-agriculture,decision-support
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: gymnasium<1.1,>=0.29
Requires-Dist: numpy<2.0,>=1.26
Requires-Dist: pandas<3.0,>=2.0
Requires-Dist: PyYAML>=6.0
Provides-Extra: simulator
Requires-Dist: tensorflow==2.17.0; extra == "simulator"
Requires-Dist: keras==3.11.3; extra == "simulator"
Requires-Dist: h5py>=3.10; extra == "simulator"
Provides-Extra: sb3
Requires-Dist: stable-baselines3==2.3.2; extra == "sb3"
Requires-Dist: torch>=2.1; extra == "sb3"
Provides-Extra: all
Requires-Dist: tensorflow==2.17.0; extra == "all"
Requires-Dist: keras==3.11.3; extra == "all"
Requires-Dist: h5py>=3.10; extra == "all"
Requires-Dist: stable-baselines3==2.3.2; extra == "all"
Requires-Dist: torch>=2.1; extra == "all"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# GreenOpt-AI Gym

A research-preview Python library and predefined **Gymnasium** environment for
training and evaluating continuous-control agents against the GreenOpt-AI
paper-faithful greenhouse simulator.

## What is included

- Registered environment: `GreenOpt/Greenhouse-v0`
- Exact observation and nine-control action contracts
- Fixed training-weather scaler metadata
- Transparent multi-objective reward breakdown
- Compatibility checks for Stable-Baselines3 TD3, DDPG and SAC agents
- CLI tools and publication-ready metadata

The public Python wheel does **not** embed the trained `.h5` files. The private
complete release bundle supplied to the project owner includes the verified files
under `models/weights/`. Confirm ownership and redistribution permissions before
placing those model files in a public repository or release.

## Installation

```bash
pip install greenopt-ai-gym
```

For the real predictive simulator:

```bash
pip install "greenopt-ai-gym[simulator]"
```

For Stable-Baselines3 training and validation:

```bash
pip install "greenopt-ai-gym[all]"
```

## Required predictive model files

```text
models/weights/
├── ghc_mlp_model_fs_model.h5
├── wcp_LSTM_model_fs_model.h5
└── rc_LSTM_model_fs_model.h5
```


## Verified trained-model contract

The supplied trained models were inspected and tested as one complete inference
chain without retraining or changing their weights:

| Model | Required input | Output | Role |
|---|---:|---:|---|
| Climate MLP | `(2016, 12)` | `(2016, 17)` | Five-minute greenhouse-climate prediction |
| Crop Conv1D-LSTM | `(1, 2016, 16)` | `(1, 3)` | Weekly stem elongation, stem thickness and cumulative trusses |
| Resource Conv1D-LSTM | `(7, 288, 10)` | `(7, 5)` | Daily heating, high/low electricity, CO₂ and irrigation |

The files were originally saved with Keras 2.8. The backend removes the obsolete
`time_major` field from a **temporary copy** during modern-Keras loading. The
original HDF5 files and learned weights remain unchanged.

Run the deep structural check with:

```bash
greenopt-ai validate-models models/weights
```

See `MODEL_MANIFEST.json` and `FULL_MODEL_VALIDATION_REPORT.json` for hashes,
architectures and the end-to-end validation result.

## Prediction-domain transparency

The predictive models use linear output layers. Consequently, a normalized
prediction can occasionally fall outside the training interval `[0, 1]` even
when model loading and feature ordering are correct. The simulator preserves raw
predictions for paper fidelity and returns `result["quality_flags"]`, identifying
which outputs are extrapolations. A user interface should show those warnings and
must not silently clip values used to calculate the original reward.

## Create the environment

```python
import gymnasium as gym
import greenopt_ai  # registers the environment

env = gym.make(
    "GreenOpt/Greenhouse-v0",
    model_dir=r"C:\path\to\models\weights",
    weather_path=r"C:\path\to\weather.csv",
    max_episode_weeks=23,
    reward_mode="paper_v1",
)

obs, info = env.reset(seed=42)
print({key: value.shape for key, value in obs.items()})
print(env.action_space.shape)  # (18144,) = 2016 five-minute rows × 9 controls
```

## Train a TD3 agent

```python
from stable_baselines3 import TD3
import gymnasium as gym
import greenopt_ai

env = gym.make(
    "GreenOpt/Greenhouse-v0",
    model_dir="models/weights",
    weather_path="weather.csv",
)

model = TD3(
    "MultiInputPolicy",
    env,
    learning_rate=1e-4,
    buffer_size=100,
    batch_size=256,
    gamma=0.99,
    verbose=1,
)
model.learn(total_timesteps=5000)
model.save("my_greenopt_td3_agent")
```

## Inspect the scientific contract

```bash
greenopt-ai schema
greenopt-ai physical-ranges
greenopt-ai validate-models C:\path\to\models\weights
greenopt-ai validate-agent my_agent.zip --algorithm TD3
```

## Observation dictionary

| Key | Shape | Meaning |
|---|---:|---|
| `weather` | `(2016, 10)` | Fixed-scaler normalized external weather for the next week |
| `crop_params` | `(1, 3)` | Normalized predicted crop state |
| `resource_consumption` | `(1, 5)` | Normalized previous weekly resource state |
| `gh_climate` | `(2016, 10)` | Normalized predicted greenhouse-climate state |

## Action space

A flat `Box(0, 1, shape=(18144,))`, reshaped internally to `(2016, 9)` in this
exact control order:

1. `co2_vip`
2. `int_white_vip`
3. `pH_drain_PC`
4. `scr_blck_vip`
5. `scr_enrg_vip`
6. `t_heat_vip`
7. `t_ventlee_vip`
8. `water_sup`
9. `water_sup_intervals_vip_min`

## Scientific boundaries

- Uploaded weather is transformed using the **fixed training scaler**; the
  package never refits a scaler per uploaded file.
- Predictive models continue to exchange normalized values internally.
- Physical-unit conversion is only for reporting and diagnostics.
- Results are simulation outcomes within the learned-data domain, not field
  guarantees or autonomous deployment instructions.
- GreenOpt-AI is a research simulation and decision-support environment. 
  It is not a field-certified autonomous greenhouse controller.

See `PUBLISHING_GUIDE.md` before public release.
