Merge branch 'main' into skeleton

Author: Darktex

.gitignore

@@ -20,15 +20,14 @@ parts/
 sdist/
 var/
 wheels/
+pip-wheel-metadata/
 share/python-wheels/
 *.egg-info/
 .installed.cfg
 *.egg
 MANIFEST
 
 # PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
 *.manifest
 *.spec
 
@@ -49,77 +48,8 @@ coverage.xml
 *.py,cover
 .hypothesis/
 .pytest_cache/
-cover/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-# .python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-#poetry.lock
-
-# pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#pdm.lock
-#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
-#   in version control.
-#   https://pdm.fming.dev/#use-with-ide
-.pdm.toml
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
+
+# Virtual environments
 .env
 .venv
 env/
@@ -128,16 +58,6 @@ ENV/
 env.bak/
 venv.bak/
 
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
 # mypy
 .mypy_cache/
 .dmypy.json
@@ -175,4 +95,4 @@ Desktop.ini
 # Exclude anything containing "claude" (case-insensitive)
 *claude*
 *Claude*
-*CLAUDE*
+*CLAUDE*

pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "envtorch"
+version = "0.1.0"
+requires-python = ">=3.8"
+dependencies = [
+    "torch>=1.9.0",
+    "numpy>=1.19.0",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

src/core/__init__.py

@@ -10,4 +10,4 @@
 from .env import *
 from .docker import *
 
-# Note: MCP module doesn't export anything yet
+# Note: MCP module doesn't export anything yet

src/core/base.py

@@ -0,0 +1,45 @@
+# Abstract base classes for EnvTorch
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Generic, TypeVar
+
+from .types import StepResult
+
+# Generic type variables
+ActT = TypeVar("ActT")  # Type for the action sent to the environment
+ObsT = TypeVar("ObsT")  # Type for the observation returned by the environment
+
+
+class BaseEnv(ABC, Generic[ActT, ObsT]):
+    """
+    Abstract base class for all environments.
+
+    Each environment must implement:
+      - reset(): to initialize or reinitialize environment state
+      - step(action): to execute an action and return results
+      - close(): to release resources (containers, sessions, etc.)
+    """
+
+    @abstractmethod
+    def reset(self) -> ObsT:
+        """
+        Resets the environment to its initial state.
+
+        Returns:
+            ObsT: The initial observation after resetting.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def step(self, action: ActT) -> StepResult[ObsT]:
+        """
+        Performs one logical step in the environment.
+
+        Args:
+            action (ActT): The action to perform in the environment.
+
+        Returns:
+            StepResult[ObsT]: The resulting observation, reward, done flag, and info.
+        """
+        raise NotImplementedError

src/core/types.py

@@ -0,0 +1,22 @@
+# Type definitions for EnvTorch
+from dataclasses import dataclass
+from typing import Any, Generic, Optional, TypeVar
+
+# Generic type for observations
+ObsT = TypeVar("ObsT")  # TypeVar for typehinting in IDEs
+
+
+@dataclass
+class StepResult(Generic[ObsT]):
+    """
+    Represents the result of one environment step.
+
+    Attributes:
+        observation: The environment's observation after the action.
+        reward: Scalar reward for this step (optional).
+        done: Whether the episode is finished.
+    """
+
+    observation: ObsT
+    reward: Optional[float] = None
+    done: bool = False

src/envs/__init__.py

@@ -8,4 +8,4 @@
 
 from .coding import CodingEnv
 
-__all__ = ["CodingEnv"]
+__all__ = ["CodingEnv"]

src/envs/coding_env/env.py

@@ -0,0 +1,72 @@
+"""
+envs/coding_env/env.py
+--------------------------------
+Concrete environment implementation using the core BaseEnv.
+POC implementation runs code locally via subprocess that can be changed later.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from typing import Optional
+
+from core.base import BaseEnv
+from core.types import StepResult
+
+from .models import CodeAction, CodeObservation
+
+
+class CodingEnv(BaseEnv[CodeAction, CodeObservation]):
+    """
+    Minimal Coding Environment.
+
+    POC behavior:
+      - reset(): returns a fresh, empty observation (no persistent state).
+      - step(action): runs Python code with `python -c` and returns stdout/stderr/exit_code.
+
+    Future swap:
+      Replace _run_code_locally() with a call to your Docker/gateway backend without
+      changing the public API.
+    """
+
+    def __init__(
+        self,
+        default_timeout_s: float = 10.0,
+        python_executable: str = "python",
+    ):
+        """
+        Args:
+            default_timeout_s: Max seconds to allow code execution before timing out.
+            python_executable: Interpreter to run (e.g., "python3", a venv path, etc.).
+        """
+        self._default_timeout_s = float(default_timeout_s)
+        self._python = python_executable
+
+    # --- BaseEnv interface ---
+
+    def reset(self) -> CodeObservation:
+        # No state to clear in this POC; return an initial observation.
+        return CodeObservation(stdout="", stderr="", exit_code=0)
+
+    def step(self, action: CodeAction) -> StepResult[CodeObservation]:
+        if not isinstance(action, CodeAction):
+            raise TypeError(f"Expected CodeAction, got {type(action)!r}")
+
+        # TODO: replace dummy response with the call to the code executor inside the container
+        obs, timed_out = CodeObservation(stderr="", stdout="", exit_code=0), False
+
+        # Simple reward heuristic: success and no stderr -> 1.0 else 0.0
+        reward: Optional[float] = (
+            1.0 if (obs.exit_code == 0 and not obs.stderr) else 0.0
+        )
+
+        info = {
+            "timed_out": timed_out,
+            "interpreter": self._python,
+        }
+
+        return StepResult(
+            observation=obs,
+            reward=reward,
+            done=False,  # Coding env is not episodic by default
+        )

src/envs/coding_env/models.py

@@ -0,0 +1,31 @@
+"""
+envs/coding_env/models.py
+--------------------------------
+Action/Observation types for the Coding environment.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+
+@dataclass
+class CodeAction:
+    """
+    Represents a single code execution request.
+    """
+
+    code: str
+    # Optional: future fields like 'lint': bool, 'timeout_s': float, etc.
+
+
+@dataclass
+class CodeObservation:
+    """
+    Result of executing code in the environment.
+    """
+
+    stdout: str = ""
+    stderr: str = ""
+    exit_code: int = 0