[ENHANCEMENT] migrate to pydantic models and add parameterized reset/step support

[rycerzes]

This PR addresses issues #182 and #183 by migrating all data models from dataclasses to Pydantic BaseModel and adding support for parameterized environment reset and step operations. This provides enhanced validation, better error handling, auto-generated documentation, and flexible environment control.

Changes Made

Core Infrastructure Migration (#182)

• types.py: Migrated all base classes (Action, Observation, State, CodeExecResult, EnvironmentMetadata) from dataclasses to Pydantic models
  • Added comprehensive field validation with descriptions and constraints
  • Configured strict validation settings with ConfigDict
  • Added support for arbitrary types (numpy arrays, torch tensors, etc.)
  • Introduced new request/response models (ResetRequest, ResetResponse, StepRequest, StepResponse)
• http_server.py: Enhanced HTTP server with comprehensive API documentation and validation
  • Added detailed OpenAPI documentation with examples and error responses
  • Implemented proper HTTP 422 error handling for validation failures
  • Added new schema endpoints (/schema/action, /schema/observation, /schema/state)
  • Added metadata endpoint (/metadata) for environment information
  • Enhanced FastAPI app with comprehensive documentation and tags
• web_interface.py: Updated web interface to use Pydantic serialization
  • Migrated to use model_dump() instead of asdict()
  • Enhanced form generation using Pydantic JSON schema
  • Improved field extraction with better metadata support
  • Updated all serialization calls throughout the interface

Parameterized Environment Operations (#183)

• interfaces.py: Updated Environment interface to support flexible parameters
  • reset() method now accepts optional seed, episode_id, and custom parameters
  • step() method now accepts optional timeout_s and custom parameters
  • Added get_metadata() method for environment information
• http_env_client.py: Enhanced client to forward arbitrary parameters
  • reset() method forwards all keyword arguments to server
  • step() method forwards all keyword arguments to server
  • Maintains backward compatibility while enabling new functionality

Environment Updates

Echo Environment: Updated to use new Pydantic models

• Migrated EchoAction and EchoObservation to Pydantic with field validation
• Added proper field descriptions and constraints
• Updated environment implementation with type annotations

API Enhancements

New Endpoints

• GET /schema/action - JSON schema for action validation
• GET /schema/observation - JSON schema for observation structure
• GET /schema/state - JSON schema for state representation
• GET /metadata - Environment metadata and information

Enhanced Existing Endpoints

• POST /reset - Now accepts optional parameters (seed, episode_id, etc.)
• POST /step - Now accepts optional parameters (timeout_s, request_id, etc.)
• All endpoints include comprehensive OpenAPI documentation

Closes #182
Closes #183

TODOs:

• Update the echo_env to be compatible with the new changes and serve as reference for updating the rest

[rycerzes]

@burtenshaw could you review this when you get the opportunity, thanks!

[burtenshaw]

Nice work again @rycerzes ! I've tested this PR on the echo env with examples/local_echo_env.py and everything looks good.

That said, this does break all server <> client compatibility so I would like to release this as 0.2.0. That will allow users to work from openenv-core==0.1.0. I expect that 0.2.0 can also include:

• forth coming websockets changes
• paclkaging improvements [ENHANCEMENT] library install improvement #203.
• converted envs to standard format + pydantic.

I'll discuss with @zkwentz how to set this up. But for now, I would work on websockets from this branch and we'll sort it out from there.

[Darktex]

Hi @rycerzes !

Can you offer more background as of why you want to move to Pydantic? We generally want to stick to clean Python as much as possible, and config logic can always happen at the config layer with a tool like Hydra.

In general, I would say that opening a RFC may be the better option for these deep changes to core so that we can discuss before you write code (though maybe in this day and age you can have an LLM write code so maybe that's ok :) ).

As things are for now, I would reject this PR but I want to understand some more of the background to see what we can do

[Darktex]

Blocked until we discuss some more

[rycerzes]

Thanks for the context, @Darktex! I appreciate you taking the time to review this.

You raise valid concerns about introducing Pydantic as a dependency. The primary motivation comes from issue #182, where @burtenshaw identified that the current dataclass approach leads to poor error handling (HTTP 500s instead of proper validation errors) and missing auto-generated documentation for the web interface.

The core problems I was trying to solve are validation failures that result in cryptic errors, lack of proper OpenAPI documentation, and the need for manual form generation in the web interface. Pydantic addresses these directly since our HTTP server already uses FastAPI, which is built on Pydantic.

That said, I completely understand the preference for minimal dependencies. You're absolutely right that an RFC would have been the better approach for such a foundational change. I jumped straight into implementation when I should have discussed the architectural direction first.

Would you prefer I close this PR and open an RFC to discuss alternatives? We could explore lighter-weight solutions or find a way to address the validation and documentation issues without the full Pydantic migration. The parameterized reset/step functionality could potentially be implemented separately in a different PR with simpler validation.

I'm happy to work within whatever architectural constraints the team prefers.

[burtenshaw]

@Darktex I would also add that pydantic is the standard for FastAPI and standard practice in modern python web APIs.

[rycerzes]

@Darktex I would also add that pydantic is the standard for FastAPI and standard practice in modern python web APIs.

Yes and the dataclasses are converted to Pydantic's own flavor of dataclasses using Pydantic.
from FastAPI docs

FastAPI is built on top of Pydantic, and I have been showing you how to use Pydantic models to declare requests and responses.

But FastAPI also supports using dataclasses the same way:

Python 3.8+

from dataclasses import dataclass
from typing import Union

from fastapi import FastAPI


@dataclass
class Item:
   name: str
   price: float
   description: Union[str, None] = None
   tax: Union[float, None] = None


app = FastAPI()



@app.post("/items/")
async def create_item(item: Item):
   return item

This is still supported thanks to Pydantic, as it has internal support for dataclasses.

So, even with the code above that doesn't use Pydantic explicitly, FastAPI is using Pydantic to convert those standard dataclasses to Pydantic's own flavor of dataclasses.

And of course, it supports the same:

• data validation
• data serialization
• data documentation, etc.

This works the same way as with Pydantic models. And it is actually achieved in the same way underneath, using Pydantic.